Fiwix: a POSIX-shaped i386 kernel small enough to read in a weekend

A kernel sized for reading rather than for running servers

Fiwix is an operating system kernel written from scratch, based on the UNIX architecture and focused on being POSIX compatible. The stated motivation is unusual and worth reading closely: it is designed and developed mainly as a hobby OS, and since it also serves an educational purpose, the kernel code is kept as simple as possible for the benefit of students and OS enthusiasts.

That constraint is the identity of the project. The kernel is small in size, less than 50K lines of code, it runs on the i386 hardware platform, and it is compatible with a good base of existing GNU applications. The audience is a person who wants to read a kernel end to end rather than a person who wants a filesystem.

The implementation is written in ANSI C, with assembly used only in the needed parts, and it boots through the GRUB Multiboot Specification v1. The kernel itself is described as a full 32bit protected mode non-preemptive kernel for i386 processors and higher, with preemptive multitasking on top of that.

The project was created by Jordi Sanfeliu, and the documentation points to a website, an IRC channel on Libera Chat, and a fiwix-general mailing list.

Licence details carry a wrinkle that is easy to miss. The README states that Fiwix is free software licensed under the terms of the MIT License, with the copyright line given as 2018-2025 Jordi Sanfeliu, while the licence field on the repository itself is recorded as a custom licence that GitHub cannot classify, and the Makefile header describes the code as distributed under the terms of the Fiwix License. If licence terms matter to you, read the LICENSE file directly rather than relying on either summary.

The build is one make command and a 32 bit C89 target

The command needed to build the Fiwix kernel is short:

make clean ; make

That produces two files in the root directory of the source tree, the kernel itself named fiwix and System.map.gz, which is the symbol table. Before compiling you might want to tweak the kernel configuration by changing the default values in include/fiwix/config.h and include/fiwix/limits.h, so the build is not entirely a one-liner if you want to change the limits.

The Makefile shows exactly what the compiler is asked for. The architecture and language settings are fixed in the file: ARCH is set to -m32, CPU to -march=i386 and LANG to -std=c89. So the kernel is 32 bit, i386 instructions only, and C89. The default compiler is gcc, and the comment in the Makefile notes that CCEXE can be overridden on the command line, for instance with make CCEXE="tcc", with a pointer to docs/tcc.txt for using the Tiny C Compiler. The C flags add -ffreestanding, since there is no hosted C library under a kernel, along with -O2, -fno-pie, -fno-common and strict prototype warnings. Linking uses -m elf_i386.

The tree is also where you can see the module boundaries at a glance. The build walks kernel and kernel/syscalls, mm, fs, drivers/char, drivers/block, drivers/net, drivers/pci, drivers/video, net and lib, with the filesystem and driver directories broken down further in the object list, such as fs/ext2, fs/iso9660, fs/minix, fs/pipefs, fs/procfs and fs/sockfs.

The kernel boots to /sbin/init, which you have to provide

This is the single most important thing to understand about the project before you try it. The kernel does not do anything on its own, and you need a user space environment to make use of it.

Upon booting, the kernel mounts the root filesystem and tries to run /sbin/init on it. If that program is not there, there is no system. The kernel is a scheduler, a memory manager and a driver layer, and the init process and everything it pulls in are your responsibility.

The project solves this for you in a specific way. FiwixOS provides a full user-space UNIX-like environment to test the Fiwix kernel, and the downloads page at fiwix.org is where you get it. The practical arrangement is that you build the kernel from this repository and pair it with the FiwixOS distribution as the environment that supplies /sbin/init and the GNU applications that the kernel is compatible with.

That separation is also the educational design. A student can change the kernel and watch the same user space behave differently, and the compatibility work stays in the kernel where it can be read.

What is not in the repository is worth noting too. There is no shell, no C library and no package manager here, only kernel code, a network stack directory, drivers, and the userland-independent pieces of the tree.

Installing FiwixOS to a hard disk from CD or floppy

You install FiwixOS on a hard disk either by booting from the CD-ROM or from a floppy. If you choose the floppy route, you also need the Installation CD-ROM inserted, because the packages that form the whole system environment are installed from it. Let the system boot and, when you are ready, type install.sh.

The documented minimal hardware is deliberately modest and gives a good sense of the scope:

- Standard IBM PC-AT architecture. - i386 processor with a floating-point processor. - 4MB of RAM memory, with 128MB recommended. - IDE/ATAPI CD-ROM or floppy disk, 3.5 inches and 1.44MB. - 1GB ATA hard disk.

A 1GB ATA hard disk as the minimum says a lot about what era this kernel targets, and it is the reason the 4MB RAM figure is not a limitation in practice.

Before you go further, read the warning that the documentation repeats twice, in almost the same words. This is a kernel in its very early stages and may well have serious bugs and broken features which have not yet been identified or resolved. The documentation then states it again, and adds the banner: USE AT YOUR OWN RISK. That is not boilerplate caution. It is the most accurate description of the project's maturity, and it is written by the author.

What the kernel implements underneath the slogan

The feature list is long for a hobby project, and it is where the substance is. Memory management gets virtual memory splits of 3GB/1GB and 2GB/2GB between user and kernel space, plus demand paging with a Copy-On-Write feature. Process management gets preemptive multitasking, process groups, sessions and job control, and a round robin based scheduler algorithm, though the documentation notes there are no priorities yet. That single caveat matters for anyone porting software that expects priority scheduling.

The compatibility layer is a distinctive choice. The kernel offers Linux 2.0 i386 ABI system call compatibility, mostly, along with ELF-i386 executable format support for both statically and dynamically linked binaries. That is a deliberate design decision: instead of inventing an API, it reuses the one a large body of existing code already targets, and the documentation is careful to say mostly rather than completely.

Interprocess communication covers pipes, signals and UNIX-domain sockets, and UNIX System V IPC with semaphores, message queues and shared memory. File locking follows the BSD mechanism, with POSIX restricted to file and advisory only.

The filesystem layer sits behind a VFS abstraction layer. EXT2 is supported with 1KB, 2KB and 4KB block sizes, along with Minix v1 and v2, ISO9660 with Rock Ridge extensions, a RAMdisk device, initrd images, a PIPE pseudo-filesystem, and a Linux-like PROC filesystem that is read only.

Hardware support is broad for the platform: IDE/ATA hard disk and ATAPI CD-ROM drivers, floppy with DMA management, PCI local bus, a QEMU and Bochs graphics adapter, framebuffer devices for VESA VBE 2.0 and newer cards, an fbcon framebuffer console, UNIX98 pseudoterminals with devpts, virtual consoles up to 12, a keyboard driver with Linux keymaps, PS/2 mouse, serial RS-232 with a remote serial console, a QEMU Bochs style debug console, and a parallel port printer. There is also a basic pseudo-random number generator and SVGAlib support for applications.

A TCP/IP stack is vendored in the tree, with a lwip-STABLE-2_2_1_RELEASE.tar.gz archive at the root and headers referenced from net/lwip/include in the compiler flags.

Why read a 50K line kernel instead of reading Linux

The comparison with Linux is unavoidable and, handled fairly, it favours Fiwix for one specific purpose. Linux is a general purpose kernel that must run on everything from a phone to a datacentre, which is exactly why it is hard to read end to end. Fiwix accepts a narrow hardware target, one architecture, no priorities in the scheduler, and mostly compatible Linux 2.0 behaviour, and in exchange produces a codebase you can hold in your head.

The practical difference shows up in what happens when something misbehaves. On Linux you are reading documentation and searching a source tree with hundreds of thousands of files. On Fiwix you are reading the file that does the thing, and the documentation is a single README with a feature list that tells you exactly which parts are complete and which are caveats, such as the read only proc filesystem, the file and advisory only POSIX locking, and the absence of scheduler priorities.

The other alternative is not writing a kernel at all and using a hosted or containerised system. That is obviously the right answer for any workload with users, and it is worth saying plainly that nothing in Fiwix competes with it. The difference in approach is that a hosted system gives you a running system, while Fiwix gives you the ability to change one and watch the consequences.

There is a middle path worth naming too. Bochs and QEMU, both of which Fiwix explicitly supports through its graphics adapter and debug console drivers, let you run the whole thing in a virtual machine, so the experiments are repeatable and the risk of the USE AT YOUR OWN RISK banner stays inside a disk image.

Editorial conclusion

Adopt Fiwix if you are studying operating system internals, want a kernel small enough to hold in your head, and can work inside a QEMU or Bochs session with a FiwixOS user space that you install separately. Do not adopt it as a production kernel, for a 64 bit machine, or for anything with real data on it, since the project states plainly that it is in very early stages with serious bugs and broken features, and it targets i386 with 32 bit protected mode only. Verify first that you can build the kernel with make clean ; make, that a 32 bit C toolchain is available, and that the guest has the IDE hard disk and CD-ROM the installation path expects.

Frequently asked questions

Official sources

1. Issues
2. mikaku/Fiwix on GitHub
3. Project website
4. README
5. Releases