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/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml index c84a256..1d7a241 100644 --- a/.github/workflows/markdownlint.yml +++ b/.github/workflows/markdownlint.yml @@ -13,7 +13,10 @@ jobs: uses: actions/checkout@v4 - name: Install markdown lint - run: sudo gem install mdl - - - name: Lint markdown - run: .github/workflows/lazy-lint.bash + uses: DavidAnson/markdownlint-cli2-action@v20 + with: + # keep in sync with Makefile + globs: | + src/**/*.md + !src/SUMMARY.md + !src/{case_studies/TiogaPass,coreboot.u-root.systemboot/index,utilities/dut,utilities/UEFI_Tool_Kit}.md diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..653f5f3 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,7 @@ +{ + "default": true, + "MD013": { "code_blocks": false, "tables": false }, + "MD029": { "style": "ordered" }, + "MD033": false, + "MD045": false +} diff --git a/.mdl_style.rb b/.mdl_style.rb deleted file mode 100644 index 466a6cb..0000000 --- a/.mdl_style.rb +++ /dev/null @@ -1,9 +0,0 @@ -all -# This should be 2 by default per the docs, but turned out to be 8 -rule 'MD007', :indent => 2 -# Ignore line length in code blocks and tables -rule 'MD013', :ignore_code_blocks => true, :tables => false -# Allow inline HTML -exclude_rule 'MD033' -# Order ordered lists -rule 'MD029', :style => :ordered diff --git a/.mdlrc b/.mdlrc deleted file mode 100644 index 1f82ca2..0000000 --- a/.mdlrc +++ /dev/null @@ -1 +0,0 @@ -style '.mdl_style.rb' diff --git a/Makefile b/Makefile index e7e4525..a2d9107 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,5 @@ +MARKDOWNLINT ?= markdownlint-cli2 + build: book i18n # linkcheck causes output files to end up in html/, so move them to root mv book/html/* book/ @@ -19,3 +21,15 @@ prepare: prepare_i18n cargo install mdbook-mermaid mdbook-mermaid install cargo install mdbook-linkcheck + +lint_install: + npm i -g --prefix ~/bin/node/ markdownlint-cli2 + +# keep in sync with .github/workflows/markdownlint.yml +SHAMELIST := '!src/{case_studies/TiogaPass,coreboot.u-root.systemboot/index,utilities/dut,utilities/UEFI_Tool_Kit}.md' + +lint: ARGS = +lintfix: ARGS = --fix +lint lintfix: + # NOTE: SUMMARY.md is the ToC, which has no headline + $(MARKDOWNLINT) $(ARGS) 'src/**/*.md' !src/SUMMARY.md $(SHAMELIST) diff --git a/README.md b/README.md index 5099dbb..02df029 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ make run The book is linted with markdownlint and Vale. Follow the official documentation to [install -markdownlint](https://github.com/markdownlint/markdownlint?tab=readme-ov-file#installation) +markdownlint](https://github.com/DavidAnson/markdownlint-cli2) and [install Vale](https://vale.sh/docs/install). Then run `vale sync` to download the necessary styles. diff --git a/src/case_studies/TiogaPass.md b/src/case_studies/TiogaPass.md index 4d4b464..a105879 100644 --- a/src/case_studies/TiogaPass.md +++ b/src/case_studies/TiogaPass.md @@ -14,15 +14,15 @@ Corporation](http://www.wiwynn.com/english). It contains following sections: -* [Quick Start](#Quick-Start) -* [Details](#Details) - * [How to build](#How-to-build) - * [How to operate](#How-to-operate) - * [Platform info](#Platform-info) -* [Support](#Support) - * [Hardware support](#Hardware-support) - * [Community support](#Community-support) - * [Professional support](#Professional-support) +* [Quick Start](#quick-start) +* [Details](#details) + * [How to build](#how-to-build) + * [How to operate](#how-to-operate) + * [Platform info](#platform-info) +* [Support](#support) + * [Hardware support](#hardware-support) + * [Community support](#community-support) + * [Professional support](#professional-support) ## Quick Start @@ -33,11 +33,14 @@ It contains following sections: * Flash the firmware. * Copy the downloaded firmware to OpenBMC. * From OpenBMC + ``` fw-util mb --update bios --force ./ ``` + * Boot and enjoy. * From OpenBMC + ``` power-util mb reset sol-util mb @@ -47,7 +50,7 @@ It contains following sections: ### How to build -Follow [Build Details](#Build-Details) for details on how to get the source +Follow [Build Details](#build-details) for details on how to get the source code, and how to build. Boot flow of the current firmware solution is: Power on → minimized UEFI → @@ -59,15 +62,19 @@ target OS. #### Build Details * Download the code from [linuxboot github](https://github.com/linuxboot/linuxboot) + ``` git clone https://github.com/linuxboot/linuxboot.git ``` + * You need to apply Wiwiynn's linuxboot patch for now + ``` cd linuxboot wget -O TiogaPass.patch https://github.com/johnnylinwiwynn/linuxboot/commit/28ae8450b3b05c6e6b8c74e29d0974ccf711d5e6.patch git am TiogaPass.patch ``` + * Build the kernel bzImage (has embedded initramfs) for linuxboot, please reference [Building u-root](https://github.com/linuxboot/book/tree/master/coreboot.u-root.systemboot#building-u-root) and [Building a suitable Linux kernel](https://github.com/linuxboot/book/tree/master/coreboot.u-root.systemboot#building-a-suitable-linux-kernel) @@ -77,12 +84,14 @@ target OS. * Place the tioga.rom into linuxboot/boards/tioga which is provided from Wiwynn after ordering, and also put your bzImage to the root folder of linuxboot, and then make + ``` cp path/to/tioga.rom linuxboot/boards/tioga cp path/to/bzImage linuxboot cd linuxboot BOARD=tioga make ``` + * You should see the built image at build/tioga/linuxboot.rom. ### How to operate @@ -122,4 +131,4 @@ IRC channel, a mailing list and regular meetings. Following companies provides professional support services: -** TBD ** +**TBD** diff --git a/src/coreboot.u-root.systemboot/index.md b/src/coreboot.u-root.systemboot/index.md index 6d2232d..a85c84e 100644 --- a/src/coreboot.u-root.systemboot/index.md +++ b/src/coreboot.u-root.systemboot/index.md @@ -78,7 +78,7 @@ path with `-o`. Run `u-root -h` for additional command line parameters. Note: the above command will include only pure-Go commands from `u-root`. If you need to include other files or non-Go binaries, use the `-file` option in `u-root`. For example, you may want to include static builds of `kexec` or -`flashrom`, that we build on https://github.com/systemboot/binaries . +`flashrom`, that we build on . Then, the initramfs has to be compressed. This step is necessary to embed the initramfs in the kernel as explained below, in order to maintain the image size @@ -143,7 +143,7 @@ make tinyconfig ``` Some more information about tiny configs can be found at -https://tiny.wiki.kernel.org (last checked 2018-12-01). + (last checked 2018-12-01). ### A few fundamental features @@ -184,7 +184,7 @@ In menuconfig: → `Enable eventpoll support` Additional information about Go's minimum requirements can be found at -https://github.com/golang/go/wiki/MinimumRequirements (last checked + (last checked 2018-12-01). ### Enable devtmpfs @@ -302,7 +302,7 @@ The image will be located under `arch/${ARCH}/boot/bzImage` if your architecture supports bzImage (e.g. x86). For more details on how to build a kernel, see -https://kernelnewbies.org/KernelBuild (last checked 2018-12-01). + (last checked 2018-12-01). ## Building coreboot diff --git a/src/intro.md b/src/intro.md index 1119e42..2adfb77 100644 --- a/src/intro.md +++ b/src/intro.md @@ -13,8 +13,8 @@ This is the official “LinuxBoot Book” for the LinuxBoot project. The book: LinuxBoot is the idea of replacing proprietary or corporate-driven late-stage boot [firmware](./glossary.md) with the Linux kernel and a community-based user-space. That idea grew into a project that over the years includes various -initiatives with the overarching goal of moving from obscure and complex -firmware to simpler and open source firmware. +initiatives with the overarching goal of moving from obscure and closed source +firmware to clear and open source firmware. The LinuxBoot project provides two reference implementations; `linuxboot` and Heads. The [`linuxboot`](https://github.com/linuxboot/linuxboot) build system diff --git a/src/utilities/UEFI_Tool_Kit.md b/src/utilities/UEFI_Tool_Kit.md index 25a8218..120da83 100644 --- a/src/utilities/UEFI_Tool_Kit.md +++ b/src/utilities/UEFI_Tool_Kit.md @@ -422,8 +422,8 @@ Visitor pattern means decoupling the structure from the operations. Good resources: -1. https://sourcemaking.com/design_patterns/visitor -2. https://en.wikipedia.org/wiki/Visitor_pattern +1. +2. A good visitor still works when new Firmware are introduced. A good Firmware still works when a new visitor is introduced. diff --git a/src/utilities/cpu.md b/src/utilities/cpu.md index dba4567..caafa22 100644 --- a/src/utilities/cpu.md +++ b/src/utilities/cpu.md @@ -574,7 +574,7 @@ Even though the binaries themselves are running on the remote ARM system. #### cpu and virtiofs -While 9p is very general, because it is *transport-independent*, there are +While 9p is very general, because it is _transport-independent_, there are cases where we can get much better performance by using a less general file system. One such case is with virtofs. @@ -633,7 +633,7 @@ There are thus several choices for setting up the mounts * 9p support by the cpu client * 9p supported by the cpu client, with additional mounts via -fstab or -namespace -* 9p *without* any bind mounts, i.e. -9p=false -namespace "", in which case, on +* 9p _without_ any bind mounts, i.e. -9p=false -namespace "", in which case, on the remote machine, files from the client are visible in /tmp/cpu, but no bind mounts are done; with additional mounts provided by fstab mounts are provided diff --git a/src/utilities/dut.md b/src/utilities/dut.md index 38a63c4..ed79f3a 100644 --- a/src/utilities/dut.md +++ b/src/utilities/dut.md @@ -1,4 +1,4 @@ -# DUT, a simple Device Under Test utility. +# DUT, a simple Device Under Test utility Points of contact: [Ron Minnich](https://github.com/rminnich) @@ -19,6 +19,7 @@ This chapter describes how we build and use DUT. ## Components DUT is intended to be built into a u-root image. First one must fetch it: + ``` go get github.com/linuxboot/dut # ignore the warning message. @@ -27,17 +28,20 @@ go get github.com/linuxboot/dut DUT source tree is structured such that a program called uinit is produced. This is convenient for u-root usage. Building it into a u-root image is easy: + ``` 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: + ``` 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 ``` ### DUT on the device + On boot, the standard init program will find dut, and run it. The standard mode on a device is device mode, and dut will bring up the ethernet, currently using 192.168.0.2, and assuming the tester is 192.168.0.1 (this should be fixed ...). @@ -45,13 +49,16 @@ It will then attempt to connect to a uinit running in 'tester' mode on 192.168.0 as a server and waits for requests. ### DUT on the controller + Running on the controller is easy: + ``` 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: + ``` RPCWelcome - return a welcome message RPCExit - exit the testing mode @@ -61,6 +68,7 @@ RPCSsh - start the sshd ``` Each of these RPCs takes arguments and returns a result, with Welcome being the most fun: + ``` ______________ < welcome to DUT >