About {#mainpage}

FreeNOS (Free Niek's Operating System) is an experimental microkernel based operating system for learning purposes written in C++. You may use the code as you wish under the terms of the GPLv3.

Visit the project website at http://www.FreeNOS.org for more information.

Features

• Intel x86 (PC) and ARMv6/ARMv7/ARMv8 architectures (Raspberry Pi 1,2,3, Allwinner H2+/H3)
• Virtual memory
• Simple task scheduling
• Inter Process Communication (IPC)
• Symmetric Multi Processing with MPI support (via console and ethernet)
• Devices:
  • VGA/Keyboard consoles (also supported by Ed's libteken http://80386.nl/projects/libteken/)
  • i8250 serial UART
  • PCI host controller
  • CMOS RTC clock
  • ATA host controller
  • Allwinner H2+/H3 ethernet controller
  • Loopback ethernet controller
• Filesystems:
  • Virtual file system (VFS)
  • Temporary file system (TmpFS)
  • Linnenbank file system (LinnFS)
• Networking (IP, UDP, ICMP, ARP)
• POSIX, ANSI C libraries
• Dynamic and Shared memory
• Fully automatic autotester
• Automated continuous integration using jenkins (http://www.jenkins.io) and Vagrant (http://www.vagrantup.com)
• All sources documented with Doxygen (http://www.doxygen.org/)
• User and kernel code written from scratch in C++
• Very small microkernel (~2K lines of C++ code including a tiny part in assembly)
• Builds with recent GCC (http://gcc.gnu.org/), LLVM (http://www.llvm.org/) and SCons (http://www.scons.org/) versions on POSIX systems

Host Setup

First install all required build dependencies. FreeNOS needs SCons, an C++ compiler and for Intel targets a tool to generate ISO images. Follow the instructions below to install the build dependencies on your host OS.

Ubuntu

Update your system repository cache and install the required development tools using:

$ sudo apt-get update
$ sudo apt-get install build-essential scons grub-pc-bin xorriso qemu-system binutils-multiarch u-boot-tools liblz4-tool

If your Ubuntu host is 64-bit, you need to install the GCC multilib package to cross compile for the 32-bit architecture:

$ sudo apt-get install gcc-multilib g++-multilib

Alternatively, you can install the LLVM/Clang compiler as well:

$ sudo apt-get install clang

If you want to compile 32bit RaspberryPi 2b in Ubuntu24.04:

$ sudo apt-get install g++-arm-linux-gnueabi

If you want to compile 64bit RaspberryPi 3b in Ubuntu24.04:

$ sudo apt-get install g++-aarch64-linux-gnu

FreeBSD

Update your system repository cache and install the required development tools using:

% su -
# pkg update
# pkg install qemu scons cdrkit-genisoimage xorriso gcc u-boot-tools liblz4

On FreeBSD, make sure that the latest version of the GNU linker (from pkg) is used:

# mv /usr/bin/ld.bfd /usr/bin/ld.bfd.orig

Building FreeNOS

To download and extract the released source code on your host OS, run the following commands. Replace 'x.x.x' with the version of FreeNOS:

$ wget http://www.FreeNOS.org/pub/FreeNOS/source/FreeNOS-x.x.x.tar.gz
$ tar zxf FreeNOS-x.x.x.tar.gz

To get the latest development source, you can clone the GIT archive:

$ git clone https://github.com/nieklinnenbank/FreeNOS

To build FreeNOS using default settings (Intel, using GCC with debugging enabled), run:

$ scons

To build FreeNOS with all full build commands printed on the console, set the VERBOSE build variable to True:

$ scons VERBOSE=True

To build FreeNOS with compiler optimizations enabled, set DEBUG to False. Note that will make debugging using GDB more difficult:

$ scons DEBUG=False

Instead of providing build variables on the command line, you can also change the 'build.conf' configuration file for the target. The build configuration file contains build variables, such as compiler flags and parameters for the target. Similary, the 'build.host.conf' file contains build variables for the host OS programs. See the example build.conf and build.host.conf files for more details.

Additionally, any environment variables set in the shell will be automatically converted to identical build variables when running scons.

To build for the Raspberry Pi 2, copy the example build configuration file and run SCons:

$ cp config/arm/raspberry2/build.conf .
$ scons

To cleanup your build directory, use:

$ scons -c

Or use the following command to also remove temporary SCons files:

$ rm -rf build .sconf_temp .sconsign.dblite

Running FreeNOS

To run the autotester of FreeNOS on the host OS, run:

$ scons test

To run the same autotester on FreeNOS under Qemu, run:

$ scons qemu_test

To start FreeNOS in a Qemu virtual machine with a serial console, use the following command:

$ scons qemu

To debug FreeNOS using GDB, you need to build with the build variable DEBUG=True. Debugging symbols must available in the compiled programs which the debugger needs to translate between source code, CPU instructions and vice versa. Compiler optimizations are disabled with DEBUG=True, which gives reduced performance but improved debugging experience. By default, the DEBUG build variable is already set to True.

In case you have configured your build.conf with DEBUG=False, you can pass it on the commandline (or edit your build.conf to set DEBUG to True):

$ scons DEBUG=True

Ensure that your host OS has GDB available for debugging the target architecture (Intel or ARM). For Ubuntu:

$ sudo apt-get install gdb-multiarch

Open two terminals. In the first terminal, launch FreeNOS in Qemu with the internal gdbserver enabled:

$ scons qemu_debug

In the second terminal, start GDB and connect to the Qemu internal gdbserver using:

$ gdb-multiarch ./build/intel/pc/kernel/intel/pc/kernel
(gdb) target remote localhost:1234

You can now use standard GDB commands to interactively debug the FreeNOS kernel for intel. Similarly, you can also debug a user program (./build/intel/pc/bin/XXX). Note that when debugging user programs, the mapped virtual memory changes frequently due to scheduling. When you set a breakpoint on a virtual memory address, for example a function, it can happen that another program is scheduled and executes on the same virtual address which incorrectly triggers the breakpoint. In order to only trigger the breakpoint for a selected user program, you can put a condition on a breakpoint that matches the process name:

(gdb) condition 1 $_streq((char *)0xe0000000, "./server/datastore/server")

The above command puts a condition on the breakpoint with index number 1 that says it should only halt execution when the program name string equals "./server/datastore/server".

intel/pc

For Intel targets, you can also launch Qemu using the graphical VGA console (using SDL):

$ scons qemu_sdl

To test FreeNOS on real hardware, write the boot ISO to a bootable device, such as an USB disk. Insert the USB disk to your host OS and find the appropriate device name:

$ fdisk -l

Alternatively, use the dmesg command to find the device name. Write the boot ISO using the following command, where sdX is the name of the USB disk device. Note: make sure to select the correct device to prevent data loss:

$ sudo dd if=build/intel/pc/boot.iso of=/dev/sdX
$ sudo sync

Insert the USB disk device to the target system and make sure to choose it as boot device when the computer starts (e.g. via BIOS). You should see the FreeNOS VGA console.

arm/raspberry

To build FreeNOS for running on the Raspberry Pi 1, use the provided build.conf file and rebuild the system:

$ cp config/arm/raspberry/build.conf .
$ scons

To test FreeNOS for the raspberry pi 1 under Qemu, rebuild the system with the QEMU_BUILD build variable set to True:

$ scons QEMU_BUILD=True
$ scons qemu

To test on a real Raspberry Pi using SD card, download the latest Raspbian 'Lite' image from https://www.raspberrypi.org/downloads/raspbian/ and unzip it. Insert the SD card to your reader/writer slot on your host OS and find the appropriate device name using:

$ fdisk -l

Alternatively, use the dmesg command to find the device name. Write the Raspbian image to the SD card using the following command, where sdX is the name of the SD card device. Note: make sure to select the correct device to prevent data loss:

$ sudo dd if=/path/to/raspbian/image.img of=/dev/sdX
$ sudo sync

Re-insert the SD-card to auto mount it on your host OS. Copy the FreeNOS raspberry pi kernel executable to the '/boot' partition on the Raspbian image using (on Ubuntu):

$ sudo cp build/arm/raspberry/kernel.img /media/boot/kernel.img
$ sudo sync
$ sudo umount /media/boot

You will need a USB-to-TTL-serial cable to connect to the Raspberry Pi UART. Any USB-to-TTL-serial cable will work, for example the Adafruit USB-to-TTL-serial cable:

https://www.adafruit.com/product/954

Connect your USB-to-serial cable to the Raspberry Pi using the GPIO pins:

[ ] [ ]
[ ] [X]  Pin 4  (V5)     <---  Red (only needed if powered via USB)
[ ] [X]  Pin 6  (Ground) <---  Black
[ ] [X]  Pin 8  (RX)     <---  White
[ ] [X]  Pin 10 (TX)     <---  Green
[ ] [ ]
[ ] [ ]
[ ] [ ]
[ ] [ ]
[ ] [ ]

Also see the following tutorial by Adafruit on connecting the serial cable to the Raspberry Pi:

https://learn.adafruit.com/adafruits-raspberry-pi-lesson-5-using-a-console-cable/connect-the-lead

Connect your Raspberry Pi to the host to power it via USB or use an external power adapter. On the host OS, launch a serial console client program such as minicom and connect it to the USB serial device (baudrate 115200):

$ minicom -D /dev/ttyUSB0

You should now see the FreeNOS console output.

arm/raspberry2

Follow the same instructions as for the Raspberry Pi 1 above, but use the Raspberry Pi 2 configuration file instead to build FreeNOS:

$ cp