From 323bfc9d66ea8f14c524a78eb3fd5ea91c830716 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Mon, 7 Apr 2025 14:07:43 +0200 Subject: [PATCH] doc: add netboot howto, for developers [skip ci] Signed-off-by: Joachim Wiberg --- doc/developers-guide.md | 15 +++-- doc/netboot.md | 130 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 140 insertions(+), 5 deletions(-) create mode 100644 doc/netboot.md diff --git a/doc/developers-guide.md b/doc/developers-guide.md index 45b8fd2c..e8210c89 100644 --- a/doc/developers-guide.md +++ b/doc/developers-guide.md @@ -131,6 +131,8 @@ This rebuilds (and installs) `foo` and `bar`, the `all` target calls on Buildroot to finalize the target filesystem and generate the images. The final `run` argument is explained below. + + ### `confd` The Infix `src/confd/` is the engine of the system. Currently it is a @@ -217,21 +219,24 @@ structure of an existing one. However, before making any changes, **always discu them with the Infix core team**. This helps avoid issues later in development and makes pull request reviews smoother. + Testing ------- Manual testing can be done using Qemu by calling make run, -see also [Infix in Virtual Environments](virtual.md). +see also [Infix in Virtual Environments](virtual.md), or on a physical +device by upgrading to the latest build or "[netbooting](netboot.md)" +and running the image from RAM. The latter is how most board porting +work is done -- **much quicker** change-load-test cycles. The Infix automated test suite is built around Qemu and [Qeneth][2], see: * [Testing](testing.md) * [Docker Image](../test/docker/README.md) -With any new feature added to Infix, it is essential to include a -relevant test case. See the -[Test Development](testing.md#test-development) section for guidance -on adding test cases. +With any new feature added to Infix, it is essential to include relevant +test case(s). See the [Test Development](testing.md#test-development) +section for guidance on adding test cases. Reviewing diff --git a/doc/netboot.md b/doc/netboot.md new file mode 100644 index 00000000..202f0daa --- /dev/null +++ b/doc/netboot.md @@ -0,0 +1,130 @@ +Netboot HowTo +============= + +This document describes how to set up network booting U-Boot devices on +a LAN, e.g., when working with an evaluation board or other embedded +system. The most secure way to do this is with a local LAN between a PC +and the device. + +Instead of setting up everything in U-Boot to download the Linux Image, +device tree, and initramfs, we will let U-Boot download a script with +instructions to run. When you have multiple systems (boards) this +quickly becomes a lot easier to manage. + +> [!NOTE] +> Instructions in this HowTo assume a Debian based development system, +> e.g., Ubuntu or Linux Mint. + + +## Network Interface Setup + +For two dedicated network interfaces, here `eth2` and `eth3` (ymmv), we +create an old-style interfaces config[^1] with the following content: + +``` +# /etc/network/interfaces.d/gimli +auto eth2 +iface eth2 inet static + address 192.168.0.1 + netmask 255.255.255.0 + +auto eth3 +iface eth3 inet manual +``` + +> [!TIP] +> Use configuration file names in `.d/` directories that make sense and +> can easily be remembered. Here we use the hostname of the PC. + + +## DHCP/TFTP Server Setup + +The examples given here use `dnsmasq`, which provides both DHCP and TFTP +server support. The same can be achieved with other implementations. + +Similar to `interfaces.d`, dnsmasq has an `/etc/dnsmasq.d` directory so +we can use "snippets" instead of modifying `/etc/dnsmasq.conf` directly. +Add a file called `/etc/dnsmasq.d/gimli`. + +Initial content: + +``` +# Remember IP address handed out to BOOTP clients +bootp-dynamic +# Disable check-if-ip-address-is-already-used +no-ping + +# Enable TFTP server, use /srv/ftp, same as any FTP server, useful +# when using the same images for system upgrade as for netbooting. +enable-tftp +tftp-root=/srv/ftp +``` + +> [!CAUTION] +> First of all, make sure you DO NOT accidentally set up dnsmasq so that +> it starts acting as a DHCP server also on your office LAN! Follow the +> instructions below for more details. + +If you have many interfaces used for lab equipment and only one office +LAN interface, then use something like this: + +``` +# Disable DHCP server on loopback and office LAN (eth0) +except-interface=lo +except-interface=eth0 +``` + +To further lock this down, we only run the DHCP server on each of the +interfaces used for lab equipment, with a dedicated IP range as well: + +``` +# Currently I have an imx8mp-evk on eth2, so on my system I have a +# symlink bootfile-eth2 -> netboot.scr +interface=eth2 +dhcp-range=192.168.0.100,192.168.0.199,1h +dhcp-boot=tag:eth2,bootfile-eth2 +``` + +## Bootfile netboot.scr + +The bootfile U-Boot retrieves from the TFTP server is a script that +looks like this, `netboot.sh`: + +```sh +setenv ramdisk_addr_r 0x58000000 +setenv fdt_addr_r 0x50400000 + +setenv autoboot off +tftp ${fdt_addr_r} imx8mp-evk/imx8mp-evk.dtb +tftp ${kernel_addr_r} imx8mp-evk/Image +tftp ${ramdisk_addr_r} imx8mp-evk/rootfs.squashfs + +setenv bootargs console=ttymxc1,115200 root=/dev/ram0 brd.rd_size=500000 rauc.slot=net +booti ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr_r} +``` + +U-Boot cannot read script files directly, so we need to wrap it with a +FIT format header, this is done by first converting it on the PC: + +``` +$ mkimage -T script -d netboot.sh netboot.scr +``` + +The output is `netboot.scr` which we symlink to above in the dnsmasq +setup step. + + +## U-Boot Commands + +U-Boot is a maze of environment variables, some with values, some wrap +commands, and most are undocumented. We will use a prefix for our +variables to ensure we do not overwrite anything you may want to use +later. + +```sh +==> setenv ixboot 'dhcp && source \${fileaddr}' +==> saveenv +``` + + +[^1]: To prevent NetworkManager from automatically managing the interfaces.