Refactoring

- Don't wildcard-import from arch modules. Make it explicit.
- Put translation table code into its own module.
- Put boot code in boot.rs instead of cpu.rs
- Other minor changes, most memory subsystem.

Author: andre-richter

00_before_we_start/README.md

@@ -12,7 +12,7 @@ the tutorials advance.
 
 Have fun!
 
-## Code organization and architecture
+# 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,
@@ -25,15 +25,22 @@ architecture. For each supported processor architecture, there exists a subfolde
 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.
+code that belongs to the `kernel`'s MMU subsystem (`src/memory/mmu.rs`) would go into
+`src/_arch/aarch64/memory/mmu.rs`. The latter file is loaded as a module in `src/memory/mmu.rs`
+using the `path attribute`. Usually, the chosen module name is the generic module's name prefixed
+with `arch_`.
 
-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.
+For example, this is the top of `src/memory/mmu.rs`:
+
+```
+#[cfg(target_arch = "aarch64")]
+#[path = "../_arch/aarch64/memory/mmu.rs"]
+mod arch_mmu;
+```
+
+Often times, items from the `arch_ module` will be publicly reexported by the parent module. This
+way, each architecture specific module can provide its implementation of an item, while the caller
+must not be concerned which architecture has been conditionally compiled.
 
 ## BSP code
 
@@ -42,9 +49,8 @@ target board specific definitions and functions. These are things such as the bo
 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`'s subsystem modules, but there is no reexporting this time. That means whatever is provided
+must be called starting from the `bsp` namespace, e.g. `bsp::driver::driver_manager()`.
 
 ## Kernel interfaces
 
@@ -96,3 +102,10 @@ From a namespace perspective, **memory** subsystem code lives in:
 
 - `crate::memory::*`
 - `crate::bsp::memory::*`
+
+# Boot flow
+
+1. The kernel's entry point is the function `cpu::boot::arch_boot::_start()`.
+    - It is implemented in `src/_arch/__arch_name__/cpu/boot.rs`.
+
+

01_wait_forever/Makefile

@@ -34,8 +34,9 @@ export LINKER_FILE
 RUSTFLAGS          = -C link-arg=-T$(LINKER_FILE) $(RUSTC_MISC_ARGS)
 RUSTFLAGS_PEDANTIC = $(RUSTFLAGS) -D warnings -D missing_docs
 
+FEATURES      = bsp_$(BSP)
 COMPILER_ARGS = --target=$(TARGET) \
-    --features bsp_$(BSP)          \
+    --features $(FEATURES)         \
     --release
 
 RUSTC_CMD   = cargo rustc $(COMPILER_ARGS)

01_wait_forever/README.md

@@ -23,8 +23,8 @@
     - Only `.text` section.
 - `main.rs`: Important [inner attributes]:
     - `#![no_std]`, `#![no_main]`
-- `cpu.S`: Assembly `_start()` function that executes `wfe` (Wait For Event), halting all cores that
-  are executing `_start()`.
+- `boot.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 to make the compiler happy.
     - Make it `unimplemented!()` because it will be stripped out since it is not used.
 

01_wait_forever/src/_arch/aarch64/cpu.rs

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! Architectural boot code.
+//!
+//! # Orientation
+//!
+//! Since arch modules are imported into generic modules using the path attribute, the path of this
+//! file is:
+//!
+//! crate::cpu::boot::arch_boot
+
+// Assembly counterpart to this file. Includes function _start().
+global_asm!(include_str!("boot.S"));

01_wait_forever/src/_arch/aarch64/cpu.S …ait_forever/src/_arch/aarch64/cpu/boot.S01_wait_forever/src/_arch/aarch64/cpu.S renamed to 01_wait_forever/src/_arch/aarch64/cpu/boot.S 01_wait_forever/src/_arch/aarch64/cpu.S renamed to 01_wait_forever/src/_arch/aarch64/cpu/boot.S

@@ -2,7 +2,7 @@
 //
 // Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
 
-//! Conditional re-exporting of Board Support Packages.
+//! Conditional reexporting of Board Support Packages.
 
 #[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))]
 mod raspberrypi;

01_wait_forever/src/_arch/aarch64/cpu/boot.rs

@@ -4,7 +4,4 @@
 
 //! Processor code.
 
-#[cfg(target_arch = "aarch64")]
-#[path = "_arch/aarch64/cpu.rs"]
-mod arch_cpu;
-pub use arch_cpu::*;
+mod boot;

01_wait_forever/src/bsp.rs

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! Boot code.
+
+#[cfg(target_arch = "aarch64")]
+#[path = "../_arch/aarch64/cpu/boot.rs"]
+mod arch_boot;

01_wait_forever/src/cpu.rs

@@ -20,15 +20,22 @@
 //! `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.
+//! architectural code that belongs to the `kernel`'s MMU subsystem (`src/memory/mmu.rs`) would go
+//! into `src/_arch/aarch64/memory/mmu.rs`. The latter file is loaded as a module in
+//! `src/memory/mmu.rs` using the `path attribute`. Usually, the chosen module name is the generic
+//! module's name prefixed with `arch_`.
 //!
-//! 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.
+//! For example, this is the top of `src/memory/mmu.rs`:
+//!
+//! ```
+//! #[cfg(target_arch = "aarch64")]
+//! #[path = "../_arch/aarch64/memory/mmu.rs"]
+//! mod arch_mmu;
+//! ```
+//!
+//! Often times, items from the `arch_ module` will be publicly reexported by the parent module.
+//! This way, each architecture specific module can provide its implementation of an item, while the
+//! caller must not be concerned which architecture has been conditionally compiled.
 //!
 //! ## BSP code
 //!
@@ -37,9 +44,8 @@
 //! 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`'s subsystem modules, but there is no reexporting this time. That means whatever is
+//! provided must be called starting from the `bsp` namespace, e.g. `bsp::driver::driver_manager()`.
 //!
 //! ## Kernel interfaces
 //!
@@ -91,14 +97,17 @@
 //!
 //! - `crate::memory::*`
 //! - `crate::bsp::memory::*`
+//!
+//! # Boot flow
+//!
+//! 1. The kernel's entry point is the function `cpu::boot::arch_boot::_start()`.
+//!     - It is implemented in `src/_arch/__arch_name__/cpu/boot.S`.
 
 #![feature(asm)]
 #![feature(global_asm)]
 #![no_main]
 #![no_std]
 
-// `mod cpu` provides the `_start()` function, the first function to run.
-
 mod bsp;
 mod cpu;
 mod panic_wait;