move dts config from kernel to boot

The kernel does not need to know about the DTS. I am prepared
to be very slightly injured on this hill.

THOUGHTS.txt

@@ -674,7 +674,7 @@ are annoying enough that I might poke at them anyway:
 15a) is bordervm derivation tested?
 18) gl-mt300a
 19) gl-mt300n-v2
-
+20) publish the manual using CI
 
 12) write secrets holder as a service with outputs
 16) writable filesystem (ubifs?)

devices/gl-ar750/default.nix

@@ -42,6 +42,12 @@
       boot.tftp = {
         loadAddress = "0x00A00000";
       };
+      boot.dts = {
+        src = "${openwrt}/target/linux/ath79/dts/qca9531_glinet_gl-ar750.dts";
+        includes =  [
+          "${openwrt}/target/linux/ath79/dts"
+        ];
+      };
       kernel = {
         src = pkgs.pkgsBuildBuild.fetchurl {
           name = "linux.tar.gz";
@@ -61,12 +67,6 @@
           patches ${openwrt}/target/linux/generic/hack-5.15/*.patch
           patches ${openwrt}/target/linux/ath79/patches-5.15/*.patch
         '';
-        dts = {
-          src = "${openwrt}/target/linux/ath79/dts/qca9531_glinet_gl-ar750.dts";
-          includes =  [
-            "${openwrt}/target/linux/ath79/dts"
-          ];
-        };
         config = {
           MIPS_ELF_APPENDED_DTB = "y";
           OF = "y";

devices/gl-mt300a/default.nix

@@ -29,6 +29,12 @@
       boot.tftp = {
         loadAddress = "0x00A00000";
       };
+      boot.dts = {
+        src = "${openwrt}/target/linux/ramips/dts/mt7620a_glinet_gl-mt300a.dts";
+        includes = [
+          "${openwrt}/target/linux/ramips/dts"
+        ];
+      };
 
       kernel = {
         src = pkgs.fetchurl {
@@ -49,12 +55,6 @@
           patches ${openwrt}/target/linux/generic/hack-5.15/*.patch
           patches ${openwrt}/target/linux/ramips/patches-5.15/*.patch
         '';
-        dts = {
-          src = "${openwrt}/target/linux/ramips/dts/mt7620a_glinet_gl-mt300a.dts";
-          includes = [
-            "${openwrt}/target/linux/ramips/dts"
-          ];
-        };
         config = {
           MIPS_ELF_APPENDED_DTB = "y";
           OF = "y";

devices/gl-mt300n-v2/default.nix

@@ -29,6 +29,12 @@
       boot.tftp = {
         loadAddress = "0x00A00000";
       };
+      boot.dts = {
+        src = "${openwrt}/target/linux/ramips/dts/mt7628an_glinet_gl-mt300n-v2.dts";
+        includes = [
+          "${openwrt}/target/linux/ramips/dts"
+        ];
+      };
 
       kernel = {
         src = pkgs.fetchurl {
@@ -49,12 +55,6 @@
           patches ${openwrt}/target/linux/generic/hack-5.15/*.patch
           patches ${openwrt}/target/linux/ramips/patches-5.15/*.patch
         '';
-        dts = {
-          src = "${openwrt}/target/linux/ramips/dts/mt7628an_glinet_gl-mt300n-v2.dts";
-          includes = [
-            "${openwrt}/target/linux/ramips/dts"
-          ];
-        };
         config = {
           MIPS_ELF_APPENDED_DTB = "y";
           OF = "y";

doc/developer.rst

@@ -7,11 +7,9 @@ than by building and flashing a new image every time. This manual
 documents various affordances for iteration and experiments.
 
 In general, packages and tools that run on the "build" machine are
-available in the ``buildEnv`` derivation.
+available in the ``buildEnv`` derivation and can most easily
+be added to your environment by running :command:`nix-shell`
 
-.. code-block:: console
-
-    nix-shell -A buildEnv
 
 
 Emulated devices
@@ -29,19 +27,19 @@ To build it,
 
     nix-build -I liminix-config=path/to/your/configuration.nix --arg device "import ./devices/qemu" -A outputs.default
 
-In a ``buildEnv`` nix-shell, you can use the ``mips-vm`` command
+In a ``buildEnv`` nix-shell, you can use the :command:`mips-vm` command
 to run Qemu with appropriate options. It connects the Liminix
 serial console and the `QEMU monitor  <https://www.qemu.org/docs/master/system/monitor.html>`_ to stdin/stdout. Use ^P (not ^A) to switch to the monitor.
 
 .. code-block:: console
 
-    nix-shell -A buildEnv --run "mips-vm result/vmlinux result/squashfs"
+    nix-shell --run "mips-vm result/vmlinux result/squashfs"
 
 If you run with ``--background /path/to/some/directory`` as the first
 parameter, it will fork into the background and open Unix sockets in
-that directory for console and monitor.  Use ``connect-vm`` (also in the
-``buildEnv`` environment) to connect to either of these sockets, and ^O
-to disconnect.
+that directory for console and monitor.  Use :command:`connect-vm`
+(also in the ``buildEnv`` environment) to connect to either of these
+sockets, and ^O to disconnect.
 
 Networking
 ==========
@@ -49,13 +47,13 @@ Networking
 VMs can network with each other using QEMU
 socket networking.  We observe these conventions, so that we can run
 multiple emulated instances and have them wired up to each other in
-the right way
+the right way:
 
 * multicast 230.0.0.1:1234  : access (interconnect between router and "isp")
 * multicast 230.0.0.1:1235  : lan
 * multicast 230.0.0.1:1236  : world (the internet)
 
-A VM started with ``mips-vm`` is connected to "lan" and "access", and
+A VM started with :command:`mips-vm` is connected to "lan" and "access", and
 the emulated border network gateway (see below) runs PPPoE and is
 connected to "access" and "world".
 
@@ -67,11 +65,11 @@ In pkgs/routeros there is a derivation to install and configure
 concentrator connected to the ``access`` and ``world`` networks, so that
 Liminix PPPoE client support can be tested without actual hardware.
 
-This is made available as the ``routeros`` command in ``buildEnv``, so you
-can do something like::
+This is made available as the :command:`routeros` command in
+``buildEnv``, so you can do something like::
 
     mkdir ros-sockets
-    nix-shell -A buildEnv
+    nix-shell
     nix-shell$ routeros ros-sockets
     nix-shell$ connect-vm ./ros-sockets/console
 
@@ -97,15 +95,14 @@ TFTP.
 There is a rudimentary TFTP server bundled with the system which runs
 from the command line, has an allowlist for client connections, and
 follows symlinks, so you can have your device download images direct
-from the ``./result`` directory without exposing ``/nix/store/`` to the
-internet or mucking about copying files to ``/tftproot``. If the
+from the :file:`./result` directory without exposing :file:`/nix/store/` to the
+internet or mucking about copying files to :file:`/tftproot`. If the
 permitted device is to be given the IP address 192.168.8.251 you might
 do something like this:
 
 .. code-block:: console
 
-    nix-shell -A buildEnv
-	 --run "tufted -a 192.168.8.251 result"
+    nix-shell --run "tufted -a 192.168.8.251 result"
 
 and then issue appropriate U-boot commands to download and flash the
 image.
@@ -125,9 +122,9 @@ image instead of flashing. In your device configuration add
   };
 
 and then build ``outputs.tftproot``. This creates a file in
-``result/`` called ``boot.scr`` containing commands that you can copy
-and paste into U-Boot which will transfer the kernel and filesystem
-over TFTP and boot the kernel from RAM.
+``result/`` called ``boot.scr``, which you can copy and paste into
+U-Boot to transfer the kernel and filesystem over TFTP and boot the
+kernel from RAM.
 
 
 Networking
@@ -147,33 +144,39 @@ router from the internet so you can borrow the cable/fibre/DSL.
 * an L2TP service such as https://www.aa.net.uk/broadband/l2tp-service/
 
 You need to configure the Ethernet card for VFIO passthru, then
-you can execute ``run-border-vm`` in a ``buildEnv`` shell,
+you can execute :command:`run-border-vm` in a ``buildEnv`` shell,
 which starts up QEMU using the NixOS configuration in
-``bordervm-configuration.nix``
+:file:`bordervm-configuration.nix`.
 
 In this VM
 
-* your Liminix checkout is mounted under ``/home/liminix/liminix``
+* your Liminix checkout is mounted under :file:`/home/liminix/liminix`
 
 * TFTP is listening on the ethernet device and serving
-  ``/home/liminix/liminix``.  The server IP address is 10.0.0.1
+  :file:`/home/liminix/liminix`.  The server IP address is 10.0.0.1
 
-* a PPPOE-L2TP relay is running on the same ethernet card, which
-  spawns L2TPv2 Access Concentrator sessions to your specified
-  L2TP LNS when the connected Liminix device makes PPPoE requests.
+* a PPPOE-L2TP relay is running on the same ethernet card.  When the
+  connected Liminix device makes PPPoE requests, the relay spawns
+  L2TPv2 Access Concentrator sessions to your specified L2TP LNS.
   Note that authentication is expected at the PPP layer not the L2TP
-  layer, so the same PAP/CHAP credentials provided by your L2TP
-  service can be configured into your test device - bordervm
-  doesn't need to know about them.
+  layer, so the PAP/CHAP credentials provided by your L2TP service can
+  be configured into your test device - bordervm doesn't need to know
+  about them.
 
-To configure bordervm, you need a file called ``bordervm.conf.nix``
-which you can create by copying and appropriately editing  ``bordervm.conf-example.nix``
+To configure bordervm, you need a file called :file:`bordervm.conf.nix`
+which you can create by copying and appropriately editing  :file:`bordervm.conf-example.nix`
+
+.. note::
+
+    If you make changes to the bordervm configuration after executing
+    :command:`run-border-vm`, you need to remove the :file:`border.qcow2` disk
+    image file otherwise the changes won't get picked up.
 
 
 Running tests
 *************
 
-You can run all of the tests by evaluating ``ci.nix``, which is the
+You can run all of the tests by evaluating :file:`ci.nix`, which is the
 input I use in Hydra. Note that it expects Nixpkgs stable `and` unstable
 as inputs, because it builds the qemu device against both.
 
@@ -196,9 +199,13 @@ Diagnosing unexpectedly large images
 Sometimes you can add a package and it causes the image size to balloon
 because it has dependencies on other things you didn't know about. Build the
 ``outputs.manifest`` attribute, which is a JSON representation of the
-filesystem, and you can run ``nix-store --query`` on it.::
+filesystem, and you can run :command:`nix-store --query` on it.
 
-    nix-build -I liminix-config=path/to/your/configuration.nix --arg device "import ./devices/qemu" -A outputs.manifest -o manifest
+.. code-block:: console
+
+    nix-build -I liminix-config=path/to/your/configuration.nix \
+      --arg device "import ./devices/qemu" -A outputs.manifest \
+      -o manifest
     nix-store -q --tree manifest
 
 

modules/base.nix

@@ -29,13 +29,6 @@ in {
         default = "true";
         type = types.lines;
       } ;
-      dts = {
-        src = mkOption { type = types.path; };
-        includes = mkOption {
-          default = [];
-          type = types.listOf types.path;
-        };
-      };
       config = mkOption {
         # mostly the values are y n or m, but sometimes
         # other strings are also used
@@ -48,9 +41,18 @@ in {
     users =  mkOption {
       type = types.attrsOf types.anything;
     };
-    boot.commandLine = mkOption {
-      type = types.listOf types.nonEmptyStr;
-      default = [];
+    boot = {
+      dts = {
+        src = mkOption { type = types.path; };
+        includes = mkOption {
+          default = [];
+          type = types.listOf types.path;
+        };
+      };
+      commandLine = mkOption {
+        type = types.listOf types.nonEmptyStr;
+        default = [];
+      };
     };
     device.defaultOutput = mkOption {
       type = types.nonEmptyStr;

modules/outputs.nix

@@ -23,8 +23,8 @@ in
         inherit (config.kernel) config src extraPatchPhase;
       };
       dtb =  (callPackage ../kernel/dtb.nix {}) {
-        dts = config.kernel.dts.src;
-        includes = config.kernel.dts.includes ++ [
+        dts = config.boot.dts.src;
+        includes = config.boot.dts.includes ++ [
           "${kernel.headers}/include"
         ];
       };

shell.nix

@@ -5,4 +5,9 @@ let
     liminix-config = ./vanilla-configuration.nix;
     inherit nixpkgs;
   });
-in liminix
+in liminix.buildEnv.overrideAttrs (o: {
+  nativeBuildInputs = o.nativeBuildInputs ++ [ (import nixpkgs {}).sphinx ] ;
+  shellHook = ''
+    publish(){  make -C doc html && rsync -azv doc/_build/html/ myhtic.telent.net:/var/www/blogs/www.liminix.org/_site/doc; }
+  '';
+})