From 2cb17e61dc4d6282010fa9f18ff8ca0ab9beca3d Mon Sep 17 00:00:00 2001 From: Leah Rowe Date: Mon, 10 Apr 2023 05:56:52 +0100 Subject: [PATCH] update docs/maintain/ --- site/contrib.md | 2 +- site/contrib.uk.md | 2 +- site/docs/maintain/index.md | 594 +++++++++++++++++++++++++++--------- 3 files changed, 457 insertions(+), 141 deletions(-) diff --git a/site/contrib.md b/site/contrib.md index b6b754c..76ac296 100644 --- a/site/contrib.md +++ b/site/contrib.md @@ -109,7 +109,7 @@ Alyssa Rosenzweig Switched the website to use markdown in lieu of handwritten HTML and custom PHP. **Former libreboot project maintainer (sysadmin for libreboot.org).** -Alyssa wrote the original static site generator (bash scripts converting +Alyssa wrote the original static site generator (shell scripts converting markdown to html, via pandoc) for libreboot.org. This static site generator has now been heavily modified and forked into a formal project, by Leah Rowe: diff --git a/site/contrib.uk.md b/site/contrib.uk.md index 3c06361..39a4db4 100644 --- a/site/contrib.uk.md +++ b/site/contrib.uk.md @@ -100,7 +100,7 @@ ARM Chromebook з підтримкою coreboot. Переключила веб-сайт на використання розмітки замість рукописного HTML та користувацького PHP. **Колишній супроводжувач проекту libreboot (системний адміністратор libreboot.org).** -Алісса написала оригінальний генератор статичних сайтів (скрипти bash, що перетворюють +Алісса написала оригінальний генератор статичних сайтів (скрипти `sh`, що перетворюють markdown в html, через pandoc) для libreboot.org. Цей генератор статичних сайтів був значно змінений і відгалужений Лією Роу у формальний проект: diff --git a/site/docs/maintain/index.md b/site/docs/maintain/index.md index 10ed278..c61c3c4 100644 --- a/site/docs/maintain/index.md +++ b/site/docs/maintain/index.md @@ -160,12 +160,76 @@ implementing the `lbmk` build system. All sections below pertain to actual files in lbmk: +.gitcheck +========= + +This checks whether Git credentials are set, and sets placeholder credentials +if required, locally for the given project. + +If something went wrong during build, these placeholder credentials will still +be in effect, but only within `lbmk`. You can unset them like so: + + ./.gitcheck Clean + +This is important, when working on Libreboot. Ordinarily, temporary credentials +are cleared after running lbmk, but may not be cleared in error conditions. + +A bit of a hack, but it avoids build issues when the user hasn't set a name +and email address in Git. If you've set a *global* one, then this script is +irrelevant. + +NOTE: In a git repository, the directory `.git` and files like `.gitignore` +or `.gitmodules` are used by the Git software. The name of this script begins +with `.git`, but the Git software does not make use of this file. It is +a *shell script*, executed by lbmk when you run commands in it. + +More context about Git name/email can be found in +the [Libreboot build instructions](../build/). + +.git +==== + +Metadata used by git-scm, the version control system that Libreboot uses for +development. This directory will be present in the Git repository. It is not +provided in Libreboot *releases*. Learn more about Git here: + + + +.gitignore +========== + +This file is used by Git. It tells Git to *ignore* certain files, so that they +do not get added accidentally to commits for the Libreboot Git repository, +named `lbmk.git`. + +You can learn more about `.gitignore` files here: + + + COPYING ======= This file contains a copy of the GNU General Public License, version 3.0. It is the license that most parts of `lbmk` are released under. +NOTE: Not all of Libreboot is released under this license, but it is heavily +used in the Libreboot *build system*. Much of coreboot is GPL version 2 and +in some cases, other licenses (such as BSD-style licenses) are used. This is +inevitable, with Libreboot being an *aggregate distribution* of software, +namely coreboot and *payloads*, plus utilities. + +Including a `COPYING` file is a good, conservative first step in adhering +to *good practise* when it comes to software, and it is *mostly* technically +correct in the context of *lbmk*, because *most* of lbmk is under GPLv3. This +is a legacy from when Libreboot started, where that license was chosen, and +it has just been *de facto* standard for Libreboot (build system) ever since. + +You should perform an audit, to learn more about other licenses. This can be +done by inspecting the various projects that lbmk makes use of, like coreboot. +For aggregate distributions such as coreboot distributions or Linux distros, +it's not trivial to keep track of every license in a simple way, so such an +audit is inevitable if you want to know more. + Makefile ======== @@ -176,16 +240,59 @@ Use of this file is purely optional, and largely beneficial if you simply want to build all of `lbmk` (just run `make` when the current work directory is the root directory of `lbmk`). -README.md -========= +README*.*md +=========== This file contains a brief description of libreboot, along with information about the project +It's basically a copy of the homepage text, relative to libreboot.org. + +blobs/ +====== + +This directory contains binary blobs, presently only GbE and IFD files which +are non-software blobs; they are binary-encoded configuration files. + +The IFD files are *Intel Flash Descriptors* configuring the machine, on Intel +machines that use flash descriptors, and the GbE files are configs for Intel +gigabit ethernet. You can read more about these on +the [freedom status page](../../freedom-status.md) - the `ifdtool` +and `nvmutil` programs interact with these (nvmutil is provided by Libreboot, +and ifdtool is supplied by the upstream coreboot project). + +When `blobutil` is running, it will place temporary files here, extracting +binary blobs such as Intel ME firmware, for running through `me_cleaner`. + +At present, only the GbE and IFD files are included here for Libreboot +releases, but other files such as `me.bin` are stored here during the build +process (auto-downloaded and processed through `me_cleaner` on boards that +need them). + +NOTE: Other blobs such as EC firmware and Intel MRC are *not* placed here, by +lbmk. + +blobutil +======== + +This script is responsible for downloading, extracting and inserting binary +blobs that are required on specific machines for coreboot. This is done +automatically, during the build process, but `blobutil` can also be used as +a standalone program, for *release* ROM images (many of which will have certain +blobs like Intel ME *scrubbed*, where the user is expected to insert them). + +You can read more about this on the page: [Inserting binary blobs +on Sandybridge/Ivybridge/Haswell](../install/ivy_has_common.md) + +NOTE: This utility may be expanded in future Libreboot revisions, to handle +things such as EC firmware, and it may expand to other platforms. It is, at +present, only utilised for handling ROM images on Intel Sandybridge, Ivybridge +and Haswell platforms. + build ===== -This is the main BASH script, part of `lbmk`, used for running most `lbmk` +This is the main shell script, part of `lbmk`, used for running most `lbmk` commands. You could say that this file *is* `lbmk`. Run `./build help` for usage instructions. @@ -226,7 +333,7 @@ You may also refer to the [build instructions](../build) download ======== -This is the main BASH script for downloading various components used by `lbmk`. +This is the main shell script for downloading various components used by `lbmk`. For example, this script downloads coreboot. Scripts called by `download` may also apply patches and such, to the corresponding project; for example, it will apply custom patches to GRUB. @@ -251,6 +358,23 @@ For a full list of all `download` commands, run: ./download help +*Most* download modules are defined in `resources/git/revisions`, showing the +link to git repositories and info about revisions, for each given project. +More on this is available in the page you're reading now (keep reading). + +gitclone +======== + +This script is used by the `download` script, specifically for cloning of +Git repositories, for certain projects as defined in the file at location, +path `resources/git/revisions` within lbmk. + +It downloads a project, from a main Git repository or a backup if defined and +the main one is down. It then resets to a defined revision (commit ID). If +patches are supplied for that project, by lbmk, then those patches are applied. +The patches are applied as per: ascending, alphanumerical order of patch file +name. + modify ====== @@ -271,6 +395,8 @@ This would run: ./resources/scripts/modify/coreboot/configs x200_8mb x60 +If you run it without arguments, help text is shown. + projectname =========== @@ -280,6 +406,54 @@ If you were to fork libreboot, you could very easily just modify this file, so as to rename your fork in a largely automated way. Many parts of lbmk use this file. +resources/blobs/ +================ + +This directory contains ME7 Update Parser, and a file defining links to vendor +update files, from which Intel ME images are extracted, to be neutered +via `me_cleaner`. + +resources/blobs/me7\_update\_parser.py +====================================== + +This is a special fork of `me_cleaner`, specifically for parsing and neutering +Intel ME images provided by Lenovo for ThinkPad X220 and other Lenovo +ThinkPads of Intel SandyBridge platform. You can find information about this +on the original repository: + + + +ME7 Update Parser was originally written for *Heads*, another coreboot distro +very similar to Libreboot that provides coreboot build automation with Linux +based payload configurations. *Their* build system auto-downloads and +auto-neuters Intel ME images, during build, so that the user does not have to +manually extract such images from dumps of the original vendor firmware (in +the flash) on a given machine. + +Such logic was ported to Libreboot, courtesy of `shmalebx9` as mentioned +on the [who page](../../who.md) - Caleb is a core developer in the Libreboot +project. + +resources/blobs/sources +======================= + +URLs and hashes for vendor files containing Intel ME images within them. Where +feasible, backup URLs are also provided. SHA1 checksums are defined, so that +lbmk can verify the integrity of downloaded files. + +When building for sandybridge, ivybridge and haswell machines, Libreboot's +bulid system automatically downloads such updates from the vendor, to extract +the Intel ME image and neuter it with `me_cleaner` or `me7_update_parser.py`. + +Such auto-download logic was ported from the *Heads* build system, to be used +in the *Libreboot* build system. It is the bee's knees, because it prevents +the need for manual extraction of Intel ME images from vendor dumps. It means +that you can just *build Libreboot* (from `lbmk`) and then just flash the +resulting image, without having to worry. + +Of course, backing up the original firmware is still a good idea, before +installing Libreboot or any other spin of coreboot. + resources/coreboot/ =================== @@ -518,136 +692,17 @@ for instance, and `lbmk` will not erroneously try to apply `README` as though it were a patch file. This might be useful if you have a *lot* of patches, and you want to provide some explanations about specific files. -resources/u-boot/ -================= +resources/git/revisions +======================= -This directory contains configuration, patches and so on, for each mainboard -that can use U-Boot as a payload in the `lbmk` build system. U-Boot doesn't yet -have reliable generic configurations that can work across all coreboot boards -(per-architecture), so these are used to build it per-board. +This defines git repositories and commit IDs (revisions) to reset to, for +various projects used by Libreboot. *This* file is used, for projects that +are relatively simple to handle when downloading (coreboot is not defined +here). -resources/u-boot/BOARDNAME/ -=========================== - -Each `BOARDNAME` directory defines configuration for a corresponding mainboard. -It doesn't actually have to be for a board; it can also be used to just define -a U-Boot revision, with patches and so on. To enable use as a payload in ROM -images, this must have the same name as its `resources/coreboot/BOARDNAME/` -counterpart. - -resources/u-boot/BOARDNAME/board.cfg -==================================== - -This file can contain several configuration lines, each being a string, such -as: - -* `ubtree="default"` (example entry) -* `ubrevision="4debc57a3da6c3f4d3f89a637e99206f4cea0a96"` (example entry) -* `arch="AArch64"` (example entry) - -These are similar in meaning to their coreboot counterparts. - -The `ubtree` entry is actually a link, where its value is a directory name -under `resources/u-boot`. For example, `ubtree="default"` would refer to -`resources/u-boot/default` and the corresponding U-Boot source tree created -(when running `./download u-boot`, which makes use of `board.cfg`) would be -`u-boot/default/`. In other words: a `board.cfg` file in `resources/u-boot/foo` -might refer to `resources/u-boot/bar` by specifying `ubtree="bar"`, and the -created u-boot source tree would be `u-boot/bar/`. ALSO: - -FUN FACT: such references are infinitely checked until resolved. For -example, `foo` can refer to `bar` and `bar` can refer to `baz` but if there is -an infinite loop, this is detected and handled by `lbmk`. For example, -if `bar` refers to `foo` which refers back to `bar`, this is not permitted -and will throw an error in `lbmk`. - -The `ubrevision` entry defines which U-Boot revision to use, from the U-Boot -Git repository. *At present, lbmk only supports use of the official repository -from the upstream U-Boot project*. - -The `arch` entry specifies which CPU architecture is to be used: currently -recognized entries are `x86_32`, `x86_64`, `ARMv7` and `AArch64`. *Setting it -to a non-native arch means that necessary crossgcc-arch will be compiled and be -available when building roms, but not necessarily built or discovered when -individual scripts are called manually.* - -resources/u-boot/BOARDNAME/config/\* -==================================== - -Files in this directory are *U-Boot* configuration files. Configuration file -names can be anything, but for now `default` is the only one used. - -In `lbmk`, a board-specific directory under `resources/u-boot/` should never -specify a U-Boot revision. Rather, a directory *without* U-Boot configs should -be created, specifying a U-Boot revision. For example, the directory -`resources/u-boot/default/` specifies a U-Boot revision. In the board-specific -directory, your `board.cfg` could then specify `ubtree="default"` but without -specifying a U-Boot revision (this is specified by -`resources/u-boot/default/board.cfg`). - -Normally, the U-Boot build process results in the U-Boot executable and a -device-tree file for the target board, which must further be packaged together -to make things work. When you create a U-Boot configuration, you should enable -`CONFIG_REMAKE_ELF` or `CONFIG_OF_EMBED` that handles this. The former option -enables creation of a `u-boot.elf` that bundles them together after the build, -and the latter option embeds it into the `u-boot` executable. - -When making a U-Boot configuration, you should also pay special attention to -the `CONFIG_SYS_TEXT_BASE` (`CONFIG_TEXT_BASE` in later versions), whose defaults -may cause it to overlap coreboot, in which case it won't boot. Normally, the -upstream coreboot build system checks for this when given `CONFIG_PAYLOAD_ELF`, -but `lbmk` injects the payload itself and doesn't check for this yet. - -Another interesting config option is `CONFIG_POSITION_INDEPENDENT` for ARM -boards, which has been so far enabled in the ones `lbmk` supports, just to be -safe. - -U-Boot build system -------------------- - -If you wish to know about U-Boot, refer here:\ - - -This and other documents from U-Boot shall help you to understand *U-Boot*. - -You create a config, for `resources/u-boot/BOARDNAME/configs`, by finding the -corresponding board name in the upstream U-Boot `configs` directory, and -running `make BOARDNAME_defconfig` and `make menuconfig` commands in the -*U-Boot* build system. You should do this after running `./download u-boot` in -`lbmk`. - -You might want to consider basing your config on the upstream `coreboot` boards -when possible, but such a board is not available upstream for ARM yet. - -You can simply clone U-Boot upstream, add whatever patches you want, and -then you can make your config. It will appear afterwards in a file -named `.config` which is your config for inside `resources/u-boot/BOARDNAME/`. - -You can then use `git format-patch -nX` where `X` is however many patches you -added to that U-Boot tree. You can put them in the patches directory -under `resources/u-boot/BOARDNAME`. - -The *base* revision, upon which any custom patches you wrote are applied, -shall be the `ubrevision` entry. - -Scripts exist in `lbmk` for automating the modification/updating of *existing* -configs, but not for adding them. Adding them is to be done manually, based on -the above guidance. - -resources/u-boot/BOARDNAME/patches/\* -===================================== - -In cases where `ubrevision` is specified, where the given directory -under `resources/u-boot/` does in fact define a version of U-Boot to -download, you can add custom *patches* on top of that revision. When you run -the command `./download u-boot`, those patches will be applied chronologically -in alphanumerical order as per patch file names. - -The patch files should be named with `.patch` file extensions. All other files -will be ignored. By having `lbmk` do it this way, you could add a `README` file -for instance, and `lbmk` will not erroneously try to apply `README` as though -it were a patch file. This might be useful if you have a *lot* of patches, and -you want to provide some explanations about specific files. +In the past, Libreboot had bespoke logic for *each* program, to download it. +This was repetitive, so much of the download logic was centralised with the +use of the `gitclone` script, which references this file. resources/grub/background/ ========================== @@ -698,10 +753,64 @@ resources/grub/patches/ This directory contains custom patches for GRUB. -resources/memtest86plus/patch/ +resources/me\_cleaner/patches +============================= + +Patches applied to `me_cleaner` when downloading it. + +resources/memtest86plus/patches/ ============================== -This directory contains custom patches for Memtest86+. +Patches applied to Memtest86+ when downloading it. Libreboot includes +memtest86+ as a secondary payload, loaded from SeaBIOS *or* GRUB when booted +via int10h text mode on x86 hosts. + +(using it with corebootfb mode is also possible, if your machine has a viable +serial output on it with memtest86+ configured accordingly, and this was done +on some older Libreboot releases in the past, but current Libreboot releases +only provide memtest86+ in text mode, for use directly on the machine) + +resources/scripts/ +================== + +These scripts implement the *core* logic of Libreboot's *automated build +system*, to produce coreboot ROM images with payloads. + +resources/scripts/blobs/download +================================ + +Where certain binary blobs like Intel ME or MRC are needed on a given board, +this script is called automatically by the build system, to download the files +for insertion. + +resources/scripts/blobs/extract +=============================== + +Where auto-download is not viable, this script can provide a somewhat automated +experience for *extracting* blobs. You will supply a *dump* of the original +vendor firmware, dumped from the flash IC on whichever target machine you wish +to flash. + +Dumping the original firmware is *always* recommended, regardless of what you +want to do. + +resources/scripts/blobs/inject +============================== + +Where a blob is provided, via the `extract` or `download` method, *this* +script *inserts* a blob (ME, MRC etc) into a given target image. + +resources/scripts/build/ +======================== + +This directory contains shell scripts for compiling various binaries from +available sources. + +resources/scripts/build/boot/ +============================= + +This directory contains shell scripts for compiling ROM images. Many other +scripts in lbmk are called by these scripts; for example, GRUB payload scripts. resources/scripts/build/boot/roms ================================= @@ -720,6 +829,15 @@ example: ./build boot roms x60 x200_8mb +Since November 2022, this script can build images for x86 *and* ARM targets. +The *ARM* targets are ChromeOS devices (chromebooks and such); Libreboot uses +the *U-Boot* payload, rather than Google's *depthcharge* bootloader. In this +setup, U-Boot is running on the bare metal, as enabled by *coreboot*. + +For x86 targets, these scripts build with the GRUB and/or SeaBIOS payloads +inserted into the ROM images; secondary payloads like Memtest86+ are also +handled and inserted here. + resources/scripts/build/boot/roms\_helper ========================================= @@ -809,6 +927,8 @@ the default anyway) to enable *all* option ROMs, unless `vgarom` setups are used, in which case the option is set to *0* (disabled) because coreboot is then expected to handle option ROMs, and SeaBIOS should not do it. +This script handles U-Boot separately, for ARM-based chromeos devices. + Essentially, the `roms_helper` script makes use of each and every part of lbmk. It is the heart of libreboot. @@ -870,7 +990,7 @@ Command: `./build clean payloads` resources/scripts/build/clean/rom\_images ========================================= -This deletes the `bin/` directory. +This deletes the `bin/` directory, containing compiled coreboot ROM images. Command: `./build clean rom_images` @@ -1011,6 +1131,13 @@ on all coreboot source trees. Command: `./build release src` +NOTE: This script *scrubs* certain binary blobs from release ROMs, such as +Intel ME or MRC firmware. The release ROMs shall then exclude these blobs +within them, requiring manual insertion by the user post-release. See: + +[Insert binary blobs +on Sandybridge/Ivybridge/Haswell](../install/ivy_has_common.md) + resources/scripts/download/coreboot =================================== @@ -1042,12 +1169,13 @@ This downloads and patches GRUB. Command: `./download grub` -resources/scripts/download/ich9utils -==================================== +resources/scripts/download/me\_cleaner +====================================== -This downloads `ich9utils`, which includes `ich9gen`. +This downloads the `me_cleaner` program, for neutering Intel ME images. You +can read more about it here: -Command: `./download ich9utils` + resources/scripts/download/memtest86plus ======================================== @@ -1056,6 +1184,21 @@ This downloads and patches Memtest86+. Command: `./download memtest86plus` +resources/scripts/download/mrc +============================== + +Where required, this will download Intel MRC images. This is called +automatically by lbmk, on platforms that require it (currently only +Intel Haswell, where Libreboot-covered hardware is concerned, and a +libre replacement of `mrc.bin` exists on that platform, provided as +an option in Libreboot 20230319 or newer releases). + +This is a fork of *coreboot's* MRC image download script, which does +not guarantee specific versions of the file nor does it check SHA1 +hashes and such. It was forked for Libreboot purpose, because the +Libreboot build system *enforces* such verification during the build +process. + resources/scripts/download/seabios ================================== @@ -1172,6 +1315,12 @@ resources/seabios/config/vgarom This version is for normal SeaBIOS configurations, where `libgfxinit` is not to be used. +resources/seabios/patches/ +========================== + +This directory contains patch files, automatically applied to SeaBIOS after +downloading it. + update ====== @@ -1192,3 +1341,170 @@ This would run: ./resources/scripts/update/coreboot/configs x200_8mb x60 +resources/u-boot/ +================= + +This directory contains configuration, patches and so on, for each mainboard +that can use U-Boot as a payload in the `lbmk` build system. U-Boot doesn't yet +have reliable generic configurations that can work across all coreboot boards +(per-architecture), so these are used to build it per-board. + +resources/u-boot/BOARDNAME/ +=========================== + +Each `BOARDNAME` directory defines configuration for a corresponding mainboard. +It doesn't actually have to be for a board; it can also be used to just define +a U-Boot revision, with patches and so on. To enable use as a payload in ROM +images, this must have the same name as its `resources/coreboot/BOARDNAME/` +counterpart. + +resources/u-boot/BOARDNAME/board.cfg +==================================== + +This file can contain several configuration lines, each being a string, such +as: + +* `ubtree="default"` (example entry) +* `ubrevision="4debc57a3da6c3f4d3f89a637e99206f4cea0a96"` (example entry) +* `arch="AArch64"` (example entry) + +These are similar in meaning to their coreboot counterparts. + +The `ubtree` entry is actually a link, where its value is a directory name +under `resources/u-boot`. For example, `ubtree="default"` would refer to +`resources/u-boot/default` and the corresponding U-Boot source tree created +(when running `./download u-boot`, which makes use of `board.cfg`) would be +`u-boot/default/`. In other words: a `board.cfg` file in `resources/u-boot/foo` +might refer to `resources/u-boot/bar` by specifying `ubtree="bar"`, and the +created u-boot source tree would be `u-boot/bar/`. ALSO: + +FUN FACT: such references are infinitely checked until resolved. For +example, `foo` can refer to `bar` and `bar` can refer to `baz` but if there is +an infinite loop, this is detected and handled by `lbmk`. For example, +if `bar` refers to `foo` which refers back to `bar`, this is not permitted +and will throw an error in `lbmk`. + +The `ubrevision` entry defines which U-Boot revision to use, from the U-Boot +Git repository. *At present, lbmk only supports use of the official repository +from the upstream U-Boot project*. + +The `arch` entry specifies which CPU architecture is to be used: currently +recognized entries are `x86_32`, `x86_64`, `ARMv7` and `AArch64`. *Setting it +to a non-native arch means that necessary crossgcc-arch will be compiled and be +available when building roms, but not necessarily built or discovered when +individual scripts are called manually.* + +resources/u-boot/BOARDNAME/config/\* +==================================== + +Files in this directory are *U-Boot* configuration files. Configuration file +names can be anything, but for now `default` is the only one used. + +In `lbmk`, a board-specific directory under `resources/u-boot/` should never +specify a U-Boot revision. Rather, a directory *without* U-Boot configs should +be created, specifying a U-Boot revision. For example, the directory +`resources/u-boot/default/` specifies a U-Boot revision. In the board-specific +directory, your `board.cfg` could then specify `ubtree="default"` but without +specifying a U-Boot revision (this is specified by +`resources/u-boot/default/board.cfg`). + +Normally, the U-Boot build process results in the U-Boot executable and a +device-tree file for the target board, which must further be packaged together +to make things work. When you create a U-Boot configuration, you should enable +`CONFIG_REMAKE_ELF` or `CONFIG_OF_EMBED` that handles this. The former option +enables creation of a `u-boot.elf` that bundles them together after the build, +and the latter option embeds it into the `u-boot` executable. + +When making a U-Boot configuration, you should also pay special attention to +the `CONFIG_SYS_TEXT_BASE` (`CONFIG_TEXT_BASE` in later versions), whose defaults +may cause it to overlap coreboot, in which case it won't boot. Normally, the +upstream coreboot build system checks for this when given `CONFIG_PAYLOAD_ELF`, +but `lbmk` injects the payload itself and doesn't check for this yet. + +Another interesting config option is `CONFIG_POSITION_INDEPENDENT` for ARM +boards, which has been so far enabled in the ones `lbmk` supports, just to be +safe. + +U-Boot build system +------------------- + +If you wish to know about U-Boot, refer here:\ + + +This and other documents from U-Boot shall help you to understand *U-Boot*. + +You create a config, for `resources/u-boot/BOARDNAME/configs`, by finding the +corresponding board name in the upstream U-Boot `configs` directory, and +running `make BOARDNAME_defconfig` and `make menuconfig` commands in the +*U-Boot* build system. You should do this after running `./download u-boot` in +`lbmk`. + +You might want to consider basing your config on the upstream `coreboot` boards +when possible, but such a board is not available upstream for ARM yet. + +You can simply clone U-Boot upstream, add whatever patches you want, and +then you can make your config. It will appear afterwards in a file +named `.config` which is your config for inside `resources/u-boot/BOARDNAME/`. + +You can then use `git format-patch -nX` where `X` is however many patches you +added to that U-Boot tree. You can put them in the patches directory +under `resources/u-boot/BOARDNAME`. + +The *base* revision, upon which any custom patches you wrote are applied, +shall be the `ubrevision` entry. + +Scripts exist in `lbmk` for automating the modification/updating of *existing* +configs, but not for adding them. Adding them is to be done manually, based on +the above guidance. + +resources/u-boot/BOARDNAME/patches/\* +===================================== + +In cases where `ubrevision` is specified, where the given directory +under `resources/u-boot/` does in fact define a version of U-Boot to +download, you can add custom *patches* on top of that revision. When you run +the command `./download u-boot`, those patches will be applied chronologically +in alphanumerical order as per patch file names. + +The patch files should be named with `.patch` file extensions. All other files +will be ignored. By having `lbmk` do it this way, you could add a `README` file +for instance, and `lbmk` will not erroneously try to apply `README` as though +it were a patch file. This might be useful if you have a *lot* of patches, and +you want to provide some explanations about specific files. + +util/ +===== + +This directory contains utilities that `lbmk` makes use of. + +util/nvmutil/ +============= + +The `nvmutil` software allows you to set the MAC address on Intel GbE NVM +files. It also allows you to set *random* MAC addresses, in addition to +arbitrary ones. + +This directory contains the source code for `nvmutil`, which you can read +about here: + +[nvmutil manual](../install/nvmutil.md) + +util/ich9utils/ +=============== + +The `ich9utils` utilities handle ICH9M Flash Descriptors, and GbE NVM configs +for Intel Gigabit Ethernet chipsets used on certain laptops of Intel GM45 +platform, combined with ICH9M southbridge. + +This directory contains the source code for `ich9utils`, which you can read +about here: + +[ich9utils manual](../install/ich9utils.html) + +This source code also pertains to `ich9gen`, which is what GM45 laptops in +Libreboot use in order to generate a config that *excludes* Intel ME firmware. + +Patches welcome. + +If you read this manual from start to finish, you've been assimilated. Welcome +to the team!