Frostbyte

A baremetal lightweight kernel with POSIX compliant system call API (user/lib/flib.h) and shell commands. Runs in headless mode.

Architecture

ARM64

Board support

qemu, raspberrypi 3, raspberrypi 4

Build from source

For out of box images, check out Releases and skip ahead to the Run and Test section

Environment setup

A Linux host machine

You will need a pre-compiled cross toolchain to build the kernel. Download a Linux host based cross toolchain for aarch64 bare-metal target from https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads

You will either need gcc-arm-11.2-2022.02-x86_64-aarch64-none-elf.tar.xz or gcc-arm-11.2-2022.02-aarch64-aarch64-none-elf.tar.xz depending on your host machine architecture. You can choose a different or newer version but it should be for bare metal target only

Append the toolchain root and binary path to your PATH env variable to enable make to resolve include paths and run seamlessly with the cross compiler prefix:

export PATH=$PATH:/path/to/toolchain/directory/gcc-arm-11.2-2022.02-x86_64-aarch64-none-elf:/path/to/toolchain/directory/gcc-arm-11.2-2022.02-x86_64-aarch64-none-elf/bin

Build

Select target platform using the optional BOARD make variable. Currently available options based on board support:

• rpi3 (WIP, builds image for qemu emulated raspberrypi 3)
• rpi4 (builds image for raspberrypi 4 SoC)
• qemu => default https://github.com/amoldhamale1105/frostbyte?tab=readme-ov-file#board-support To build the entire project with the kernel and userspace apps, at the top of the source tree

make all

For a release build, set the DEBUG make variable to 0

make all DEBUG=0

To mount and unmount the FAT16 disk image, you can use the mount and unmount targets as below

make mount
make unmount

Note: If the build fails upon any changes, the disk image may have to be unmounted with make unmount before make all can be run again

To clean build and output artifacts,

make clean

Run and Test

Hardware

Flash an SD card with a 64-bit raspberrypi OS image. Mount the boot parition and edit the config.txt file to add the following 2 lines:

dtoverlay=disable-bt
enable_uart=1

Replace the kernel8.img file in the mounted boot partition directory with frostbyte's. Insert the SD card into the board.

Connect the board serially to your host machine. Set the serial port device (mostly /dev/ttyUSB0) and baud rate to 115200 in your serial port communication program. Boot.

Emulator

Start a raspberry pi 3 emulator running frostbyte

qemu-system-aarch64 \
    -m 1G \
    -machine raspi3b \
    -serial mon:stdio \
    -kernel /path/to/kernel8.img \
    -nographic

On older qemu versions, you may have to use machine type as raspi3 instead of raspi3b. Run qemu-system-aarch64 -machine help if in doubt.

The OS boots up to a login prompt on the serial console. The login process parses the passwd file on the disk for registered users. Default user is root with default password toor

On successful login, a shell for current user is activated.

Features and Capabilities

This section may not be up to date with the current version of the kernel on master branch. However, it is highly recommended to read through it to get an idea of what frostbyte offers as its core functionality and extended features.

Features

• Kernel runs at privileged exception level 1 (EL1)
• Userspace apps run at exception level 0 (EL0)
• Synchronous and asynchronous exception handling
• Interrupt handling and interrupt vector table
• Timer interrupt based FIFO scheduler
• Paging and virtual memory management
• FAT16 filesystem support
• VFS (Virtual filesystem)
• Multi-user mode with login prompt
• Serial console interactive shell
• POSIX compliant system calls, library functions and commands
• POSIX signal handling framework with default and custom handlers
• Custom program execution on shell with command-line arguments
• User inputs (stdin) to foreground user programs
• Foreground and background process control
• Environment variables

You can execute commands and programs on the shell by simply entering their name with or without extension. Commands entered on the shell are case insensitive. All executables on frostbyte need to have the .bin extension to be qualified as an executable. However, during execution, usage of the .bin extension is optional
For example, all of the following commands will yield same output

uname
uname.bin
UNAME.BIN
uNaMe.BiN
uNaMe

Commands

The following POSIX commands are currently supported by frostbyte with options.

sh, uname, ls, ps, jobs, fg, bg, export, echo, env, unset, cat, kill, exit, shutdown

Usage and short description of any command can be viewed with the -h option. For instance, uname -h will yield the following output:

Usage:	uname [OPTION]
	Print certain system information.  With no OPTION, same as -s.

	-h	display this help and exit
	-a	print all system information in following order:
	-s	print the kernel name
	-r	print the kernel release
	-m	print the machine hardware name
	-i	print the hardware platform architecture

Contributions

You can contribute to this project if you find it interesting enough.

As a potential contributor you are welcome to

• Review pull requests and address open issues
• Create new issues for bugs or feature requests
• Raise PRs to address existing issues, fix bugs, make improvements or add new features

Point of contact in case of any questions or suggestions: [email protected]