Building a Linux System from Scratch via RISC-V Emulation

This project, hosted by WerWolv on GitHub, provides a comprehensive toolkit for creating a functional Linux environment running on a custom-built emulator. It is designed to accompany the detailed technical walkthrough found at werwolv.net/posts/linux_bringup/.

Core Objective: To implement a RISC-V rv32ima emulator that is robust enough to successfully boot the Linux kernel.

🏗️ Project Architecture

The emulator targets the rv32ima instruction set. In mathematical terms, this implies a 32-bit address space, meaning the system can address up to $2^{32}$ bytes of memory.

Directory Layout

The repository is organized into three primary segments:

/lib: This directory houses the core logic for the rv32ima instruction set and the minimal hardware devices required for system operation.
/main: Contains the specific machine configurations and the functions necessary to expose the emulator to WebAssembly.
/boot: A critical folder containing all configuration files needed to compile Linux. ~~It is not just for storage~~; the main executable expects all resulting binaries to reside here.

🛠️ Boot Configuration & Tooling

The following table outlines the essential files located in the /boot directory and their specific roles in the system bring-up:

File	Purpose	Tool Used
`riscv32-unknown-linux-gnu.config`	Toolchain configuration	`crosstool-ng`
`riscv_emulator_defconfig`	Linux Kernel configuration	`make`
`device_tree.dts`	Minimal hardware description	`dtc`
`init.c`	The system's first user-space process	`riscv32-unknown-linux-gnu-gcc`
`initramfs.txt`	Configuration for the initial RAM filesystem	`gen_init_cpio`

Compilation Commands

To transform these configuration files into bootable binaries, the following commands are utilized:

1. Compiling the Device Tree:

dtc -I dts -O dtb device_tree.dts -o device_tree.dtb

2. Compiling the Init Program: The init program must be linked statically to ensure it runs without external dependencies:

riscv32-unknown-linux-gnu-gcc -static init.c -o init

3. Generating the Initramfs:

usr/gen_init_cpio initramfs.txt -o initramfs.cpio

📋 Implementation Checklist

If you are following along with the source code, ensure you complete these steps:

Clone the WerWolv/riscv-emulator repository.
Configure the toolchain using riscv32-unknown-linux-gnu.config.
Build the Linux kernel using the riscv_emulator_defconfig.
Generate the .dtb from the .dts file.
Compile the init binary and package the initramfs.cpio.

🖼️ System Visualization

Figure 1: Conceptual flow from emulator initialization to Linux kernel execution.

⚖️ Licensing

This project is released under the MIT License, allowing for broad use and modification.