DEV Community: BENKAY THE FIRST

Building an Operating System In Rust Part 2

BENKAY THE FIRST — Fri, 24 Jul 2026 10:12:51 +0000

In Part 1 we built the foundation of our operating system using Rust, dove deep into murky low level waters and broke free from the shackles of stdlib while still keeping the compiler happy. Now we are going into the meat of it all - the entry point.

Feel free to clone the source code for part 2 from Github and follow along.

Prepare for Entry

When running programs on an operating system, there are a lot of things that are handled under the hood for us by the operating system. They are invisible to us and we take them for granted, we expect them to just work. In kernel space however, there are no training wheels, no invisible cogs turning in the background, everything is laid bare for us to see. Everything that works does so because we made it happen. It may sound overwhelming but it's this kind of foundational control that makes you truly appreciate how computers work at the lowest level.

At the lowest level, the way a CPU executes instructions is very different from the mental model that high level languages try to paint. If you are familiar with assembly then you already know this. Let's look at some core concepts you need to know in order to fully get into the vibe of low level program execution:

Register

Registers are ultra-fast, small-capacity temporary storage locations built directly into the CPU. They hold the exact data, instructions, or memory addresses the processor is currently working with, acting as the CPU’s immediate "scratchpad" before calculations are sent to the cache or main memory (RAM). There are general purpose registers and registers designed to perform a specific task.

Execution stack

As instructions execute, the stack is a LIFO data structure used to keep track of the execution context which may include local variables, function parameters or return addresses.

Stack pointer

The stack pointer is a special CPU register that automatically tracks the top of the execution stack. In Aarch64, the stack grows downward, so logically it tracks the bottom of the stack pointer but the idea remains the same. When the CPU pushes into the stack, the stack pointer gets decremented and the entry is written to that address where the stack is pointing to. When the CPU pops from the stack, it reads the entry at the current stack pointer and then increments the stack pointer effectively freeing the previous memory slot.

See illustration here

Instruction

An instruction is the smallest unit of work that can be performed by a CPU. It takes one or more operands and stores it's result in a register depending on the operation. There are tons of instructions built into a CPU to perform almost any operation you can think of and it varies from CPU to CPU so you have to learn the Instruction Set of the CPU you are working with if you want to write Assembly for it.

Program Counter

The program counter is a special CPU register that always contains the memory location of the next instruction to execute. As soon as the CPU finishes executing an instruction it checks the program counter and goes on to execute the instruction at the location stored in the program counter. After the CPU reads the program counter, the program counter gets incremented to point to the next instruction and the cycle continues.

Implementing the boot image

Now that we have a foundational understanding of the building blocks, let's write some assembly code for booting into our kernel. I know I promised we will write as much Rust as possible but this is one of those scenarios where Rust does not cut it. This part of the process cannot be handled by Rust because Rust expects a stack pointer to have already been set up so it is a chicken and egg problem. Remember, the training wheels are off and everything is being done manually so this is one time when we will have to drop down to Assembly in order to configure our entrypoint. This is a delicate point so I want you to pay as much attention as you can afford to.

For your information, any code related to the entrypoint of a kernel is called the boot code. We will be writing the our boot code, or as I prefer to call it "boot image", in a bit but let us first structure our crate.

Let's create a main function for our kernel in a new file src/kernel.rs:

pub fn main() -> ! {
    loop {}
}

This function will be called from our entrypoint and will handle all our kernel code but for now it just runs an infinite loop. Load this module in src/main.rs:

mod kernel;

Create a file src/processors/aarch64/bootimage.rs:

use core::arch::global_asm;

global_asm!(
    include_str!("boot.S"),
    CONST_CORE_ID_MASK = const 0b11
);

#[unsafe(no_mangle)]
pub fn _start_rust() -> ! {
    crate::kernel::main()
}

This is processor specific code. In this case it is expected to run only on aarch64 cpus. We load some assembly from the file boot.S substituting a variable CONST_CORE_ID_MASK in the assembly with the value 0b11. Then we define fn _start_rust() which will serve as the first point of contact between assembly land and rust land. It calls our kernel main which we defined earlier. Note the no_mangle directive. It is required in order for the name of the function to not become scrambled during compilation since we will be calling the function from Assembly.

Then load the module in src/processors/aarch64/mod.rs:

mod bootimage;

Add the following content to src/processors/aarch64/boot.S:

//--------------------------------------------------------------------------------------------------
// Definitions
//--------------------------------------------------------------------------------------------------

// Load the address of a symbol into a register, PC-relative.
//
// The symbol must lie within +/- 4 GiB of the Program Counter.
.macro ADR_REL register, symbol
    adrp    \register, \symbol
    add \register, \register, #:lo12:\symbol
.endm

//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
.section .text._start

//------------------------------------------------------------------------------
// fn _start()
//------------------------------------------------------------------------------
_start:
    // Only proceed on the boot core. Park it otherwise.
    mrs x0, MPIDR_EL1
    and x0, x0, {CONST_CORE_ID_MASK}
    ldr x1, BOOT_CORE_ID      // provided by __board__/<board_name>/cpu.rs
    cmp x0, x1
    bne .L_parking_loop

    // If execution reaches here, it is the boot core.

    // Initialize DRAM.
    ADR_REL x0, __bss_start
    ADR_REL x1, __bss_end_exclusive

.L_bss_init_loop:
    cmp x0, x1
    beq .L_prepare_rust
    stp xzr, xzr, [x0], #16
    b   .L_bss_init_loop

    // Prepare the jump to Rust code.
.L_prepare_rust:
    // Set the stack pointer.
    ADR_REL x0, __boot_core_stack_end_exclusive
    mov sp, x0

    // Jump to Rust code.
    b   _start_rust

    // Infinitely wait for events (aka "park the core").
.L_parking_loop:
    wfe
    b   .L_parking_loop

.size   _start, . - _start
.type   _start, function
.global _start

Whoa! That's a huge chunk of foreign code. Lucky you, I can demystify what's going on there. Let's take it apart line by line.

Assembly Breakdown

The ADR_REL macro

.macro ADR_REL register, symbol
    adrp    \register, \symbol
    add \register, \register, #:lo12:\symbol
.endm

This is a two-instruction helper that loads the address of a symbol into a register in a PC-relative way (relative to the program counter, no absolute addressing, so the code works regardless of where it's loaded as long as the symbol is within ±4 GiB).

adrp ("Address of Page") computes the 4 KiB-aligned page address containing the symbol, relative to the PC. So it gets you within 4 KiB of the symbol.
add … #:lo12:symbol adds the low 12 bits of the symbol's address (the offset within the page) to finish the address. Together they materialize an arbitrary symbol address with two instructions and no memory load. This matters because the BSS hasn't been zeroed yet and the stack isn't set; we can't yet rely on memory loads of address tables.

Let's use a practical example, Assume the Program Counter is at 0x00BC3000. We want to get the PC relative address of a symbol msg which for the sake of this example is stored at 0x00BC5B70. The question that this macro answers is how to get that symbol's address into a register. First we get the page address of the symbol relative to the program counter. The way this works is by finding which 4KiB slice (called a page) the symbol's address falls into:

See illustration here

So we know that the symbol is 3 pages away from the program counter. Next we get the lower 12 bits of the symbol's address using #:lo12:\symbol. Under the hood, this operation does this:

0x00BC5B70 & 0xFFF = 0xB70 // retains only the lower 12 bits

Then we add the result to the page address to get the symbol address:

0x00BC5000 + 0xB70 = 0x00BC5B70 // returned by ADR_REL macro

Code section

Assembly code is organized into sections. Each section contains a sequence of instructions and directives that define a logical unit of our program. The following labels a new section named .text._start which is the start of our code for this module:

//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
.section .text._start

Boot into primary CPU core

The next piece of code is responsible for selecting one of the available cores as our primary core and parking the remaining cores. By default all the CPU cores will pick up the kernel and try to run it so this is a crucial step to disqualify all but one, our primary core.

_start:
    mrs   x0, MPIDR_EL1
    and   x0, x0, {CONST_CORE_ID_MASK}
    ldr   x1, BOOT_CORE_ID
    cmp   x0, x1
    bne   .L_parking_loop

It starts by reading the value of the Multiprocessor Affinity Register, MPIDR_EL1 into register x0. The system register MPIDR_EL1 identifies which CPU we're on, specifically the low bits which contain the core number. Assuming we are on raspberry pi 4 or 5 then there are only 4 CPUs available which can be represented with two bits. So the value of MPIDR_EL1 may look like this on the different cores:

Core 1 - 01110000
Core 2 - 01110001
Core 3 - 01110010
Core 4 - 01110011

so we need a mask that can select only the last two bits of this register value and that mask is 0b11 because we can take any of the values and AND them with this mask to retrieve the last two bits:

0b01110000 & 0b11 = 0b00
0b01110001 & 0b11 = 0b01
0b01110010 & 0b11 = 0b10
0b01110011 & 0b11 = 0b11

We defined the mask CONST_CORE_ID_MASK a while ago in src/processors/aarch64/bootimage.rs and this is where it gets used. Depending on the board we are running on we can change this mask to 0b111 to support up to 7 cores or 0b1111 to support up to 15 cores.

Next, we load the value of the variable BOOT_CORE_ID (which we will define soon in Rust) and store that in the register x1. At this point x0 contains the CPU number which the code is currently executing on and x1 contains the target CPU we want to take control while parking the rest. We compare their values and branch to the parking logic if x0 is not equal to x1, else we continue execution.

Before we continue describing our startup logic, let's define the BOOT_CORE_ID variable that we used above. Create a file src/motherboards/raspberrypi/cpu.rs:

#[cfg(target_arch = "aarch64")]
#[unsafe(no_mangle)]
#[unsafe(link_section = ".text._start_arguments")]
pub static BOOT_CORE_ID: u64 = 0;

link_section = ".text._start_arguments" adds a new section labelled .text._start_arguments and the variable BOOT_CORE_ID in that section. We are keeping the value as 0 because we want to boot into the first core as our primary core.

Create another file src/motherboards/raspberrypi/mod.rs:

mod cpu;

Then another file src/motherboards/mod.rs:

pub mod raspberrypi;

and then add the module to src/main.rs:

mod motherboards;

Initialize BSS

The BSS is a data segment that stores uninitialized global and static variables. At startup we need to zero all the addresses within the BSS in preparation for uninitialized variables that will be stored in this segment. The following segment handles this:

    // If execution reaches here, it is the boot core.

    // Initialize DRAM.
    ADR_REL x0, __bss_start
    ADR_REL x1, __bss_end_exclusive

.L_bss_init_loop:
    cmp x0, x1
    beq .L_prepare_rust
    stp xzr, xzr, [x0], #16
    b   .L_bss_init_loop

This is a simple routine that loads the start and end of the BSS into x0 and x1 using the symbols __bss_start and __bss_end_exclusive (will be defined later in the linker script). Then we recursively store zeroes in the memory locations stored in x0 and increment the memory location stored in x0 by 16. This continues until the memory location in x0 matches the end of bss stored in x1 then we branch to .L_prepare_rust.

Jumping into Rust land

The next piece of code is the bridge into our Rust code:

// Prepare the jump to Rust code.
.L_prepare_rust:
    // Set the stack pointer.
    ADR_REL x0, __boot_core_stack_end_exclusive
    mov sp, x0

    // Jump to Rust code.
    b   _start_rust

First we store the address of the end of the stack (configured later in the linker script) in x0. Then we set the value of the stack pointer register to that address. Finally we branch to the label for our Rust entry point (defined in src/processors/aarch64/bootimage.rs).

The next piece of code just defines the label for our parking loop so the other cores know what to do after being disqualified from running the kernel:

// Infinitely wait for events (aka "park the core").
.L_parking_loop:
    wfe
    b   .L_parking_loop

Lastly, we define some metadata for this assembly module at the very end:

.size   _start, . - _start
.type   _start, function
.global _start

The first directive .size computes the size of the routine _start. The second directive .type specifies the type of _start which is a function. The last directive .global makes the _start label a global entity which can be referenced by other libraries.

Summarily, here is the boot flow:

See illustration here

We have implemented our boot image in pure Assembly. I hope you enjoyed that! One last important step before we can run our kernel for the first time is Linking.

Writing the Linker Script

Linking is the glue for everything we have done. A linker is responsible for taking both the assembly code and the Rust code and linking them into one binary but we have to explicitly tell the linker how we want our code to be organized; we have to define the memory layout for our binary!

Create the file src/motherboards/raspberrypi/kernel.ld and add the following content:

__rpi_phys_dram_start_addr = 0;

/* The physical address at which the the kernel binary will be loaded by the Raspberry's firmware */
__rpi_phys_binary_load_addr = 0x80000;


ENTRY(__rpi_phys_binary_load_addr)

/* Flags:
 *     4 == R
 *     5 == RX
 *     6 == RW
 *
 * Segments are marked PT_LOAD below so that the ELF file provides virtual and physical addresses.
 * It doesn't mean all of them need actually be loaded.
 */
PHDRS
{
    segment_boot_core_stack PT_LOAD FLAGS(6);
    segment_code            PT_LOAD FLAGS(5);
    segment_data            PT_LOAD FLAGS(6);
}

SECTIONS
{
    . =  __rpi_phys_dram_start_addr;

    /***********************************************************************************************
    * Boot Core Stack
    ***********************************************************************************************/
    .boot_core_stack (NOLOAD) :
    {
                                             /*   ^             */
                                             /*   | stack       */
        . += __rpi_phys_binary_load_addr;    /*   | growth      */
                                             /*   | direction   */
        __boot_core_stack_end_exclusive = .; /*   |             */
    } :segment_boot_core_stack

    /***********************************************************************************************
    * Code + RO Data + Global Offset Table
    ***********************************************************************************************/
    .text :
    {
        KEEP(*(.text._start))
        *(.text._start_arguments) /* Constants (or statics in Rust speak) read by _start(). */
        *(.text._start_rust)      /* The Rust entry point */
        *(.text*)                 /* Everything else */
    } :segment_code

    .rodata : ALIGN(8) { *(.rodata*) } :segment_code

    /***********************************************************************************************
    * Data + BSS
    ***********************************************************************************************/
    .data : { *(.data*) } :segment_data

    /* Section is zeroed in pairs of u64. Align start and end to 16 bytes */
    .bss (NOLOAD) : ALIGN(16)
    {
        __bss_start = .;
        *(.bss*);
        . = ALIGN(16);
        __bss_end_exclusive = .;
    } :segment_data

    /***********************************************************************************************
    * Misc
    ***********************************************************************************************/
    .got : { *(.got*) }
    ASSERT(SIZEOF(.got) == 0, "Relocation support not expected")

    /DISCARD/ : { *(.comment*) }
}

The above linker script is a lot to digest but let's take it step by step and see what makes it tick.

First, we are declaring some link time variables that will be used by the rest of the script:

__rpi_phys_dram_start_addr = 0;

/* The physical address at which the the kernel binary will be loaded by the Raspberry's firmware */
__rpi_phys_binary_load_addr = 0x80000;

In Raspberry Pi Aarch64, the kernel image will be loaded into the address 0x80000. This is standard for Raspberry Pi running in 64 bit mode and will be different for different motherboards so we store the value here for use later in the script.

Next line is:

ENTRY(__rpi_phys_binary_load_addr)

It sets the ELF header's entry-point field to 0x80000. Some loaders use that field to decide where to jump; the Pi firmware ignores it and just jumps to 0x80000 regardless. Still good practice to set it right.

Then we have the program-header segments:

PHDRS
{
    segment_boot_core_stack PT_LOAD FLAGS(6);
    segment_code            PT_LOAD FLAGS(5);
    segment_data            PT_LOAD FLAGS(6);
}

ELF binaries describe memory in two layers: small sections for the linker (.text, .data, …) and bigger segments that an actual loader maps. PHDRS declares those segments and their permissions.

PT*LOAD = "an ELF loader should make this segment exist in memory."
FLAGS(...) bits: 4 = R, 5 = R+X, 6 = R+W.
So you end up with three logical regions: the stack (RW), the code+rodata (RX), and the mutable data + BSS (RW). Each section below is assigned to one of these via the trailing :segment*… syntax.

The next part is the meat of the script; sections. It walks down memory address-by-address and places things. Describes start and endpoints for the different sections in our binary:

SECTIONS
{
    . =  __rpi_phys_dram_start_addr;

    /***********************************************************************************************
    * Boot Core Stack
    ***********************************************************************************************/
    .boot_core_stack (NOLOAD) :
    {
                                             /*   ^             */
                                             /*   | stack       */
        . += __rpi_phys_binary_load_addr;    /*   | growth      */
                                             /*   | direction   */
        __boot_core_stack_end_exclusive = .; /*   |             */
    } :segment_boot_core_stack

    /***********************************************************************************************
    * Code + RO Data + Global Offset Table
    ***********************************************************************************************/
    .text :
    {
        KEEP(*(.text._start))
        *(.text._start_arguments) /* Constants (or statics in Rust speak) read by _start(). */
        *(.text._start_rust)      /* The Rust entry point */
        *(.text*)                 /* Everything else */
    } :segment_code

    .rodata : ALIGN(8) { *(.rodata*) } :segment_code

    /***********************************************************************************************
    * Data + BSS
    ***********************************************************************************************/
    .data : { *(.data*) } :segment_data

    /* Section is zeroed in pairs of u64. Align start and end to 16 bytes */
    .bss (NOLOAD) : ALIGN(16)
    {
        __bss_start = .;
        *(.bss*);
        . = ALIGN(16);
        __bss_end_exclusive = .;
    } :segment_data

    /***********************************************************************************************
    * Misc
    ***********************************************************************************************/
    .got : { *(.got*) }
    ASSERT(SIZEOF(.got) == 0, "Relocation support not expected")

    /DISCARD/ : { *(.comment*) }
}

The summary of what is going on is it defines the bounds of the Execution Stack, the actual code segment, and the data and BSS segment. I don't want to go too deep into the details of the linker script because it is vanity to master it all but feel free to discuss the details with any LLM in order to fully understand what is going on here.

We are done with our boot image and at this stage we can boot our kernel on either a physical device or the QEMU emulator.
Before we build, add the following to your Cargo.toml so that our Make script can run happily:

[features]
default = ["device", "rpi5"]
emulator = ["ltr-rgb"]
device = []
rpi5 = []
rpi4 = []
ltr-rgb = []

We aren't using some of the features listed here yet but in due time we will cover them.

Let's build and run the kernel on QEMU using our emulator:

cargo make emulate

You should see a black QEMU screen pop up with no errors just like this one:
{{ image(src="/images/os-part2-result.png", alt="operating system on qemu part2 result") }}

In order to run on a physical Raspberry Pi 5 device there is also a convenient cargo make task:

cargo make sync

It attempts to copy the binary into a memory stick containing an existing Raspbian installation. Alter the task in Makefile.toml so it gets copied into the right path.

Conclusion

In this part, we implemented a boot image and successfully booted our kernel on a raspberry pi environment but we still have a blank screen. In Part 3 we will be writing to the display; in QEMU that's the screen but on Raspberry Pi 5 that is the HDMI output.

Building an Operating System In Rust Part 1

BENKAY THE FIRST — Fri, 24 Jul 2026 09:48:23 +0000

Building an operating system is a project I have had my eyes set on ever since I discovered free will in the realm of programming. Years ago, I did a reasonable amount of research, paying extra attention to the subject during my computer science degree and I was able to understand Operating System Theory and how it works from first principles but I never really got around to building one. I had only flimsy reasons for not embarking on it like "why build one when there are tons of working ones out there? The theoretical knowledge is enough". More recently, I am ignoring the need to not re-invent the wheel for the joy of programming. So if you are interested in also rebuilding stuff because you can, join me on this series as I document how I am going to be building kluster.

kluster is in its infancy and the direction is not clear but the one certain thing is that I will be building it entirely in Rust, save some assembly instructions and a linker script and I will be explaining every single line of code along the way. It will also be designed to target the raspberrypi 4 & 5, on qemu and on real hardware respectively. This is an opportunity for anyone who wants to see how Rust works at the lowest of levels to hop on and join the ride.

Note that this series will be your biggest lesson on delayed gratification because we will write a lot of code before we even get to see anything meaningful on screen but I will foreshadow what you can get by the end of part 3 if you are patient enough:
{{ image(src="/images/os-part3-result.png", alt="Part 3 Results OS Dev") }}

You can also clone the source code for part 1 from Github and follow along.

Project Setup

First things first, let us setup the foundation of the project. I'll be straight with you, I love Rust and I enjoy using the Rust ecosystem in its entirety so I will stay true to that and use it as obsessively as any true Rustacean; I won't hold back. Without doubt, all the dependencies we need are freely available as long as you have a working Rust/Cargo installation.

Installing Rust

I should assume you have the runtime if you are even opening any page with this title but for the benefit of doubt:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Run the above command to install the Rust toolchain. If you already have the Rust toolchain then update it to the latest version:

rustup update

Create a new Rust binary crate:

cargo new --bin op-sys

Now let's do some plumbing to setup the foundation for the project.

Let there be night

I will explain in a couple paragraphs why, but we need the rust nightly toolchain for this project so go ahead and install it:

rustup toolchain install nightly

Also configure it as the default for this project by creating a file rust-toolchain.toml in the root and adding the following content:

[toolchain]
channel = "nightly"

For our OS we are also going to be targetting the Aarch64 CPU barebones so first we install the target:

rustup target add aarch64-unknown-none-softfloat

Then we configure it as the default compilation target for this project by creating a file .cargo/config.toml in the root and adding the following content:

[build]
target = "aarch64-unknown-none-softfloat"

Build tools

We need to install llvm-tools on the nightly toolchain because we make use of llvm-objcopy during the build process to turn the ELF into a raw kernel image. cargo-binutils is a wrapper around the tools installed by llvm-tools that allow them to work well with our cargo project and we will also be installing that.

rustup component add llvm-tools --toolchain nightly
cargo install cargo-binutils

Next we need to install cargo-make. It will help us organize our build harness into smaller manageable tasks.

cargo install cargo-make

Install the Emulator

We need to install the emulator on which we will be running our Operating System. We will be using QEMU. I won't go into platform specific details on how to install QEMU but feel free to dig through the documentation to get your installation up and running.
After installing it run this command to make sure you have raspi4b emulator installed:

qemu-system-aarch64 -M help | grep raspi4b

Note that this OS will also be designed to target Raspberry Pi 5 hardware so if you have that then you are in luck.

Setting up the Makefile.toml

In the spirit of using Rust from top to bottom we have opted for using cargo make a build tool reminiscient of make the C build tool.
Cargo make is more modern and has a better syntax, we would be crazy not to go with it. Cargo make is a very flexible tool that can achieve almost any kind of configuration you are looking for. It is not in our best interest to cover all of its capabilities in this series but we will cover as many features as we end up using.

Let us set up our Makefile.toml:

[env]
RUSTFLAGS = "-C target-cpu=cortex-a76 -C link-arg=--library-path=src/motherboards/raspberrypi -C link-arg=--script=kernel.ld"
RUSTFLAGS_PI4 = "-C target-cpu=cortex-a72 -C link-arg=--library-path=src/motherboards/raspberrypi -C link-arg=--script=kernel.ld"

[tasks.compile]
script = "RUSTFLAGS=${RUSTFLAGS} cargo objcopy --release  -- --strip-all -O binary target/kernel_2712.img"

[tasks.compile-emulate]
script = "RUSTFLAGS=${RUSTFLAGS_PI4} cargo objcopy --release --no-default-features --features emulator,rpi4  -- --strip-all -O binary target/kernel_2712.img"

[tasks.sync]
dependencies = ["compile"]
command = "cp"
args = ["target/kernel_2712.img", "/Volumes/bootfs/kernel_2712.img"]

[tasks.emulate]
dependencies = ["compile-emulate"]
command = "qemu-system-aarch64"
args = [
    "-machine",
    "raspi4b",
    "-kernel",
    "target/kernel_2712.img",
    "-serial",
    "stdio",
    "-display",
    "cocoa",
]

Let's go over everything that's happening here section by section:

[env]
RUSTFLAGS = "-C target-cpu=cortex-a76 -C link-arg=--library-path=src/motherboards/raspberrypi -C link-arg=--script=kernel.ld"
RUSTFLAGS_PI4 = "-C target-cpu=cortex-a72 -C link-arg=--library-path=src/motherboards/raspberrypi -C link-arg=--script=kernel.ld"

The [env] directive is used to setup environment variables that all make tasks can inherit from and pass into their execution scope.
Here we define two variables called RUSTFLAGS. They are used to pass special configuration options to rustc during compilation. One is used when compiling for the Pi 4 and the other is used for the Pi 5.
Next we have the compile tasks. These tasks are responsible for compiling the kernel into a raw image for either Pi 4 or Pi 5.

[tasks.compile]
script = "RUSTFLAGS=${RUSTFLAGS} cargo objcopy --release  -- --strip-all -O binary target/kernel_2712.img"

[tasks.compile-emulate]
script = "RUSTFLAGS=${RUSTFLAGS_PI4} cargo objcopy --release --no-default-features --features emulator,rpi4  -- --strip-all -O binary target/kernel_2712.img"

In one pass, cargo will first build the project, then run objcopy on the output and store the binary at the path we have provided. In the second task compile-emulate, we have added some features to customize the build output namely emulator and rpi4. You will see how we use these features later in the code but for now just understand that they allow us include or exclude some lines of code from the final output depending on which machine we are targeting. It is worth mentioning at this stage that this kernel was not tested on a physical raspberry pi 4 device, rather it was set up on QEMU raspi4. It was however tested on a physical raspberry pi 5 device.

You can try to run it on a physical raspberry pi 4 without the emulator feature but I can't guarantee the success of your experiments in this direction. Of course if you run into any issues, leave a comment and I will respond with some advice on how to resolve them.

Next we have the actual execution instructions for our operating system:

[tasks.sync]
dependencies = ["compile"]
command = "cp"
args = ["target/kernel_2712.img", "/Volumes/bootfs/kernel_2712.img"]

The task named sync is used for copying the raw kernel image to a hard drive containing a raspberry pi installation. As you can see it depends on the compile task which compiles the raspberrypi 5 variant of our kernel. The process is pretty straightforward, burn a regular raspbian OS image to a drive or memory stick using Raspberry Pi Imager as you normally would. then update the above command such that it copies kernel_2712.img into the root of the drive. Afterwards all you need to do is stick it into a physical Raspberry Pi 5 device and voila! You have your OS running; obviously not at this stage because we have not written any actual OS code.

[tasks.emulate]
dependencies = ["compile-emulate"]
command = "qemu-system-aarch64"
args = [
    "-machine",
    "raspi4b",
    "-kernel",
    "target/kernel_2712.img",
    "-serial",
    "stdio",
    "-display",
    "cocoa",
]

The task named emulate is used for spinning up a QEMU emulator running our raw kernel image. As per our configuration, it depends on compile-emulate task which compiles the raspberrypi4 variant of our kernel.

For fast iterative development, using the emulator is preferred but if you think plugging and unplugging a memory stick every time you want to test your changes is exciting then I am not going to stop you. Either approach will work with this tutorial, I have made sure of that.

Building the Foundation

Okay now that we have our project setup, let us discuss one of the most fundamental concepts in building an operating system, the entry point. When writing any kind of program, Your code needs to be loaded into a particular memory location in order for the CPU to start executing it. This is true for any kind of program not just operating systems. In higher level Rust, we define fn main() and that becomes the entry point of the program but the only reason this works is because the compiler is designed to output object code placing the start of the main function at a memory location where the CPU is expecting it to be. In lower level environments like the one we are currently working in, we have to do everything manually. We have to configure our kernel so that the entry point is located where the CPU will be looking for code to execute. If we don't do this then the CPU cannot run the kernel.

So let's update src/main.rs to something more befitting of a low level project:

#![no_std]
#![no_main]
#![allow(internal_features)]
#![feature(lang_items)]

The first directive no_std simply tells the compiler that we want to build a freestanding binary without linking in the Rust standard library. Then no_main allows us compile code that does not explicitly define a fn main(). Like I said we are taking full control so the training wheels come off at this point. The next directive allow(internal_features) is just a lint ignore that allows us to use the last directive feature(lang_items) which is a special nightly feature gate (hence the nightly toolchain we installed at the beginning) that allows us to supply important behavior (like error handling) needed by the compiler in specific scenarios now that we are abandoning the training wheels.

You should be getting an annoying error from rust-analyzer:

can't find crate for `test`

To fix it, go into Cargo.toml and add the following lines to what is already there:

[[bin]]
name = "op_sys"
path = "src/main.rs"
test = false
bench = false

[profile.dev]
panic = "abort"

[profile.release]
lto = true
panic = "abort"

You see what we have just done is configure an explicit binary for our low level needs. We disabled test and bench so the compiler doesn't bootstrap the testing and benchmarking harnesses into our binary. We won't be needing that for our kernel anyways. Let's run cargo check to see if the coast is clear!

error: `#[panic_handler]` function required, but not found

Well the error is quite descriptive. Our dear compiler dumped std and put all its faith in us. Now we need to provide it with all the language items that it needs to function properly.

Create a new file src/panic_cfg.rs:

use core::panic::PanicInfo;

#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {}

#[lang = "eh_personality"]
extern "C" fn eh_personality() {}

Then add the module to src/main.rs:

mod panic_cfg;

Now we need to implement the panic handler. remove the dependencies section in Cargo.toml and replace it with:

[target.'cfg(target_arch = "aarch64")'.dependencies]
aarch64-cpu = { version = "9.x.x" }

This adds a new crate with which we can conveniently run Aarch64 CPU instructions from Rust land in a rusty way. For the first time, we are going to write code which is expected to run on only one CPU architecture, aarch64. We will structure our code so that we can easily extend the operating system to work on a matrix of CPUs and Motherboards.

Create a new file src/processors/aarch64/cpu.rs:

use aarch64_cpu::asm;

#[inline(always)]
pub fn wait_forever() -> ! {
    loop {
        asm::wfe()
    }
}

This function is really simple, it loops forever but with an interesting twist; it calls the Wait-For-Event instruction in ASM in order to optimize the forever loop so that the processor can go into a low power sleep mode until an event is received. Let's link this file into the rest of our crate and use it in our panic handler.

Create a file src/processors/aarch64/mod.rs:

pub mod cpu;

Then create src/processors/mod.rs:

mod aarch64;

#[cfg(target_arch = "aarch64")]
pub use aarch64::cpu::wait_forever;

Most of the code we are going to write will be either specific to a CPU type or specific to a motherboard so we will be doing this kind of modularization from the start so that our code is well organized and maintainable.

Finally, add the following content to src/main.rs:

mod processors;

We can go back to panic_cfg.rs and update the implementation of fn panic():

#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    crate::processors::wait_forever()
}

At this point, cargo check is no longer failing and if we run cargo build it succeeds with a warning:

warning: linker stderr: rust-lld: cannot find entry symbol _start; not setting start address

Bro is looking for a way in but we have not provided any.

Conclusion

The binary is pretty much useless without a recognizable entry point but we have one foot in the door now. In Part 2 we are going to be implementing an entry point for our kernel

Concurrency in Golang

BENKAY THE FIRST — Sun, 20 Dec 2020 19:06:01 +0000

In golang, concurrency is made possible through the use of goroutines and channels.
goroutines are basically "thread-like" lightweight structures that complete activities without blocking the main thread. They are basically a "fire and forget" cause go cleans up when a goroutine is completed. If however, we want to get data out of our goroutine process when it is done then we can use channels.

import "fmt"

// Essentially this is how we fire a goroutine

func runForAWhile(){
  // do something pretty that takes 5 secs or 2 yrs
}

func main(){
  go runForAWhile()
  fmt.Println("I am not waiting for that...")
}

Once we use the go keyword, Go knows to send the operation of that function out of the main scope and continue executing the rest of the code. The program does not end however until the goroutine is complete.
When you run the above example, you'd notice that the Println statement runs almost instantly while the program itself ends after the goroutine has supposedly ended.
Channels are an effective way to wait on output from our goroutine before ending the program. Let's say we made two API calls using two goroutines, we surely want to get that result back into the main scope. Here is an example code that describes how you could achieve that:

import "fmt"

func apiRequest1(c chan string){
  var result string
  result = makeApiCall1()
  c <- result
}

func apiRequest2(c chan string){
  var result string
  result = makeApiCall2()
  c <- result
}

func main(){
  var channel1, channel2 chan string
  go apiRequest1(channel1)
  go apiRequest2(channel2)

  result1 := <- channel1
  result2 := <- channel2

  fmt.Println(result1, result2)
}

How to write quality time-based tests in Golang

BENKAY THE FIRST — Sun, 20 Dec 2020 07:33:28 +0000

A few days ago, I decided to make a Pull Request of a feature I wrote myself for use at my company, a Rate-Limiting Middleware. Unlike other conventional middlewares in the package, rate-limiting is a really tricky one to write tests for because it requires a strictly time-based testing suite in order to test that it works as intended. Didn't seem like much to me at first. I wrote the tests and hit a 100% coverage and they all passed on my computer.

Opened a PR at Echo and noticed that on some environments, tests passed, while they failed on others. After trying to make sense of it I noticed that there was no pattern, the failure was totally random and unpredictable. I studied the source code and tried to pin the fault on a particular unit but every thing seemed flawless. That was when I tried to study the only variable factor, time. Since my tests depended on the clock of the host computer and the system ticks are subject to lags when the CPU undergoes strain, my tests will most likely fail on systems that have lower CPU power because of lags during each tick.
Here is a link to the Updated PR incase you want to see what is going on yourself:

adds middleware for rate limiting #1724

iambenkay posted on Dec 17, 2020

What's New?

This feature implements a store agnostic rate limiting middleware i.e configurable with any store of user's choice.

Here is a dummy snippet of how a certain (unconventional) redis store might be integrated with the rate limiting middleware

type RedisStore struct {
   client redis.Client
}

// Store config must implement Allow for rate limiting middleware
func (store *RedisStore) Allow(identifier) bool {
   // run logic here that decides if user should be permitted
   return true
}

func main(){
   e := echo.New()

   redisStore := RedisStore{
      client: redis.Client{}
   }
   
   limiterMW := middleware.RateLimiter(redisStore)
   e.Use(limiterMW)
}

I threw in an InMemory implementation for people like me who want to get on the go fast.

func main(){
   e := echo.New()

   var inMemoryStore = middleware.RateLimiterMemoryStore{
      rate: 1,
      burst: 3,
   }
   
   limiterMW := middleware.RateLimiterWithConfig(RateLimiterConfig{
      Store: &inMemoryStore,
      SourceFunc: func(ctx echo.Context) string {
         return ctx.RealIP()
      },
   })
   e.Use(limiterMW)
}

closes #1721

View on GitHub

So after I established that the system ticker cannot be trusted to provide a consistent tick rate enough to verify that my rate limiter works as intended, I set off to trick my tests by finding a stable time model that does not depend on the system ticker. The rest of this blog will cover the specifics.

Firstly, you'd need to wrap all usages of standard time helpers with custom functions that resolve to them. In my case the only main helper I needed to wrap was time.Now.

var now func() time.Time

now = func() time.Time {
  return time.Now()
}

Now in your source code, replace all occurrences of the now wrapped helpers with your custom helpers. The goal of this is to be able to use the original helpers in the main source code but easily mock them in the corresponding tests.

func (store *RateLimiterMemoryStore) Allow(identifier string) bool {
    store.mutex.Lock()
    limiter, exists := store.visitors[identifier]
    if !exists {
        limiter = new(Visitor)
        limiter.Limiter = rate.NewLimiter(store.rate, store.burst)
        limiter.lastSeen = now() // instead of time.Now()
        store.visitors[identifier] = limiter
    }
    limiter.lastSeen = now() // instead of time.Now()
    store.mutex.Unlock()
    if now().Sub(store.lastCleanup) > store.expiresIn {
        store.cleanupStaleVisitors()
    }
    return limiter.AllowN(now() /* instead of time.Now() */, 1)
}

Now in the context of our tests we have to change what now() returns from the standard time to our custom computed time:

func TestRateLimiterMemoryStore_Allow(t *testing.T) {
  var inMemoryStore = NewRateLimiterMemoryStore(RateLimiterMemoryStoreConfig{rate: 1, burst: 3, expiresIn: 2 * time.Second})
  testCases := []struct {
    id      string
    allowed bool
  }{
    {"127.0.0.1", true},  // 0 ms
    {"127.0.0.1", true},  // 220 ms burst #2
    {"127.0.0.1", true},  // 440 ms burst #3
    {"127.0.0.1", false}, // 660 ms block
    {"127.0.0.1", false}, // 880 ms block
    {"127.0.0.1", true},  // 1100 ms next second #1
    {"127.0.0.2", true},  // 1320 ms allow other ip
    {"127.0.0.1", false}, // 1540 ms no burst
    {"127.0.0.1", false}, // 1760 ms no burst
    {"127.0.0.1", false}, // 1980 ms no burst
    {"127.0.0.1", true},  // 2200 ms no burst
    {"127.0.0.1", false}, // 2420 ms no burst
    {"127.0.0.1", false}, // 2640 ms no burst
    {"127.0.0.1", false}, // 2860 ms no burst
    {"127.0.0.1", true},  // 3080 ms no burst
    {"127.0.0.1", false}, // 3300 ms no burst
  }

  for i, tc := range testCases {
    t.Logf("Running testcase #%d => %v", i, time.Duration(i)*220*time.Millisecond)
    // Should have been a time.Sleep here but we manually increase the value of the date that the now function returns using the iterator from the for loop.
    now = func() time.Time {
      return time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC).Add(time.Duration(i) * 220 * time.Millisecond)
    }
    allowed := inMemoryStore.Allow(tc.id)
    assert.Equal(t, tc.allowed, allowed)
  }
}

You'd notice I am not depending on time.Sleep or the system ticker to simulate a change in time for my tests. I am flexibly computing the next time in the for loop based on the iteration count. This way tests don't have to literally wait for the system ticker to actually tick before working with it's value and since the time is computed, in reality the tests will not actually have to wait for the required number of real live seconds to complete. Brings speed back to your tests and CPU agnostic flexibility. Now you can write time-based tests that will pass regardless of the clock speed of the CPU.

Setting up a git server on your Ubuntu Server for Continous Integration

BENKAY THE FIRST — Sat, 14 Nov 2020 18:13:28 +0000

Hey there! 👋 In the spirit of modern dev practices, I am writing this blog to highlight a life saver for me. When I started out as a backend developer, I used Heroku (and still use it occasionally) which has this amazing way of automatically building and deploying your apps whenever you push to the connected git repositories. I was forced to learn how to do it myself when my work started driving me to use bare-bone machines on AWS or Digital Ocean and I would always have to SSH into the server just to manually pull from my git repo and build it on my server before deploying. Coming from a lazy perspective, this was crazy work that I wasn't ready to do each time I make a change to the app and the spirit of automation started ringing in my ears.
The words that came into my head were "GIT SERVER"! I googled to see if it was a thing and luckily it was. I finally figured out how GitHub was able to do it. So I embarked on my own journey to make my own git server.
The next few paragraphs detail how I conquered that beast;
Well you do need git installed for starters so go do that first. This article assumes you have SSH set up on your ubuntu server.

Step 1

The first thing we need to do is create a git bare repository on our server.

# incase you already have a codebase
git clone --bare remote_repo_url.git server_repo.git

# but if you wanna start from scratch you could just use init
mkdir server_repo.git && cd server_repo.git
git init --bare

A bare git repository isn't like a regular repository. It stores our git objects but not the actual source code. It's typically the .git folder in a regular repository. After that we need to create a directory on the server to store the actual source code:

mkdir server_source

Step 2

Now, from a machine that has SSH Access to your ubuntu server you'll add your bare repository as a git remote:

git remote add production <username>@<machine>:server_repo.git

# You can now push to this remote
git push production master

# Or pull from it
git pull production master

basically server_repo.git has to be the location of your bare repo on the ubuntu server while username and machine are your login details just like when logging in with SSH.

Step 3

Next is the feature that makes all this possible. GIT HOOKS! I have written about them in the past here:

How to run tests automatically on each push to the repository | by Benjamin Chibuzor-Orie | FAUN — Developer Community 🐾

Benjamin Chibuzor-Orie ・ Aug 29, 2020 ・
Medium

Feel free to check it out. So essentially the hook we would be needing is the post-receive hook.

As the name implies, It runs after (post-) git objects are received from a remote.

Below is a typical post-receive file:

#! /bin/bash

# we have to set GIT_DIR env var to the bare repo
WORK_TREE=$HOME/server_source
GIT_DIR=$HOME/server_repo.git

# next up we have to checkout from our bare repo
git --work-tree=$WORKTREE --git-dir=$GIT_DIR checkout -f

# from here on we can do any other processes like building and 
# deploying the app
cd $WORK_TREE
docker-compose up --build -d

Now all we need to do is add this file to our git hooks. In our bare repo server_repo.git we need to create a new file post-receive under the hooks folder and then store the above in it.
We also need to make it executable on linux using chmod.

chmod a+x post-receive

After this we are good to go! Anytime we push to our production remote from our local, it will run the post-receive script and deploy our app.

If you have any questions, I'll be waiting in the comment sections to deal with it 🏌️‍♂️🏌️‍♂️

DEV Community: BENKAY THE FIRST

Building an Operating System In Rust Part 2

Prepare for Entry

Register

Execution stack

Stack pointer

Instruction

Program Counter

Implementing the boot image

Assembly Breakdown

The ADR_REL macro

Code section

Boot into primary CPU core

Initialize BSS

Jumping into Rust land

Writing the Linker Script

Conclusion

Building an Operating System In Rust Part 1

Project Setup

Installing Rust

Let there be night

Build tools

Install the Emulator

Setting up the Makefile.toml

Building the Foundation

Conclusion

Concurrency in Golang

How to write quality time-based tests in Golang

adds middleware for rate limiting #1724

What's New?

Setting up a git server on your Ubuntu Server for Continous Integration

Step 1

Step 2

Step 3

How to run tests automatically on each push to the repository | by Benjamin Chibuzor-Orie | FAUN — Developer Community 🐾

Benjamin Chibuzor-Orie ・ Aug 29, 2020 ・ Medium

Benjamin Chibuzor-Orie ・ Aug 29, 2020 ・
Medium