From 8dd7bb958a1fd9f5edd2e1f6b5aea4324a06aea3 Mon Sep 17 00:00:00 2001
From: Daniel Barlow <dan@telent.net>
Date: Sat, 24 Sep 2022 21:03:26 +0100
Subject: [PATCH] improve qemu tooling, and document it

---
 README.md               | 48 ++++++++++++++++++++++++++++++++++++++---
 run-qemu.sh             |  8 -------
 scripts/connect-qemu.sh |  2 ++
 scripts/run-qemu.sh     | 22 +++++++++++++++++++
 4 files changed, 69 insertions(+), 11 deletions(-)
 delete mode 100755 run-qemu.sh
 create mode 100755 scripts/connect-qemu.sh
 create mode 100755 scripts/run-qemu.sh

diff --git a/README.md b/README.md
index 0cad9bc..ec457e5 100644
--- a/README.md
+++ b/README.md
@@ -32,11 +32,53 @@ you plan to install onto it. For example:
 
 `outputs.default` is intended to do something appropriate for the
 device, whatever that is. For the qemu device, it creates a directory
-containing a squashfs root image and a kernel, with which you could
-then run
+containing a squashfs root image and a kernel.
 
-    ./run-qemu.sh result/vmlinux result/squashfs
 
+## QEMU
+
+QEMU is useful for developing userland without needing to keep
+flashing or messing with U-Boot: it also enables testing against
+emulated network peers using [QEMU socket networking](https://wiki.qemu.org/Documentation/Networking#Socket),
+which may be preferable to letting Liminix loose on your actual LAN.
+
+We have some tooling to make this easier.
+
+### Networks
+
+We observe these conventions for QEMU network sockets, so that we can
+run multiple emulated instances and have them wired up to each other
+in 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)
+
+### Running instances
+
+`./scripts/run-qemu.sh` accepts a kernel vmlinux image and a squashfs
+and runs qemu with appropriate config for two ethernet interfaces
+hooked up to "lan" and "access" respectively. 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.
+
+If you run with `--background /path/to/unix/socket` it will fork into
+the background and open a Unix socket at that pathname to communicate
+on. Use `./scripts/connect-qemu.sh` to connect to it, and ^O to
+disconnect.
+
+### Emulated upstream connection
+
+In the tests/support/ppp-server directory there are instructions and a script
+to configure [Mikrotik RouterOS](https://mikrotik.com/software) as
+a PPPoE access concentrator connected to the `access` and `world`
+networks, so that Liminix PPPoE client support can be tested.
+_Liminix does not provide RouterOS licences and it is your own
+responsibility if you use this to ensure you're compliant with
+the terms of Mikrotik's licencing._
+
+This may be supplemented or replaced in time with configuurations for
+RP-PPPoE and/or Accel PPP.
 
 ## Running tests
 
diff --git a/run-qemu.sh b/run-qemu.sh
deleted file mode 100755
index f530683..0000000
--- a/run-qemu.sh
+++ /dev/null
@@ -1,8 +0,0 @@
-#!/usr/bin/env nix-shell
-#! nix-shell -i bash -p qemu
-
-qemu-system-mips \
-    -M malta -m 256 \
-    -append "default console=ttyS0,38400n8 panic=10 oops=panic init=/bin/init  loglevel=8 root=/dev/vda" \
-    -drive file=$2,format=raw,readonly,if=virtio \
-    -kernel $1  -nographic -display none -serial mon:stdio
diff --git a/scripts/connect-qemu.sh b/scripts/connect-qemu.sh
new file mode 100755
index 0000000..27f3f69
--- /dev/null
+++ b/scripts/connect-qemu.sh
@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+nix-shell -p socat --run "socat -,raw,echo=0,icanon=0,isig=0,icrnl=0,escape=0x0f    unix-connect:$1"
diff --git a/scripts/run-qemu.sh b/scripts/run-qemu.sh
new file mode 100755
index 0000000..cad03e4
--- /dev/null
+++ b/scripts/run-qemu.sh
@@ -0,0 +1,22 @@
+#!/usr/bin/env nix-shell
+#! nix-shell -i bash -p qemu
+
+if test "$1" = "--background" ; then
+    socket=$2
+    echo "running in background, socket is $socket"
+    flags="--daemonize -chardev socket,id=sock,path=$2,server=on,wait=off,mux=on -mon chardev=sock,mode=readline -serial chardev:sock  "
+    shift;shift
+else
+    flags="-serial mon:stdio"
+fi
+
+qemu-system-mips \
+    -M malta -m 256 \
+    -echr 16 \
+    -append "default console=ttyS0,38400n8 panic=10 oops=panic init=/bin/init  loglevel=8 root=/dev/vda" \
+    -drive file=$2,format=raw,readonly=on,if=virtio \
+    -netdev socket,id=access,mcast=230.0.0.1:1234 \
+    -device virtio-net-pci,disable-legacy=on,disable-modern=off,netdev=access,mac=ba:ad:1d:ea:21:02 \
+    -netdev socket,id=lan,mcast=230.0.0.1:1235 \
+    -device virtio-net-pci,disable-legacy=on,disable-modern=off,netdev=lan,mac=ba:ad:1d:ea:21:01 \
+    -kernel $1 -display none $flags