Minimalist educational operating system
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


X1 - A minimalist educational operating system

X1 is a very small operating system meant to introduce students to low-level
system programming. As a result, it focuses on clarity of explanation. It's
not meant to demonstrate state-of-the-art methods and algorithms, but rather
simple, naive ones that do the job, while providing pointers and references
to the more modern ways.

X1 is a single address space operating system, always running with the
highest privileges. There is no userspace, and no system calls. Despite
that, the operating system is also called the kernel.


X1 expects a Unix-like environment, including make and a GCC compilation
toolchain. It's been tested on a few Linux distributions such as Debian
and Arch.

Building the kernel is done using the make command from the source root
directory. The end result is a statically linked ELF [1] file named x1.
On Debian, the following packages are required :

 - build-essential
     Meta-package pulling the gcc and make packages, among others.
 - gcc-multilib
     Multilib support for GCC, which provides the 32-bits static libgcc
     library required to link the kernel on 64-bits machines.

Examining the kernel binary

The kernel can be examined with standard GNU binutils tools [2]. Here are
some common command line examples to obtain information directly from the
kernel binary :

 - objdump -d x1 | less
     Disassemble the kernel machine code.
 - readelf -aW x1 | less
     Display ELF information, such as headers and sections.
 - addr2line -e x1 0x1003f0
     Convert an address into a source location.
 - nm x1
     List symbol names.


X1 targets the x86 32-bits architecture only (i386) [3], and ignores some
advanced features such as virtual memory and SMP. It is compliant with the
original multiboot specification [4] and GRUB is the recommended boot loader.
It only supports legacy BIOS systems (no EFI/UEFI).

A simple way to run the kernel is to use the shell script, which
relies on the QEMU -kernel option to act as a multiboot boot loader.
On Debian, the following packages are required :

 - qemu
     The well known machine emulator.

When QEMU is running, you may enter (and leave) its monitor prompt using
the Ctrl-a c key sequence. The most useful monitor commands are :

 - info registers
     Print the content of all core registers.
 - info pic
     Print the state of the legacy PIC interrupt controller.

If you're interested in the details, the following commands may be of interest :

 - info mtree
     Print the various emulated address spaces.
 - info qtree
     Print the emulated device tree.

Getting started

Even a simple project like X1 requires broad knowledge, spanning from a basic
understanding of processors, memory, assembly and compilation toolchains. The
OSDev website [5] provides a good starting point to find information of decent
quality. Beyond that, readers are encouraged to refer to actual reference
documentation, and of course, search engines.

Here is a non-exhaustive list of topics readers should hopefully develop their
understanding of with this project, and are encouraged to briefly learn about
even before starting playing with X1 :

 - Processor architecture, including core registers, machine instructions
   and accessing memory through loads and stores.
 - Control of the link step through a linker script.
 - The concept of an executable format, including partitioning the content into
   sections, such as code and data sections. See ELF [1].
 - The C programming language, including common extensions, such as controlling
   alignment. The source code conforms to C99 [6] with some GNU extensions.

The two files reader should use as their entry points are :

 - src/boot_asm.S
     The assembly source file containing the very first instructions.
 - src/
     The linker script used to control the link step.

Sources organization

The project sources are split into three directories :

- include
    This directory may only contain standard headers, normally provided
    by the "implementation" (e.g. the compiler and the C library) in a
    hosted environment. Because this is a kernel, the environment is
    free standing instead, so any additional standard service must be
    added manually. See ISO/IEC 9899:1999 "Freestanding environment"
    in the C99 specification for all the details.
- lib
    This directory contains external code used as a library by the kernel.
    These files are copied from the librbraun library [7] and are meant to
    provide a tiny and easily embedded "development kit".
- src
    This directory contains the actual kernel code.

The coding style used is borrowed from X1's big brother X15 [8].


[1] ELF:
[2] GNU binutils :
[3] Intel combined manuals :
[4] Multiboot specification :
[5] OSDev website :
[6] C99 specification :