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