diff --git a/doc/boot.md b/doc/boot.md index b48112cb..947affc8 100644 --- a/doc/boot.md +++ b/doc/boot.md @@ -146,8 +146,7 @@ To initiate a system upgrade from the shell[^1], run: rauc install -Where the file or URL points to a [RAUC Upgrade -Bundle](#rauc-upgrade-bundle). +Where the file or URL points to a [RAUC Upgrade Bundle](#rauc-upgrade-bundle). This will upgrade the partition not currently running. After a successful upgrade is completed, you can reboot your system, which @@ -155,8 +154,6 @@ will then boot from the newly installed image. Since the partition from which you were originally running is now inactive, running the same upgrade command again will bring both partitions into sync. -[RAUC]: https://rauc.io - Image Formats ------------- @@ -172,8 +169,6 @@ this image, or is dependent on it, in one way or another. On its own, it can be used as an [initrd][] to efficiently boot a virtual instance of Infix. -[initrd]: https://docs.kernel.org/admin-guide/initrd.html - ### FIT Framed Squash Image **Canonical Name**: `rootfs.itb` @@ -213,20 +208,19 @@ validate the SquashFS's contents. This path was chosen because: In its full form, it can be used to netboot Infix, as it contains all the information needed by U-Boot in a single file. -[FIT]: https://u-boot.readthedocs.io/en/latest/usage/fit.html - ### RAUC Upgrade Bundle **Canonical Name**: `infix-${ARCH}.pkg` -Itself a SquashFS image, it contains the Infix [SquashFS -Image](#squashfs-image) along with the header of the [FIT Framed -Squash Image](#fit-framed-squash-image), and some supporting files to -let [RAUC][] know how install it on the target system. +Itself a SquashFS image, this bundle (sometimes referred to package) +contains the Infix [SquashFS Image](#squashfs-image) along with the +header of the [FIT Framed Squash Image](#fit-framed-squash-image), and +some supporting files to let [RAUC][] know how install it on the target +system. -When performing a [System Upgrade](#system-upgrade), this is the -format to use. +When performing a [System Upgrade](#system-upgrade), this is the format +to use. ### Disk Image @@ -287,10 +281,12 @@ bootloader configuration etc. Typical layout when using U-Boot bootloader: +``` / ├ primary.itbh ├ secondary.itbh └ uboot.env +``` During boot, an ITB header along with the corresponding root filesystem image are concatenated in memory, by U-Boot, to form a @@ -340,8 +336,9 @@ can funtion reasonably well without a persistent `/var`, loosing If `var` is not available, Infix will still persist `/var/lib` using `cfg` as the backing storage. -[^1]: See [Upgrading procedures and boot - order](system.md#upgrade-procedures-and-boot-order) for - information on upgrading via CLI. +[^1]: See [Upgrade & Boot Order](upgrade.md) for more information. -[2]: netboot.md +[2]: netboot.md +[FIT]: https://u-boot.readthedocs.io/en/latest/usage/fit.html +[RAUC]: https://rauc.io +[initrd]: https://docs.kernel.org/admin-guide/initrd.html diff --git a/doc/developers-guide.md b/doc/developers-guide.md index 09a8fa89..f8019c34 100644 --- a/doc/developers-guide.md +++ b/doc/developers-guide.md @@ -14,6 +14,9 @@ the Buildroot `make menuconfig` system. -> System configuration -> [*]Enable root login with password +> [!IMPORTANT] +> Please see the [Contributing](#contributing) section, below, for +> details on how to fork and clone when contributing to Infix. Cloning ------- @@ -25,14 +28,12 @@ tree to your PC: ```bash $ mkdir ~/Projects; cd ~/Projects $ git clone https://github.com/kernelkit/infix.git +.. $ cd infix/ $ git submodule update --init +.. ``` -> Please see the [Contributing](#contributing) section, below, for -> details on how to fork and clone when contributing to Infix. - - ### Customer Builds Customer builds add product specific device trees, more OSS packages, @@ -57,6 +58,10 @@ Other caveats should be documented in the customer specific trees. Building -------- +> [!TIP] +> For more details, see the Getting Started and System Requirements +> sections of the [excellent Buildroot manual][1]. + Buildroot is almost stand-alone, it needs a few locally installed tools to bootstrap itself. The most common ones are usually part of the base install of the OS, but specific ones for building need the following. @@ -71,9 +76,6 @@ $ sudo apt install bc binutils build-essential bzip2 cpio \ mtools ``` -> For details, see the Getting Started and System Requirements sections -> of the [excellent manual][1]. - To build an Infix image; select the target and then make: make x86_64_defconfig @@ -96,12 +98,14 @@ and services are required on your system: ```bash $ sudo apt install jq graphviz qemu-system-x86 qemu-system-arm \ ethtool gdb-multiarch tcpdump tshark +.. ``` To be able to build the test specification you also need: ```bash $ sudo apt-get install python3-graphviz ruby-asciidoctor-pdf +.. ``` @@ -422,10 +426,10 @@ corresponding image for execution with our normal tooling: cd x-artifact-a1b2c3d4-x86_64 make run -> **Note:** CI artifacts are built from a merge commit of the source -> and target branches. Therefore, the version in the Infix banner -> will not match the SHA of the commit you have checked out. - +> [!NOTE] +> CI artifacts are built from a merge commit of the source and target +> branches. Therefore, the version in the Infix banner will not match +> the SHA of the commit you have checked out. Contributing ------------ @@ -437,28 +441,32 @@ fork, and then use GitHub to create a *Pull Reqeuest*. For this to work as *painlessly as possible* for everyone involved: 1. Fork Infix to your own user or organization[^1] - 2. Fork all the Infix submodules, e.g., `kernelkit/buildroot` to your + 1. Fork all the Infix submodules, e.g., `kernelkit/buildroot` to your own user or organization as well - 3. Clone your fork of Infix to your laptop/workstation - 4. [Deactivate the Actions][6] you don't want in your fork - 5. Please read the [Contributing Guidelines][5] as well! + 1. Clone your fork of Infix to your laptop/workstation + 1. [Deactivate the Actions][6] you don't want in your fork + 1. Please read the [Contributing Guidelines][5] as well! ```bash $ cd ~/Projects $ git clone https://github.com/YOUR_USER_NAME/infix.git +... $ cd infix/ $ git submodule update --init +... ``` -> **Note:** when updating/synchronizing with upstream Infix changes you -> may have to synchronize your forks as well. GitHub have a `Sync fork` -> button in the GUI for your fork for this purpose. A cronjob on your -> server of choice can do this for you with the [GitHub CLI tool][7]. + +> [!NOTE] +> When updating/synchronizing with upstream Infix changes you may have +> to synchronize your forks as well. GitHub have a `Sync fork` button +> in the GUI for your fork for this purpose. A cronjob on your server +> of choice can do this for you with the [GitHub CLI tool][7]. [^1]: Organizations should make sure to lock the `main` (or `master`) branch of their clones to ensure members do not accidentally merge changes there. Keeping these branches in sync with upstream Infix is highly recommended as a baseline and reference. For integration - of local changes another company-specific branch can be used instead. + of local changes another company-specific branch can be used instead. [0]: https://github.com/kernelkit/infix/releases [1]: https://buildroot.org/downloads/manual/manual.html diff --git a/doc/vpd.md b/doc/vpd.md index 17250296..10b58c82 100644 --- a/doc/vpd.md +++ b/doc/vpd.md @@ -74,12 +74,13 @@ encoded strings is a decision imposed by Infix; the ONIE specification allows for arbitrary binary data. **Example**: + ```json { - ... - "vendor-extension": [ - [ 12345, "my extension data" ] - ] + ... + "vendor-extension": [ + [ 12345, "my extension data" ] + ] } ``` @@ -102,12 +103,13 @@ Since the extension is itself stored in a JSON document, it has to be appropriately quoted. **Example**: + ```json { - ... - "vendor-extension": [ - [ 61046, "{\"pwhash\":\"$6$9rufAxdqCrxrwfQR$G0l9cTVlu/vOhxgo/uMKfRDOmZRd5XWF3vKr5da6qYoxuTJBS/Pl9K.5lrabWoWFFc.71yFMaSlZz0O8FtAtl.\"}" ] - ] + ... + "vendor-extension": [ + [ 61046, "{\"pwhash\":\"$6$9rufAxdqCrxrwfQR$G0l9cTVlu/vOhxgo/uMKfRDOmZRd5XWF3vKr5da6qYoxuTJBS/Pl9K.5lrabWoWFFc.71yFMaSlZz0O8FtAtl.\"}" ] + ] } ```