libreboot / lbwww (public) (License: Unspecified) (since 2023-04-11) (hash sha1)
libreboot website (markdown files). https://libreboot.org/
Clone URLs: https://rocketgit.com/user/libreboot/lbwww ssh://rocketgit@ssh.rocketgit.com/user/libreboot/lbwww git://git.rocketgit.com/user/libreboot/lbwww
25.04 master
List of commits:
Subject Hash Author Date (UTC)
update docs/maintain/ c18402c8a7013e7811cd1994db1c51aa7017b504 Leah Rowe 2024-09-23 16:57:06
grub_cbfs: add -t raw to example cbfs command 025ac72aeeeee92698e05686ed5177f6763e3b7f Leah Rowe 2024-09-07 01:24:15
simplify docs/install and merge docs/hardware 09844d6258bd27026f53f9cdb731b4086c20fda3 Leah Rowe 2024-08-31 21:28:18
remove wrong info about 820 g2 2f1107f2ca852f154332046a871822663ca792ac Leah Rowe 2024-08-30 01:40:32
minor 820 g2 docs cleanup 2cf3d6911a46707ccd820d94194cbe4fc5af6148 Leah Rowe 2024-08-30 01:39:11
update the 820 g2 hp guide a6d33c415884f109b4b040e92bea2d31730f3704 Leah Rowe 2024-08-30 01:36:57
hp2560.md: remove note about wifi 002b0520f4b361e59b480fa971acfca3f73ea90b Leah Rowe 2024-08-30 00:47:04
clarify pre-install requirement for latitudes 406f9f03529764bf3a2011e08653b36b64310c84 Leah Rowe 2024-08-29 22:59:28
actually add latitude.md 1b938fa4147b6734c29ed8e83a65a319794a88ac Leah Rowe 2024-08-29 22:57:10
unified dell latitude instructions ac0e6833360bd9b0e7ccd51b07bd0c80ce5168da Leah Rowe 2024-08-29 22:54:48
update commands on the porting page 040a918adf09eac5ed119bcb7d721dbace29ff2f Leah Rowe 2024-08-29 21:21:02
add safety link on the e6400 news page 1687ff6e98205ce7f430fdc42e7089882903c2c0 Leah Rowe 2024-08-29 21:20:29
add safety link on the 20240612 page a2e2d85ca17e070f93a9d955c505034b08cc0deb Leah Rowe 2024-08-29 21:19:58
maintain/style: update err reference d450d080ffd70161feaa7734140378987c834d58 Leah Rowe 2024-08-29 20:11:48
ivy_has_common: explicitly mention latitudes 9909590362282181f8507320d0738171e9e270b1 Leah Rowe 2024-08-29 00:00:37
grammar feda02a728026e6e3dd92d0d957bbe4a4c433d0d Leah Rowe 2024-08-27 15:29:19
policy: re-add section saying why fsdg sucks e8aaa24fb8b747f790a26931d7ba669a5f30ec97 Leah Rowe 2024-08-27 15:27:19
add safety instructions on ivy_has_common 3c4f5d78e314e405cdb1215230c7ae9d490805e4 Leah Rowe 2024-08-27 03:12:07
shorten ivy_has_common.md 87fb10032cdd73a1880478c0467c92fd9c68f93a Leah Rowe 2024-08-27 03:06:28
complete cleanup of grub.cfg docs c50c0e16768ac5e62a3a4cb8d0f6455bf280afdd Leah Rowe 2024-08-27 00:38:53
Commit c18402c8a7013e7811cd1994db1c51aa7017b504 - update docs/maintain/
it was missing a few items, and some items were out of date,
based on changes in lbmk audit 6

Signed-off-by: Leah Rowe <info@minifree.org>
Author: Leah Rowe
Author date (UTC): 2024-09-23 16:57
Committer name: Leah Rowe
Committer date (UTC): 2024-09-23 16:57
Parent(s): 025ac72aeeeee92698e05686ed5177f6763e3b7f
Signer:
Signing key:
Signing status: N
Tree: d39b85ae3b0175a97953c3da7032ec12f5f7c9e1
File Lines added Lines deleted
site/docs/maintain/index.md 87 39
File site/docs/maintain/index.md changed (mode: 100644) (index 1cc4265..1ee07c8)
... ... hence `xarch`.
657 657 The `payload_grub` entry specifies whether or not GRUB is to be included in The `payload_grub` entry specifies whether or not GRUB is to be included in
658 658 ROM images. ROM images.
659 659
660 The `payload_grub_withseabios` entry specifies whether or not SeaBIOS is to
661 be included *with* GRUB, in ROM images. Turning this on also turns
662 on `payload_seabios_withgrub`, unless that option is explicitly turned off.
663
664 660 The `payload_seabios` entry specifies whether or not SeaBIOS is to be included The `payload_seabios` entry specifies whether or not SeaBIOS is to be included
665 in ROM images. This option is *automatically* enabled
666 if `payload_grub_withseabios` and/or `payload_seabios_withgrub` are also turned
667 on.
668
669 The `payload_seabios_grubonly` option, if enabled, creates separate ROM
670 images alongside regular `seabios_withgrub` ones, where the `grubonly` ones
671 start SeaBIOS but disable the menu and only ever load GRUB from CBFS, which
672 then provides the boot for your machine.
661 in ROM images. If GRUB is also enabled, standalone SeaBIOS images will be
662 created alongside SeaGRUB images. SeaGRUB is where SeaBIOS automatically
663 loads GRUB, via `bootorder` inserted into CBFS.
673 664
674 665 The `payload_memtest` entry specifies whether or not MemTest86+ is to be The `payload_memtest` entry specifies whether or not MemTest86+ is to be
675 666 included in ROM images; it will only be included in ROM images for *text mode* included in ROM images; it will only be included in ROM images for *text mode*
 
... ... of their own; for example, `config/grub/` exists.
812 803 Multiple files exist here, and they are *concatenated* in a temporary file by Multiple files exist here, and they are *concatenated* in a temporary file by
813 804 lbmk, which is then scanned to find information about projects. lbmk, which is then scanned to find information about projects.
814 805
806 config/data/PROJECT/mkhelper.cfg
807 --------------------------------
808
809 These `mkhelper.cfg` files define common configuration that can be supplied
810 for any single- or multi-tree project. Arguments available are as follows:
811
812 * `makeargs`: This defines what arguments to append when running the
813 main `make` command on a given project. For example, this is used on coreboot
814 to tell coreboot's build system that the submodules have been updated (to
815 avoid downloading any that we didn't manually specify).
816 * `build_depend`: Just before running the main `make` command on a given
817 project, this specifies other projects to build. It also works with multi
818 tree projects. Example: `seabios/default grub/xhci memtest86plus`
819 * `premake`: This defines a function to be called *before* running make, on a
820 given project; the mkhelper file itself can also import any given file to
821 provide that function.
822 * `mkhelper` (variable name): Defines a function to be called just after
823 running make, on a given project.
824 * `postmake`: This is run *after* `mkhelper`, and can be used for additional
825 functions. For example, it's used on coreboot to call `mkcoreboottar` which
826 will create tarballs of ROM images if `XBMK_RELEASE` is enabled.
827
828 You can define anything else here, for use by a given project. More specifically,
829 anything you put in mkhelper files will be imported as part of a normal shell
830 script during operation of lbmk, to complement core functionality across all
831 the various projects.
832
833 The `mkhelper` file is a global configuration for the project. Individual
834 projects can complement what is set in mkhelper, via `target.cfg` files for
835 each project, project tree or target on a given multi-tree project.
836
837 The `mkhelper` functionality (and postmake/premake) was originally implemented
838 so that lots of special configuration could be done per project, without a lot
839 of code repetition. This is a unique design of lbmk, different from many other
840 coreboot-distro build systems.
841
842 The `mkhelper` functionality is an essential component that makes lbmk work
843 the way it does; for example, the `trees` script builds coreboot images without
844 payloads, and functions to add payloads are handled by mkhelper-type functions.
845 This design allows almost all functionality to be centralised, where the mkhelper
846 functions only provide functionality that differs from core functionality.
847
848 In the simplest of terms, you may regard mkhelpers as *plugins*, of a sort.
849 They simply extend the core functionality of the build system, in a way that
850 can differ flexibly between projects.
851
815 852 GRUB config GRUB config
816 853 --------------- ---------------
817 854
 
... ... Author info for GRUB configuration files.
849 886
850 887 Licensing info for GRUB configuration files. Licensing info for GRUB configuration files.
851 888
852 ### config/grub/TREE/config/grub.cfg
889 ### config/grub/TREE/config/payload
853 890
854 891 This is a configuration file. It is used to program GRUB's shell. This is a configuration file. It is used to program GRUB's shell.
855 892
 
... ... A `grubtest.cfg` can be inserted into CBFS, but it will not override the
863 900 default `grub.cfg` (either in CBFS or on memdisk); however, the one in memdisk default `grub.cfg` (either in CBFS or on memdisk); however, the one in memdisk
864 901 will provide a menuentry for switching to this, if available. will provide a menuentry for switching to this, if available.
865 902
866 ### config/data/grub/config/memdisk.cfg
903 ### config/data/grub/memdisk.cfg
867 904
868 905 This GRUB configuration checks whether `grub.cfg` exists in CBFS and switches This GRUB configuration checks whether `grub.cfg` exists in CBFS and switches
869 906 to that first (not provided by default) or, if one is not available in CBFS, to that first (not provided by default) or, if one is not available in CBFS,
 
... ... These files are binary-encoded, defining which characters correspond to which
887 924 scancodes. It is handled by `grub-core/commands/keylayouts.c` in the GRUB source scancodes. It is handled by `grub-core/commands/keylayouts.c` in the GRUB source
888 925 code. code.
889 926
890 ### config/grub/TREE/modules.list
927 ### config/data/grub/module/TREE
891 928
892 929 This defines which modules are inserted into `grub.elf`. These modules can be This defines which modules are inserted into `grub.elf`. These modules can be
893 930 anything from file systems, small applications/utilities, launchers (e.g. anything from file systems, small applications/utilities, launchers (e.g.
 
... ... This list is used by lbmk when it runs `grub-mkstandalone`, which is the utility
901 938 from GRUB that generates `grub.elf` files (to be compressed inside CBFS and then from GRUB that generates `grub.elf` files (to be compressed inside CBFS and then
902 939 executed as a coreboot payload). executed as a coreboot payload).
903 940
904 ### config/grub/patches/
941 ### config/grub/TREE/patches/
905 942
906 943 For a given GRUB revision, patches with the `patch` file extension are placed For a given GRUB revision, patches with the `patch` file extension are placed
907 944 here, alphanumerically in the order that they should be applied. For example, here, alphanumerically in the order that they should be applied. For example,
 
... ... by lbmk to build coreboot ROM images.
920 957 config/seabios/ config/seabios/
921 958 --------------- ---------------
922 959
923 ### config/seabios/build.list
960 ### config/data/seabios/build.list
924 961
925 962 When a given SeaBIOS tree is compiled, for a given target, this file defines When a given SeaBIOS tree is compiled, for a given target, this file defines
926 963 which files to copy from the `seabios/` directory, which are then copied to which files to copy from the `seabios/` directory, which are then copied to
 
... ... that can use U-Boot as a payload in the `lbmk` build system. U-Boot doesn't yet
966 1003 have reliable generic configurations that can work across all coreboot boards have reliable generic configurations that can work across all coreboot boards
967 1004 (per-architecture), so these are used to build it per-board. (per-architecture), so these are used to build it per-board.
968 1005
969 ### config/u-boot/build.list
1006 ### config/data/u-boot/build.list
970 1007
971 1008 When a given U-Boot tree is compiled, for a given target, this file defines When a given U-Boot tree is compiled, for a given target, this file defines
972 1009 which files to copy from the U-Boot source build, which are then copied to which files to copy from the U-Boot source build, which are then copied to
 
... ... the above guidance.
1138 1175 Config files in lbmk root directory Config files in lbmk root directory
1139 1176 =================================== ===================================
1140 1177
1178 projectsite
1179 -------------
1180
1181 Domain name linking to the project home page (e.g. libreboot.org).
1182
1141 1183 projectname projectname
1142 1184 --------------- ---------------
1143 1185
 
... ... Scripts in root directory of lbmk
1167 1209 build build
1168 1210 --------------- ---------------
1169 1211
1170 This is the main script. Symlinks `vendor` and `update` also point to it.
1212 This is the main script. Symlinks `vendor` and `update` also point to it, as
1213 does `mk`. Direct use of this script is considered deprecate, because in a
1214 future audit, it will be removed; the `./mk` commands will be used,
1215 exclusively, so please use only `./mk` as directed here and elsewhere.
1171 1216
1172 1217 Take any given file under `script/` and you can do: Take any given file under `script/` and you can do:
1173 1218
 
... ... For example:
1181 1226 Special commands available (not provided by files under `script/`): Special commands available (not provided by files under `script/`):
1182 1227
1183 1228 ./mk release ./mk release
1184 ./mk download
1185 1229 ./mk inject ./mk inject
1230 ./mk -d coreboot TARGET # also downloads vendor files
1186 1231
1187 1232 The `vendor` commands are handled by the `build` script, calling functions The `vendor` commands are handled by the `build` script, calling functions
1188 1233 inside `include/vendor.sh`, and the `./mk release` logic is handled inside `include/vendor.sh`, and the `./mk release` logic is handled
 
... ... now the logic under `include/vendor.sh` is used for downloads. This file now
1225 1270 only contains those functions used for extraction of MRC files from Google only contains those functions used for extraction of MRC files from Google
1226 1271 Chromebook images, currently only used for Haswell mainboards. Chromebook images, currently only used for Haswell mainboards.
1227 1272
1228 This is an include, used by `script/vendor/download`, but it's here in
1273 This is an include, used by `include/vendor.sh`, but it's here in
1229 1274 this file because the vendor download script is GPLv3-only, while the MRC this file because the vendor download script is GPLv3-only, while the MRC
1230 1275 extract logic in this file is GPLv2-only (forked from coreboot ages ago). Thus, extract logic in this file is GPLv2-only (forked from coreboot ages ago). Thus,
1231 1276 it is provided as an include to bypass license incompatibility. It has been it is provided as an include to bypass license incompatibility. It has been
1232 1277 heavily modified to use the same style of logic and general control flow used heavily modified to use the same style of logic and general control flow used
1233 in the script at `script/vendor/download`, and it is used from there.
1278 in the script at `include/vendor.sh`, and it is used from there.
1234 1279
1235 1280 include/lib.sh include/lib.sh
1236 1281 --------------- ---------------
 
... ... This function also contains `x_()` which lbmk uses to execute commands
1252 1297 and ensure that they cause an exit (with non-zero status) from lbmk, if they and ensure that they cause an exit (with non-zero status) from lbmk, if they
1253 1298 return an error state. return an error state.
1254 1299
1255 script/
1256 =======
1257
1258 script/roms
1300 include/rom.sh
1259 1301 ----------- -----------
1260 1302
1261 This builds coreboot ROM images.
1303 This builds coreboot ROM images. Specifically, this contains mkhelper functions.
1304 It also builds serprog images, and it could be used to provide functions for
1305 building other types of firmware.
1262 1306
1263 1307 Command: `./mk -b coreboot targetname` Command: `./mk -b coreboot targetname`
1264 1308
 
... ... To build *all* targets, specify:
1275 1319
1276 1320 ./mk -b coreboot ./mk -b coreboot
1277 1321
1278 Since November 2022, this script can build images for x86 *and* ARM targets.
1279 The *ARM* targets are ChromeOS devices (chromebooks and such); Libreboot uses
1280 the *U-Boot* payload, rather than Google's *depthcharge* bootloader. In this
1281 setup, U-Boot is running on the bare metal, as enabled by *coreboot*.
1282
1283 1322 For x86 targets, these scripts build with the GRUB and/or SeaBIOS payloads For x86 targets, these scripts build with the GRUB and/or SeaBIOS payloads
1284 1323 inserted into the ROM images; secondary payloads like Memtest86+ are also inserted into the ROM images; secondary payloads like Memtest86+ are also
1285 1324 handled and inserted here. handled and inserted here.
 
... ... This script is the beating heart of Libreboot. Break it, and you break
1327 1366 Libreboot! Libreboot!
1328 1367
1329 1368 Serprog images: Serprog images:
1369 --------------
1330 1370
1331 1371 Build firmware images for serprog-based SPI programmers, where they use an Build firmware images for serprog-based SPI programmers, where they use an
1332 1372 STM32 MCU. It also builds for RP2040-based programmers like Raspberry Pi Pico. STM32 MCU. It also builds for RP2040-based programmers like Raspberry Pi Pico.
1333 1373
1334 Example command: `./build roms serprog stm32`
1374 Example command: `./mk -b pico-serprog`
1375
1376 Example command: `./mk -b stm32-vserprog`
1335 1377
1336 Example command: `./build roms serprog rp2040`
1378 This also uses `rom.sh` as with the coreboot image build logic. It's all
1379 defined in that file, so read the main section pertaining to this file.
1337 1380
1338 The `list` argument is available:
1381 include/vendor.sh
1382 -----------------
1339 1383
1340 ./build roms serprog stm32 list
1341 ./build roms serprog rp2040 list
1384 Helper functions for downloading and injecting vendor files. How to use:
1342 1385
1343 Without arguments, all targets would be compiled, but you can specify a short
1344 list of targets instead, based on the output of `list`.
1386 ./mk inject ARGUMENTS
1387 ./mk -d coreboot TARGET
1388
1389 Refer elsewhere in the documentation for how to handle vendor files.
1390
1391 script/
1392 =======
1345 1393
1346 1394 script/trees script/trees
1347 1395 ------------ ------------
Hints:
Before first commit, do not forget to setup your git environment:
git config --global user.name "your_name_here"
git config --global user.email "your@email_here"

Clone this repository using HTTP(S):
git clone https://rocketgit.com/user/libreboot/lbwww

Clone this repository using ssh (do not forget to upload a key first):
git clone ssh://rocketgit@ssh.rocketgit.com/user/libreboot/lbwww

Clone this repository using git:
git clone git://git.rocketgit.com/user/libreboot/lbwww

You are allowed to anonymously push to this repository.
This means that your pushed commits will automatically be transformed into a merge request:
... clone the repository ...
... make some changes and some commits ...
git push origin main