rust-raspberrypi-OS-tutorials/00_before_we_start/README.md

Before we start

The following text is a 1:1 copy of the documentation that can be found at the top of the kernel's main source code file in each tutorial. It describes the general structure of the source code, and tries to convey the philosophy behind the respective approach. Please read it to make yourself familiar with what you will encounter during the tutorials. It will help you to navigate the code better and understand the differences and additions between the separate tutorials.

Please also note that the following text will reference source code files (e.g. **/memory.rs) or functions that won't exist yet in the first bunch of the tutorials. They will be added gradually as the tutorials advance.

Have fun!

Code organization and architecture

The code is divided into different modules, each representing a typical subsystem of the kernel. Top-level module files of subsystems reside directly in the src folder. For example, src/memory.rs contains code that is concerned with all things memory management.

Visibility of processor architecture code

Some of the kernel's subsystems depend on low-level code that is specific to the target processor architecture. For each supported processor architecture, there exists a subfolder in src/_arch, for example, src/_arch/aarch64.

The architecture folders mirror the subsystem modules laid out in src. For example, architectural code that belongs to the kernel's memory subsystem (src/memory.rs) would go into src/_arch/aarch64/memory.rs. The latter file is directly included and re-exported in src/memory.rs, so that the architectural code parts are transparent with respect to the code's module organization. That means a public function foo() defined in src/_arch/aarch64/memory.rs would be reachable as crate::memory::foo() only.

The _ in _arch denotes that this folder is not part of the standard module hierarchy. Rather, it's contents are conditionally pulled into respective files using the #[path = "_arch/xxx/yyy.rs"] attribute.

BSP code

BSP stands for Board Support Package. BSP code is organized under src/bsp.rs and contains target board specific definitions and functions. These are things such as the board's memory map or instances of drivers for devices that are featured on the respective board.

Just like processor architecture code, the BSP code's module structure tries to mirror the kernel's subsystem modules, but there is no transparent re-exporting this time. That means whatever is provided must be called starting from the bsp namespace, e.g. bsp::driver::driver_manager().

Kernel interfaces

Both arch and bsp contain code that is conditionally compiled depending on the actual target and board for which the kernel is compiled. For example, the interrupt controller hardware of the Raspberry Pi 3 and the Raspberry Pi 4 is different, but we want the rest of the kernel code to play nicely with any of the two without much hassle.

In order to provide a clean abstraction between arch, bsp and generic kernel code, interface traits are provided whenever possible and where it makes sense. They are defined in the respective subsystem module and help to enforce the idiom of program to an interface, not an implementation. For example, there will be a common IRQ handling interface which the two different interrupt controller drivers of both Raspberrys will implement, and only export the interface to the rest of the kernel.

        +-------------------+
        | Interface (Trait) |
        |                   |
        +--+-------------+--+
           ^             ^
           |             |
           |             |
+----------+--+       +--+----------+
| kernel code |       |  bsp code   |
|             |       |  arch code  |
+-------------+       +-------------+

Summary

For a logical kernel subsystem, corresponding code can be distributed over several physical locations. Here is an example for the memory subsystem:

• src/memory.rs and src/memory/**/*
  • Common code that is agnostic of target processor architecture and BSP characteristics.
    • Example: A function to zero a chunk of memory.
  • Interfaces for the memory subsystem that are implemented by arch or BSP code.
    • Example: An MMU interface that defines MMU function prototypes.
• src/bsp/__board_name__/memory.rs and src/bsp/__board_name__/memory/**/*
  • BSP specific code.
  • Example: The board's memory map (physical addresses of DRAM and MMIO devices).
• src/_arch/__arch_name__/memory.rs and src/_arch/__arch_name__/memory/**/*
  • Processor architecture specific code.
  • Example: Implementation of the MMU interface for the __arch_name__ processor architecture.

From a namespace perspective, memory subsystem code lives in:

• crate::memory::*
• crate::bsp::memory::*