Loading repository data…
Loading repository data…
nieklinnenbank / repository
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.
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.
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
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
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".
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.
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.
Follow the same instructions as for the Raspberry Pi 1 above, but use the Raspberry Pi 2 configuration file instead to build FreeNOS:
$ cp config/arm/raspberry2/build.conf .
$ scons
When copying the kernel executable to the SD card '/boot' partition, use the 'kernel7.img' filename to make sure the Raspberry Pi bootloader correctly starts the kernel (ARMv7):
$ cp build/arm/raspberry/kernel.img /media/boot/kernel7.img
Additionally, for raspberry pi 2 and newer, add the following to the /boot/config.txt file to ensure the first UART is available on GPIO pins 8 and 10:
dtoverlay=pi3-miniuart-bt
enable_uart=1
Follow the same instructions as for the Raspberry Pi 1 above, but use the Raspberry Pi 3 configuration file instead to build FreeNOS:
$ cp config/arm64/raspberry3/build.conf .
$ scons
When copying the kernel executable to the SD card '/boot' partition, use the 'kernel8.img' filename to make sure the Raspberry Pi bootloader correctly starts the kernel (ARMv8):
$ cp build/arm64/raspberry3/kernel/arm64/raspberry3/kernel.img /media/boot/kernel8.img
Additionally, for raspberry pi 3b(64 bit), use the following settings for the /boot/config.txt file to ensure the first UART is available on GPIO pins 8 and 10:
arm_64bit=1
dtoverlay=disable-bt
enable_uart=1
FreeNOS has support for ARM boards with Allwinner H3 System-on-chips such as the Orange Pi PC and Orange Pi Zero (H2+ is a H3 variant). To build FreeNOS for the Allwinner H3, copy the provided configuration file:
$ cp config/arm/sunxi-h3/build.conf .
$ scons
The kernel image in U-Boot format can be copied to an SD card with U-Boot installed:
$ cp build/arm/sunxi-h3/kernel/arm/sunxi-h3/kernel.ub /media/sdcard/kernel.ub
To install U-Boot mainline on the SD-card, clone the source and select the proper configuration for your board (Orange Pi PC: orangepi_pc_defconfig, Orange Pi Zero: orangepi_zero_defconfig):
$ git clone https://gitlab.denx.de/u-boot/u-boot u-boot-git
$ cd u-boot-git
$ ARCH