From 1b154e4a3890e43a256825426f640ec236036e41 Mon Sep 17 00:00:00 2001 From: Leah Rowe Date: Tue, 18 May 2021 14:08:27 +0100 Subject: [PATCH] fix build instructions --- site/docs/build/index.md | 14 +- site/docs/maintain/index.old | 1332 ---------------------------------- 2 files changed, 7 insertions(+), 1339 deletions(-) delete mode 100644 site/docs/maintain/index.old diff --git a/site/docs/build/index.md b/site/docs/build/index.md index e003098..68f751c 100644 --- a/site/docs/build/index.md +++ b/site/docs/build/index.md @@ -81,11 +81,11 @@ Now, simply build the coreboot images like so: This single command will build ROM images for *every* board integrated in Libreboot. If you only wish to build a limited set, you can use `lbmk` directly: - ./build libreboot roms x200_8mb + ./build boot roms x200_8mb You can specify more than one argument: - ./build libreboot roms x200_8mb x60 + ./build boot roms x200_8mb x60 ROM images appear under the newly created `bin/` directory in the build system. @@ -135,11 +135,11 @@ required utilities for GRUB are not built, to produce payloads. As a result, you can now (after installing the correct build dependencies) run just a single command, from a fresh Git clone, to build the ROM images: - ./build libreboot roms + ./build boot roms or even just build specific ROM images, e.g.: - ./build libreboot roms x60 + ./build boot roms x60 If you wish to build payloads, you can also do that. For example: @@ -158,7 +158,7 @@ please continue reading! Second, download all of the required software components -------------------------------------------------------- -If you didn't simply run `./build libreboot roms` (with or without extra +If you didn't simply run `./build boot roms` (with or without extra arguments), you can still perform the rest of the build process manually. Read on! You can read about all available scripts in `lbmk` by reading the [Libreboot maintenance manual](../maintain/); lbmk is designed to be modular @@ -251,7 +251,7 @@ Fifth, build the ROMs! Run this command: - ./build libreboot roms + ./build boot roms Each board has its own configuration in `lbmk` under `resources/coreboot/` which specifies which payloads are supported. @@ -260,7 +260,7 @@ By default, all ROM images are built, for all boards. If you wish to build just a specific board, you can specify the board name based on the directory name for it under `resources/coreboot/`. For example: - ./build libreboot roms x60 + ./build boot roms x60 Board names, like above, are the same as the directory names for each board, under `resources/coreboot/` in the build system. diff --git a/site/docs/maintain/index.old b/site/docs/maintain/index.old deleted file mode 100644 index 2d7bcff..0000000 --- a/site/docs/maintain/index.old +++ /dev/null @@ -1,1332 +0,0 @@ ---- -title: Libreboot maintenance manual -x-toc-enable: true -... - -This document describes how to maintain `lbmk` (Libreboot Make). If you just -want to *build it*, refer to this document instead: -[How to build Libreboot from source](../build/) - -Libreboot's build system is named `lbmk`, short for `Libreboot Make`, and this -document describes every aspect of how it works. You can use this document as -a reference for modifying `lbmk`. -**This document assumes that you are using the Libreboot git repository, which -you can download here: -** - -If you're using a release archive of Libreboot, please refer to the -documentation included with *that* release. It will be an older version of the -document that you're now reading. For *development*, we prefer that you modify -`lbmk` in the *Git repository* and read this document as a reference. - -If you've made changes to Libreboot and you wish to submit them for review, -you can! Refer to the following document: -[Sending patches for review](../../contrib.md) - -Git -=== - -Before you use the build system, please know: the build system itself uses -Git extensively, like when downloading software like coreboot and patching it. - -You should make sure to initialize your Git properly, before you begin or else -the build system will not work properly. Do this: - - git config --global user.name "John Doe" - git config --global user.email johndoe@example.com - -Change the name and email address to whatever you want, when doing this. - -You may also want to follow more of the steps here: - - -Use the Git repository! -======================= - -An overview of Libreboot: -------------------------- - -As of 5 January 2021, any command in the build system can run and, if required -pre-requisite steps are not performed, the build system will run the -necessary commands. For example, if you run `./build module grub` but a -GRUB directory is not present, the build system will automatically run -`./download grub`. This also means that you can now, from a fresh Git clone of -Libreboot, simply run `./build Libreboot roms` and it will work! - -In the git repository, Libreboot does not actually host projects such as -coreboot, GRUB or SeaBIOS. Libreboot is, in a nutshell, a series of scripts -that define how to: - -* Download all of the required software components -* Patch all of the required software components, where necessary -* Build all of the required software components -* Build ROM images - -Basically, Libreboot is mostly "metadata" defining where to grab everything -and how to put it all together, from start to finish. No actual development -on upstream projects (coreboot, GRUB, SeaBIOS etc) is done directly within -Libreboot; development is done upstream, when development is done. - -Another way of thinking about it is this: Libreboot is a recipe for building -coreboot ROM images, much like a recipe for cake tells you how to prepare -and bake a cake. - -Libreboot doesn't just contain such scripts. It also contains: - -- config files (for board configs, payloads, etc) -- option ROMs (e.g. for VGA initialization on boards without libgfxinit support) -- 3rd party submodules from coreboot. This is available under `3rdparty/` under - each coreboot directory, for each board - -You can also think of it as a "package manager". Development within Libreboot -is done purely on the build scripts that download, patch, build and integrate -everything, which then results in tested ROM images at known good versions of -each and every software component. - -This document assumes that you have downloaded Libreboot from the Git repository. -If you are using a source code release archive, you can *skip* the download -commands. - -It is *strongly* recommended that you always build from Git, not the release -archives. Technically, you can do whatever you want, but the releases are -considered *reference* level, with source code included simply for GNU GPLv2/3 -compliance and such. For actual development, you should use the Git repository. - -In some cases, if you don't intend to develop Libreboot upstream but you simply -want to make a quick modification to the version you're using, then working on -the source code release archives would make sense. However, such a use-case -scenario is not covered in this document. This page (at least the one hosted -on Libreboot.org) is geared towards the Git repository. - -Let's begin! - -Build dependencies ------------------- - -Before you begin, you should install all of the pre-requisite build -dependencies so that you can compile Libreboot. These can be installed by -running the following command in the build system (tested on Ubuntu 20.04): - - ./build dependencies ubuntu2004 - -Simply speaking, this runs a script that automatically installs all of the -build dependencies in apt-get. - -How to build Libreboot from source ----------------------------------- - -Before you begin working on the build system, and reading the information on -this page, it can help to get a high level view of how the build system is -*used*. We already provide such documentation: - -[Learn how to compile Libreboot from source](../build/) - -Main build scripts -================== - -Libreboot's build system is highly centralized: all build commands revolve -around two scripts: - -- `./download` (runs scripts under `resources/scripts/download/`) -- `./build` (runs scripts under `resources/scripts/build/`) - -The `download` script downloads modules. - -The `build` script builds them. - -A `meclean` script is also included. This runs the `me_cleaner` utility. It's -not required for building anything in Libreboot, but the `download` script can -download `me_cleaner`. The `meclean` script lets you run `me_cleaner` on a batch -of ROM images. - -Libreboot's build system is highly modular. For the most part, individual -scripts within Libreboot are not tied to each other, and can be replaced or -modified very easily, without affecting other parts of the build system too -much, if at all. It is designed specifically to be easily adaptable, in this -manner. - -Everything used by the main build scripts (`download` and `build`) uses -resources under the `resources/` directory from the root of the Git repository -or source code archive. - -Resources directory -=================== - -Everything in the Libreboot build system exists under the `resources/` -directory. The only exception to this is the `docs/` and `www/` directory, -which are their own directory relative to the root of the main directory in -the Git repository or Libreboot source code archive. - -resources/util/ ---------------- - -This directory contains utilities that are included as part of Libreboot, and -not downloaded as *modules* like many parts of Libreboot are. - -resources/util/ich9utils/ -------------------------- - -This is the `ich9utils` directory for source code of the following programs: - -* `ich9gen` -* `ich9deblob` -* `ich9show` -* `demefactory` - -Assuming you have basic dependencies such as GCC installed, simply type `make` -in this directory to compile these utilities. Related commands in the Libreboot -build system: - - ./build module ich9utils - ./build descriptors ich9m - -These utilities have everything to do with manipulating ICH9M based Intel -Flash Descriptors on GM45 laptops such as ThinkPad X200 or T400. These were -adapted from Libreboot. - -More documentation about ICH9M and `ich9utils` is littered throughout the -Libreboot documentation. - -resources/coreboot/ -------------------- - -This directory contains individual subdirectories for each board supported -in Libreboot (whether it's a laptop, desktop or server mainboard). It contains -config files, patches, information about coreboot/3rdparty commit IDs and so -on. It reproducibly downloads and patches coreboot, for several mainboards that -are supported in the Libreboot build system. - -Inside each is the following: - -### resources/coreboot/BOARD\_NAME/romtype - -This file is *optional*. - -Put a single line of text here, which can be anything. Specific lines of text -can be used to instruct the ROM build script. Those are: - -* `4MiB IFD BIOS region` (if specified, the 4MiB BIOS region will be extracted - which is actually just 4MiB CBFS size. For instance, `x230_4mb` ROMs are - provided in Libreboot because X230 splits its 12MiB NOR flash into 8MiB and - 4MiB chips, with upper 3MiB of the 8MiB flash being first part of the default - BIOS region unless IFD is modified, with the 4MiB chip containing the final - upper 4MiB part of the BIOS region. These 4MiB ROMs are useful when flashing, - to flash just that 4MiB chip) -* `4MiB ICH9 IFD NOR flash` (instructs the ROM script to insert ICH9M flash - descriptor with disabled ME, on GM45/ICH9 boards such as ThinkPad X200/T400. - This one is for 4MiB NOR flash) -* `8MiB ICH9 IFD NOR flash` (same as above but for 8MiB NOR flash) -* `16MiB ICH9 IFD NOR flash` (same as above but for 16MiB NOR flash) -* `i945 laptop` (if this is specified, the upper 64KiB bootblock will be copied - to the space for the lower 64KiB bootblock, in the resulting coreboot ROM. - This is useful for BUC.TS purposes on machines such as ThinkPad X60/T60) - -As of 5 January 2021, no other strings are specified in the build system, so -anything else (or the `romtype` file being absent) will result in default -behaviour: just copy the ROM but don't modify it in any way. - -In this configuration, the descriptor specifies regions based on 16MiB NOR flash. - -### resources/coreboot/BOARD\_NAME/x86\_32 - -This file is optional. If present, Tianocore will not be included at all when -building ROM images. - -Only the 64-bit version of Tianocore is built in Libreboot's build system. -Some machines are 32-bit only, and in practise those older machines are -typically quite useless with Tianocore. - -Tianocore is only really useful on 64-bit machines, in most use-case scenarios, -so Libreboot only builds the 64-bit version. - -### resources/coreboot/BOARD\_NAME/config/ - -The following files (at least one, or all) can be included: - -* `libgfxinit_txtmode` -* `libgfxinit_corebootfb` -* `vgarom_txtmode` -* `vgarom_corebootfb` - -Configs with `vgarom` in the name must specify a PCI option ROM file name -under format `pciVVVV,DDDD.rom` where VVVV is the vendor ID and DDDD is the -device ID. This option ROM will be under `resources/blobs/pciroms/` -and the config: 1) disables VBT in coreboot, 2) Disables libgfxinit if present -and 3) Enables loading and executing of PCI option ROM (Video BIOS) for that -video chipset, with the exact PCI ID specified in the coreboot config. - -Configs with `libgfxinit` in the name must specify that libgfxinit is to be -used, with a VBT (Video BIOS Table) supplied by coreboot. Loading of PCI option -ROMs must not be enabled in this setup (but on desktops, where libgfxinit is -used for the built-in GPU, an add-on GPU can still be used if you use the -SeaBIOS payload, because SeaBIOS will automatically load the Video BIOS from -your graphics card). - -Regardless of whether you use `vgarom` or `libgfxinit` setup: - -* `txtmode` specifies that coreboot must start in legacy VGA text mode. This is - useful for textmode applications such as MemTest86+ or operating systems such - as FreeDOS -* `corebootfb` specifies that coreboot must start in a VESA framebuffer. This option - is most useful combined with `libgfxinit` when dealing with GNU+Linux or BSD - operating systems in the GNU GRUB payload, or in SeaBIOS with SeaVGABIOS. - This mode is also implied when using Tianocore, and Libreboot's build system - does not provide Tianocore ROMs with `txtmode` startup. - -These are specific coreboot configs for that board. These configs do not -specify a payload, but enable PS/2 keyboard initialization in case SeaBIOS -and GRUB are used (other payloads such as linuxboot and tianocore can do -keyboard initialization on their own). - -Each of these are coreboot configurations, for that board. - -The rules (for Libreboot purposes) are as follows: - -* Payload must be set to *None*. The Libreboot build system builds payloads - externally, instead of using the coreboot build system. -* VGA ROM must be included, if required, and set in coreboot config such that - coreboot itself is loading and executing the ROM. -* The config must not make coreboot's build system grab anything from - external sources, *except* the `3rdparty` repositories hosted by the - coreboot project. The Libreboot build system provides the chance to specify - exactly which 3rdparty submodule revisions are used. 3rdparty modules are - downloaded *after* setting the coreboot revision, to ensure a consistent - set of 3rdparty modules, and then resets the revisions of each submodule - based on what is written in the Libreboot build system -* NOTE: exception to above rule is VGA ROMs, and other PCI option ROMs, which - the user may want to include. However, only VGA option ROMs are really - useful in most cases. Normally for other options ROMs, the user would - want to have the SeaBIOS payload - -General rules/principles for configuring a board in `make menuconfig` on the -coreboot build system: - -* `General -> Use CMOS for configuration values` (ENABLE) -* `General -> Load default configuration values into CMOS on each boot` (ENABLE) -* Hardcode your own desired CMOS config - in `src/mainboard/manufacturer_name/mainboard_name/cmos.default` -* It's possible to change the CMOS config in nvramtool, directly on the ROM - image. Simply dump it, change the value you want, then re-flash. Hardcoded - config is desired, for consistent functionality on all systems where a given - ROM image is used. This makes Libreboot behave more consistently at startup. -* Select what mainboard you want under `Mainboard` -* If it's a system with Intel Flash Descriptor, set the CBFS size to exactly - the size of the BIOS region (as per Intel Flash Descriptor). For example, - on X230, coreboot sets 1MiB CBFS size by default but the default BIOS region - is 4MiB, so: - * `Mainboard -> Size of CBFS filesystem in ROM = 0x400000` - (this is 4MiB specified in bytes as a hexadecimal value) -* Chipset -> Include CPU microcode in CBFS = Do not include microcode updates\ - NOTE: microcode updates are non-free, and not available in Libreboot -* `Chipset -> Bootblock behaviour = Always load fallback` - Based on a setting in CMOS memory, coreboot's bootblock can load either the - `fallback` or `normal` payload. You can also put different ramstage and - romstage in cbfs. This is useful for development, but not really useful for - end users that Libreboot is targeting. - (the Libreboot build system currently does not support use of fallback+normal - but this could change in the future. Coreboot provides a mechanism where you - put a setting in CMOS config that makes fallback/normal be used depending - on that setting. If the RTC battery is pulled, then the other payload will - be used. This other payload can be anything. This is useful - for development purposes, like when developing a payload. You can have a - known working payload, and the one you're working on, to prevent soft bricks - and speed up development. Libreboot is geared towards end users, so just - always use the fallback, and only include a fallback payload as - `fallback/payload` in CBFS. This is the default behaviour of the Libreboot - build system. This is OK because we verify each setup before releasing it. -* `Devices -> Graphics initialization = Use libgfxinit` - * If you use this option, also do: - * `Add a Video BIOS Table (VBT) binary to CBFS (NEW) = ENABLED` - * `Display -> Framebuffer mode = whatever you want` - * `txtmode` in the config name if setting legacy VGA framebuffer - * `corebootfb` in the config name if setting vesa framebuffer with a higher resolution -* Devices -> Graphics initialization = Run VGA Option ROMs - * If you use this option, also do: - * Display -> Leave it alone if you just want text mode (legacy VGA mode) - * Display -> Select a resolution and set Framebuffer mode to VESA framebuffer - if you want a high resolution framebuffer at startup - * Add a VGA BIOS image = ENABLED - * Include the PCI option ROM from `resources/blobs/pciroms/` (see below) - and in in coreboot menuconfig specify the filename as `pciVVVV,DDDD.rom` - where VVVV is the vendor ID and DDDD is the device ID. You can find - this information by running `lspci -nn` under GNU+Linux, and you can - check that the option ROM is for your specific VGA adapter by running - `romheaders` utility on the ROM. Check build date and other information - of the VGA ROM by running `strings pciVVVV,DDDD.rom | head` - * Example entry for path to VGA ROM in coreboot menuconfig: - `../../resources/blobs/pciroms/pciVVVV,DDDD.rom` - * `Add a Video BIOS Table (VBT) binary to CBFS = DISABLE` (it's VERY - important to disable this option, because the VGA ROM itself will handle - VBT stuff and you don't want to conflict anything at start up) -* `Generic Drivers -> PS/2 keyboard init = DISABLE` - * Only enable if necessary, like if you actually need to have PS/2 - keyboard support, otherwise USB keyboard support will usually Just Work. - GRUB, SeaBIOS and Tianocore all provide PS/2 keyboard init. - * Tianocore (UEFI) payload does not require this option to be enabled. It - handles PS/2 keyboard initialization by itself - * Don't enable "PS/2 keyboard delay" in coreboot menuconfig. The Libreboot - build system adds this externally, using a `cbfstool` command -* `Security -> Memory initialization -> Always clear all DRAM on regular boot = - ENABLE` - * This helps to reduce the threat posed by Cold Boot attacks - * Other security features here you can choose to enable or disable - depending on your preferences -* `Console -> Default console log level = 0` - * Libreboot is intended for end users, who want a faster boot speed - * The extra debug options slow down the boot process -* `Payload -> Add a payload = NONE` - * Libreboot's build system compiles payloads externally, and adds them - during the build process using `cbfstool` - -### resources/coreboot/BOARD\_NAME/patches/ - -**NOTE: This directory is ignored when you include a symlink file (see below)** - -You can make modifications to coreboot, on the upstream coreboot repository, -reset to whatever coreboot commit ID you want to base your patches on. - -For however many custom patches you've applied, run the following command: - - git format-patch -nX - -X is the number of patches. This might be applied in the `master` branch, or -you might be working on another branch. If you're working in another branch, -the commit ID is from whatever commit that branch forks from. - -Libreboot's build system does not remove `.git` resources from coreboot, -when downloading it for each board. Therefore, even if you've already applied -patches (using the build system from Libreboot), you can then make further -modifications on top of coreboot and include your patch. - -The patches must be in ascending alpanumerical order from the first patch to -be applied. - -For example: - -* `0001-first.patch` -* `0002-second.patch` -* `0003-third.patch` -* ...and so on - -NOTE: If you're using a symlink file (see below), do not put the patches here. -In that situation, the patch directory should be empty (but the directory -should still be present). For example, let's say X220 uses the same coreboot -revision as X230, with X220 having a symlink file pointing to the X230 -directory. - -If symlink file present, put your patches in the `patch/` directory of the -board that is being linked to instead. - -### resources/coreboot/BOARD\_NAME/revision/ - -**NOTE: This directory is ignored when you include a symlink file (see below)** - -This directory contains files with single lines in them, specifying the exact -commit ID of each coreboot submodule that go inside the `3rdparty/` directory -of the coreboot Git repository. - -Download coreboot and reset it to the revision you wish to use. Then you can -download the submodules using this command: - - git submodule update --init --checkout - -Check the `.gitmodules` file in your coreboot directory. It specifies where -all of the 3rdparty submodules will be downloaded to. Most of them will be -downloaded into the `3rdparty/` directory. - -For the ones in `3rdparty/` you should put a file with the same name as the -corresponding directory under `3rdparty/` with that file containing just a -single line specifying the commit ID you wish to use. - -Generally, you should always set the 3rdparty revisions to the same ones used -when you first downloaded the 3rdparty submodules in that version of coreboot, -when *that* commit ID was the newest one in coreboot. This is because the -submodule commit IDs will always be the latest ones in that repository, even -when resetting to an older coreboot revision (Libreboot resets to the coreboot -revision specified in cbrevision, see below). - -If you are *retroactively* selecting an older coreboot revision, you should -set the 3rdparty submodule revisions to ones that are either the exact same -commit date as the date of the coreboot commit or, if none are that exact date, -the latest date(s) *before* the date of the coreboot commit, *not* after. This -will be verified when you submit a pull request anyway. - -NOTE: Not all 3rdparty submodules are downloaded into `3rdparty/`, and those -ones will not automatically be reset to a specific revision by the Libreboot -build system. For these, you should reset the commit using the `extra.sh` -script (see below). - -### resources/coreboot/BOARD\_NAME/cbrevision - -**NOTE: This file is ignored when you include a symlink file (see below).** - -This file must contain a single line, with no whitespace, just specifying -the commit ID of the coreboot revision you intend to use (as per the coreboot -Git repository). - -### resources/coreboot/BOARD\_NAME/extra.sh (optional) - -Technically, this script is optional but if you are not specifying a symlink -via `symlink` file (see below) you should always, at the very least, reset -submodule revisions of coreboot in this script, for those submodules that -are *not* downloaded into the `3rdparty/` subdirectory of coreboot. - -This is useful if you want to extend the default functionality of the build -in Libreboot, for the particular board you're working on. - -For example, if coreboot is downloading some submodules to a directory other -than `3rdparty/` in the coreboot Git repository, you should script something in -here to reset the revision of *that* submodule. - -Another example of how this `extra.sh` script can be used is to apply custom -patches to *submodules* in coreboot, or any other such functionality that is -not yet implemented by the main build system in Libreboot. In other words, -extra.sh can be used to extend the Libreboot build system functionality! -That's why it's called `extra.sh`! - -However, Libreboot's build system is released under a free license and you're -free to extend it anyway. However! Sometimes, you will want to implement -specific functionality that only benefits one specific mainboard in Libreboot. -You could *also* make the `extra.sh` script symlink to *another* `extra.sh` -script. - -### resources/coreboot/BOARD\_NAME/symlink (optional) - -When you run the `./download coreboot` command, or coreboot is downloaded when -running the `./download all` command, coreboot is only downloaded (via git -clone) *once*, and then copied (using `cp -R`) for *each* board specified as -per directory names under `resources/coreboot/`. - -A separate coreboot directory for each board is therefore created. For example, -X230's coreboot directory would be `coreboot/x230_4mb/`. Coreboot's own crossgcc -toolchain, utilities and other modules are compiled *separately*, for each -directory. This means that different coreboot revisions can be used for -different boards. - -However, in practise we often use the same coreboot revision for most boards, -or at most 2-3 coreboot revisions are used and each revision has a few boards -using it in the Libreboot build system. It would be a waste to create a -separate coreboot directory for multiple boards that all use the same coreboot -revision. - -Therefore, Libreboot's build system supports linking to another board, thus -skipping the creation of a new coreboot directory. - -The `symlink` file is not actually a symlink, but instead should contain the -board name, per directory name of that board under `resources/coreboot/`. - -The build system goes into the `coreboot/` directory and creates a relative -symlink. For example, if X220 contained a symlink pointing to X230, in -the `coreboot/` directory there would be a symlink `x220 -> x230_4mb`. - -resources/grub/ ---------------- - -This directory contains the GRUB configuration files (for the target systems -that Libreboot's build system contains GRUB ROMs for), GRUB fonts, keymap files -and a file specifying which modules are to be included in the GRUB payload. - -### resources/grub/config/ - -GRUB configs. There is not a full GRUB config here, because the build system -mixed different *snippets* together to create various *full* GRUB configs, for -various setups. - -To understand how these files are used, read the following script: - -* `resources/scripts/build/payload/grub` - -### resources/grub/font/ - -Fonts go in here. Currently, only the Dejavu Sans Mono is provided, as a font -used in GRUB (but only is VESA mode, not text mode). - -### resources/grub/keymap/ - -Keymap configurations are included here, for various keyboard layouts. -Libreboot's build system provides multiple ROM images with the GRUB payload, -each with a different default payload. Even Dvorak (US, UK and French variants) -are supported! This is one reason why Libreboot is so great. - -I, Leah Rowe, created the UK Dvorak keymap file by hand, many years ago, by -manually modifying the scan codes in the US Dvorak file. This is because there -was no UK Dvorak keymap file available, and automatically generating it caused -problems when actually using it. I did this many years ago, for Libreboot, -because I'm a long time Dvorak user. - -If you wish to add new keymaps, you can do so using the instructions here: - -[Adding new keymap files to GRUB](../grub/#grub-keyboard-layouts-for-reference) - -### resources/grub/modules.list - -This file contains a list of modules to be used in the GRUB payload. It is -important to not use too many, because of limited storage capacity in the main -boot flash on most systems that Libreboot has support for. - -resources/memtest86plus/patch/ ------------------------------- - -Patches for Memtest86+, which is included as a payload on certain Libreboot -configurations. It is used to test your RAM, and it will tell you if your -RAM is faulty. - -resources/scripts/build/ -======================== - -This directory contains all of the scripts used that make up the entire -Libreboot build system. - -resources/scripts/build/clean/ ------------------------------- - -Basically, these scripts do the equivalent of `make clean` or `make distclean` -on various modules thet are a part of Libreboot. - -### resources/scripts/build/clean/ich9utils - -This runs `make clean` on the `ich9utils` directory -at `resources/util/ich9utils/` - -This also deletes the descriptors generated at `descriptors/ich9m/` - -### resources/scripts/build/clean/cbutils - -This runs `make clean` on the following coreboot utilities, in each coreboot -directory for each board, on the following directories in coreboot: - -* `util/cbfstool/` -* `util/ifdtool/` -* `util/nvramtool/` -* `util/cbmem/` - -It also runs `make distclean` on `payloads/libpayload/` in each coreboot -directory. - -These directories were created when running `./download coreboot` in the -Libreboot build system. - -### resources/scripts/build/clean/crossgcc - -In each coreboot directory, for each board, this script does `make distclean` -on `util/crossgcc/` which is the cross-compiler toolchain that comes with -coreboot. - -The crossgcc binaries were compiled when running `./build module crossgcc` in -the Libreboot build system, which in turn runs `make crossgcc` in each and -every coreboot directory created when running `./download coreboot` in the -Libreboot build system. - -### resources/scripts/build/clean/flashrom - -This runs `make clean` on the `flashrom/` directory, which was created when -running `./download flashrom` in the Libreboot build system. - -### resources/scripts/build/clean/grub - -This runs `make distclean` on the `grub/` directory, which was downloaded -when running `./download grub` in the Libreboot build system. - -However, it does *not* delete the payload executables in the `payload/` -directory, which were created when running `./build payload grub`, -`./build payload seabios` or `./build payload all` in the Libreboot build -system. - -The files under `payload/` are cleaned out when running the -`./build clean payloads` command. - -### resources/scripts/build/clean/memtest86plus - -This runs `make clean` on the `memtest86plus/` directory, which was created -when running `./download memtest86plus` in the Libreboot build system. - -### resources/scripts/build/clean/payloads - -This literally just deletes the `payload/` directory, which was created when -running `./build payload grub` or `./build payload seabios` or -`./build payload all` in the Libreboot build system. - -### resources/scripts/build/clean/rom\_images - -This literally just deletes the `bin/` directory, which was created when -running the following command in the Libreboot build system: - - ./build Libreboot roms - -The `bin/` directory contains coreboot ROM images, which were built when -running one of the above commands. - -### resources/scripts/build/clean/seabios - -This runs `make distclean` on the `seabios/` directory, which was created when -running `./download seabios` in the Libreboot build system. - -resources/scripts/build/dependencies/ -------------------------------------- - -### resources/scripts/build/dependencies/ubuntu2004 - -Using the `apt-get` software, this script downloads and installs the required -build dependencies on Ubuntu 20.04, which is a GNU+Linux distribution. - -In Libreboot 20160907, which Libreboot was originally forked from (on December -11th, 2020), there was also a script for Parabola GNU+Linux. However, the -Parabola script was deleted in Libreboot due to lack of testing. Libreboot -20160907 contained a script for Trisquel 7.0, which was updated for Ubuntu -20.04. - -resources/scripts/build/descriptors/ ------------------------------------- - -Various commands to do with Intel Flash Descriptors - -### resources/scripts/build/descriptors/ich9m - -This is executed when running `./build descriptors ich9m` - -This simply runs `ich9gen` located at `resources/util/ich9utils/` - -Descriptors are made available at `descriptors/ich9m/` - -resources/scripts/build/module/ -------------------------------- - -These scripts compile the required modules, as a pre-requisite for then -compiling payloads, which in turn is a pre-requisite for compiling coreboot -ROM images for the end user to install (flash) on their machine. - -### resources/scripts/build/module/ich9utils - -This runs `make` on `ich9utils` included at `resources/util/ich9utils/`. - -This makes the following utilities available in that directory: - -* `ich9gen` -* `ich9show` -* `ich9deblob` -* `demefactory` - -More information about `ich9utils` is littered throughout the Libreboot -documentation. - -### resources/scripts/build/module/cbutils - -This runs `make` on the following coreboot utilities: - -* `util/cbfstool` -* `util/ifdtool` -* `util/nvramtool` -* `util/cbmem` - -The `cbfstool` utility is used extensively by the Libreboot build system, when -building coreboot ROM images. It is used to: - -* Insert payloads into the ROM images (Libreboot does not rely on the coreboot - build system to insert payloads. They are compiled externally, and the ROM - images are compiled with payloads. Cbfstool is then used, to insert the - payloads *after* the coreboot ROM images are compiled) -* Insert GRUB configurations into the ROM images -* ...and more - -The `ifdtool` utility is not currently used by the Libreboot build system, but -it is provided for people who use Intel platforms that have an Intel Flash -Descriptor in the boot flash. For example, X230's Intel Flash Descriptor sets -some of the flash regions read-only by default, and ifdtool can be used to -set these regions read-write by modifying the Intel Flash Descriptor in a -dump of it, which can then be re-flashed to enable internal re-flashing. - -The `nvramtool` utility is not currently used by the Libreboot build system, -but it is recommended for changing CMOS settings in the coreboot ROM image. -Libreboot hardcodes these settings, but you can dump the ROM and use nvramtool -to change the defaults specified in the ROM; this modified ROM can then be -re-flashed. The reason these settings are hardcoded is to ensure consistent -behaviour of a given Libreboot ROM image, on a given system (unless the end -user changes the default behaviour, and this is documented on the Libreboot -website). - -The `cbmem` utility is not currently used by the Libreboot build system, but it -is useful for debugging purposes. End users can usually ignore this one. - -### resources/scripts/build/module/crossgcc - -For *each and every* coreboot directory created by running `./download coreboot` -in the Libreboot build system, this script goes into said directory and runs -the following command: - - make crossgcc-i386 - -This is *required* for building coreboot ROM images in the Libreboot build -system. Coreboot has its own cross-compiler toolchain, which it calls *crossgcc* -and it is compiled by running the above command (in the *coreboot* build -system). - -### resources/scripts/build/module/flashrom - -This script runs `make` in the `flashrom/` directory, which was created when -running `./download flashrom` in the Libreboot build system. - -### resources/scripts/build/module/grub - -This does *not* build the actual GRUB payload, which is inserted into coreboot -ROM images for configurations that use GNU GRUB bootloader as default payload. - -Rather, this script builds the required GRUB utilities when are then executed -by running `./build payload grub` in the Libreboot build system, to create -the GNU GRUB payloads (there are several different GRUB payload configurations, -which Libreboot uses for different machine configurations). - -GNU GRUB can be compiled for several different systems. On x86, the most -common configuration is for BIOS or UEFI and is referred to generically as *PC -GRUB*. - -Libreboot compiles GNU GRUB with the following command in GRUB's build system: - - ./configure --with-platform=coreboot - -This is a special build-time configuration. When this configuration is used, -GNU GRUB runs on *bare metal* as a coreboot payload, and does not make use of -BIOS or UEFI based services. Several features are present in this version of -GRUB, that are not present in other versions. For example, the `lscoreboot` -command becomes available on the GNU GRUB terminal, which displays information -about the version of coreboot that is currently running on the end user's -machine. - -### resources/scripts/build/module/memtest86plus - -This script runs `make` in the `memtest86plus/` directory, which was created -when running `./download memtest86plus` in the Libreboot build system. - -resources/scripts/build/payload/ --------------------------------- - -These scripts build the payloads (ELF executables) that are inserted into the -coreboot ROM images, when built using the Libreboot build system. - -### resources/scripts/build/payload/grub - -This script, using utilities compiled when running `./build module grub` in the -Libreboot build system, builds several GRUB payloads (ELF executables) -and configuration files (for the GRUB payload) and places these files in -the `payload/grub/` directory. - -These files are inserted into coreboot ROM images, when -running `./build Libreboot roms` in the Libreboot build system, if GRUB payload -is specified on that platform. - -Essentially, there are 2 GRUB configurations per keymap (keyboard layout) -supported in the Libreboot build system: - -* Config for high resolution VESA framebuffer startup in coreboot -* Config for legacy VGA text mode startup in coreboot - -The `grub/grub-mkstandalone` utility is used, which was built when -running `./build module grub` in the Libreboot build system. -The `grub-mkstandalone` utility is what creates the ELF executable to then -be used in coreboot, as a payload. - -It uses the following resources for this: - -* GRUB config files in `resources/grub/config/` -* GRUB keymap layout files in `resources/grub/keymap/` -* GRUB modules specified in `resources/grub/modules.list` - -Because these files are created seperately, in this manner, you could also -use these compiled ELF files in any coreboot ROM, not just ones compiled by -the Libreboot build system, in the situation where you built coreboot without -inserting a payload. Run the following `cbfstool` commands. Like so: - -NOTE: the build system in Libreboot already does these commands, when building -ROM images. The commands below are only examples, for if you built your own -coreboot ROM by hand, and wanted to include some payloads in the ROM - -For `fallback` payload in coreboot: - - cbfstool coreboot.rom add-payload -f payload/grub/filename.elf -n fallback/payload -c lzma - -For `normal` payload in coreboot: - - cbfstool coreboot.rom add-payload -f payload/grub/filename.elf -n normal/payload -c lzma - -For normal *or* fallback payload in coreboot, also do: - - cbfstool coreboot.rom add -f payload/grub/filename.cfg -n grub.cfg -t raw - - cbfstool coreboot.rom add -f payload/grub/filename_test.cfg -n grubtest.cfg -t raw - -The `.elf` and `.cfg` must match! E.g. ELF+config for DE Qwertz keymap with -legacy VGA text mode startup. - -### resources/scripts/build/payload/seabios - -This script compiles two separate SeaBIOS payloads (ELF executables), using -the configuration files stored in `resources/seabios/config/`: - -* `resources/seabios/config/libgfxinit` -* `resources/seabios/config/vgarom` - -The `libgfxinit` config specifies that SeaBIOS must use the video initialization -in coreboot, which provides a framebuffer interface. For this purpose, SeaBIOS -will also compile its own option ROM called SeaVGABIOS, which emulates a Video -BIOS for providing legacy VGA support (however, it currently does not support -switching between different video modes and INT 10H interrupt services are not -completely functional when using this). SeaVGABIOS is useful for several things: - -* SYSLINUX/ISOLINUX bootloaders, displayed on a native coreboot framebuffer -* BSD bootloaders, displayed on a native coreboot framebuffer -* Similar use case scenarios versus the above - -The `vgarom` config specifies that SeaBIOS must not build its own Video BIOS -option ROM, nor should it provide any video initialization. In this -configuration, coreboot itself is loading and execution a Video BIOS option ROM -supplied by the manufacturer (e.g. Intel/AMD/Nvidia). - -Both configs support all of the standard BIOS functions, which is useful for -legacy operating systems. However, INT 10H video interrupt services and -especially mode switching are not fully functional when using SeaVGABIOS. They -both load and execute PCI option ROMs, load and execute MBR based bootsectors -and in general provide a legacy BIOS interface that legacy operating systems -can use, such as DOS or old versions of Windows. - -If you use the `vgarom` config, it is assumed that you will inserted a Video -BIOS option ROM supplied by the manufacturer of your video chipset, into the -coreboot ROM. For example: Intel, Nvidia or AMD/ATI option ROM. - -Everything else (besides video initialization) is the same, in both SeaBIOS -configs. Which one you use is based on your own needs/preferences. - -### resources/scripts/build/payload/tianocore - -This script is executed when running `./build payload tianocore` in the -Libreboot build system. - -This builds Tianocore UEFI payload. Currently it only builds the x86-64 setup, -so this will not currently work on 32-bit only machines such as most T60 -thinkpads. - -Libreboot does not directly build Tianocore. It uses a dummy coreboot config, -and uses the coreboot build system to download Tianocore. The coreboot build -system always downloads Tianocore every time you want to build it, but this -behaviour is disabled in Libreboot by a custom coreboot patch. Similarly, -coreboot always re-builds Tianocore from scratch every time; this behaviour -is also disabled. - -Libreboot simply uses the Tianocore build script in the coreboot build system, -and then the Tianocore payload is available at `payload/tianocore/tianocore.elf` -in the Libreboot build system. - -Coreboot's own download function for Tianocore is disabled. Libreboot downloads -Tianocore itself, using the `coreboot_fb` branch from MrChromebox's fork of -Tianocore (modified for better compatibility as a coreboot payload). - -Planned: build SeaBIOS as CSM for Tianocore. This means that SeaBIOS will run -as a UEFI app. The benefit to this setup is that Tianocore provides the option -for INT10H video bios interrupt services to work in this setup, when using -legacy operating systems (e.g. old Windows versions). Currently, Libreboot -only provides a pure Tianocore setup or pure SeaBIOS setup, standalone, but -does not provide both at the same time. - -resources/scripts/build/libreboot/ ------------------------------ - -### resources/scripts/build/libreboot/roms - -This script is called when running `./build Libreboot roms` in the Libreboot -build system. - -This script builds all ROM images, for all payloads. In earlier versions of -Libreboot, separate coreboot configs were specified for each payload but now -they are universal. This one script builds every ROM for every payload. -In older versions, there were separate scripts for each payload config. - -If no argument is given, this script will build ROM images for every board, for -every payload. However, you can specify whatever boards you want and it will -only build for that (with every payload). For example: - - ./build Libreboot roms x230_4mb x220 - -If no special argument is given, this script will simply build *all* ROM images -as defined by configuration files in `resources/coreboot/*/config/` - -No actual instructions are contained within this script, for building anything. -Instead, this script makes use of a *helper* script named `roms_helper` -which you can read about in the next section. - -Each coreboot image with GRUB payload will appear under the directory at -location `bin/grub_boardname/` (SeaBIOS and Tianocore are also available to -select in the default GRUB menu). - -At present, Libreboot only builds withs GNU GRUB as the default payload, -with SeaBIOS and Tianocore as an option in the menu (SeaBIOS not yet included -as CSM in Tianocore, but rather it is a standalone SeaBIOS setup). - -### resources/scripts/build/libreboot/roms_helper - -This script is not intended to be used directly, but it is called by the script -named `roms` under `resources/scripts/build/libreboot/` - -This script builds ROM images for a single specified board. For example, the -script named `roms` may give `x230_4mb` as an argument. For the purpose of -explaining how this script works, we will assume that `x230_4mb` is the given -argument, where `roms` runs `./build Libreboot roms x230_4mb` - -This script makes use of the following resources: - -* Coreboot source code directory at `coreboot/board_name/` where in this - example, `board_name` is `x230_4mb`. -* Utility `cbfstool` under `coreboot/board_name/util/cbfstool/` -* SeaBIOS payload (plus SeaVGABIOS) under `payload/seabios/` (the coreboot - images are compiled with GNU GRUB bootloader as the main payload, but SeaBIOS - is also added and provided as an option in the GNU GRUB boot menu, as a menu - option). When used as a coreboot payload, GNU GRUB can boot any other coreboot - payload by using the `chainloader` command. GRUB has many advanced security - features, unknown to most people but fully documented on the Libreboot website - and we strongly recommend its use as default payload for your setup. -* Tianocore payload under `payload/tianocore/` -* Coreboot configuration(s) provided for a given board, located - at `resources/coreboot/board_name/config/` -* keymap (keyboard layout) files located - at `resources/grub/keymap/original/` to know which keymaps are supported - and, for each one, this script compiles a coreboot ROM image with its own - version of GNU GRUB that uses the given keymap configuration. - -The coreboot configuration under `resource/coreboot/board_name/config/` -can have one of the following file names: - -* `libgfxinit_txtmode` -* `libgfxinit_corebootfb` -* `vgarom_txtmode` -* `vgarom_txtmode` - -It is not required to have all of these files present. You may choose which -combination you would like, when adding new boards to Libreboot or modifying -existing ones. - -Configs with `txtmode` in the name are for setups where coreboot initializes -the display in legacy VGA *text mode*, which is useful for legacy operating -systems such as DOS, or text mode applications like MemTest86+. It is the most -compatible option overall and, if your Video BIOS supports mode switching (which -SeaVGABIOS does not, but most vendor option ROMs do), you can switch to higher -resolution modes which means that more modern operating systems will show a -video display. (NOTE: even with text mode startup, most GNU+Linux distributions -and BSD operating systems will still show a video display, because their -kernels support *Kernel Mode Setting* where the kernel itself is controlling -video modes, without relying on Video BIOS services; this is standard practise -on Intel video chipsets, for example). If you're using a vendor-supplied VGA -ROM, it is recommended that you start in text mode as it will be the most -compatible setup (in terms of operating system support, especially if you -switch to SeaBIOS from the GNU GRUB menu). - -Configs with `corebootfb` in the name are for setups where coreboot initializes the -display in a high resolution VESA frame buffer. This is useful in some -situations, such as when using libgfxinit but if using text mode startup, it's -not very important. If you are using SeaVGABIOS, it's recommended to use this -setup as it will be the most compatible (with SYSLINUX/ISOLINUX bootloader menus -and such). - -The `libgfxinit_txtmode` config is for setups where libgfxinit is used. This is -coreboot's own native video initialization, which coreboot provides on a lot of -mainboards nowadays. In this setup, a PCI Option ROM for the Video BIOS is not -needed because coreboot handles that functionality by itself. *Not needed* does -not mean you won't use one; you may decide (at your own discretion) that you -prefer to do so, if you wish. This setup is recommended when you wish to use -text mode applications such as MemTest86+ or boot operating systems in text -mode, such as FreeDOS (NOTE: FreeDOS will boot just fine on text mode setup -with libgfxinit, but will only run text mode applications. Games and such will -not work, because libgfxinit does not currently support mode switching) - -The `libgfxinit_corebootfb` config is for setups where libgfxinit is used, but you -wish to start in a high-resolution VESA framebuffer. This setup is the most -compatible, when dealing with GNU+Linux and BSD operating systems while booting -the kernel of those operating systems directly from GRUB, without relying on -SeaBIOS (which is provided in Libreboot's GRUB menu, an a menu option). It is -also the best option for SeaBIOS+SeaVGABIOS, in terms of compatibility; most -ISOLINUX/SYSLINUX boot menus will display correctly (loaded from SeaBIOS) in -this setup, albeit at a higher resolution (compared to booting from text mode -with the vendor VGA ROM, from SeaBIOS) so it might look *weird* to you at first -if you're not used to ISOLINUX/SYSLINUX menus displaying at your monitor's -native resolution. This also means that you can use SYSLINUX/ISOLINUX installed -to the HDD/SSD on your system (though, this is largely pointless because GNU -GRUB does the same things). - -In addition, this build script inserts a file into CBFS (coreboot file system, -which is a file system inside the coreboot ROM that is installed onto the end -user's machine) that specifies a PS/2 keyboard delay; this makes SeaBIOS, when -loaded, wait up to three seconds for the PS/2 keyboard to initialize, if -present. This works around a potential race condition due to how fast coreboot -is capable of booting, which would otherwise prevent the keyboard from being -fully initialized, thus leaving you with a non-functioning keyboard (until -booting an OS, which would presumably handle initialization on its own). - -resources/scripts/download/ -=========================== - -The scripts in this directory download the required components that are used -in the Libreboot build system. - -resources/scripts/download/coreboot ------------------------------------ - -This script is executed when running the following command in the Libreboot -build system: - - ./download coreboot - -First, this script checks whether a `coreboot/` directory exists. If it does -not exist, it is created. If it does exist, it is deleted and then created (to -clear what was previously there). - -This `coreboot/` directory does not actually contain the coreboot Git -repository; rather, it is populated with *multiple* coreboot directories (one -for each *board*, technically, and boards specify which coreboot revision is to -be used, but boards in Libreboot can be configured to merely *link* to another -board; this means that, potentially, a single coreboot source code directory -could be used for multiple different mainboards so as to reduce waste of system -resources during the build process). - -For every board defined in `resources/coreboot/` a coreboot directory is created -from a `git clone` of the official coreboot Git repository hosted at - - -If the script fails to download from the above link, it will default to the -official backup repository hosted at - -If both downloads fail (usually this is because your internet is down or not -connected), the script will produce an error message and exit with non-zero -status. - -For each board, a dedicated coreboot source code directory is created, with -the `.git` files/directory from coreboot fully intact and: - -* The commit ID is reset to a known coreboot revision, as per what is specified - in `resources/coreboot/boardname/cbrevision` -* Coreboot submodules are downloaded by - running `git submodule update --init --checkout` in the coreboot build system. -* For each submodule, specified in `.gitmodules` under the coreboot build - system, the commit ID is reset to a known revision. This only applies to - submodules that exist under `3rdparty/` in the coreboot build system, but - a script named `extra.sh` can be supplied - in `resources/coreboot/boardname/extra.sh` which you can make do whatever you - want, including resetting commit IDs in other submodules not located - at `3rdparty/` under the coreboot build system. -* For submodules that coreboot downloads into `3rdparty/`, the revisions in - Libreboot's build system are specified - in `resources/coreboot/boardname/revision/` by files whose file name matches - the directory name of the submodule at `3rdparty/` (under the coreboot build - system) and which contain a single line specifying the intended commit ID for - use in the Git repository of that submodule (from the coreboot build system). -* Custom patches located in `resources/coreboot/boardname/patches/` are - applied on top of that coreboot revision. This is useful for patches that - are not yet merged in coreboot, or patches that exist in newer versions that - you wish to use in an older version. -* Custom patches are only applied (automatically, by the Libreboot build - system) to coreboot itself, but you can handle this for coreboot submodules - by writing instructions in the `extra.sh` script located - at `resources/coreboot/boardname/extra.sh` -* The `extra.sh` script is mainly intended for custom functionality, as - a *plugin* to the Libreboot build system, when you wish to add such - functionality when it is not useful for other boards. In cases where such - functionality will benefit other boards, it should be implemented in the - main build system of Libreboot, rather than inside the `extra.sh` script. -* Optionally, you can include a file named `symlink` located - at `resources/coreboot/boardname/` containing a single line naming another - Libreboot board (per directory name in `resources/coreboot/`). If this file - is included, a separate coreboot directory will not be created for the given - board that includes the given board. Instead, a symlink will be created under - `coreboot/` pointing to the actual coreboot directory at `coreboot/otherboard` - where `otherboard` is the other board. In this setup, the following files are - ignored in `resources/coreboot/boardname/`: - * `cbrevision` (specify it in the `cbrevision` file for the other board) - * anything under `patches/` (place them in the `patches/` directory for the - other board instead, even if they aren't needed for that board) - * anything under `revision/` (place them in the `revision/` directory for - the other board instead) - * `extra.sh` (write instructions in the `extra.sh` script for the other - board instead, if you wish) - -resources/scripts/download/flashrom ------------------------------------ - -This script is executed when running the following command in the Libreboot -build system: - - ./download flashrom - -This downloads flashrom from the following Git repository: - - -The commit ID is reset to a known revision, typically a *tag* for the latest -stable release. - -The repository is then available under `flashrom/` in the Libreboot build -system. Everything is self-contained in the script; typically, upstream -flashrom is used and right now there are no custom patches in use, so nothing -exists in `resources/` for flashrom and such is not accounted for by the -download script. - -resources/scripts/download/grub -------------------------------- - -This script is executed when running the following command in the Libreboot -build system: - - ./download grub - -This downloads GNU GRUB from the following Git repository: - - -If that fails, the script defaults to this Git repository: - - -If the download fails for whatever reason, for both repository links, the -script will produce an error message and exit with non-zero status. - -The commit ID is then reset to a known revision. The resulting repository is -available at `grub/` in the Libreboot build system. Everything is -self-contained in the script, and currently no patches are applied. - -Since SeaBIOS is also included as an option in GRUB boot menus generated by -Libreboot, this script also runs the following command: - - ./download seabios - -resources/scripts/download/me\_cleaner --------------------------------------- - -This script is executed when running the following command in the Libreboot -build system: - - ./download me_cleaner - -The `me_cleaner` is downloaded from the official Git repository, hosted at - - -The commit ID is reset to a known revision. Everything is self-contained in -this download script. - -This utility is not currently used in the Libreboot build system, but a script -named `meclean` is included in the root of the Libreboot Git repository or -source code release archive. The script allows you to specify, as argument, as -many filenames as you would like and, then, the script will run me\_cleaner on -a batch of files specified. - -The `me_cleaner` strips out AMT, networking support and many other functions in -the Intel ME firmware, while also setting ME Alt Disable and a few other bits -in the Intel Flash Descriptor, on a dumped ROM containing the Intel ME, GbE -and Flash Descriptor. - -The `meclean` script automatically places the *neutered* Intel ME firmware -under `bin/neutered/filename.neutered` where `filename` was the original file -name(s) of the ROM dump(s) provided as argument(s) to the `meclean` script. - -Intel ME is, in its default state, a huge security threat and should never be -used. In the past, there was no real solution on most platforms that have it. -The Libreboot project *strongly* recommends that you use `me_cleaner`. It can -also be used on systems for which no coreboot support exists, so long as the -`me_cleaner` utility has support for the Intel ME version in use on that -machine. - -Basically, you dump (using SPI programmer device) the contents of boot flash -on your system. You run the dump through `me_cleaner` and it will produce a -heavily modified ROM. How heavily? A 6MiB Intel ME image is reduced to roughly -90KiB of code which merely handles initialization and power management on the -target platform. - -Read more about `me_cleaner` here: - - -NOTE: On some older systems with Intel ME, the firmware can be removed entirely -from the boot flash and a few bits can be set in the Intel Flash Descriptor to -disable the Intel ME in its entirety. For example, -[Libreboot](https://libreboot.org/) supports many GM45 based laptops such as -the ThinkPad X200, X200T, T400 and so on; those systems have Intel ME, but can -be re-configured to remove the Intel ME firmware and disable it (Libreboot does -exactly that). - -resources/scripts/download/memtest86plus ----------------------------------------- - -This script, using GNU Wget, downloads MemTest86+ and verifies the SHA512 -checksum of the file. It then extracts the archive (MemTest86+ project does not -host an official Git repository). - -It applies custom patches provided in `resources/memtest86plus/patch/` - -The resulting source code is available at `memtest86plus/` in the Libreboot -build system. - -resources/scripts/download/tianocore ------------------------------------- - -This script is executed when running `./download tianocore` in the Libreboot -build system. - -This script downloads Tianocore. It checks out the `coreboot_fb` branch in -MrChromebox's fork of Tianocore; this is a special fork with modifications that -make Tianocore work much better as a coreboot payload (MrChromebox himself -offers pre-compiled coreboot ROMs for several systems, using Tianocore, and -thus his project competes with Libreboot; he's a really good guy btw :) - -Tianocore is not downloaded to the main directory in the Libreboot build system. -This script assumes that coreboot is already downloaded, using -the `./download coreboot` command in Libreboot's build system. - -This script goes into `payloads/external/tianocore/` on the coreboot build -system. Coreboot's `Makefile` for Tianocore is heavily modified so that it: - -* Does not automatically download Tianocore. Such functionality is moved to - a specific command, called `make download` -* Does not re-build Tianocore every time - -Planned: fully de-couple the coreboot scripts, out of the coreboot file system -and, based on them, fully and properly integrate building and downloading of -Tianocore in the Libreboot build system. This also implies that Libreboot will -have its own toolchain (coreboot's crossgcc build scripts will be forked) -because Tianocore's build system is *extremely* temperamental. - -resources/scripts/download/seabios ----------------------------------- - -This script downloads SeaBIOS from the following Git repository: - - -If the download fails, the script produces an error message and exits with -non-zero status. - -The script resets SeaBIOS to a known revision, and does not currently apply -custom patches on top of SeaBIOS. - -resources/seabios/config/ -------------------------- - -### resources/seabios/config/libgfxinit - -This is the configuration used for SeaBIOS on coreboot configurations where -libgfxinit is used. In this configuration, SeaBIOS also compiles SeaVGABIOS. - -SeaVGABIOS is a special option ROM that emulates a Video BIOS, for legacy VGA -support, but in fact uses the coreboot framebuffer, on configurations where -coreboot does its own native video initialization. - -At present, SeaVGABIOS does not fully support INT10H video interrupts and does -not properly support mode switching. For example, DOS games (in FreeDOS) will -not work. However, SeaVGABIOS supports just enough functionality that, when -coreboot starts in high resolution VESA frame buffer mode, ISOLINUX and SYSLINUX -bootloader menus will display properly (which makes dealing with GNU+Linux -distributions much easier). BSD bootloader menus will probably also display -correctly with this configuration. - -### resources/seabios/config/vgarom - -This is the configuration used for SeaBIOS on coreboot configurations where -a PCI Option ROM is included in the coreboot ROM, for VGA support. This is used -in situations where native video initialization in coreboot is not used and/or -unavailable. The PCI Option ROM is, in this configuration, usually supplied by -the manufacturer of the video chipset; it is usually extracted from a dump of -the original vendor firmware, before coreboot is installed. - -Occasionally, this Video BIOS ROM is extracted from memory on a running system. - -Occasionally, this Video BIOS ROM is extracted (dumped) from an add-on -PCI/PCI-E video card. Normally, SeaBIOS will extract this at boot time but in -some situations you will want coreboot to execute it, like when using another -payload such as GNU GRUB.