libreboot
/
lbwww
1
0
Fork 0
Code Packages Projects Releases Activity

update docs/maintain/ 

Signed-off-by: Leah Rowe <info@minifree.org>
master
Leah Rowe 2024-05-26 15:39:50 +01:00
parent 15f0b41108
commit b2b2b7a956
2 changed files with 95 additions and 205 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

285
site/docs/maintain/index.md
View File

@ -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: <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`
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).

15
site/tasks/index.md
View File

@ -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.