MINIX 1.1

MINIX 1.1 source code with cross-platform 8088 build environment.

Build env tested on Debian 13, x86-64, but should work with minimal effort on any recent version of Linux.

Getting up and running quickly

• Run make dev86 to setup the 8088 cross-compile toolchain.
• Build MINIX with make.
• Create 360K MINIX floppy disk images with make disks.

Hacking MINIX

• Run make dev86 followed by make disks to build MINIX and create some disks.
• Boot from a PC emulator with 640K of RAM. E.g. Use a 5150/5160 machine on pcjs.org, or install something locally like 86Box.
• Make changes to the OS by working on the files in the src directory.
• Run make disks to rebuild MINIX and the disks and boot the system again with your changes.

You can run source ./scripts/activate-shell from the project root to spawn a new shell with the dev86 toolchain added to your path, making life easier when running the toolchain outside of make or reading the man pages.

Speed tips

Disk IO is often a significant bottleneck when working with MINIX 1. Configuring 86Box floppy disk drives to use "turbo timings" speeds things up a lot.

Resources

A copy of Tanenbaum's "Operating Systems: Design and Implementation", FIRST EDITION, is highly recommended when working with MINIX 1 as it contains a huge amount of documentation.

The ./disks directory contains the original MINIX 1.1 disks distributed by Prentice-Hall.

What is this?

This project allows the original MINIX 1.1 operating system, as distributed at the time of the launch of Tanenbaum's original "Operating Systems: Design and Implementation" book in 1987, to be built on a modern system (tested with an x86-64).

Developing MINIX on an original 4.77 MHz IBM XT with 640K of RAM is a tedious process by today's standards. Building takes a couple of hours and many floppy disk swaps, and the environment contains only a rudimentary text editor (mined). On the other hand, cross-compiling MINIX from a modern PC takes just a couple of seconds (tested on an AMD Ryzen 9 6900HX), doesn't require floppy disk swaps to work with different parts of the source tree and allows working from your most productive editer/IDE.

The first edition of Tanenbaum's "Operating Systems: Design and Implementation" was released in 1987. It contains a detailed explanation of both the concepts and source code that make up the original MINIX operating system. This makes MINIX a great way to get your hands dirty and explore the internals of a fully functioning operating system.

MINIX 1.1 was designed to run on the 16-bit 8086/8088 processor, which is no longer supported as a compilation target by modern compilers like gcc or clang. Furthermore, the source code is written in a very old, pre-ANSI dialect of C (K&R) and the assembly listings use an old PC-IX syntax. This means that the MINIX 1.1 source code cannot be built using the standard toolchains of today.

However, MINIX 1 is still valuable as both an educational tool and to satisfy historical curiosity. Luckily, the dev86 cross-compilation toolchain has been maintained for many years and is relatively straitforward to set up on modern hardware. It includes an 8088 K&R C cross-compiler (Bruce's C Compiler), assembler, linker and a bunch of other helpful tools.

This project pulls together these tools and the MINIX source code making it easy to build the original MINIX OS for the original hardware. It also produces 360K MINIX boot floppy disk images that are compatible with the IBM PC/XT (5150/5160) machines that the OS was originally designed to run on. The disk images can be used with PC emulators like 86Box, MartyPC and pcjs, or with period hardware.

Running MINIX

Using an 8088 emulator

TODO

On the metal

TODO: Test on an Olivetti PCS86, XT class machine once floppy driver is fixed.

Cross-compilation build environment

The 8086/8088 cross-compilation toolchain is provided by Bruce Evans's bcc/as86/ld86 tools (currently maintained in the dev86 project), rathen than the original MINIX toolchain (ACK - Amsterdam Compiler Kit). Minimal updates to the MINIX source code are included to work with this newer toolchain. Dev86 is included in vendor/dev86 directory and is built on the host machine by running make dev86 from the project root.

The project makefiles use hardcoded paths to utilise the included dev86 toolchain, but it can get tedious as a human to use these same paths when experimenting/running the tools yourself. To update your shell's $PATH and $MANPATH variables run source ./scripts/activate-shell from the project root. This allows the more convenient bcc, man bcc, etc. commands to be used rather than something like ../../vendor/bcc/bin/bcc or MANPATH=../../vendor/bcc/man man bcc.

Building MINIX

Running make will build each part of MINIX: libc, kernel, mm, fs, init, fsck and bootblok. Running make disks will create the MINIX 360K floppy disk images. The bootdisk can then be used to boot MINIX from an IBM PC/XT or simulator.

Compiling MINIX executables

The headers generated by ld86 are compatible with MINIX with the following important caveat: The MINIX exec syscall does not use the "entry point" field in the header. This means that the C runtime start-off routine, ctrso.o, MUST be placed at address 0 of the text segment by the linker. This is achieved with ld86 by making sure that ctrso.o is the first specified object file in the list of objects to link.

To mimic the behaviour of the MINIX C compiler, the initial stack address of executables should be set to the largest possible value of 0xFFFF (the linker option -H can be used for this). The value can then be updated later from within MINIX with chmem. TODO: add chmem to host build tools.

For a breakdown of MINIX vs dev86 executable headers, see src/mm/exec.c and ./vendor/dev86/include/a.out.h.

MINIX executables require MINIX libc and crtso.o to be linked in, like so:

ld86 -0 -s -L<host_minix_libc_dir> -Cso -lc main.o -o a.out -H 0xFFFF

Note that the C runtime start-off routine is linked before anything else by specifying -Cso first. Also note that end.o (end.s in MINIX book) is no longer needed as assembly code has been updated to use built-in __end label provided by ld86.

Building libc

MINIX libc for the host environment can be built with make libc. It is built from the libc source code provided in MINIX and a few internal compiler routines extracted from the bcc compiler which implement mathematical operations on 32-bit (long in 8088) types. Since ld86 is a two-pass linker, there is no need to worry about the order of object files in the libc.a archive and no need to include a symbol index.

Mounting MINIX filesystems

Linux supports mounting MINIX filesystems such as MINIX floppy disks:

sudo mount -t minix ./some_minix_disk.img /mnt

Use this to pull/push files to/from a MINIX system.