update docs/maintain/

Signed-off-by: Leah Rowe <info@minifree.org>

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
+XBMK\_RELEASE
-------------
-
-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
 -------------
 
-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
+	export XBMK_RELEASE=y
-
-This has a similar effect compared to `LBMK_STATUS="y"` but you probably don't
-need to use this option yourself.
 
 Projects/files downloaded/generated by lbmk
 ===========================================
@@ -193,7 +181,7 @@ visit: <https://doc.coreboot.org/northbridge/intel/haswell/mrc.bin.html> - 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: <https://github.com/corna/me_cleaner/>
-
-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:
-
-* <https://github.com/corna/me_cleaner/>
-* 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: <https://github.com/LongSoft/UEFITool>
 
 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`
+The `release` variable can be set to n, which makes the `./update release`
-script skip that target, when creating release images. For example, a given
+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
+This is the main script. Symlinks `vendor` and `update` also point to it.
-all other parts of the Libreboot build system. The rules are as follows:
 
-* Argument zero, representing the name of the symlink, will be used to
+Take any given file under `script/` and you can do:
-  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.
 
-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
+	./build roms
-by lbmk, referencing scripts under `script/update/`.
+	./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
+	./update release
-by lbmk, referincing scripts under `script/vendor/`
+	./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,
+script/roms
-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
 
 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/
+script/trees
---------------
+------------
-
-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
 
 *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).

site/tasks/index.md

@@ -2214,3 +2214,18 @@ ec hacking on lenovo x230
 =========================
 
 <https://zmatt.net/unlocking-my-lenovo-laptop-part-2/>
+
+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.