diff --git a/01_wait_forever/Cargo.toml b/01_wait_forever/Cargo.toml index 6d320b6e..e11addd3 100644 --- a/01_wait_forever/Cargo.toml +++ b/01_wait_forever/Cargo.toml @@ -14,4 +14,3 @@ bsp_rpi3 = [] bsp_rpi4 = [] [dependencies] - diff --git a/01_wait_forever/Makefile b/01_wait_forever/Makefile index 1c2be3c7..7b972f11 100644 --- a/01_wait_forever/Makefile +++ b/01_wait_forever/Makefile @@ -13,16 +13,16 @@ ifeq ($(BSP),rpi3) OUTPUT = kernel8.img QEMU_BINARY = qemu-system-aarch64 QEMU_MACHINE_TYPE = raspi3 - QEMU_RELEASE_ARGS = -serial stdio -display none - LINKER_FILE = src/bsp/rpi/link.ld + QEMU_RELEASE_ARGS = -d in_asm -display none + LINKER_FILE = src/bsp/raspberrypi/link.ld RUSTC_MISC_ARGS = -C target-cpu=cortex-a53 else ifeq ($(BSP),rpi4) TARGET = aarch64-unknown-none-softfloat OUTPUT = kernel8.img # QEMU_BINARY = qemu-system-aarch64 # QEMU_MACHINE_TYPE = - # QEMU_RELEASE_ARGS = -serial stdio -display none - LINKER_FILE = src/bsp/rpi/link.ld + # QEMU_RELEASE_ARGS = -d in_asm -display none + LINKER_FILE = src/bsp/raspberrypi/link.ld RUSTC_MISC_ARGS = -C target-cpu=cortex-a72 endif @@ -60,8 +60,7 @@ $(OUTPUT): $(CARGO_OUTPUT) $(OBJCOPY_CMD) $< $(OUTPUT) doc: - cargo xdoc --target=$(TARGET) --features bsp_$(BSP) --document-private-items - xdg-open target/$(TARGET)/doc/kernel/index.html + cargo xdoc --target=$(TARGET) --features bsp_$(BSP) --document-private-items --open ifeq ($(QEMU_MACHINE_TYPE),) qemu: diff --git a/01_wait_forever/README.md b/01_wait_forever/README.md index e8994cb3..489ad99a 100644 --- a/01_wait_forever/README.md +++ b/01_wait_forever/README.md @@ -2,11 +2,13 @@ ## tl;dr -Project skeleton is set up; Code just halts all CPU cores executing the kernel code. +The project skeleton is set up; A small piece of assembly code runs that just halts all CPU cores +executing the kernel code. -- Toolchain: `cargo xbuild` tools (`xrustc`, `xclippy`) and the - `aarch64-unknown-none-softfloat` target are used for building `AArch64` - bare-metal code. +## Building + +- Toolchain: `cargo xbuild` tools (`xrustc`, `xclippy`) and the `aarch64-unknown-none-softfloat` + target are used for building `AArch64` bare-metal code. - `Makefile` targets: - `doc`: Generate documentation. - `qemu`: Run the `kernel` in QEMU @@ -15,17 +17,16 @@ Project skeleton is set up; Code just halts all CPU cores executing the kernel c - `readelf`: Inspect the `ELF` output. - `objdump`: Inspect the assembly. - `nm`: Inspect the symbols. -- Code is organized into `kernel`, `arch` and `BSP` (Board Support Package) - parts. - - Conditional compilation includes respective `arch` and `BSP` according to - user-supplied arguments. + +## Code to look at + - Custom `link.ld` linker script. - Load address at `0x80_000` - Only `.text` section. - `main.rs`: Important [inner attributes]: - `#![no_std]`, `#![no_main]` -- Assembly `_start()` function that executes `wfe` (Wait For Event), halting all - cores that are executing `_start()`. +- `cpu.S`: Assembly `_start()` function that executes `wfe` (Wait For Event), halting all cores that + are executing `_start()`. - We (have to) define a `#[panic_handler]` function. - Just waits infinitely for a cpu event. @@ -35,7 +36,7 @@ Project skeleton is set up; Code just halts all CPU cores executing the kernel c In the project folder, invoke QEMU and observe the CPU core spinning on `wfe`: ```console -ยป make qemu +$ make qemu [...] IN: 0x00080000: d503205f wfe diff --git a/01_wait_forever/src/arch/aarch64/start.S b/01_wait_forever/src/_arch/aarch64/cpu.S similarity index 100% rename from 01_wait_forever/src/arch/aarch64/start.S rename to 01_wait_forever/src/_arch/aarch64/cpu.S diff --git a/01_wait_forever/src/arch/aarch64.rs b/01_wait_forever/src/_arch/aarch64/cpu.rs similarity index 73% rename from 01_wait_forever/src/arch/aarch64.rs rename to 01_wait_forever/src/_arch/aarch64/cpu.rs index b8cc7b47..dbd73bab 100644 --- a/01_wait_forever/src/arch/aarch64.rs +++ b/01_wait_forever/src/_arch/aarch64/cpu.rs @@ -2,15 +2,16 @@ // // Copyright (c) 2018-2020 Andre Richter -//! AArch64. +//! Architectural processor code. -global_asm!(include_str!("aarch64/start.S")); +// Assembly counterpart to this file. +global_asm!(include_str!("cpu.S")); //-------------------------------------------------------------------------------------------------- -// Implementation of the kernel's architecture abstraction code +// Public Code //-------------------------------------------------------------------------------------------------- -/// Pause execution on the calling CPU core. +/// Pause execution on the core. #[inline(always)] pub fn wait_forever() -> ! { unsafe { diff --git a/01_wait_forever/src/arch.rs b/01_wait_forever/src/arch.rs deleted file mode 100644 index 005f848b..00000000 --- a/01_wait_forever/src/arch.rs +++ /dev/null @@ -1,11 +0,0 @@ -// SPDX-License-Identifier: MIT OR Apache-2.0 -// -// Copyright (c) 2018-2020 Andre Richter - -//! Conditional exporting of processor architecture code. - -#[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))] -mod aarch64; - -#[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))] -pub use aarch64::*; diff --git a/01_wait_forever/src/bsp.rs b/01_wait_forever/src/bsp.rs index e8222317..db48385e 100644 --- a/01_wait_forever/src/bsp.rs +++ b/01_wait_forever/src/bsp.rs @@ -2,10 +2,10 @@ // // Copyright (c) 2018-2020 Andre Richter -//! Conditional exporting of Board Support Packages. +//! Conditional re-exporting of Board Support Packages. #[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))] -mod rpi; +mod raspberrypi; #[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))] -pub use rpi::*; +pub use raspberrypi::*; diff --git a/01_wait_forever/src/bsp/rpi.rs b/01_wait_forever/src/bsp/raspberrypi.rs similarity index 71% rename from 01_wait_forever/src/bsp/rpi.rs rename to 01_wait_forever/src/bsp/raspberrypi.rs index b5fc8d05..cdaac740 100644 --- a/01_wait_forever/src/bsp/rpi.rs +++ b/01_wait_forever/src/bsp/raspberrypi.rs @@ -2,6 +2,6 @@ // // Copyright (c) 2018-2020 Andre Richter -//! Board Support Package for the Raspberry Pi. +//! Top-level BSP file for the Raspberry Pi 3 and 4. // Coming soon. diff --git a/01_wait_forever/src/bsp/rpi/link.ld b/01_wait_forever/src/bsp/raspberrypi/link.ld similarity index 100% rename from 01_wait_forever/src/bsp/rpi/link.ld rename to 01_wait_forever/src/bsp/raspberrypi/link.ld diff --git a/01_wait_forever/src/cpu.rs b/01_wait_forever/src/cpu.rs new file mode 100644 index 00000000..fd5c9794 --- /dev/null +++ b/01_wait_forever/src/cpu.rs @@ -0,0 +1,10 @@ +// SPDX-License-Identifier: MIT OR Apache-2.0 +// +// Copyright (c) 2020 Andre Richter + +//! Processor code. + +#[cfg(target_arch = "aarch64")] +#[path = "_arch/aarch64/cpu.rs"] +mod arch_cpu; +pub use arch_cpu::*; diff --git a/01_wait_forever/src/main.rs b/01_wait_forever/src/main.rs index 4b62a48e..28b68b59 100644 --- a/01_wait_forever/src/main.rs +++ b/01_wait_forever/src/main.rs @@ -5,20 +5,102 @@ // Rust embedded logo for `make doc`. #![doc(html_logo_url = "https://git.io/JeGIp")] -//! The `kernel` +//! The `kernel` binary. +//! +//! # 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::*` #![feature(asm)] #![feature(global_asm)] #![no_main] #![no_std] -// Conditionally includes the selected `architecture` code, which provides the `_start()` function, -// the first function to run. -mod arch; +// `mod cpu` provides the `_start()` function, the first function to run. -// Conditionally includes the selected `BSP` code. mod bsp; - +mod cpu; mod panic_wait; // Kernel code coming next tutorial. diff --git a/01_wait_forever/src/panic_wait.rs b/01_wait_forever/src/panic_wait.rs index 015a36d0..560a1724 100644 --- a/01_wait_forever/src/panic_wait.rs +++ b/01_wait_forever/src/panic_wait.rs @@ -4,9 +4,10 @@ //! A panic handler that infinitely waits. +use crate::cpu; use core::panic::PanicInfo; #[panic_handler] fn panic(_info: &PanicInfo) -> ! { - crate::arch::wait_forever() + cpu::wait_forever() }