From 267157ddd42d9e3732c0ac6df38056c37c974086 Mon Sep 17 00:00:00 2001 From: Philip Molloy Date: Mon, 9 Nov 2026 20:06:54 +0100 Subject: [PATCH 1/8] SUMMARY: Fix Markdown issues - MD041 First line in file should be a top level header Signed-off-by: Philip Molloy --- src/SUMMARY.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index c689119..3598ed6 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -1,3 +1,5 @@ +# Summary + - [LinuxBoot Introduction](intro.md) - [Use cases](use-cases.md) - [Talks and news coverage](talks-news.md) From a3a6d70f0e1e89df453ef91bbd749f173165a988 Mon Sep 17 00:00:00 2001 From: Philip Molloy Date: Mon, 9 Nov 2026 20:06:54 +0100 Subject: [PATCH 2/8] TiogaPass: Fix Markdown issues - MD036 Emphasis used instead of a header - MD040 Fenced code blocks should have a language specified Signed-off-by: Philip Molloy --- src/case_studies/TiogaPass.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/case_studies/TiogaPass.md b/src/case_studies/TiogaPass.md index a105879..e73c827 100644 --- a/src/case_studies/TiogaPass.md +++ b/src/case_studies/TiogaPass.md @@ -63,13 +63,13 @@ target OS. * Download the code from [linuxboot github](https://github.com/linuxboot/linuxboot) - ``` + ```sh git clone https://github.com/linuxboot/linuxboot.git ``` * You need to apply Wiwiynn's linuxboot patch for now - ``` + ```sh cd linuxboot wget -O TiogaPass.patch https://github.com/johnnylinwiwynn/linuxboot/commit/28ae8450b3b05c6e6b8c74e29d0974ccf711d5e6.patch git am TiogaPass.patch @@ -85,7 +85,7 @@ target OS. after ordering, and also put your bzImage to the root folder of linuxboot, and then make - ``` + ```sh cp path/to/tioga.rom linuxboot/boards/tioga cp path/to/bzImage linuxboot cd linuxboot @@ -131,4 +131,4 @@ IRC channel, a mailing list and regular meetings. Following companies provides professional support services: -**TBD** +TBD From 60f7d7f202c4c557afb29135a50412d123d880a5 Mon Sep 17 00:00:00 2001 From: Philip Molloy Date: Mon, 9 Nov 2026 20:06:54 +0100 Subject: [PATCH 3/8] components: Fix Markdown issues - MD040 Fenced code blocks should have a language specified Signed-off-by: Philip Molloy --- src/components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/components.md b/src/components.md index 1082240..09e4e73 100644 --- a/src/components.md +++ b/src/components.md @@ -35,7 +35,7 @@ essentially a set of files and directories bundled into a single cpio archive. The minimum structure is this: -``` +```text /dev/console /dev/null /init From be8f7f95b9c496a909bf0c1d0d4dbb4249aa6810 Mon Sep 17 00:00:00 2001 From: Philip Molloy Date: Mon, 9 Nov 2026 20:06:54 +0100 Subject: [PATCH 4/8] coreboot.u-root.systemboot: Fix Markdown issues - MD040 Fenced code blocks should have a language specified Signed-off-by: Philip Molloy --- src/coreboot.u-root.systemboot/index.md | 30 ++++++++++++------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/src/coreboot.u-root.systemboot/index.md b/src/coreboot.u-root.systemboot/index.md index a85c84e..10ea1f0 100644 --- a/src/coreboot.u-root.systemboot/index.md +++ b/src/coreboot.u-root.systemboot/index.md @@ -13,7 +13,7 @@ builds will cover virtual and physical OCP hardware. Run these commands in a directory you create or in `/tmp`; do so because it creates some files and directories: -``` +```console $ go get github.com/linuxboot/corebootnerf $ go run github.com/linuxboot/corebootnerf --fetch ... lots and lots of output! @@ -22,7 +22,7 @@ $ go run github.com/linuxboot/corebootnerf --fetch This produces a coreboot image in coreboot-4.9/build/coreboot.rom You can now run this ROM image: -``` +```sh qemu-system-x86_64 -serial stdio -bios coreboot-4.9/build/coreboot.rom ``` @@ -60,14 +60,14 @@ command that we will use in the next steps. Then, fetch `u-root` and its dependencies: -``` +```sh go get -u github.com/u-root/u-root ``` Then build the ramfs in busybox mode, and add fbnetboot, localboot, and a custom uinit to wrap everything together: -``` +```sh u-root -build=bb core github.com/u-root/u-root/cmds/boot/{uinit,localboot,fbnetboot} ``` @@ -85,7 +85,7 @@ initramfs in the kernel as explained below, in order to maintain the image size smaller. Linux has a limited XZ compressor, so the compression requires specific options: -``` +```sh xz --check=crc32 --lzma2=dict=512KiB /tmp/initramfs.linux_amd64.cpio ``` @@ -124,7 +124,7 @@ You can either download a tarball from kernel.org, or get it via git and use a version tag. We recommend at least a kernel 4.16, in order to have VPD variables support. -``` +```sh # download the kernel tarball. Replace 4.19.6` with whatever kernel version you want wget https://cdn.kernel.org/pub/linux/kernel/v4.x/linux-4.19.6.tar.xz tar xvJf linux-4.19.6.tar.xz @@ -135,7 +135,7 @@ make tinyconfig You can also check out the `linux-stable` branch, that will point to the latest stable commit. You need to download it via `git` as follows: -``` +```sh git clone --depth 1 -b linux-stable git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git cd linux-stable @@ -267,7 +267,7 @@ As mentioned above, the kernel will embed the compressed initramfs image. Your kernel configuration should point to the appropriate file using the `CONFIG_INITRAMFS_SOURCE` directive. E.g. -``` +```text CONFIG_INITRAMFS_SOURCE="/path/to/initramfs_linux.x86_64.cpio.xz" ``` @@ -282,7 +282,7 @@ We use "linuxboot" as the default hostname. You may want to adjust it to a different value. You need to set `CONFIG_DEFAULT_HOSTNAME` for the purpose. For example: -``` +```text CONFIG_DEFAULT_HOSTNAME="linuxboot" ``` @@ -294,7 +294,7 @@ In menuconfig: Once your configuration is ready, build the kernel as usual: -``` +```sh make -j$(nproc --ignore=1) ``` @@ -321,7 +321,7 @@ Steps overview: Our preferred method is to download coreboot from the git repository: -``` +```sh git clone https://review.coreboot.org/coreboot.git cd coreboot ``` @@ -331,7 +331,7 @@ cd coreboot This step is required to have, among other things, reproducible builds, and a compiler toolchain that is known to work with coreboot. -``` +```sh make crossgcc-i386 CPUS=$(nproc) BUILD_LANGUAGES=c ``` @@ -364,7 +364,7 @@ Then save your configuration and exit menuconfig. This is done with a simple -``` +```sh make -j$(nproc) ``` @@ -374,7 +374,7 @@ code, and our bzImage payload. The output file is at `build/coreboot.rom`. If everything works correctly you will get an output similar to the following: -``` +```text This image contains the following sections that can be manipulated with this tool: 'COREBOOT' (CBFS, size 16776704, offset 512) @@ -414,7 +414,7 @@ the machine type `q35`, as specified in the coreboot mainboard section. Assuming that your coreboot image is located at `build/coreboot.rom`, you can run the following command: -``` +```sh sudo qemu-system-x86_64\ # sudo is required to enable KVM below -M q35 \ # the machine type specified in the coreboot mainboard configuration -enable-kvm \ # use KVM to avail of hardware virtualization extensions From 3e695e0becda8704f9bcabccf7c2809d34ba9863 Mon Sep 17 00:00:00 2001 From: Philip Molloy Date: Mon, 9 Nov 2026 20:06:54 +0100 Subject: [PATCH 5/8] UEFI_Tool_Kit: Fix Markdown issues - MD040 Fenced code blocks should have a language specified Signed-off-by: Philip Molloy --- src/utilities/UEFI_Tool_Kit.md | 42 +++++++++++++++++----------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/src/utilities/UEFI_Tool_Kit.md b/src/utilities/UEFI_Tool_Kit.md index 120da83..fcbbf45 100644 --- a/src/utilities/UEFI_Tool_Kit.md +++ b/src/utilities/UEFI_Tool_Kit.md @@ -26,7 +26,7 @@ In this chapter, we'll go over how to: ## Synopsis -``` +```sh make bzImage sudo flashrom -r /tmp/ROM.bin utk /tmp/ROM.bin replace_pe32 Shell arch/86/boot/bzImage save /tmp/NEWROM.bin @@ -47,13 +47,13 @@ our first step on a new board. Get the tool: -``` +```sh go get -u github.com/linuxboot/fiano/cmds/utk ``` Replace the shell: -``` +```sh utk ROM.bin replace_pe32 Shell bzImage save NEWROM.bin ``` @@ -72,7 +72,7 @@ a few more tools besides UTK, but UTK is a big element. We'll assume you already have Go installed. Check your installation with: -``` +```console $ go version go version go1.11 linux/amd64 ``` @@ -83,7 +83,7 @@ official binary distributions of Go or install from source. See With Go, download and install UTK: -``` +```sh go get -u github.com/linuxboot/fiano/cmds/utk ``` @@ -93,7 +93,7 @@ directory to your `$PATH` is recommended. Make sure it works with: -``` +```console $ utk -h Usage: utk [flags] [0 or more operations] @@ -131,7 +131,7 @@ the land". Start by downloading the UEFI image used in these examples: -``` +```sh wget https://github.com/linuxboot/fiano/raw/master/integration/roms/OVMF.rom ``` @@ -142,7 +142,7 @@ below. If you encounter any problems, please file an issue at First, it is advisable to print a count of each firmware element: -``` +```console $ utk OVMF.rom count { "FirmwareTypeCount": { @@ -195,7 +195,7 @@ TODO: Diagram showing a tree of these firmware elements. To view a human-readable tree of all the firmware elements, types and sizes, run: -``` +```console $ utk OVMF.rom table | less Node GUID/Name Type Size BIOS 0x400000 @@ -222,7 +222,7 @@ This format is compact and easy for humans reading, but not ideal for machine consumption. Use the `json` command to print everything (including much more metadata) as JSON: -``` +```sh utk OVMF.rom json | less ``` @@ -230,7 +230,7 @@ Combine `utk` with the JSON query command, `jq` (`sudo apt-get install jq`), and other UNIX commands to quickly write powerful queries. For example, the following lists all the GUIDs, sorted and without duplicates: -``` +```console $ utk OVMF.rom json | jq -r '..|.GUID?|select(type=="string")' | sort -u 00000000-0000-0000-0000-000000000000 0167CCC4-D0F7-4F21-A3EF-9E64B7CDCE8B @@ -242,7 +242,7 @@ $ utk OVMF.rom json | jq -r '..|.GUID?|select(type=="string")' | sort -u To only print the JSON for specific files, use the find command: -``` +```console # The find command uses a regex to match on the name or GUID. # These three examples find and print the JSON for the same file: $ utk OVMF.rom find 'Sh.*' @@ -282,13 +282,13 @@ contents. The `extract ` command extracts all the files from the image and saves them to ``. `/summary.json` lists all the paths to the extracted files along with their metadata. -``` +```sh utk OVMF.rom extract OVMF/ ``` After modifying the files, they can be reassembled with: -``` +```sh utk OVMF/ save OVMF2.rom ``` @@ -298,7 +298,7 @@ First, let's verify the image works by running it inside QEMU. This step is not absolutely necessary, but gives us confidence the image works before and after each change we make. -``` +```sh qemu-system-x86_64 -bios OVMF.rom -nographic -net none ``` @@ -311,7 +311,7 @@ always loads the image into memory and the last argument typically writes the output. The commands in between operate on the image in memory and are reminiscent of a UNIX pipeline. The general syntax is: -``` +```sh utk \ ... \ ... \ @@ -334,7 +334,7 @@ with Usb and the Legacy8259 driver which has the GUID you need to remove drivers to make room for Linux which makes the pipeline convenient. This is the essence of LinuxBoot: -``` +```console $ stat linux.efi linux.efi: Linux kernel x86 boot executable bzImage, version 4.17.0 $ utk OVMF.rom \ @@ -354,7 +354,7 @@ insert. In order to be properly bootable as a DXE, kernels must have the following enabled: -``` +```text CONFIG_EFI=y CONFIG_EFI_STUB=y ``` @@ -378,7 +378,7 @@ GUID in the json summary. ### File size too big -``` +```text File size too big! File with GUID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX has length 543210, but is only 123450 bytes big ``` @@ -389,7 +389,7 @@ If you were inserting files, you will need to delete existing files to make room There is a special cases where this error is generated without any operations: -``` +```sh utk OVMF.rom save OVMF2.rom ``` @@ -516,7 +516,7 @@ fv.Apply(v) It would be exciting/useful to be able to chain these small actions together through the command line. For example: -``` +```sh utk extract bios.rom \ remove a2dad2a-adadad-a2d2-ad23a3 \ remove 9d8cd98-d9c8d9-d9c8-9d8c8c \ From cddb1618ed0e52d76cb5f5c1af226344d3f3e18e Mon Sep 17 00:00:00 2001 From: Philip Molloy Date: Mon, 9 Nov 2026 20:06:54 +0100 Subject: [PATCH 6/8] dut: Fix Markdown issues - MD025 Multiple top level headers in the same document - MD040 Fenced code blocks should have a language specified Signed-off-by: Philip Molloy --- src/utilities/dut.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/utilities/dut.md b/src/utilities/dut.md index ed79f3a..add86a7 100644 --- a/src/utilities/dut.md +++ b/src/utilities/dut.md @@ -20,7 +20,7 @@ This chapter describes how we build and use DUT. DUT is intended to be built into a u-root image. First one must fetch it: -``` +```sh go get github.com/linuxboot/dut # ignore the warning message. ``` @@ -29,14 +29,14 @@ DUT source tree is structured such that a program called uinit is produced. This Building it into a u-root image is easy: -``` +```sh go run $(GOPATH)/src/github.com/u-root/u-root -build=bb minimal github.com/linuxboot/dut/uinit ``` I almost always add an sshd to u-root; it's just too handy. U-root sshd does not support passwords, so you have to supply the public key: -``` +```sh go run $(GOPATH)/src/github.com/u-root/u-root -build=bb -files key.pub minimal github.com/linuxboot/dut/uinit github.com/u-root/u-root/xcmds/sshd ``` @@ -52,14 +52,14 @@ as a server and waits for requests. Running on the controller is easy: -``` +```sh uinit -m tester ``` On the controller, the program waits for a connection and then starts issuing commands to the device. The controller has the option of calling the following RPC functions: -``` +```text RPCWelcome - return a welcome message RPCExit - exit the testing mode RPCReboot - reboot the system @@ -69,7 +69,7 @@ RPCSsh - start the sshd Each of these RPCs takes arguments and returns a result, with Welcome being the most fun: -``` +```text ______________ < welcome to DUT > -------------- @@ -86,6 +86,6 @@ a reboot. It's been good for finding out if a particular DXE can be removed. Once the second Welcome has happened, if an sshd is installed, it will have been started, and you can do additional commands. -# Future work +## Future work Obviously, much more can be done. But this is a useful foundation on which to build DUT environments. From 6dc95fe897694b4d7ac9778bcc3ad37349b3f702 Mon Sep 17 00:00:00 2001 From: Philip Molloy Date: Mon, 9 Nov 2026 20:17:48 +0100 Subject: [PATCH 7/8] mdl: Only lint files known to git Skip the generated book/ directory, which is ignored by git and removed by `mdbook clean`, when linting with `mdl .` Signed-off-by: Philip Molloy --- .github/workflows/lazy-lint.bash | 27 --------------------------- .mdlrc | 1 + 2 files changed, 1 insertion(+), 27 deletions(-) delete mode 100755 .github/workflows/lazy-lint.bash diff --git a/.github/workflows/lazy-lint.bash b/.github/workflows/lazy-lint.bash deleted file mode 100755 index 187d3d6..0000000 --- a/.github/workflows/lazy-lint.bash +++ /dev/null @@ -1,27 +0,0 @@ -#!/usr/bin/env bash - -declare -A shame_list -shame_list=( - [./src/case_studies/TiogaPass.md]=1 - [./src/coreboot.u-root.systemboot/index.md]=1 - [./src/SUMMARY.md]=1 - [./src/u-root.md]=1 - [./src/utilities/dut.md]=1 - [./src/utilities/UEFI_Tool_Kit.md]=1 -) - -ll_rv=0 -for md_file in $(find . -name "*.md"); do - if [[ "${shame_list[$md_file]}" ]]; then - echo -e "\\e[93mSkipping ${md_file}\\e[0m" - else - echo "$ mdl ${md_file}" - mdl ${md_file} - - mdl_rv="$?" - if [[ "${mdl_rv}" -ne 0 ]]; then - ll_rv="${mdl_rv}" - fi - fi -done -exit ${ll_rv} diff --git a/.mdlrc b/.mdlrc index 1f82ca2..a633e76 100644 --- a/.mdlrc +++ b/.mdlrc @@ -1 +1,2 @@ style '.mdl_style.rb' +git_recurse true From 1c36531746da6d2a7c16fb13d04de85132106f6c Mon Sep 17 00:00:00 2001 From: Philip Molloy Date: Mon, 9 Nov 2026 20:17:48 +0100 Subject: [PATCH 8/8] github: Lint all Markdown files All files on the list of shame now pass mdl, so drop lazy-lint.bash and run mdl on the whole repository Signed-off-by: Philip Molloy --- .github/workflows/markdownlint.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml index 70342be..44c6108 100644 --- a/.github/workflows/markdownlint.yml +++ b/.github/workflows/markdownlint.yml @@ -20,4 +20,4 @@ jobs: run: sudo gem install mdl - name: Lint markdown - run: .github/workflows/lazy-lint.bash + run: mdl .