From b9a58b798444c4e510f4b0c54f8df5d79efb29c6 Mon Sep 17 00:00:00 2001 From: Leah Rowe Date: Fri, 10 May 2024 05:09:49 +0100 Subject: [PATCH] update docs/maintain/index.md Signed-off-by: Leah Rowe --- site/docs/maintain/index.md | 86 ++++++++++++++++++++++++------------- 1 file changed, 55 insertions(+), 31 deletions(-) diff --git a/site/docs/maintain/index.md b/site/docs/maintain/index.md index 38c0ff3..88ef36a 100644 --- a/site/docs/maintain/index.md +++ b/site/docs/maintain/index.md @@ -162,8 +162,8 @@ This directory is created when running any of the following commands, with the right arguments: ./build roms ARGUMENTS_HERE - ./build serprog stm32 - ./build serprog rp2040 + ./build roms serprog stm32 + ./build roms serprog rp2040 Simply speaking, `bin/` shall contain finished ROM images or firmware, that can then be installed (flashed) to the target device. @@ -473,9 +473,8 @@ This file can contain several configuration lines, each being a string, such as: * `tree="default"` (example entry) -* `romtype="normal"` (example entry) * `rev="ad983eeec76ecdb2aff4fb47baeee95ade012225"` (example entry) -* `arch="x86_64"` (example entry) +* `xarch="i386-elf"` (example entry) * `payload_grub="y"` (example entry) * `payload_grub_withseabios="y"` (example entry) * `payload_seabios="y"` (example entry) @@ -485,24 +484,23 @@ as: * `payload_seabios_grubonly="y"` (example entry) * `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) The `tree` value refers to `config/coreboot/TREE`; in other words, a given target could specify a name other than its own as the tree; it would then re-use code from that tree, rather than providing its own. -The `romtype` entry is used during the building of ROM images, to define -special steps; for example, d8d16sas` would tell cbmk that a fake PIKE2008 -ROM must be inserted into CBFS (prevents hanging on SeaBIOS). - The `rev` entry defines which coreboot revision to use, from the coreboot Git repository. *At present, cbmk only supports use of the official repository from the upstream coreboot 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.* +The `xarch` entry specifies which CPU architecture is to be used: currently +recognized entries are `i386-elf`, `arm-eabi` and `aarch64-elf`. This is the +target architecture for building GCC/toolchain from coreboot crossgcc, +hence `xarch`. The `payload_grub` entry specifies whether or not GRUB is to be included in ROM images. @@ -541,6 +539,33 @@ 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 +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. + +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. @@ -1013,32 +1038,31 @@ This entire file is heavily inspired by `err.h` in BSD libc code. This file is heavily used by cbmk (it's used by every script), to provide clean error handling in `sh`. -include/git.sh --------------- - -These functions in here previously existed as independent scripts, but they -were unified here, and they are used when you pass the `-f` argument -to `script/update/trees` (e.g. `./update trees -f coreboot`). - -These functions deal with git cloning, submodule updates, revision resets and -the application of patch files via `git am`. *Every* git repository downloaded -by cbmk is handled by the functions in this file. - -This script also handles deletion of binary blobs, for downloaded projects, -based on a `blobs.list` file that can (for single-tree projects) be included -at `config/PROJECT/blobs.list` or (multi-tree project) -at `config/PROJECT/TREE/blobs.list`. Learn more about how de-blobbing is -handled by reading the [about page](../../about.md). - include/option.sh --------------- -Several other parts of cbmk will use this file. It is added to as little as +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 cbmk also use this file. It is added to as little as possible, and contains miscallaneous functions that don't belong anywhere else. The functions here are mostly those that deal with configuration files; scanning them to set variables and so on. +This file also contains generic error handling, used by all cbmk scripts. + +This also contains functions to verify the current canoeboot version, and check +whether Git is properly initialised on the host system. It also contains +the `setvars` function, which provides a shorthand way of initialising many +variables (combined with use of `eval`), which cbmk uses heavily. + +This function also contains `x_()` which cbmk uses to execute commands +and ensure that they cause an exit (with non-zero status) from cbmk, if they +return an error state. + script/ =======