https://github.com/rucub100/kruspix
A hands-on, educational kernel for the Raspberry Pi, written in Rust. Get a feel for bare metal and build your own OS from the ground up.
https://github.com/rucub100/kruspix
arm64 education experiment kernel operating-system raspberry-pi rust
Last synced: 16 days ago
JSON representation
A hands-on, educational kernel for the Raspberry Pi, written in Rust. Get a feel for bare metal and build your own OS from the ground up.
- Host: GitHub
- URL: https://github.com/rucub100/kruspix
- Owner: rucub100
- License: mit
- Created: 2025-09-06T10:14:59.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-05-27T12:07:58.000Z (25 days ago)
- Last Synced: 2026-05-27T13:23:55.077Z (25 days ago)
- Topics: arm64, education, experiment, kernel, operating-system, raspberry-pi, rust
- Language: Rust
- Homepage:
- Size: 5.09 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# kruspix
Kruspix is an experimental bare-metal hobby OS kernel for the Raspberry Pi, written in Rust.
It is also a learning project: the codebase explores OS fundamentals from the ground up –
boot, memory management, exceptions, scheduling, and device drivers, all without an OS
underneath.
## Current Status
Kruspix currently targets the Raspberry Pi 3 Model B v1.2 (BCM2837). The kernel boots into
a preemptive, single-core environment with virtual memory, heap allocation, device-tree based
platform drivers, UART logging, an interactive debug shell, framebuffer output, DMA-assisted
framebuffer scrolling, and USB HID boot-keyboard input.
Some recent driver work, especially the framebuffer console, DMA support, and USB keyboard
stack, was implemented with heavy AI assistance and is treated as experimental. These areas
work as project milestones, but still need review, cleanup, testing, and explanatory
documentation before they fully serve the project's educational goals.
## Hardware Support
- [ ] Raspberry Pi 2 Model B v1.2 (BCM2837)
- [x] Raspberry Pi 3 Model B v1.2 (BCM2837)
- [ ] Raspberry Pi 4 Model B (BCM2711)
- [ ] Raspberry Pi 5 (BCM2712)
## Prerequisites
- [Rust](https://www.rust-lang.org/): Make sure you have Rust installed.
- Add the target for Bare ARM64 (see [The rustc book - Platform Support](https://doc.rust-lang.org/rustc/platform-support.html)):
```shell
rustup target add aarch64-unknown-none
```
- Install [cargo-binutils](https://github.com/rust-embedded/cargo-binutils#cargo-binutils) for using `llvm-objcopy` and other tools:
```shell
cargo install cargo-binutils
rustup component add llvm-tools
```
- [Raspberry Pi Imager](https://www.raspberrypi.com/software/): To install kruspix OS to a microSD card
- [QEMU](https://www.qemu.org/): Required for emulating the Raspberry Pi and testing the kernel without real hardware
## Getting Started
### Building the Kernel
#### Build the kernel image
```shell
cargo objcopy --release -- -O binary target/kruspix.img
```
### Run in QEMU
Before running, the Raspberry Pi 3 device tree binary must be placed at `raspberrypi/bcm2710-rpi-3-b.dtb`.
This file is not included in the repository – download it from the
[official Raspberry Pi firmware repo](https://github.com/raspberrypi/firmware/tree/master/boot):
```shell
# create the folder and download the DTB
mkdir raspberrypi
curl -L -o raspberrypi/bcm2710-rpi-3-b.dtb https://github.com/raspberrypi/firmware/raw/master/boot/bcm2710-rpi-3-b.dtb
```
Then launch the kernel in QEMU:
```shell
cargo run
```
This uses the runner configured in `.cargo/config.toml` – it launches `qemu-system-aarch64`
with the `raspi3b` machine, the BCM2710 device tree, and serial output on stdio.
### Run on Hardware
#### Copy to microSD card and eject (Windows)
```shell
cp .\target\kruspix.img H:\boot\kruspix.img; (New-Object -ComObject Shell.Application).Namespace(17).ParseName("H:").InvokeVerb("Eject")
```
#### `usercfg.txt`
```text
kernel=boot/kruspix.img
arm_64bit=1
enable_uart=1
uart_2ndstage=1
dtparam=watchdog=off
#gpio=22-27=np
enable_jtag_gpio=1
# UM232H FT232H JTAG RPi3 GPIO
# Name Pin Name Func Pin
# AD0 J2-6 ADBUS0 TCK 25
# AD1 J2-7 ADBUS1 TDI 26
# AD2 J2-8 ADBUS2 TDO 24
# AD3 J2-9 ADBUS3 TMS 27
# AD4 J2-10 ADBUS4 (GPIOL0) 22
# AD5 J2-11 ADBUS5 (GPIOL1)
# AD6 J2-12 ADBUS6 (GPIOL2)
# AD7 J2-13 ADBUS7 (GPIOL3)
# AD0 J1-14 ACBUS0 /TRST
# AD1 J1-13 ACBUS1 /SRST
# AD2 J1-12 ACBUS2 (GPIOH2)
# AD3 J1-11 ACBUS3 (GPIOH3)
# AD4 J1-10 ACBUS4 (GPIOH4)
# AD5 J1-9 ACBUS5 (GPIOH5)
# AD6 J1-8 ACBUS6 (GPIOH6)
# AD7 J1-7 ACBUS7 (GPIOH7)
```
## JTAG Debugging
```shell
openocd -f interface/ftdi/um232h.cfg -f board/rpi3.cfg
```
## Project Structure
`src/`:
- `arch/` – architecture-specific code (ARM64 boot, MMU, CPU, exception vectors)
- `common/` – general utilities and data structures
- `drivers/` – platform device drivers (DTB-based model, including UART, timers,
watchdog, RNG, mailbox/firmware, DMA, framebuffer display, and USB keyboard support)
- `fs/` – filesystem (planned)
- `init/` – init system (planned)
- `ipc/` – inter-process communication (planned)
- `kernel/` – core kernel services (scheduler, IRQ, sync, shell, logging)
- `mm/` – physical memory management and heap
- `net/` – networking stack (planned)
## Roadmap
See [ROADMAP.md](ROADMAP.md) for the full list of completed milestones and planned features.
## Learning Material & Resources
### Rust
- [The Rust Programming Language Book](https://doc.rust-lang.org/book/)
- [The Rust Reference](https://doc.rust-lang.org/reference/index.html)
- [The Rustonomicon](https://doc.rust-lang.org/nomicon/index.html)
### Embedded Rust
- [The Discovery book](https://docs.rust-embedded.org/discovery/)
- [The Embedded Rust book](https://docs.rust-embedded.org/book/)
- [The Embedonomicon](https://docs.rust-embedded.org/embedonomicon/)
### Raspberry Pi and ARM
- [Raspberry Pi Documentation](https://www.raspberrypi.com/documentation/)
- [Raspberry Pi Firmware](https://github.com/raspberrypi/firmware)
- [BCM2835 ARM Peripherals](https://datasheets.raspberrypi.com/bcm2835/bcm2835-peripherals.pdf)
- [BCM2836 ARM-local peripherals](https://datasheets.raspberrypi.com/bcm2836/bcm2836-peripherals.pdf)
- [Cortex-A53 MPCore Processor Technical Reference Manual](https://developer.arm.com/documentation/ddi0500/latest/)
- [BCM2711 ARM Peripherals](https://datasheets.raspberrypi.com/bcm2711/bcm2711-peripherals.pdf)
- [ARM Cortex-A72](https://en.wikipedia.org/wiki/ARM_Cortex-A72)
### OS Development
- [Writing an OS in Rust (x86_64)](https://os.phil-opp.com/)
- [Simple RPi3 OS in C](https://github.com/s-matyukevich/raspberry-pi-os)
- [Operating System development tutorials in Rust on the Raspberry Pi](https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials)
- [OSDev Wiki](https://wiki.osdev.org/Main_Page)
- [QEMU Documentation](https://wiki.qemu.org/Documentation)
- [Linux Source](https://github.com/torvalds/linux)
- [The Linux Kernel documentation](https://docs.kernel.org/)
- [Device Tree Specification](https://www.devicetree.org/specifications/)
- [Device Bindings](https://github.com/devicetree-org/devicetree-source/tree/master/Bindings)
- [UEFI Specification](https://uefi.org/specifications)
- [POSIX.1-2024](https://pubs.opengroup.org/onlinepubs/9799919799/)
## Contact
📧 [info@ruslan-curbanov.de](mailto:info@ruslan-curbanov.de)
*Feel free to reach out regarding bug reports, technical discussions, or collaboration opportunities.*