Genesis

A bare-metal bootloader for RISC-V. Part of the bedrock[RTOS] ecosystem, but deliberately self-contained, you can drop it into any hobby osdev project without dragging in the rest of bedrock.

Targets RISC-V 32-bit (RV32IMA) and 64-bit (RV64GC). Primary development environment is QEMU virt machine.

Prerequisites

You need a RISC-V cross-compiler and QEMU. On most distributions:

# Arch Linux
pacman -S riscv64-elf-gcc qemu-system-riscv

# Ubuntu / Debian
apt install gcc-riscv64-unknown-elf qemu-system-misc

# macOS (Homebrew)
brew install riscv-gnu-toolchain qemu

Building

RV64 (default)

make

RV32

make ARCH=rv32

With SBI (S-mode, requires OpenSBI as firmware)

make ARCH=rv64 MODE=sbi

Debug build (assertions enabled, no optimization, verbose log)

make ARCH=rv64 DEBUG=1

Build artifacts land in build/<arch>-<platform>-<mode>/.

Running in QEMU

# RV64, M-mode bare-metal
make run

# RV32
make ARCH=rv32 run

Expected output:

Genesis v0.1.0
RISC-V bootloader — part of bedrock[RTOS]

[INF] core/main.c:18 (genesis_main): hart 0 started
[INF] core/main.c:24 (genesis_main): timer frequency: 10000000 Hz
[INF] core/main.c:30 (genesis_main): Genesis initialized successfully
[INF] core/main.c:31 (genesis_main): no kernel image to load in v0.1.0 — halting

Genesis halted. Attach GDB or reset the machine.

Press Ctrl-A X to exit QEMU.

Debugging with GDB

make debug

This starts QEMU with -s -S (GDB server on port 1234, CPU halted at reset) and prints connection instructions. In a second terminal:

riscv64-elf-gdb build/rv64-qemu_virt-baremetal/genesis.elf

Inside GDB:

(gdb) target remote :1234
(gdb) break genesis_main
(gdb) continue

For RV32 debugging, use the same riscv64-elf-gdb binary — it handles both widths.

Other Makefile targets

Target	Description
make build	Compile and link (default)
make run	Build and launch in QEMU
make debug	Build and launch with GDB server
make size	Print ELF section sizes
make disasm	Disassemble the binary with source interleaving
make clean	Remove the build directory

Porting to new hardware

1. Create platform/<your_board>/platform.h — define UART0_BASE, DRAM_BASE, and any peripheral addresses.
2. Create platform/<your_board>/platform.c — implement platform_uart_init, platform_uart_putc, platform_uart_getc, platform_uart_rx_ready, and platform_init.
3. Build with make PLATFORM=<your_board>.

The HAL layer (hal/uart.c, hal/timer.c) calls these functions — everything else in core/ is portable C.

License

GNU General Public License v3.0. See LICENSE for details.

This project is part of bedrock[RTOS].