From 7cfb92e3ced96ca6d71768e616ca437fba421bcc Mon Sep 17 00:00:00 2001 From: Daniel Barlow Date: Fri, 10 Nov 2023 21:17:20 +0000 Subject: [PATCH] more doc --- ci.nix | 1 + devices/belkin-rt3200/default.nix | 5 ++- devices/gl-mt300a/default.nix | 5 ++- devices/gl-mt300n-v2/default.nix | 5 ++- devices/qemu-aarch64/default.nix | 21 ++++++++-- devices/qemu-armv7l/default.nix | 18 ++++++-- devices/qemu/default.nix | 24 +++++------ doc/development.rst | 2 + doc/hardware.nix | 8 ++-- modules/all-modules.nix | 4 +- modules/outputs.nix | 2 + modules/{ => outputs}/flashimage.nix | 0 modules/{ => outputs}/ubimage.nix | 63 +++++++++++++++++----------- modules/standard.nix | 2 +- 14 files changed, 102 insertions(+), 58 deletions(-) rename modules/{ => outputs}/flashimage.nix (100%) rename modules/{ => outputs}/ubimage.nix (75%) diff --git a/ci.nix b/ci.nix index ef65ad0..c0f91c3 100644 --- a/ci.nix +++ b/ci.nix @@ -42,6 +42,7 @@ let installers = map (f: "system.outputs.${f}") [ "vmroot" "flashimage" + "ubimage" ]; inherit (pkgs.lib) concatStringsSep; in pkgs.stdenv.mkDerivation { diff --git a/devices/belkin-rt3200/default.nix b/devices/belkin-rt3200/default.nix index 0e8197e..069a78b 100644 --- a/devices/belkin-rt3200/default.nix +++ b/devices/belkin-rt3200/default.nix @@ -1,4 +1,4 @@ -{ +rec { description = '' Belkin RT-3200 / Linksys E8450 ****************************** @@ -17,6 +17,7 @@ - b/g/n wireless using MediaTek MT7622BV (MT7615E driver) - a/n/ac/ax wireless using MediaTek MT7915E ''; + installer = "ubimage"; system = { crossSystem = { @@ -160,7 +161,7 @@ maxLEBcount = "1024"; # guessing }; - defaultOutput = "ubimage"; + defaultOutput = installer; # the kernel expects this to be on a 2MB boundary. U-Boot # (I don't know why) has a default of 0x41080000, which isn't. # We put it at the 32MB mark so that tftpboot can put its rootfs diff --git a/devices/gl-mt300a/default.nix b/devices/gl-mt300a/default.nix index b3fabbc..c45d394 100644 --- a/devices/gl-mt300a/default.nix +++ b/devices/gl-mt300a/default.nix @@ -1,6 +1,6 @@ # GL.iNet GL-MT300A -{ +rec { system = { crossSystem = { config = "mipsel-unknown-linux-musl"; @@ -54,6 +54,7 @@ OpenWrt web page: https://openwrt.org/toh/gl.inet/gl-mt300a ''; + installer = "flashimage"; module = { pkgs, config, lib, ...}: let @@ -66,7 +67,7 @@ in { imports = [ ../../modules/arch/mipsel.nix ]; hardware = { - defaultOutput = "flashimage"; + defaultOutput = installer; loadAddress = "0x80000000"; entryPoint = "0x80000000"; diff --git a/devices/gl-mt300n-v2/default.nix b/devices/gl-mt300n-v2/default.nix index 0198b6c..8f7a966 100644 --- a/devices/gl-mt300n-v2/default.nix +++ b/devices/gl-mt300n-v2/default.nix @@ -1,4 +1,4 @@ -{ +rec { system = { crossSystem = { config = "mipsel-unknown-linux-musl"; @@ -23,6 +23,7 @@ OpenWrt web page: https://openwrt.org/toh/gl.inet/gl-mt300n_v2 ''; + installer = "flashimage"; module = { pkgs, config, lib, ...}: let @@ -49,7 +50,7 @@ }; }; hardware = { - defaultOutput = "flashimage"; + defaultOutput = installer; loadAddress = "0x80000000"; entryPoint = "0x80000000"; diff --git a/devices/qemu-aarch64/default.nix b/devices/qemu-aarch64/default.nix index ea0ccfe..28f3477 100644 --- a/devices/qemu-aarch64/default.nix +++ b/devices/qemu-aarch64/default.nix @@ -2,16 +2,29 @@ # emulator. The default output is a directory containing separate # kernel ("Image" format) and root filesystem (squashfs or jffs2) # images -{ +rec { system = { crossSystem = { config = "aarch64-unknown-linux-musl"; }; }; - # this device is described by the "qemu" device - description = ""; + description = '' + QEMU Aarch64 + ************ + This target produces an image for + the `QEMU "virt" platform `_ using a 64 bit CPU type. + + ARM targets differ from MIPS in that the kernel format expected + by QEMU is an "Image" (raw binary file) rather than an ELF + file, but this is taken care of by :command:`run.sh`. Check the + documentation for the :ref:`QEMU` (MIPS) target for more information. + + ''; + + # this device is described by the "qemu" device + installer = "vmroot"; module = {pkgs, config, ... }: { imports = [ ../../modules/arch/aarch64.nix ]; @@ -51,7 +64,7 @@ klibBuild = config.system.outputs.kernel.modulesupport; }; in { - defaultOutput = "vmroot"; + defaultOutput = installer; loadAddress = "0x0"; entryPoint = "0x0"; rootDevice = "/dev/mtdblock0"; diff --git a/devices/qemu-armv7l/default.nix b/devices/qemu-armv7l/default.nix index b06fbc2..3c73e54 100644 --- a/devices/qemu-armv7l/default.nix +++ b/devices/qemu-armv7l/default.nix @@ -2,7 +2,7 @@ # emulator. The default output is a directory containing separate # kernel ("Image" format) and root filesystem (squashfs or jffs2) # images -{ +rec { system = { crossSystem = { config = "armv7l-unknown-linux-musleabihf"; @@ -10,7 +10,19 @@ }; # this device is described by the "qemu" device - description = ""; + description = '' + QEMU ARM v7 + *********** + + This target produces an image for + the `QEMU "virt" platform `_ using a 32 bit CPU type. + + ARM targets differ from MIPS in that the kernel format expected + by QEMU is an "Image" (raw binary file) rather than an ELF + file, but this is taken care of by :command:`run.sh`. Check the + documentation for the :ref:`QEMU` (MIPS) target for more information. + ''; + installer = "vmroot"; module = {pkgs, config, ... }: { imports = [ ../../modules/arch/arm.nix ]; @@ -54,7 +66,7 @@ klibBuild = config.system.outputs.kernel.modulesupport; }; in { - defaultOutput = "vmroot"; + defaultOutput = installer; loadAddress = "0x00010000"; entryPoint = "0x00010000"; rootDevice = "/dev/mtdblock0"; diff --git a/devices/qemu/default.nix b/devices/qemu/default.nix index 3d5e756..5582674 100644 --- a/devices/qemu/default.nix +++ b/devices/qemu/default.nix @@ -1,7 +1,4 @@ -# This "device" generates images that can be used with the QEMU -# emulator. The default output is a directory containing separate -# kernel (uncompressed vmlinux) and initrd (squashfs) images -{ +rec { system = { crossSystem = { config = "mips-unknown-linux-musl"; @@ -13,24 +10,21 @@ }; description = '' - QEMU - **** + QEMU MIPS + ********* - This is not a hardware device. This target produces an image for + This target produces an image for QEMU, the "generic and open source machine emulator and virtualizer". - Liminix can build QEMU for both MIPS (:code:`qemu` device) and Aarch64 (:code:`qemu-aarch64` device) - MIPS QEMU emulates a "Malta" board, which was an ATX form factor evaluation board made by MIPS Technologies, but mostly in Liminix we use paravirtualized devices (Virtio) instead of emulating - hardware. For Aarch64 we use the QEMU "virt" board. + hardware. Building an image for QEMU results in a :file:`result/` directory - containing ``run.sh`` ``vmlinux``, ``rootfs`` and possibly - (architecture-dependent) ``Image``. To invoke the emulator, - run ``run.sh``. + containing ``run.sh`` ``vmlinux``, and ``rootfs`` files. To invoke + the emulator, run ``run.sh``. The configuration includes two emulated "hardware" ethernet devices and the kernel :code:`mac80211_hwsim` module to @@ -39,6 +33,8 @@ in the Development manual. ''; + installer = "vmroot"; + module = {pkgs, config, ... }: { imports = [ ../../modules/arch/mipseb.nix ]; kernel = { @@ -74,7 +70,7 @@ klibBuild = config.system.outputs.kernel.modulesupport; }; in { - defaultOutput = "vmroot"; + defaultOutput = installer; rootDevice = "/dev/mtdblock0"; flash.eraseBlockSize = "65536"; # c.f. pkgs/run-liminix-vm/run-liminix-vm.sh networkInterfaces = diff --git a/doc/development.rst b/doc/development.rst index 9e5e0b8..8acfeec 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -56,6 +56,8 @@ Any VM started by a :command:`run.sh` script is connected to "lan" and "access", and the emulated border network gateway (see below) runs PPPoE and is connected to "access" and "world". +.. _border-network-gateway: + Border Network Gateway ---------------------- diff --git a/doc/hardware.nix b/doc/hardware.nix index bde42da..495eca2 100644 --- a/doc/hardware.nix +++ b/doc/hardware.nix @@ -1,15 +1,15 @@ with import {} ; let - devices = - builtins.readDir ../devices; + devices = builtins.readDir ../devices; + inherit (builtins) stringLength; texts = lib.mapAttrsToList (n: t: let d = import ../devices/${n}/default.nix; d' = { - description = "no description for ${n}"; + description = "${n}\n${substring 0 (stringLength n) "********************************"}\n"; } // d; installer = - if d ? installer + if d ? description && d ? installer then '' The default installation route for this device is diff --git a/modules/all-modules.nix b/modules/all-modules.nix index dce38af..e160113 100644 --- a/modules/all-modules.nix +++ b/modules/all-modules.nix @@ -11,7 +11,6 @@ ./dnsmasq ./ext4fs.nix ./firewall - ./flashimage.nix ./hardware.nix ./hostapd ./hostname.nix @@ -24,6 +23,8 @@ ./ntp ./outputs.nix ./outputs/vmroot.nix + ./outputs/ubimage.nix + ./outputs/flashimage.nix ./ppp ./ramdisk.nix ./squashfs.nix @@ -31,7 +32,6 @@ ./standard.nix ./tftpboot.nix ./ubifs.nix - ./ubimage.nix ./users.nix ./vlan ./watchdog diff --git a/modules/outputs.nix b/modules/outputs.nix index 2d51331..5e7039d 100644 --- a/modules/outputs.nix +++ b/modules/outputs.nix @@ -12,6 +12,8 @@ in imports = [ ./squashfs.nix ./outputs/vmroot.nix + ./outputs/flashimage.nix + ./outputs/ubimage.nix ]; options = { system.outputs = { diff --git a/modules/flashimage.nix b/modules/outputs/flashimage.nix similarity index 100% rename from modules/flashimage.nix rename to modules/outputs/flashimage.nix diff --git a/modules/ubimage.nix b/modules/outputs/ubimage.nix similarity index 75% rename from modules/ubimage.nix rename to modules/outputs/ubimage.nix index 17b96f7..8296321 100644 --- a/modules/ubimage.nix +++ b/modules/outputs/ubimage.nix @@ -6,11 +6,19 @@ }: let inherit (lib) mkIf mkEnableOption mkOption types concatStringsSep; - loadaddr = config.boot.tftp.loadAddress; cfg = config.boot.tftp; - instructions = pkgs.writeText "INSTALL.md" '' - -# First-time installation + instructions = pkgs.writeText "env.scr" '' + setenv serverip ${cfg.serverip} + setenv ipaddr ${cfg.ipaddr} + setenv loadaddr ${cfg.loadAddress} +''; +in { + options.system.outputs = { + ubimage = mkOption { + type = types.package; + description = '' +ubimage +******* First-time installation of a UBIFS Liminix system presently can only be done from the U-Boot command line (or from a ramdisk-based recovery @@ -25,13 +33,17 @@ U-Boot 1) determine which MTD device is being used for UBI and the partition name: +.. code-block:: console + uboot> ubi part Device 0: ubi0, MTD partition ubi -In this case the important value is `ubi0` +In this case the important value is ``ubi0`` 2) list the available volumes and create a new one on which to install Liminix +.. code-block:: console + uboot> ubi info l [ copious output scrolls past ] @@ -40,32 +52,39 @@ important. Unless you know what you're doing, don't remove anything whose name suggests it's related to uboot, or any kind of backup or recovery partition. To see how much space is free: +.. code-block:: console + uboot> ubi info [ ... ] UBI: available PEBs: 823 Now we can make our new root volume +.. code-block:: console + uboot> ubi create liminix - 3) transfer the root filesystem from the build system and write it -to the new volume +to the new volume. Paste the environment variable settings from +:file:`result/env.scr` into U-Boot, then run - uboot> setenv serverip ${cfg.serverip} - uboot> setenv ipaddr ${cfg.ipaddr} - uboot> tftpboot ${loadaddr} result/rootfs - uboot> ubi write ${loadaddr} liminix $filesize +.. code-block:: console + + uboot> tftpboot ''${loadaddr} result/rootfs + uboot> ubi write ''${loadaddr} liminix $filesize Now we have the root filesystem installed on the device. You -can even mount it and poke around using `ubifsmount ubi0:liminix; -ubifsls /` +can even mount it and poke around using ``ubifsmount ubi0:liminix; +ubifsls /`` 4) optional: before you configure the device to boot into Liminix automatically, you can try booting it by hand to see if it works: +.. code-block:: console + uboot> ubifsmount ubi0:liminix - uboot> ubifsload ${loadaddr} boot/uimage - uboot> bootm ${loadaddr} + uboot> ubifsload ''${loadaddr} boot/uimage + uboot> bootm ''${loadaddr} Once you've done this and you're happy with it, reset the device to U-Boot. You don't need to recreate the volume but you do need to @@ -76,7 +95,9 @@ device-dependent. On the Linksys E8450/Belkin RT3200, the environment variable `boot_production` governs what happens on a normal boot, so you could do - uboot> setenv boot_production 'led $bootled_pwr on ; ubifsmount ubi0:liminix; ubifsload ${loadaddr} boot/uimage; bootm ${loadaddr}' +.. code-block:: console + + uboot> setenv boot_production 'led $bootled_pwr on ; ubifsmount ubi0:liminix; ubifsload ''${loadaddr} boot/uimage; bootm ''${loadaddr}' On other devices, some detective work may be needed. Try running `printenv` and look for likely commands, try looking at the existing @@ -84,15 +105,9 @@ boot process, maybe even try looking for documentation for that device. 6) Now you can reboot the device into Liminix - uboot> reset +.. code-block:: console -''; -in { - options.system.outputs = { - ubimage = mkOption { - type = types.package; - description = '' - UBIFS image and instructions to install it + uboot> reset ''; }; }; @@ -105,7 +120,7 @@ in { mkdir $out cd $out ln -s ${o.rootfs} rootfs - ln -s ${instructions} INSTALL + ln -s ${instructions} env.scr ''; }; }; diff --git a/modules/standard.nix b/modules/standard.nix index c89017a..4c6b37d 100644 --- a/modules/standard.nix +++ b/modules/standard.nix @@ -5,7 +5,7 @@ imports = [ ./tftpboot.nix ./kexecboot.nix - ./flashimage.nix + ./outputs/flashimage.nix ./jffs2.nix ./ubifs.nix ];