mittos65/documentation/1 - toolchain.md

Mittos toolchain

• Mittos64 documentation chapter 1.

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 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