peter/infix
1
0
Fork 0
mirror of https://github.com/kernelkit/infix.git synced 2026-07-22 01:13:00 +02:00
Code Issues Packages Projects Releases Wiki Activity

doc: minor cleanup, fix markdown syntax and admonitions

Browse Source 
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
2025-07-30 14:58:05 +02:00
parent c574f23210
commit 67838fa66b
3 changed files with 53 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/boot.md
+15 -18
View File
@@ -146,8 +146,7 @@ To initiate a system upgrade from the shell[^1], run:
rauc install <file|url>
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
doc/developers-guide.md
+28 -20
View File
@@ -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
doc/vpd.md
+10 -8
View File
@@ -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.\"}" ]
]
}
```