HackENS/liminix-fork
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

improve markup

Browse source
This commit is contained in:
Daniel Barlow 2023-02-17 20:54:18 +00:00
parent 0777bb47c0
commit db70623bff
1 changed files with 32 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
doc/developer.rst
View file

@ -8,7 +8,7 @@ documents various affordances for iteration and experiments.
In general, packages and tools that run on the "build" machine are In general, packages and tools that run on the "build" machine are
available in the ``buildEnv`` derivation and can most easily available in the ``buildEnv`` derivation and can most easily
be added to your environment by running ``nix-shell`` be added to your environment by running :command:`nix-shell`
@ -27,7 +27,7 @@ To build it,
nix-build -I liminix-config=path/to/your/configuration.nix --arg device "import ./devices/qemu" -A outputs.default 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 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. 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.
@ -37,9 +37,9 @@ serial console and the `QEMU monitor <https://www.qemu.org/docs/master/system/m
If you run with ``--background /path/to/some/directory`` as the first If you run with ``--background /path/to/some/directory`` as the first
parameter, it will fork into the background and open Unix sockets in parameter, it will fork into the background and open Unix sockets in
that directory for console and monitor. Use ``connect-vm`` (also in the that directory for console and monitor. Use :command:`connect-vm`
``buildEnv`` environment) to connect to either of these sockets, and ^O (also in the ``buildEnv`` environment) to connect to either of these
to disconnect. sockets, and ^O to disconnect.
Networking Networking
========== ==========
@ -47,13 +47,13 @@ Networking
VMs can network with each other using QEMU VMs can network with each other using QEMU
socket networking. We observe these conventions, so that we can run socket networking. We observe these conventions, so that we can run
multiple emulated instances and have them wired up to each other in 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:1234 : access (interconnect between router and "isp")
* multicast 230.0.0.1:1235 : lan * multicast 230.0.0.1:1235 : lan
* multicast 230.0.0.1:1236 : world (the internet) * 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 the emulated border network gateway (see below) runs PPPoE and is
connected to "access" and "world". connected to "access" and "world".
@ -65,8 +65,8 @@ In pkgs/routeros there is a derivation to install and configure
concentrator connected to the ``access`` and ``world`` networks, so that concentrator connected to the ``access`` and ``world`` networks, so that
Liminix PPPoE client support can be tested without actual hardware. Liminix PPPoE client support can be tested without actual hardware.
This is made available as the ``routeros`` command in ``buildEnv``, so you This is made available as the :command:`routeros` command in
can do something like:: ``buildEnv``, so you can do something like::
mkdir ros-sockets mkdir ros-sockets
nix-shell nix-shell
@ -95,8 +95,8 @@ TFTP.
There is a rudimentary TFTP server bundled with the system which runs There is a rudimentary TFTP server bundled with the system which runs
from the command line, has an allowlist for client connections, and from the command line, has an allowlist for client connections, and
follows symlinks, so you can have your device download images direct follows symlinks, so you can have your device download images direct
from the ``./result`` directory without exposing ``/nix/store/`` to the from the :file:`./result` directory without exposing :file:`/nix/store/` to the
internet or mucking about copying files to ``/tftproot``. If 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 permitted device is to be given the IP address 192.168.8.251 you might
do something like this: do something like this:
@ -122,9 +122,9 @@ image instead of flashing. In your device configuration add
}; };
and then build ``outputs.tftproot``. This creates a file in and then build ``outputs.tftproot``. This creates a file in
``result/`` called ``boot.scr`` containing commands that you can copy ``result/`` called ``boot.scr``, which you can copy and paste into
and paste into U-Boot which will transfer the kernel and filesystem U-Boot to transfer the kernel and filesystem over TFTP and boot the
over TFTP and boot the kernel from RAM. kernel from RAM.
Networking Networking
@ -144,16 +144,16 @@ 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/ * 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 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 which starts up QEMU using the NixOS configuration in
``bordervm-configuration.nix``. :file:`bordervm-configuration.nix`.
In this VM 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 * 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 * a PPPOE-L2TP relay is running on the same ethernet card, which
spawns L2TPv2 Access Concentrator sessions to your specified spawns L2TPv2 Access Concentrator sessions to your specified
@ -163,18 +163,20 @@ In this VM
service can be configured into your test device - bordervm service can be configured into your test device - bordervm
doesn't need to know about them. doesn't need to know about them.
To configure bordervm, you need a file called ``bordervm.conf.nix`` To configure bordervm, you need a file called :file:`bordervm.conf.nix`
which you can create by copying and appropriately editing ``bordervm.conf-example.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 .. note::
executing ``run-border-vm``, you need to remove the ``border.qcow2``
disk image file otherwise the changes won't get picked up. 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 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 input I use in Hydra. Note that it expects Nixpkgs stable `and` unstable
as inputs, because it builds the qemu device against both. as inputs, because it builds the qemu device against both.
@ -197,9 +199,13 @@ Diagnosing unexpectedly large images
Sometimes you can add a package and it causes the image size to balloon 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 because it has dependencies on other things you didn't know about. Build the
``outputs.manifest`` attribute, which is a JSON representation of 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 nix-store -q --tree manifest