Documentation

documentation/1 - toolchain.md

@@ -0,0 +1,75 @@
+# Mittos toolchain
+
+> - [Mittos64 documentation chapter 1](https://github.com/thomasloven/mittos64/blob/master/doc/1_Toolchain.md).
+
+Building and emulating/debugging Mittos is done with Docker and docker-compose.
+
+Two containers are defined in the compose file `/toolchain/docker-compose.yml`
+
+To build them run
+```
+> docker-compose -f toolchain/docker-compose.yml build
+```
+
+The build image (`thomasloven/mittos-build`) derives from Alpine. \
+It includes a custom compiled version of gnu binutils and gcc, so it will take a few minutes to build. It also includes grub-bios and xorriso in order to build a bootable image as well as python3, git and rsync.
+
+The run image (`thomasloven/mittos-run`) derives from Debian. \
+It includes qemu and gdb for testing and debugging. It also includes novnc and will serve a HTTP vnc server on port 6080 for graphical output from qemu.
+
+## Building
+Run
+```
+> ./make
+```
+This will run the make command inside a mittos-build container. Any arguments (e.g. `make kernel`) will be forwarded.
+
+If the first argument is a dash, the following command will be run instead of `make`. E.g. `make - sh` to open a shell in the build container.
+
+## Testing
+To run the built Mittos in qemu, run
+```
+> ./emu
+```
+This will launch `qemu` inside a mittos-run container. An interface to qemu is published to [http://localhost:6080](http://localhost:6080) and also to the terminal output.
+
+The emulator is setup to not start running until a debugger has attached. Do this with
+```
+> ./dbg
+```
+which launches `gdb` and attaches it to the running container.
+
+Both commands pass any arguments to `qemu` or `gdb` respectively unless the first argument is `-` in which case the following command override the default.
+Note that the dbg script will always wait for a qemu debug connection to be available before starting, though.
+
+## Running on real hardware
+The image created by `make dist` should work when burned to a USB stick and booted on a BIOS machine.
+
+For booting on a UEFI machine, you need to create a bootable USB stick from a machine with grub-uefi installed.
+
+Format your stick with a single FAT partition `sd<XX>` and mount it to `/media/<MOUNTPOINT>`. Then run:
+
+```
+> sudo grub-install --no-floppy --root-directory=/media/<MOUNTPOINT> --recheck --force --target=i386-pc /dev/sd<XX>
+```
+
+You can then put Mittos on it (and sync changes) with
+```
+> rsync -urv sysroot/ /media/<USB stick mountpoint>
+```
+
+
+## Relevant files:
+
+- `toolchain/docker-compose.yml`
+    - `toolchain/Dockerfile.build`
+        - `toolchain/build-toolchain.sh`
+    - `toolchain/Dockerfile.run`
+        - `toolchain/run-entrypoint.sh`
+- `make`
+- `emu`
+- `dbg`
+- `Makefile`
+- `src/kernel/Makefile`
+- `toolchain/setup-grub.sh`
+- `toolchain/gdbinit`

toolchain/build-toolchain.sh

@@ -14,6 +14,7 @@ SYSROOT=/opt/sysroot
 binutils=binutils-2.37
 gcc=gcc-11.2.0
 
+# Download and install musl headers
 mkdir -p /opt/external
 cd /opt/external
 [ -d musl ] || git clone --depth=1 git://git.musl-libc.org/musl