From b2b2b7a95698b1591b3fa945a27aefdca60f82eb Mon Sep 17 00:00:00 2001 From: Leah Rowe Date: Sun, 26 May 2024 15:39:50 +0100 Subject: [PATCH] update docs/maintain/ Signed-off-by: Leah Rowe --- site/docs/maintain/index.md | 285 ++++++++++-------------------------- site/tasks/index.md | 15 ++ 2 files changed, 95 insertions(+), 205 deletions(-) diff --git a/site/docs/maintain/index.md b/site/docs/maintain/index.md index 69a1aba..34d5825 100644 --- a/site/docs/maintain/index.md +++ b/site/docs/maintain/index.md @@ -88,39 +88,27 @@ project that Libreboot imports, such as coreboot. Environmental variables ======================= -LBMK\_THREADS +XBMK\_THREADS ------------- For example: - export LBMK_THREADS=2 + export XBMK_THREADS=2 This would build on two threads, when running lbmk. It defaults to 1. Previous revisions of lbmk used `nproc` by default, but this was set to 1 instead, because nproc is not available on every operating system. -LBMK\_STATUS ------------- - -By default, the user is asked to confirm when building for a given mainboard, -if that mainboard is not marked *stable* in `target.cfg`. To disable such -dialogs, do this: - - export LBMK_STATUS=n - -LBMK\_RELEASE +XBMK\_RELEASE ------------- -If set to `y`, it signals to `script/build/roms` that a release is being built, +If set to `y`, it signals to `script/roms` that a release is being built, and it will honour `release="n"` in target.cfg files. You could also set this yourself, when doing regular builds, if you wanted to test how `./build roms` behaves running it in release mode. Do this if you want to: - export LBMK_RELEASE=y - -This has a similar effect compared to `LBMK_STATUS="y"` but you probably don't -need to use this option yourself. + export XBMK_RELEASE=y Projects/files downloaded/generated by lbmk =========================================== @@ -193,7 +181,7 @@ visit: - the handling of this, in Libreboot, is based largely on the information there. This contains the Intel MRC firmware, auto-downloaded during build -by `script/vendor/download`. +by logic contained under `include/vendor.sh`. In some cases, libre MRC firmware is also available, and provided by Libreboot as an alternative choice. @@ -208,7 +196,7 @@ currently only initialises Intel GPUs natively, on Libreboot systems. release/ --------------- -The script at `script/update/release` create tarballs in here, which +The script at `build` create tarballs in here, which constitute regular Libreboot releases. It is meticulously maintained, as per current lbmk behaviour, and executed so as to provide Libreboot release archives. @@ -218,6 +206,26 @@ containing non-redistributable vendor code are *scrubbed* such that these files in regular releases, be [re-added manually](../install/ivy_has_common.md) by the user. +You can create release archives by doing: + + ./update release + +By default, this creates a release under `release/`, but you can change the +directory, for example: + + ./update release -d path + +You can also specify that only a *source archive* be created, like so: + + ./update release -m src + +Or with a custom directory: + + ./update release -d path -m src + +The build system expects there to be a *git tag*, so make sure there is one. +This is used to create the version number for a given release. + src/ ---- @@ -290,23 +298,6 @@ GRUB image under `elf/grub/`. NOTE: This is *only* provided for x86 machines, in Libreboot. For ARM, we ship U-Boot instead. -src/me\_cleaner/ ---------------- - -Please also visit: - -This is used by Libreboot, to *neuter* Intel ME images. The intel ME images -are auto-downloaded from the vendor during each build process, cached on -disk and processed by `me_cleaner`. It removes almost all code from Intel ME, -leaving only the basic bringup code (analogous to running coreboot without a -payload). More information available at these pages: - -* -* Libreboot [freedom status page](../../freedom-status.md) - -The *vendor file* scripts are what handle this, specifically the download script -located at `script/vendor/download`. - src/memtest86plus/ --------------- @@ -347,7 +338,7 @@ src/uefitool/ Please also visit: This is compiled, so as to provide `UEFIExtract`. Currently used by the -vendor download script at `script/vendor/download`, to download SCH5545 EC +vendor download logic within `include/vendor.sh`, to download SCH5545 EC firmware (used for fan control on Dell Precision T1650). src/pico-serprog @@ -411,9 +402,6 @@ desirable, `lbmk.git` provides a few utilities as part of itself, namely: util/dell-flash-unlock/ --------------- -**NOTE (15 October 2023): The util is now called `dell-flash-unlock`, but it -was previously called `e6400-flash-unlock`. Links have been updated.** - This program, written by Nicholas Chin, unlocks the boot flash on Dell Latitude E6400; it permits internal flashing, from factory firmware to Libreboot, so that the user need not disassemble and flash externally. @@ -498,6 +486,25 @@ config/ This directory contains configuration files, used by the Libreboot build system. These next sections will cover specific configuration files. +config/PROJECT\*/nuke.list +-------------------------- + +The script `include/git.sh` handles deletion of certain files, for downloaded +projects, based on a `nuke.list` file that can (for single-tree projects) be +included at `config/PROJECT/nuke.list` or (multi-tree project) +at `config/PROJECT/TREE/nuke.list` (entries are relative links from the root +directory of the given source tree e.g. `src/coreboot/default/`). + +So, if `src/coreboot/default/` contained foo/bar.txt, you could add to +the `nuke.list` file as follows: + +``` +foo/bar.txt +``` + +Ditto `src/flashprog/`, if you wanted to delete a file from in there, as one +other example. Deletions occur when the source tree is created. + config/vendor/ --------------- @@ -526,7 +533,7 @@ When a given coreboot tree is compiled, for a given target, this file defines which files to copy from the coreboot directory, which are then copied to a location under `elf/coreboot`. -The presence of this file affects behaviour in `script/update/release`; +The presence of this file affects behaviour in `./update release` commands; specifically, PROJECT is then downloaded to `src/PROJECT/PROJECT`, and files under `config/PROJECT/TARGET/target.cfg` define which tree to use, which then looks under `config/PROJECT/TREE/target.cfg` to get the git revision; then @@ -579,7 +586,6 @@ as: * `grub_scan_disk="ata"` * `uboot_config=default` (specify which U-Boot tree to use) * `release="n"` (example entry) -* `status=stable` (example entry) * `xtree="default"` (example entry) * `tree_depend="default"` (example entry) @@ -633,19 +639,11 @@ on a ThinkPad X60 with the optical drive may cause GRUB to hang, so on that machine it is advisable to set this option to `ahci` (becuse the default HDD slot is AHCI). -The `release` variable can be set to n, which makes the `script/update/release` -script skip that target, when creating release images. For example, a given +The `release` variable can be set to n, which makes the `./update release` +call skip that target, when creating release images. For example, a given board may not be stable and you don't want images for it to be included in the release. -The `status` variable can be set to whatever you want, but anything other -than `stable` will make `script/build/roms` ask for y/n confirmation if -not building images using `script/update/release`. - -Recommended strings for `status` could be: `stable`, `unstable`, `broken` -or `untested`. Alternatively, you might state `wip`. You can set whatever -string you want here. - The `xtree` option specifies that a given tree with use a specific coreboot tree for compiling crossgcc. This can be used to skip building gcc if OK on a given board; two trees may use the same crossgcc as each other. @@ -653,13 +651,6 @@ a given board; two trees may use the same crossgcc as each other. The `tree_depend` option means that a given tree needs another tree, defined by this variable, to also be present. -### config/coreboot/BOARDNAME/warn.txt - -Additionally: the `warn.txt` file can be included alongside target.cfg, to -provide warning of any potential issues or quirks. For example, raminit may -only be reliable with certain modules. This is printed on the user's terminal -when building that target. - ### config/coreboot/BOARDNAME/config/ Files in this directory are *coreboot* configuration files. @@ -1071,44 +1062,37 @@ Scripts in root directory of lbmk build --------------- -This is the main script in lbmk, Libreboot's build system. It is what executes -all other parts of the Libreboot build system. The rules are as follows: +This is the main script. Symlinks `vendor` and `update` also point to it. -* Argument zero, representing the name of the symlink, will be used to - execute `script/LINKNAME/COMMAND` - for example: `./build roms all` - would execute `script/build/roms all` in `sh`. -* In the above example, `LINKNAME` could also be `vendor`. In examples below, - symlinks are described pointing to `build` (the actual script). The script - works by checking argument zero, so it would look in a different directory - under `script/` matching `LINKNAME` - in this case, `script/vendor/` -* `TMPDIR` is exclicitly set, providing a constant location where temporary - files and directories can be made. `TMPDIR` is exported by the parent to - all children; for example, `./build roms all` would export it - to `script/build/roms`, and then anything called by *that* will also - inherit it - the main parent process running `lbmk` will then clean up this - `TMPDIR` directory upon any exit. -* All exits from lbmk are handled by this script. *All* exits, zero or non-zero, - are engineered such that *this* script, in the parent process (the very first - instance) is what ultimately exits back to the user's shell prompt. -* This script is programmed to *exit* with non-zero status, when run as root, - unless the `./build dependencies *` commands are used, - referencing files under `config/dependencies/` -* Under fault conditions, each child process shall output to stderr, and the - main parent process running `lbmk` will output the final error message. +Take any given file under `script/` and you can do: -tl;dr break this script and you *break Libreboot*. + ./build file # (THIS IS NOT A VALID COMMAND) -update ---------------- +For example: -Symbolic link, pointing to the `build` script. This is executed by the user, or -by lbmk, referencing scripts under `script/update/`. + ./build roms + ./update trees -vendor ---------------- +Special commands available (not provided by files under `script/`): -Symbolic link, pointing to the `build` script. This is executed by the user, or -by lbmk, referincing scripts under `script/vendor/` + ./update release + ./vendor download + ./vendor inject + +The `vendor` commands are handled by the `build` script, calling functions +inside `include/vendor.sh`, and the `./update release` logic is handled +directly by the `build` script. + +More information about `./vendor` commands can be found +here: [inserting vendor files](../install/ivy_has_internal.md) + +Information about `./update release` is written elsewhere on this page. + +You can also know what build system revision you have by running: + + ./build version + +This script is the beating heart of Libreboot. Break it and you break Libreboot. include/ =============== @@ -1143,14 +1127,9 @@ it is provided as an include to bypass license incompatibility. It has been heavily modified to use the same style of logic and general control flow used in the script at `script/vendor/download`, and it is used from there. -include/option.sh +include/lib.sh --------------- -Functions used by scripts under `script/vendor/`, for checking defconfig -files. These files are checked because the scripts need to know whether a given -file is used; if it is, a path is then specified in defconfig, telling the vendor -script either where it is, or where it should be downloaded to. - Several other parts of lbmk also use this file. It is added to as little as possible, and contains miscallaneous functions that don't belong anywhere else. @@ -1171,20 +1150,8 @@ return an error state. script/ ======= -*All* scripts under `script/` are executed only by the main `lbmk` script, -conforming to the standard `buildpath/option` e.g. `build/roms` - so, -running `./build roms` would run `script/build/roms`. - -script/build/ ---------------- - -These are highly specialised build scripts, written for specific tasks, almost -entirely in the context of building firmware images themselves, but some utils -are also handled. - -The scripts that create release archives are also located under this directory. - -### script/build/roms +script/roms +----------- This builds coreboot ROM images. @@ -1226,28 +1193,6 @@ It creates ROM images with GRUB, SeaBIOS, U-Boot, optionally with Memtest86+ also included, in various separate configurations in many different ROM images for user installation. -The `romtype` entry in `target.cfg` tells this script what to do with the ROM, -after it has been built. Currently, it operates based on these possible values -for `romtype`: - -* `d8d16sas` will cause *fake* (empty) files named `pci1000,0072.rom` - and `pci1000,3050.rom` to be inserted in CBFS. This prevents SeaBIOS from - loading or executing the option ROM stored on PIKE2008 modules, present on - certain configurations with the ASUS KCMA-D8 or KGPE-D16 mainboards. Those - option ROMs cause the system to hang, so they should never be executed (this - means however that booting Linux kernels from SAS devices is impossible on - those boards, unless a Linux payload is used; Linux can use those SAS drives, - without relying on the PIKE2008 option ROMs). When SeaBIOS runs, it will - default to loading the corresponding option ROM from CBFS, if it exists, for - a given PCI device, overriding whatever option ROM is present on the device - itself, but if the option ROM is invalid/empty, SeaBIOS will not attempt to - load another one, until the empty/invalid one (in CBFS) is deleted. -* `i945 laptop`: in this configuration, the upper 64KB section of the ROM is - copied into the 64KB section below that. This results in there being two - bootblocks in the ROM, and you can decide which one is used by setting `bucts` -* If no declaration is made, or a declaration is made contrary to the above, - no special modifications will be made. - If no payload is defined in `target.cfg`, the `build/roms` script will exit with error status. @@ -1293,44 +1238,8 @@ The `list` argument is available: Without arguments, all targets would be compiled, but you can specify a short list of targets instead, based on the output of `list`. -script/update/ --------------- - -This handles most actual building of source trees, called into by scripts -under `script/build/fw` - it also contains logic for downloading source trees -or vendor files. - -### script/update/release - -This script builds the release archives, which are then provided in a new -Libreboot release. Most users do not need to look at this file at all, but it -is provided under free license for curious souls. - -Command: `./update release` - -NOTE: if the `-d` option is used, you can specify a directory other -than `release`. For example: - - ./update release -d /media/stuff/libreboot_release_test - -If `-d` is not passed, they will go under `release/` in your lbmk repository. -The script is engineered to re-initialise git if ran from a release archive. -Libreboot releases after 20230625 include `.gitignore` in the src archive. - -This builds release archives, containing ROM images for coreboot and/or serprog -programmers. It works simply: lbmk clones *itself*, and builds itself in its -clone, then cleans itself up and creates tarballs. If you run this script, you -should expect it to take at least 4 hours; slower on really old systems. On -really fast systems, it might take 2-3 hours. - -NOTE: This script *scrubs* certain vendor firmware from release ROMs, such as -Intel ME or MRC firmware. The release ROMs shall then exclude these files -within them, requiring manual insertion by the user post-release. See: - -[Insert vendor files -on Sandybridge/Ivybridge/Haswell](../install/ivy_has_common.md) - -### script/update/trees +script/trees +------------ *This* is the other beating heart of Libreboot. Used heavily by Libreboot, this script is what handles defconfig files for SeaBIOS, U-Boot *and* coreboot; it @@ -1450,37 +1359,3 @@ All of this used to about 20 different scripts, all with much-duplicated logic. Now it is unified, efficiently, under a single script. Remember: code equals bugs, so less code equals fewer bugs. - -script/vendor/ --------------- - -### script/vendor/download - -This downloads vendor code when needed, on a given coreboot target. It does -this by scanning the defconfig files of that board, to know where the files -are (or where they should be) within lbmk. Based on this, it then knows which -files to download. - -These files are then inserted at build time by the coreboot build system (as -defined by defconfigs), or post-release by running the `inject` script. - -It looks inside `config/vendor/` at the files in there, concatenating them and -then scanning that to find info about the given board; for example, info like -where to download a Lenovo BIOS updater to extract `me.bin` from, to run through -the `me_cleaner` program. - -More information is available [here](../install/ivy_has_common.md). - -This script is executed automatically, when you compile ROM images, if the given -mainboard requires vendor code to be inserted. In this way, you do not need to -manually extract such files from your original vendor image. - -### script/vendor/inject - -This is not used during the build process, but it can be run by the user on -release ROMs (which do not contain non-redistributable code handled by these -vendor scripts, even if they are required). This script inserts those files -into the coreboot ROM image; if you're building from source, using lbmk, you -do not need to run the inject script at all. - -More information is available [here](../install/ivy_has_common.md). diff --git a/site/tasks/index.md b/site/tasks/index.md index 8c31704..891bd8c 100644 --- a/site/tasks/index.md +++ b/site/tasks/index.md @@ -2214,3 +2214,18 @@ ec hacking on lenovo x230 ========================= + +DELL 7th gen +============ + + +3050 micro is being worked on. + +3050 sff and mt are TODO + +5050 models also. + +Dell 3020 +========= + +another haswell. different to 9020, but could be added.