Refactor tutorial 10

pull/51/head
Andre Richter 4 years ago
parent 13a59172a5
commit 353cc4b6d5
No known key found for this signature in database
GPG Key ID: 2116C1AB102F615E

@ -21,7 +21,7 @@ ifeq ($(BSP),rpi3)
QEMU_RELEASE_ARGS = -serial stdio -display none
OPENOCD_ARG = -f /openocd/tcl/interface/ftdi/olimex-arm-usb-tiny-h.cfg -f /openocd/rpi3.cfg
JTAG_BOOT_IMAGE = jtag_boot_rpi3.img
LINKER_FILE = src/bsp/rpi/link.ld
LINKER_FILE = src/bsp/raspberrypi/link.ld
RUSTC_MISC_ARGS = -C target-cpu=cortex-a53
else ifeq ($(BSP),rpi4)
TARGET = aarch64-unknown-none-softfloat
@ -31,7 +31,7 @@ else ifeq ($(BSP),rpi4)
# QEMU_RELEASE_ARGS = -serial stdio -display none
OPENOCD_ARG = -f /openocd/tcl/interface/ftdi/olimex-arm-usb-tiny-h.cfg -f /openocd/rpi4.cfg
JTAG_BOOT_IMAGE = jtag_boot_rpi4.img
LINKER_FILE = src/bsp/rpi/link.ld
LINKER_FILE = src/bsp/raspberrypi/link.ld
RUSTC_MISC_ARGS = -C target-cpu=cortex-a72
endif
@ -74,8 +74,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:

@ -2,8 +2,8 @@
## tl;dr
In early boot code, we transition from the `Hypervisor` privilege level (`EL2`
in AArch64) to the `Kernel` (`EL1`) privilege level.
In early boot code, we transition from the `Hypervisor` privilege level (`EL2` in AArch64) to the
`Kernel` (`EL1`) privilege level.
## Table of Contents
@ -51,10 +51,8 @@ to transition to `EL1`:
```rust
pub unsafe extern "C" fn _start() -> ! {
const CORE_MASK: u64 = 0x3;
// Expect the boot core to start in EL2.
if (bsp::BOOT_CORE_ID == MPIDR_EL1.get() & CORE_MASK)
if (bsp::cpu::BOOT_CORE_ID == cpu::smp::core_id())
&& (CurrentEL.get() == CurrentEL::EL::EL2.value)
{
el2_to_el1_transition()
@ -116,7 +114,7 @@ in an upcoming tutorial.
```rust
// Set up a simulated exception return.
//
// First, fake a saved program status, where all interrupts were masked and SP_EL1 was used as a
// First, fake a saved program status where all interrupts were masked and SP_EL1 was used as a
// stack pointer.
SPSR_EL2.write(
SPSR_EL2::D::Masked
@ -126,22 +124,22 @@ SPSR_EL2.write(
+ SPSR_EL2::M::EL1h,
);
// Second, let the link register point to init().
ELR_EL2.set(crate::runtime_init::init as *const () as u64);
// Second, let the link register point to runtime_init().
ELR_EL2.set(runtime_init::runtime_init as *const () as u64);
```
As you can see, we are populating `ELR_EL2` with the address of the [init()] function that we
earlier used to call directly from the entrypoint.
As you can see, we are populating `ELR_EL2` with the address of the [runtime_init()] function that
we earlier used to call directly from the entrypoint.
Finally, we set the stack pointer for `SP_EL1` and call `ERET`:
[init()]: src/runtime_init.rs
[runtime_init()]: src/runtime_init.rs
```rust
// Set up SP_EL1 (stack pointer), which will be used by EL1 once we "return" to it.
SP_EL1.set(bsp::BOOT_CORE_STACK_START);
SP_EL1.set(bsp::cpu::BOOT_CORE_STACK_START);
// Use `eret` to "return" to EL1. This will result in execution of `reset()` in EL1.
// Use `eret` to "return" to EL1. This results in execution of runtime_init() in EL1.
asm::eret()
```
@ -174,21 +172,22 @@ Disassembly of section .text:
8003c: mov w12, #0x80000
80040: msr HCR_EL2, x10
80044: msr SPSR_EL2, x11
80048: add x8, x8, #0xdd0
80048: add x8, x8, #0xda0
8004c: msr ELR_EL2, x8
80050: msr SP_EL1, x12
80054: eret
```
Looks good! Thanks zero-overhead abstractions in the
[cortex-a](https://github.com/rust-embedded/cortex-a) crate! :heart_eyes:
Looks good! Thanks zero-overhead abstractions in the [cortex-a] crate! :heart_eyes:
[cortex-a]: https://github.com/rust-embedded/cortex-a
## Test it
In `main.rs`, we additionally inspect if the mask bits in `SPSR_EL2` made it to `EL1` as well:
```console
» make chainboot
$ make chainboot
[...]
Minipush 1.0
@ -205,245 +204,19 @@ Minipush 1.0
[MP] ⏩ Pushing 15 KiB =========================================🦀 100% 0 KiB/s Time: 00:00:00
[ML] Loaded! Executing the payload now
[ 0.702482] Booting on: Raspberry Pi 3
[ 0.703570] Current privilege level: EL1
[ 0.705481] Exception handling state:
[ 0.707262] Debug: Masked
[ 0.708826] SError: Masked
[ 0.710389] IRQ: Masked
[ 0.711953] FIQ: Masked
[ 0.713518] Architectural timer resolution: 52 ns
[ 0.715819] Drivers loaded:
[ 0.717166] 1. GPIO
[ 0.718425] 2. PL011Uart
[ 0.719902] Timer test, spinning for 1 second
[ 1.722032] Echoing input now
[ 0.703812] Booting on: Raspberry Pi 3
[ 0.704900] Current privilege level: EL1
[ 0.706811] Exception handling state:
[ 0.708592] Debug: Masked
[ 0.710156] SError: Masked
[ 0.711719] IRQ: Masked
[ 0.713283] FIQ: Masked
[ 0.714848] Architectural timer resolution: 52 ns
[ 0.717149] Drivers loaded:
[ 0.718496] 1. BCM GPIO
[ 0.719929] 2. BCM PL011 UART
[ 0.721623] Timer test, spinning for 1 second
[ 1.723753] Echoing input now
```
## Diff to previous
```diff
diff -uNr 09_hw_debug_JTAG/src/arch/aarch64/exception.rs 10_privilege_level/src/arch/aarch64/exception.rs
--- 09_hw_debug_JTAG/src/arch/aarch64/exception.rs
+++ 10_privilege_level/src/arch/aarch64/exception.rs
@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
+
+//! Exception handling.
+
+use cortex_a::regs::*;
+
+//--------------------------------------------------------------------------------------------------
+// Arch-public
+//--------------------------------------------------------------------------------------------------
+
+pub trait DaifField {
+ fn daif_field() -> register::Field<u32, DAIF::Register>;
+}
+
+pub struct Debug;
+pub struct SError;
+pub struct IRQ;
+pub struct FIQ;
+
+impl DaifField for Debug {
+ fn daif_field() -> register::Field<u32, DAIF::Register> {
+ DAIF::D
+ }
+}
+
+impl DaifField for SError {
+ fn daif_field() -> register::Field<u32, DAIF::Register> {
+ DAIF::A
+ }
+}
+
+impl DaifField for IRQ {
+ fn daif_field() -> register::Field<u32, DAIF::Register> {
+ DAIF::I
+ }
+}
+
+impl DaifField for FIQ {
+ fn daif_field() -> register::Field<u32, DAIF::Register> {
+ DAIF::F
+ }
+}
+
+pub fn is_masked<T: DaifField>() -> bool {
+ DAIF.is_set(T::daif_field())
+}
diff -uNr 09_hw_debug_JTAG/src/arch/aarch64.rs 10_privilege_level/src/arch/aarch64.rs
--- 09_hw_debug_JTAG/src/arch/aarch64.rs
+++ 10_privilege_level/src/arch/aarch64.rs
@@ -4,6 +4,7 @@
//! AArch64.
+mod exception;
pub mod sync;
mod time;
@@ -21,15 +22,56 @@
pub unsafe extern "C" fn _start() -> ! {
const CORE_MASK: u64 = 0x3;
- if bsp::BOOT_CORE_ID == MPIDR_EL1.get() & CORE_MASK {
- SP.set(bsp::BOOT_CORE_STACK_START);
- crate::runtime_init::runtime_init()
+ // Expect the boot core to start in EL2.
+ if (bsp::BOOT_CORE_ID == MPIDR_EL1.get() & CORE_MASK)
+ && (CurrentEL.get() == CurrentEL::EL::EL2.value)
+ {
+ el2_to_el1_transition()
} else {
// If not core0, infinitely wait for events.
wait_forever()
}
}
+/// Transition from EL2 to EL1.
+///
+/// # Safety
+///
+/// - The HW state of EL1 must be prepared in a sound way.
+/// - Exception return from EL2 must must continue execution in EL1 with ´runtime_init::init()`.
+#[inline(always)]
+unsafe fn el2_to_el1_transition() -> ! {
+ // Enable timer counter registers for EL1.
+ CNTHCTL_EL2.write(CNTHCTL_EL2::EL1PCEN::SET + CNTHCTL_EL2::EL1PCTEN::SET);
+
+ // No offset for reading the counters.
+ CNTVOFF_EL2.set(0);
+
+ // Set EL1 execution state to AArch64.
+ HCR_EL2.write(HCR_EL2::RW::EL1IsAarch64);
+
+ // Set up a simulated exception return.
+ //
+ // First, fake a saved program status, where all interrupts were masked and SP_EL1 was used as a
+ // stack pointer.
+ SPSR_EL2.write(
+ SPSR_EL2::D::Masked
+ + SPSR_EL2::A::Masked
+ + SPSR_EL2::I::Masked
+ + SPSR_EL2::F::Masked
+ + SPSR_EL2::M::EL1h,
+ );
+
+ // Second, let the link register point to init().
+ ELR_EL2.set(crate::runtime_init::runtime_init as *const () as u64);
+
+ // Set up SP_EL1 (stack pointer), which will be used by EL1 once we "return" to it.
+ SP_EL1.set(bsp::BOOT_CORE_STACK_START);
+
+ // Use `eret` to "return" to EL1. This will result in execution of `reset()` in EL1.
+ asm::eret()
+}
+
//--------------------------------------------------------------------------------------------------
// Global instances
//--------------------------------------------------------------------------------------------------
@@ -61,3 +103,39 @@
asm::wfe()
}
}
+
+/// Information about the HW state.
+pub mod state {
+ use crate::arch::PrivilegeLevel;
+ use cortex_a::regs::*;
+
+ /// The processing element's current privilege level.
+ pub fn current_privilege_level() -> (PrivilegeLevel, &'static str) {
+ let el = CurrentEL.read_as_enum(CurrentEL::EL);
+ match el {
+ Some(CurrentEL::EL::Value::EL2) => (PrivilegeLevel::Hypervisor, "EL2"),
+ Some(CurrentEL::EL::Value::EL1) => (PrivilegeLevel::Kernel, "EL1"),
+ Some(CurrentEL::EL::Value::EL0) => (PrivilegeLevel::User, "EL0"),
+ _ => (PrivilegeLevel::Unknown, "Unknown"),
+ }
+ }
+
+ /// Print the AArch64 exceptions status.
+ #[rustfmt::skip]
+ pub fn print_exception_state() {
+ use super::{
+ exception,
+ exception::{Debug, SError, FIQ, IRQ},
+ };
+ use crate::info;
+
+ let to_mask_str = |x| -> _ {
+ if x { "Masked" } else { "Unmasked" }
+ };
+
+ info!(" Debug: {}", to_mask_str(exception::is_masked::<Debug>()));
+ info!(" SError: {}", to_mask_str(exception::is_masked::<SError>()));
+ info!(" IRQ: {}", to_mask_str(exception::is_masked::<IRQ>()));
+ info!(" FIQ: {}", to_mask_str(exception::is_masked::<FIQ>()));
+ }
+}
diff -uNr 09_hw_debug_JTAG/src/arch.rs 10_privilege_level/src/arch.rs
--- 09_hw_debug_JTAG/src/arch.rs
+++ 10_privilege_level/src/arch.rs
@@ -9,3 +9,13 @@
#[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))]
pub use aarch64::*;
+
+/// Architectural privilege level.
+#[allow(missing_docs)]
+#[derive(PartialEq)]
+pub enum PrivilegeLevel {
+ User,
+ Kernel,
+ Hypervisor,
+ Unknown,
+}
diff -uNr 09_hw_debug_JTAG/src/main.rs 10_privilege_level/src/main.rs
--- 09_hw_debug_JTAG/src/main.rs
+++ 10_privilege_level/src/main.rs
@@ -64,9 +64,16 @@
/// The main function running after the early init.
fn kernel_main() -> ! {
use core::time::Duration;
- use interface::time::Timer;
+ use interface::{console::All, time::Timer};
info!("Booting on: {}", bsp::board_name());
+
+ let (_, privilege_level) = arch::state::current_privilege_level();
+ info!("Current privilege level: {}", privilege_level);
+
+ info!("Exception handling state:");
+ arch::state::print_exception_state();
+
info!(
"Architectural timer resolution: {} ns",
arch::timer().resolution().as_nanos()
@@ -77,11 +84,12 @@
info!(" {}. {}", i + 1, driver.compatible());
}
- // Test a failing timer case.
- arch::timer().spin_for(Duration::from_nanos(1));
+ info!("Timer test, spinning for 1 second");
+ arch::timer().spin_for(Duration::from_secs(1));
+ info!("Echoing input now");
loop {
- info!("Spinning for 1 second");
- arch::timer().spin_for(Duration::from_secs(1));
+ let c = bsp::console().read_char();
+ bsp::console().write_char(c);
}
}
```

Binary file not shown.

Binary file not shown.

@ -2,15 +2,15 @@
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! AArch64.
//! Architectural processor code.
mod exception;
pub mod sync;
mod time;
use crate::{bsp, interface};
use crate::{bsp, cpu};
use cortex_a::{asm, regs::*};
//--------------------------------------------------------------------------------------------------
// Boot Code
//--------------------------------------------------------------------------------------------------
/// The entry of the `kernel` binary.
///
/// The function must be named `_start`, because the linker is looking for this exact name.
@ -18,12 +18,11 @@ use cortex_a::{asm, regs::*};
/// # Safety
///
/// - Linker script must ensure to place this function at `0x80_000`.
#[naked]
#[no_mangle]
pub unsafe extern "C" fn _start() -> ! {
const CORE_MASK: u64 = 0x3;
// Expect the boot core to start in EL2.
if (bsp::BOOT_CORE_ID == MPIDR_EL1.get() & CORE_MASK)
if (bsp::cpu::BOOT_CORE_ID == cpu::smp::core_id())
&& (CurrentEL.get() == CurrentEL::EL::EL2.value)
{
el2_to_el1_transition()
@ -38,9 +37,12 @@ pub unsafe extern "C" fn _start() -> ! {
/// # Safety
///
/// - The HW state of EL1 must be prepared in a sound way.
/// - Exception return from EL2 must must continue execution in EL1 with ´runtime_init::init()`.
/// - Exception return from EL2 must must continue execution in EL1 with
/// `runtime_init::runtime_init()`.
#[inline(always)]
unsafe fn el2_to_el1_transition() -> ! {
use crate::runtime_init;
// Enable timer counter registers for EL1.
CNTHCTL_EL2.write(CNTHCTL_EL2::EL1PCEN::SET + CNTHCTL_EL2::EL1PCTEN::SET);
@ -52,7 +54,7 @@ unsafe fn el2_to_el1_transition() -> ! {
// Set up a simulated exception return.
//
// First, fake a saved program status, where all interrupts were masked and SP_EL1 was used as a
// First, fake a saved program status where all interrupts were masked and SP_EL1 was used as a
// stack pointer.
SPSR_EL2.write(
SPSR_EL2::D::Masked
@ -62,80 +64,34 @@ unsafe fn el2_to_el1_transition() -> ! {
+ SPSR_EL2::M::EL1h,
);
// Second, let the link register point to init().
ELR_EL2.set(crate::runtime_init::runtime_init as *const () as u64);
// Second, let the link register point to runtime_init().
ELR_EL2.set(runtime_init::runtime_init as *const () as u64);
// Set up SP_EL1 (stack pointer), which will be used by EL1 once we "return" to it.
SP_EL1.set(bsp::BOOT_CORE_STACK_START);
SP_EL1.set(bsp::cpu::BOOT_CORE_STACK_START);
// Use `eret` to "return" to EL1. This will result in execution of `reset()` in EL1.
// Use `eret` to "return" to EL1. This results in execution of runtime_init() in EL1.
asm::eret()
}
//--------------------------------------------------------------------------------------------------
// Global instances
//--------------------------------------------------------------------------------------------------
static TIMER: time::Timer = time::Timer;
//--------------------------------------------------------------------------------------------------
// Implementation of the kernel's architecture abstraction code
// Public Code
//--------------------------------------------------------------------------------------------------
pub use asm::nop;
/// Spin for `n` cycles.
#[inline(always)]
pub fn spin_for_cycles(n: usize) {
for _ in 0..n {
asm::nop();
}
}
/// Return a reference to a `interface::time::TimeKeeper` implementation.
pub fn timer() -> &'static impl interface::time::Timer {
&TIMER
}
/// Pause execution on the calling CPU core.
/// Pause execution on the core.
#[inline(always)]
pub fn wait_forever() -> ! {
loop {
asm::wfe()
}
}
/// Information about the HW state.
pub mod state {
use crate::arch::PrivilegeLevel;
use cortex_a::regs::*;
/// The processing element's current privilege level.
pub fn current_privilege_level() -> (PrivilegeLevel, &'static str) {
let el = CurrentEL.read_as_enum(CurrentEL::EL);
match el {
Some(CurrentEL::EL::Value::EL2) => (PrivilegeLevel::Hypervisor, "EL2"),
Some(CurrentEL::EL::Value::EL1) => (PrivilegeLevel::Kernel, "EL1"),
Some(CurrentEL::EL::Value::EL0) => (PrivilegeLevel::User, "EL0"),
_ => (PrivilegeLevel::Unknown, "Unknown"),
}
}
/// Print the AArch64 exceptions status.
#[rustfmt::skip]
pub fn print_exception_state() {
use super::{
exception,
exception::{Debug, SError, FIQ, IRQ},
};
use crate::info;
let to_mask_str = |x| -> _ {
if x { "Masked" } else { "Unmasked" }
};
info!(" Debug: {}", to_mask_str(exception::is_masked::<Debug>()));
info!(" SError: {}", to_mask_str(exception::is_masked::<SError>()));
info!(" IRQ: {}", to_mask_str(exception::is_masked::<IRQ>()));
info!(" FIQ: {}", to_mask_str(exception::is_masked::<FIQ>()));
}
}

@ -0,0 +1,22 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Architectural symmetric multiprocessing.
use cortex_a::regs::*;
//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
/// Return the executing core's id.
#[inline(always)]
pub fn core_id<T>() -> T
where
T: From<u8>,
{
const CORE_MASK: u64 = 0b11;
T::from((MPIDR_EL1.get() & CORE_MASK) as u8)
}

@ -0,0 +1,23 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Architectural synchronous and asynchronous exception handling.
use cortex_a::regs::*;
//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
use crate::exception::PrivilegeLevel;
/// The processing element's current privilege level.
pub fn current_privilege_level() -> (PrivilegeLevel, &'static str) {
let el = CurrentEL.read_as_enum(CurrentEL::EL);
match el {
Some(CurrentEL::EL::Value::EL2) => (PrivilegeLevel::Hypervisor, "EL2"),
Some(CurrentEL::EL::Value::EL1) => (PrivilegeLevel::Kernel, "EL1"),
Some(CurrentEL::EL::Value::EL0) => (PrivilegeLevel::User, "EL0"),
_ => (PrivilegeLevel::Unknown, "Unknown"),
}
}

@ -0,0 +1,71 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Architectural asynchronous exception handling.
use cortex_a::regs::*;
//--------------------------------------------------------------------------------------------------
// Private Definitions
//--------------------------------------------------------------------------------------------------
trait DaifField {
fn daif_field() -> register::Field<u32, DAIF::Register>;
}
struct Debug;
struct SError;
struct IRQ;
struct FIQ;
//--------------------------------------------------------------------------------------------------
// Private Code
//--------------------------------------------------------------------------------------------------
impl DaifField for Debug {
fn daif_field() -> register::Field<u32, DAIF::Register> {
DAIF::D
}
}
impl DaifField for SError {
fn daif_field() -> register::Field<u32, DAIF::Register> {
DAIF::A
}
}
impl DaifField for IRQ {
fn daif_field() -> register::Field<u32, DAIF::Register> {
DAIF::I
}
}
impl DaifField for FIQ {
fn daif_field() -> register::Field<u32, DAIF::Register> {
DAIF::F
}
}
fn is_masked<T: DaifField>() -> bool {
DAIF.is_set(T::daif_field())
}
//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
/// Print the AArch64 exceptions status.
#[rustfmt::skip]
pub fn print_state() {
use crate::info;
let to_mask_str = |x| -> _ {
if x { "Masked" } else { "Unmasked" }
};
info!(" Debug: {}", to_mask_str(is_masked::<Debug>()));
info!(" SError: {}", to_mask_str(is_masked::<SError>()));
info!(" IRQ: {}", to_mask_str(is_masked::<IRQ>()));
info!(" FIQ: {}", to_mask_str(is_masked::<FIQ>()));
}

@ -2,25 +2,45 @@
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Timer primitives.
//! Architectural timer primitives.
use crate::{interface, warn};
use crate::{time, warn};
use core::time::Duration;
use cortex_a::regs::*;
//--------------------------------------------------------------------------------------------------
// Private Definitions
//--------------------------------------------------------------------------------------------------
const NS_PER_S: u64 = 1_000_000_000;
//--------------------------------------------------------------------------------------------------
// Arch-public
// Public Definitions
//--------------------------------------------------------------------------------------------------
/// ARMv8 Generic Timer.
pub struct GenericTimer;
//--------------------------------------------------------------------------------------------------
// Global instances
//--------------------------------------------------------------------------------------------------
pub struct Timer;
static TIME_MANAGER: GenericTimer = GenericTimer;
//--------------------------------------------------------------------------------------------------
// OS interface implementations
// Public Code
//--------------------------------------------------------------------------------------------------
impl interface::time::Timer for Timer {
/// Return a reference to the time manager.
pub fn time_manager() -> &'static impl time::interface::TimeManager {
&TIME_MANAGER
}
//------------------------------------------------------------------------------
// OS Interface Code
//------------------------------------------------------------------------------
impl time::interface::TimeManager for GenericTimer {
fn resolution(&self) -> Duration {
Duration::from_nanos(NS_PER_S / (CNTFRQ_EL0.get() as u64))
}

@ -1,21 +0,0 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! 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::*;
/// Architectural privilege level.
#[allow(missing_docs)]
#[derive(PartialEq)]
pub enum PrivilegeLevel {
User,
Kernel,
Hypervisor,
Unknown,
}

@ -1,48 +0,0 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Exception handling.
use cortex_a::regs::*;
//--------------------------------------------------------------------------------------------------
// Arch-public
//--------------------------------------------------------------------------------------------------
pub trait DaifField {
fn daif_field() -> register::Field<u32, DAIF::Register>;
}
pub struct Debug;
pub struct SError;
pub struct IRQ;
pub struct FIQ;
impl DaifField for Debug {
fn daif_field() -> register::Field<u32, DAIF::Register> {
DAIF::D
}
}
impl DaifField for SError {
fn daif_field() -> register::Field<u32, DAIF::Register> {
DAIF::A
}
}
impl DaifField for IRQ {
fn daif_field() -> register::Field<u32, DAIF::Register> {
DAIF::I
}
}
impl DaifField for FIQ {
fn daif_field() -> register::Field<u32, DAIF::Register> {
DAIF::F
}
}
pub fn is_masked<T: DaifField>() -> bool {
DAIF.is_set(T::daif_field())
}

@ -1,53 +0,0 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Synchronization primitives.
use crate::interface;
use core::cell::UnsafeCell;
//--------------------------------------------------------------------------------------------------
// Arch-public
//--------------------------------------------------------------------------------------------------
/// A pseudo-lock for teaching purposes.
///
/// Used to introduce [interior mutability].
///
/// In contrast to a real Mutex implementation, does not protect against concurrent access to the
/// contained data. This part is preserved for later lessons.
///
/// The lock will only be used as long as it is safe to do so, i.e. as long as the kernel is
/// executing single-threaded, aka only running on a single core with interrupts disabled.
///
/// [interior mutability]: https://doc.rust-lang.org/std/cell/index.html
pub struct NullLock<T: ?Sized> {
data: UnsafeCell<T>,
}
unsafe impl<T: ?Sized + Send> Send for NullLock<T> {}
unsafe impl<T: ?Sized + Send> Sync for NullLock<T> {}
impl<T> NullLock<T> {
/// Wraps `data` into a new `NullLock`.
pub const fn new(data: T) -> NullLock<T> {
NullLock {
data: UnsafeCell::new(data),
}
}
}
//--------------------------------------------------------------------------------------------------
// OS interface implementations
//--------------------------------------------------------------------------------------------------
impl<T> interface::sync::Mutex for &NullLock<T> {
type Data = T;
fn lock<R>(&mut self, f: impl FnOnce(&mut Self::Data) -> R) -> R {
// In a real lock, there would be code encapsulating this line that ensures that this
// mutable reference will ever only be given out once at a time.
f(unsafe { &mut *self.data.get() })
}
}

@ -2,12 +2,12 @@
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Conditional exporting of Board Support Packages.
//! Conditional re-exporting of Board Support Packages.
mod driver;
mod device_driver;
#[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::*;

@ -2,7 +2,7 @@
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Drivers.
//! Device driver.
#[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))]
mod bcm;

@ -7,5 +7,5 @@
mod bcm2xxx_gpio;
mod bcm2xxx_pl011_uart;
pub use bcm2xxx_gpio::GPIO;
pub use bcm2xxx_pl011_uart::{PL011Uart, PanicUart};
pub use bcm2xxx_gpio::*;
pub use bcm2xxx_pl011_uart::*;

@ -2,11 +2,15 @@
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! GPIO driver.
//! GPIO Driver.
use crate::{arch, arch::sync::NullLock, interface};
use crate::{cpu, driver, synchronization, synchronization::NullLock};
use core::ops;
use register::{mmio::ReadWrite, register_bitfields, register_structs};
use register::{mmio::*, register_bitfields, register_structs};
//--------------------------------------------------------------------------------------------------
// Private Definitions
//--------------------------------------------------------------------------------------------------
// GPIO registers.
//
@ -66,12 +70,23 @@ register_structs! {
}
}
/// The driver's private data.
struct GPIOInner {
base_addr: usize,
}
/// Deref to RegisterBlock.
//--------------------------------------------------------------------------------------------------
// Public Definitions
//--------------------------------------------------------------------------------------------------
/// Representation of the GPIO HW.
pub struct GPIO {
inner: NullLock<GPIOInner>,
}
//--------------------------------------------------------------------------------------------------
// Private Code
//--------------------------------------------------------------------------------------------------
impl ops::Deref for GPIOInner {
type Target = RegisterBlock;
@ -81,29 +96,28 @@ impl ops::Deref for GPIOInner {
}
impl GPIOInner {
const fn new(base_addr: usize) -> GPIOInner {
GPIOInner { base_addr }
const fn new(base_addr: usize) -> Self {
Self { base_addr }
}
/// Return a pointer to the register block.
/// Return a pointer to the associated MMIO register block.
fn ptr(&self) -> *const RegisterBlock {
self.base_addr as *const _
}
}
//--------------------------------------------------------------------------------------------------
// BSP-public
// Public Code
//--------------------------------------------------------------------------------------------------
use interface::sync::Mutex;
/// The driver's main struct.
pub struct GPIO {
inner: NullLock<GPIOInner>,
}
impl GPIO {
pub const unsafe fn new(base_addr: usize) -> GPIO {
GPIO {
/// Create an instance.
///
/// # Safety
///
/// - The user must ensure to provide the correct `base_addr`.
pub const unsafe fn new(base_addr: usize) -> Self {
Self {
inner: NullLock::new(GPIOInner::new(base_addr)),
}
}
@ -122,24 +136,25 @@ impl GPIO {
// Enable pins 14 and 15.
inner.GPPUD.set(0);
arch::spin_for_cycles(150);
cpu::spin_for_cycles(150);
inner
.GPPUDCLK0
.write(GPPUDCLK0::PUDCLK14::AssertClock + GPPUDCLK0::PUDCLK15::AssertClock);
arch::spin_for_cycles(150);
cpu::spin_for_cycles(150);
inner.GPPUDCLK0.set(0);
})
}
}
//--------------------------------------------------------------------------------------------------
// OS interface implementations
//--------------------------------------------------------------------------------------------------
//------------------------------------------------------------------------------
// OS Interface Code
//------------------------------------------------------------------------------
use synchronization::interface::Mutex;
impl interface::driver::DeviceDriver for GPIO {
impl driver::interface::DeviceDriver for GPIO {
fn compatible(&self) -> &str {
"GPIO"
"BCM GPIO"
}
}

@ -4,10 +4,14 @@
//! PL011 UART driver.
use crate::{arch, arch::sync::NullLock, interface};
use crate::{console, cpu, driver, synchronization, synchronization::NullLock};
use core::{fmt, ops};
use register::{mmio::*, register_bitfields, register_structs};
//--------------------------------------------------------------------------------------------------
// Private Definitions
//--------------------------------------------------------------------------------------------------
// PL011 UART registers.
//
// Descriptions taken from
@ -109,6 +113,10 @@ register_bitfields! {
]
}
//--------------------------------------------------------------------------------------------------
// Public Definitions
//--------------------------------------------------------------------------------------------------
register_structs! {
#[allow(non_snake_case)]
pub RegisterBlock {
@ -126,13 +134,24 @@ register_structs! {
}
}
/// The driver's mutex protected part.
pub struct PL011UartInner {
base_addr: usize,
chars_written: usize,
chars_read: usize,
}
// Export the inner struct so that BSPs can use it for the panic handler.
pub use PL011UartInner as PanicUart;
/// Representation of the UART.
pub struct PL011Uart {
inner: NullLock<PL011UartInner>,
}
//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
/// Deref to RegisterBlock.
///
/// Allows writing
@ -152,8 +171,13 @@ impl ops::Deref for PL011UartInner {
}
impl PL011UartInner {
pub const unsafe fn new(base_addr: usize) -> PL011UartInner {
PL011UartInner {
/// Create an instance.
///
/// # Safety
///
/// - The user must ensure to provide the correct `base_addr`.
pub const unsafe fn new(base_addr: usize) -> Self {
Self {
base_addr,
chars_written: 0,
chars_read: 0,
@ -164,7 +188,7 @@ impl PL011UartInner {
///
/// Results in 8N1 and 230400 baud (if the clk has been previously set to 48 MHz by the
/// firmware).
pub fn init(&self) {
pub fn init(&mut self) {
// Turn it off temporarily.
self.CR.set(0);
@ -186,7 +210,7 @@ impl PL011UartInner {
fn write_char(&mut self, c: char) {
// Spin while TX FIFO full is set, waiting for an empty slot.
while self.FR.matches_all(FR::TXFF::SET) {
arch::nop();
cpu::nop();
}
// Write the character to the buffer.
@ -215,42 +239,28 @@ impl fmt::Write for PL011UartInner {
}
}
//--------------------------------------------------------------------------------------------------
// Export the inner struct so that BSPs can use it for the panic handler
//--------------------------------------------------------------------------------------------------
pub use PL011UartInner as PanicUart;
//--------------------------------------------------------------------------------------------------
// BSP-public
//--------------------------------------------------------------------------------------------------
/// The driver's main struct.
pub struct PL011Uart {
inner: NullLock<PL011UartInner>,
}
impl PL011Uart {
/// # Safety
///
/// The user must ensure to provide the correct `base_addr`.
pub const unsafe fn new(base_addr: usize) -> PL011Uart {
PL011Uart {
/// - The user must ensure to provide the correct `base_addr`.
pub const unsafe fn new(base_addr: usize) -> Self {
Self {
inner: NullLock::new(PL011UartInner::new(base_addr)),
}
}
}
//--------------------------------------------------------------------------------------------------
// OS interface implementations
//--------------------------------------------------------------------------------------------------
use interface::sync::Mutex;
//------------------------------------------------------------------------------
// OS Interface Code
//------------------------------------------------------------------------------
use synchronization::interface::Mutex;
impl interface::driver::DeviceDriver for PL011Uart {
impl driver::interface::DeviceDriver for PL011Uart {
fn compatible(&self) -> &str {
"PL011Uart"
"BCM PL011 UART"
}
fn init(&self) -> interface::driver::Result {
fn init(&self) -> Result<(), ()> {
let mut r = &self.inner;
r.lock(|inner| inner.init());
@ -258,7 +268,7 @@ impl interface::driver::DeviceDriver for PL011Uart {
}
}
impl interface::console::Write for PL011Uart {
impl console::interface::Write for PL011Uart {
/// Passthrough of `args` to the `core::fmt::Write` implementation, but guarded by a Mutex to
/// serialize access.
fn write_char(&self, c: char) {
@ -274,23 +284,23 @@ impl interface::console::Write for PL011Uart {
}
fn flush(&self) {
let mut r = &self.inner;
// Spin until TX FIFO empty is set.
let mut r = &self.inner;
r.lock(|inner| {
while !inner.FR.matches_all(FR::TXFE::SET) {
arch::nop();
cpu::nop();
}
});
}
}
impl interface::console::Read for PL011Uart {
impl console::interface::Read for PL011Uart {
fn read_char(&self) -> char {
let mut r = &self.inner;
r.lock(|inner| {
// Spin while RX FIFO empty is set.
while inner.FR.matches_all(FR::RXFE::SET) {
arch::nop();
cpu::nop();
}
// Read one character.
@ -319,7 +329,7 @@ impl interface::console::Read for PL011Uart {
}
}
impl interface::console::Statistics for PL011Uart {
impl console::interface::Statistics for PL011Uart {
fn chars_written(&self) -> usize {
let mut r = &self.inner;
r.lock(|inner| inner.chars_written)

@ -0,0 +1,38 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Top-level BSP file for the Raspberry Pi 3 and 4.
pub mod console;
pub mod cpu;
pub mod driver;
pub mod memory;
//--------------------------------------------------------------------------------------------------
// Global instances
//--------------------------------------------------------------------------------------------------
use super::device_driver;
static GPIO: device_driver::GPIO =
unsafe { device_driver::GPIO::new(memory::map::mmio::GPIO_BASE) };
static PL011_UART: device_driver::PL011Uart =
unsafe { device_driver::PL011Uart::new(memory::map::mmio::PL011_UART_BASE) };
//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
/// Board identification.
pub fn board_name() -> &'static str {
#[cfg(feature = "bsp_rpi3")]
{
"Raspberry Pi 3"
}
#[cfg(feature = "bsp_rpi4")]
{
"Raspberry Pi 4"
}
}

@ -0,0 +1,30 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! BSP console facilities.
use super::{super::device_driver, memory::map};
use crate::console;
use core::fmt;
//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
/// In case of a panic, the panic handler uses this function to take a last shot at printing
/// something before the system is halted.
///
/// # Safety
///
/// - Use only for printing during a panic.
pub unsafe fn panic_console_out() -> impl fmt::Write {
let mut uart = device_driver::PanicUart::new(map::mmio::PL011_UART_BASE);
uart.init();
uart
}
/// Return a reference to the console.
pub fn console() -> &'static impl console::interface::All {
&super::PL011_UART
}

@ -0,0 +1,15 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! BSP Processor code.
//--------------------------------------------------------------------------------------------------
// Public Definitions
//--------------------------------------------------------------------------------------------------
/// Used by `arch` code to find the early boot core.
pub const BOOT_CORE_ID: usize = 0;
/// The early boot core's stack address.
pub const BOOT_CORE_STACK_START: u64 = 0x80_000;

@ -0,0 +1,49 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! BSP driver support.
use crate::driver;
//--------------------------------------------------------------------------------------------------
// Public Definitions
//--------------------------------------------------------------------------------------------------
/// Device Driver Manager type.
pub struct BSPDriverManager {
device_drivers: [&'static (dyn DeviceDriver + Sync); 2],
}
//--------------------------------------------------------------------------------------------------
// Global instances
//--------------------------------------------------------------------------------------------------
static BSP_DRIVER_MANAGER: BSPDriverManager = BSPDriverManager {
device_drivers: [&super::GPIO, &super::PL011_UART],
};
//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
/// Return a reference to the driver manager.
pub fn driver_manager() -> &'static impl driver::interface::DriverManager {
&BSP_DRIVER_MANAGER
}
//------------------------------------------------------------------------------
// OS Interface Code
//------------------------------------------------------------------------------
use driver::interface::DeviceDriver;
impl driver::interface::DriverManager for BSPDriverManager {
fn all_device_drivers(&self) -> &[&'static (dyn DeviceDriver + Sync)] {
&self.device_drivers[..]
}
fn post_device_driver_init(&self) {
// Configure PL011Uart's output pins.
super::GPIO.map_pl011_uart();
}
}

@ -0,0 +1,36 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! BSP Memory Management.
//--------------------------------------------------------------------------------------------------
// Public Definitions
//--------------------------------------------------------------------------------------------------
/// The board's memory map.
#[rustfmt::skip]
pub(super) mod map {
pub const GPIO_OFFSET: usize = 0x0020_0000;
pub const UART_OFFSET: usize = 0x0020_1000;
/// Physical devices.
#[cfg(feature = "bsp_rpi3")]
pub mod mmio {
use super::*;
pub const BASE: usize = 0x3F00_0000;
pub const GPIO_BASE: usize = BASE + GPIO_OFFSET;
pub const PL011_UART_BASE: usize = BASE + UART_OFFSET;
}
/// Physical devices.
#[cfg(feature = "bsp_rpi4")]
pub mod mmio {
use super::*;
pub const BASE: usize = 0xFE00_0000;
pub const GPIO_BASE: usize = BASE + GPIO_OFFSET;
pub const PL011_UART_BASE: usize = BASE + UART_OFFSET;
}
}

@ -1,74 +0,0 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Board Support Package for the Raspberry Pi.
mod memory_map;
use super::driver;
use crate::interface;
use core::fmt;
/// Used by `arch` code to find the early boot core.
pub const BOOT_CORE_ID: u64 = 0;
/// The early boot core's stack address.
pub const BOOT_CORE_STACK_START: u64 = 0x80_000;
//--------------------------------------------------------------------------------------------------
// Global BSP driver instances
//--------------------------------------------------------------------------------------------------
static GPIO: driver::GPIO = unsafe { driver::GPIO::new(memory_map::mmio::GPIO_BASE) };
static PL011_UART: driver::PL011Uart =
unsafe { driver::PL011Uart::new(memory_map::mmio::PL011_UART_BASE) };
//--------------------------------------------------------------------------------------------------
// Implementation of the kernel's BSP calls
//--------------------------------------------------------------------------------------------------
/// Board identification.
pub fn board_name() -> &'static str {
#[cfg(feature = "bsp_rpi3")]
{
"Raspberry Pi 3"
}
#[cfg(feature = "bsp_rpi4")]
{
"Raspberry Pi 4"
}
}
/// Return a reference to a `console::All` implementation.
pub fn console() -> &'static impl interface::console::All {
&PL011_UART
}
/// In case of a panic, the panic handler uses this function to take a last shot at printing
/// something before the system is halted.
///
/// # Safety
///
/// - Use only for printing during a panic.
pub unsafe fn panic_console_out() -> impl fmt::Write {
let uart = driver::PanicUart::new(memory_map::mmio::PL011_UART_BASE);
uart.init();
uart
}
/// Return an array of references to all `DeviceDriver` compatible `BSP` drivers.
///
/// # Safety
///
/// The order of devices is the order in which `DeviceDriver::init()` is called.
pub fn device_drivers() -> [&'static dyn interface::driver::DeviceDriver; 2] {
[&GPIO, &PL011_UART]
}
/// BSP initialization code that runs after driver init.
pub fn post_driver_init() {
// Configure PL011Uart's output pins.
GPIO.map_pl011_uart();
}

@ -1,18 +0,0 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! The board's memory map.
/// Physical devices.
#[rustfmt::skip]
pub mod mmio {
#[cfg(feature = "bsp_rpi3")]
pub const BASE: usize = 0x3F00_0000;
#[cfg(feature = "bsp_rpi4")]
pub const BASE: usize = 0xFE00_0000;
pub const GPIO_BASE: usize = BASE + 0x0020_0000;
pub const PL011_UART_BASE: usize = BASE + 0x0020_1000;
}

@ -0,0 +1,54 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! System console.
//--------------------------------------------------------------------------------------------------
// Public Definitions
//--------------------------------------------------------------------------------------------------
/// Console interfaces.
pub mod interface {
use core::fmt;
/// Console write functions.
pub trait Write {
/// Write a single character.
fn write_char(&self, c: char);
/// Write a Rust format string.
fn write_fmt(&self, args: fmt::Arguments) -> fmt::Result;
/// Block execution until the last character has been physically put on the TX wire
/// (draining TX buffers/FIFOs, if any).
fn flush(&self);
}
/// Console read functions.
pub trait Read {
/// Read a single character.
fn read_char(&self) -> char {
' '
}
/// Clear RX buffers, if any.
fn clear(&self);
}
/// Console statistics.
pub trait Statistics {
/// Return the number of characters written.
fn chars_written(&self) -> usize {
0
}
/// Return the number of characters read.
fn chars_read(&self) -> usize {
0
}
}
/// Trait alias for a full-fledged console.
pub trait All = Write + Read + Statistics;
}

@ -0,0 +1,12 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2020 Andre Richter <andre.o.richter@gmail.com>
//! Processor code.
#[cfg(target_arch = "aarch64")]
#[path = "_arch/aarch64/cpu.rs"]
mod arch_cpu;
pub use arch_cpu::*;
pub mod smp;

@ -0,0 +1,10 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Symmetric multiprocessing.
#[cfg(target_arch = "aarch64")]
#[path = "../_arch/aarch64/cpu/smp.rs"]
mod arch_cpu_smp;
pub use arch_cpu_smp::*;

@ -0,0 +1,41 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Driver support.
//--------------------------------------------------------------------------------------------------
// Public Definitions
//--------------------------------------------------------------------------------------------------
/// Driver interfaces.
pub mod interface {
/// Device Driver functions.
pub trait DeviceDriver {
/// Return a compatibility string for identifying the driver.
fn compatible(&self) -> &str;
/// Called by the kernel to bring up the device.
fn init(&self) -> Result<(), ()> {
Ok(())
}
}
/// Device driver management functions.
///
/// The `BSP` is supposed to supply one global instance.
pub trait DriverManager {
/// Return a slice of references to all `BSP`-instantiated drivers.
///
/// # Safety
///
/// - The order of devices is the order in which `DeviceDriver::init()` is called.
fn all_device_drivers(&self) -> &[&'static (dyn DeviceDriver + Sync)];
/// Initialization code that runs after driver init.
///
/// For example, device driver code that depends on other drivers already being online.
fn post_device_driver_init(&self);
}
}

@ -0,0 +1,26 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2020 Andre Richter <andre.o.richter@gmail.com>
//! Synchronous and asynchronous exception handling.
#[cfg(target_arch = "aarch64")]
#[path = "_arch/aarch64/exception.rs"]
mod arch_exception;
pub use arch_exception::*;
pub mod asynchronous;
//--------------------------------------------------------------------------------------------------
// Public Definitions
//--------------------------------------------------------------------------------------------------
/// Kernel privilege levels.
#[allow(missing_docs)]
#[derive(PartialEq)]
pub enum PrivilegeLevel {
User,
Kernel,
Hypervisor,
Unknown,
}

@ -0,0 +1,10 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2020 Andre Richter <andre.o.richter@gmail.com>
//! Asynchronous exception handling.
#[cfg(target_arch = "aarch64")]
#[path = "../_arch/aarch64/exception/asynchronous.rs"]
mod arch_exception_async;
pub use arch_exception_async::*;

@ -1,133 +0,0 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
//! Trait definitions for coupling `kernel` and `BSP` code.
//!
//! ```
//! +-------------------+
//! | Interface (Trait) |
//! | |
//! +--+-------------+--+
//! ^ ^
//! | |
//! | |
//! +----------+--+ +--+----------+
//! | Kernel code | | BSP Code |
//! | | | |
//! +-------------+ +-------------+
//! ```
/// System console operations.
pub mod console {
use core::fmt;
/// Console write functions.
pub trait Write {
/// Write a single character.
fn write_char(&self, c: char);
/// Write a Rust format string.
fn write_fmt(&self, args: fmt::Arguments) -> fmt::Result;
/// Block execution until the last character has been physically put on the TX wire
/// (draining TX buffers/FIFOs, if any).
fn flush(&self);
}
/// Console read functions.
pub trait Read {
/// Read a single character.
fn read_char(&self) -> char {
' '
}
/// Clear RX buffers, if any.
fn clear(&self);
}
/// Console statistics.
pub trait Statistics {
/// Return the number of characters written.
fn chars_written(&self) -> usize {
0
}
/// Return the number of characters read.
fn chars_read(&self) -> usize {
0
}
}
/// Trait alias for a full-fledged console.
pub trait All = Write + Read + Statistics;
}
/// Synchronization primitives.
pub mod sync {
/// Any object implementing this trait guarantees exclusive access to the data contained within
/// the mutex for the duration of the lock.
///
/// The trait follows the [Rust embedded WG's
/// proposal](https://github.com/korken89/wg/blob/master/rfcs/0377-mutex-trait.md) and therefore
/// provides some goodness such as [deadlock
/// prevention](https://github.com/korken89/wg/blob/master/rfcs/0377-mutex-trait.md#design-decisions-and-compatibility).
///
/// # Example
///
/// Since the lock function takes an `&mut self` to enable deadlock-prevention, the trait is
/// best implemented **for a reference to a container struct**, and has a usage pattern that
/// might feel strange at first:
///
/// ```
/// static MUT: Mutex<RefCell<i32>> = Mutex::new(RefCell::new(0));
///
/// fn foo() {
/// let mut r = &MUT; // Note that r is mutable
/// r.lock(|data| *data += 1);
/// }
/// ```
pub trait Mutex {
/// Type of data encapsulated by the mutex.
type Data;
/// Creates a critical section and grants temporary mutable access to the encapsulated data.
fn lock<R>(&mut self, f: impl FnOnce(&mut Self::Data) -> R) -> R;
}
}
/// Driver interfaces.
pub mod driver {
/// Driver result type, e.g. for indicating successful driver init.
pub type Result = core::result::Result<(), ()>;
/// Device Driver functions.
pub trait DeviceDriver {
/// Return a compatibility string for identifying the driver.
fn compatible(&self) -> &str;
/// Called by the kernel to bring up the device.
fn init(&self) -> Result {
Ok(())
}
}
}
/// Timekeeping interfaces.
pub mod time {
use core::time::Duration;
/// Timer functions.
pub trait Timer {
/// The timer's resolution.
fn resolution(&self) -> Duration;
/// The uptime since power-on of the device.
///
/// This includes time consumed by firmware and bootloaders.
fn uptime(&self) -> Duration;
/// Spin for a given duration.
fn spin_for(&self, duration: Duration);
}
}

@ -5,56 +5,140 @@
// Rust embedded logo for `make doc`.
#![doc(html_logo_url = "https://git.io/JeGIp")]
//! The `kernel`
//! The `kernel` binary.
//!
//! The `kernel` is composed by glueing together code from
//! # TL;DR - Overview of important Kernel entities
//!
//! - [Hardware-specific Board Support Packages] (`BSPs`).
//! - [Architecture-specific code].
//! - HW- and architecture-agnostic `kernel` code.
//! - [`bsp::console::console()`] - Returns a reference to the kernel's [console interface].
//! - [`bsp::driver::driver_manager()`] - Returns a reference to the kernel's [driver interface].
//! - [`time::time_manager()`] - Returns a reference to the kernel's [timer interface].
//!
//! using the [`kernel::interface`] traits.
//! [console interface]: ../libkernel/console/interface/index.html
//! [driver interface]: ../libkernel/driver/interface/trait.DriverManager.html
//! [timer interface]: ../libkernel/time/interface/trait.TimeManager.html
//!
//! [Hardware-specific Board Support Packages]: bsp/index.html
//! [Architecture-specific code]: arch/index.html
//! [`kernel::interface`]: interface/index.html
//! # 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(format_args_nl)]
#![feature(naked_functions)]
#![feature(panic_info_message)]
#![feature(trait_alias)]
#![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. `_start()` then calls
// `runtime_init()`, which jumps to `kernel_init()`.
// `_start()` then calls `runtime_init()`, which on completion, jumps to `kernel_init()`.
mod runtime_init;
// Conditionally includes the selected `BSP` code.
mod bsp;
mod interface;
mod console;
mod cpu;
mod driver;
mod exception;
mod memory;
mod panic_wait;
mod print;
mod runtime_init;
mod synchronization;
mod time;
/// Early init code.
///
/// Concerned with with initializing `BSP` and `arch` parts.
///
/// # Safety
///
/// - Only a single core must be active and running this function.
/// - The init calls in this function must appear in the correct order.
unsafe fn kernel_init() -> ! {
for i in bsp::device_drivers().iter() {
if let Err(()) = i.init() {
use driver::interface::DriverManager;
for i in bsp::driver::driver_manager().all_device_drivers().iter() {
if i.init().is_err() {
panic!("Error loading driver: {}", i.compatible())
}
}
bsp::post_driver_init();
bsp::driver::driver_manager().post_device_driver_init();
// println! is usable from here on.
// Transition from unsafe to safe.
@ -63,33 +147,39 @@ unsafe fn kernel_init() -> ! {
/// The main function running after the early init.
fn kernel_main() -> ! {
use console::interface::All;
use core::time::Duration;
use interface::{console::All, time::Timer};
use driver::interface::DriverManager;
use time::interface::TimeManager;
info!("Booting on: {}", bsp::board_name());
let (_, privilege_level) = arch::state::current_privilege_level();
let (_, privilege_level) = exception::current_privilege_level();
info!("Current privilege level: {}", privilege_level);
info!("Exception handling state:");
arch::state::print_exception_state();
exception::asynchronous::print_state();
info!(
"Architectural timer resolution: {} ns",
arch::timer().resolution().as_nanos()
time::time_manager().resolution().as_nanos()
);
info!("Drivers loaded:");
for (i, driver) in bsp::device_drivers().iter().enumerate() {
for (i, driver) in bsp::driver::driver_manager()
.all_device_drivers()
.iter()
.enumerate()
{
info!(" {}. {}", i + 1, driver.compatible());
}
info!("Timer test, spinning for 1 second");
arch::timer().spin_for(Duration::from_secs(1));
time::time_manager().spin_for(Duration::from_secs(1));
info!("Echoing input now");
loop {
let c = bsp::console().read_char();
bsp::console().write_char(c);
let c = bsp::console::console().read_char();
bsp::console::console().write_char(c);
}
}

@ -6,6 +6,10 @@
use core::ops::Range;
//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
/// Zero out a memory region.
///
/// # Safety

@ -4,13 +4,17 @@
//! A panic handler that infinitely waits.
use crate::{arch, bsp};
use crate::{bsp, cpu};
use core::{fmt, panic::PanicInfo};
//--------------------------------------------------------------------------------------------------
// Private Code
//--------------------------------------------------------------------------------------------------
fn _panic_print(args: fmt::Arguments) {
use fmt::Write;
unsafe { bsp::panic_console_out().write_fmt(args).unwrap() };
unsafe { bsp::console::panic_console_out().write_fmt(args).unwrap() };
}
/// Prints with a newline - only use from the panic handler.
@ -31,5 +35,5 @@ fn panic(info: &PanicInfo) -> ! {
panic_println!("\nKernel panic!");
}
arch::wait_forever()
cpu::wait_forever()
}

@ -4,16 +4,24 @@
//! Printing facilities.
use crate::{bsp, interface};
use crate::{bsp, console};
use core::fmt;
//--------------------------------------------------------------------------------------------------
// Private Code
//--------------------------------------------------------------------------------------------------
#[doc(hidden)]
pub fn _print(args: fmt::Arguments) {
use interface::console::Write;
use console::interface::Write;
bsp::console().write_fmt(args).unwrap();
bsp::console::console().write_fmt(args).unwrap();
}
//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
/// Prints without a newline.
///
/// Carbon copy from https://doc.rust-lang.org/src/std/macros.rs.html
@ -33,14 +41,14 @@ macro_rules! println {
})
}
/// Prints an info, with newline.
/// Prints an info, with a newline.
#[macro_export]
macro_rules! info {
($string:expr) => ({
#[allow(unused_imports)]
use crate::interface::time::Timer;
use crate::time::interface::TimeManager;
let timestamp = $crate::arch::timer().uptime();
let timestamp = $crate::time::time_manager().uptime();
let timestamp_subsec_us = timestamp.subsec_micros();
$crate::print::_print(format_args_nl!(
@ -52,9 +60,9 @@ macro_rules! info {
});
($format_string:expr, $($arg:tt)*) => ({
#[allow(unused_imports)]
use crate::interface::time::Timer;
use crate::time::interface::TimeManager;
let timestamp = $crate::arch::timer().uptime();
let timestamp = $crate::time::time_manager().uptime();
let timestamp_subsec_us = timestamp.subsec_micros();
$crate::print::_print(format_args_nl!(
@ -67,14 +75,14 @@ macro_rules! info {
})
}
/// Prints a warning, with newline.
/// Prints a warning, with a newline.
#[macro_export]
macro_rules! warn {
($string:expr) => ({
#[allow(unused_imports)]
use crate::interface::time::Timer;
use crate::time::interface::TimeManager;
let timestamp = $crate::arch::timer().uptime();
let timestamp = $crate::time::time_manager().uptime();
let timestamp_subsec_us = timestamp.subsec_micros();
$crate::print::_print(format_args_nl!(
@ -86,9 +94,9 @@ macro_rules! warn {
});
($format_string:expr, $($arg:tt)*) => ({
#[allow(unused_imports)]
use crate::interface::time::Timer;
use crate::time::interface::TimeManager;
let timestamp = $crate::arch::timer().uptime();
let timestamp = $crate::time::time_manager().uptime();
let timestamp_subsec_us = timestamp.subsec_micros();
$crate::print::_print(format_args_nl!(

@ -7,6 +7,10 @@
use crate::memory;
use core::ops::Range;
//--------------------------------------------------------------------------------------------------
// Private Code
//--------------------------------------------------------------------------------------------------
/// Return the range spanning the .bss section.
///
/// # Safety
@ -36,6 +40,10 @@ unsafe fn zero_bss() {
memory::zero_volatile(bss_range());
}
//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
/// Equivalent to `crt0` or `c0` code in C/C++ world. Clears the `bss` section, then jumps to kernel
/// init code.
///

@ -0,0 +1,91 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2020 Andre Richter <andre.o.richter@gmail.com>
//! Synchronization primitives.
use core::cell::UnsafeCell;
//--------------------------------------------------------------------------------------------------
// Public Definitions
//--------------------------------------------------------------------------------------------------
/// Synchronization interfaces.
pub mod interface {
/// Any object implementing this trait guarantees exclusive access to the data contained within
/// the Mutex for the duration of the provided closure.
///
/// The trait follows the [Rust embedded WG's
/// proposal](https://github.com/korken89/wg/blob/master/rfcs/0377-mutex-trait.md) and therefore
/// provides some goodness such as [deadlock
/// prevention](https://github.com/korken89/wg/blob/master/rfcs/0377-mutex-trait.md#design-decisions-and-compatibility).
///
/// # Example
///
/// Since the lock function takes an `&mut self` to enable deadlock-prevention, the trait is
/// best implemented **for a reference to a container struct**, and has a usage pattern that
/// might feel strange at first:
///
/// ```
/// static MUT: Mutex<RefCell<i32>> = Mutex::new(RefCell::new(0));
///
/// fn foo() {
/// let mut r = &MUT; // Note that r is mutable
/// r.lock(|data| *data += 1);
/// }
/// ```
pub trait Mutex {
/// The type of encapsulated data.
type Data;
/// Creates a critical section and grants temporary mutable access to the encapsulated data.
fn lock<R>(&mut self, f: impl FnOnce(&mut Self::Data) -> R) -> R;
}
}
/// A pseudo-lock for teaching purposes.
///
/// Used to introduce [interior mutability].
///
/// In contrast to a real Mutex implementation, does not protect against concurrent access from
/// other cores to the contained data. This part is preserved for later lessons.
///
/// The lock will only be used as long as it is safe to do so, i.e. as long as the kernel is
/// executing single-threaded, aka only running on a single core with interrupts disabled.
///
/// [interior mutability]: https://doc.rust-lang.org/std/cell/index.html
pub struct NullLock<T: ?Sized> {
data: UnsafeCell<T>,
}
//--------------------------------------------------------------------------------------------------
// Public Code
//--------------------------------------------------------------------------------------------------
unsafe impl<T: ?Sized> Sync for NullLock<T> {}
impl<T> NullLock<T> {
/// Wraps `data` into a new `NullLock`.
pub const fn new(data: T) -> Self {
Self {
data: UnsafeCell::new(data),
}
}
}
//------------------------------------------------------------------------------
// OS Interface Code
//------------------------------------------------------------------------------
impl<T> interface::Mutex for &NullLock<T> {
type Data = T;
fn lock<R>(&mut self, f: impl FnOnce(&mut Self::Data) -> R) -> R {
// In a real lock, there would be code encapsulating this line that ensures that this
// mutable reference will ever only be given out once at a time.
let data = unsafe { &mut *self.data.get() };
f(data)
}
}

@ -0,0 +1,35 @@
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// Copyright (c) 2020 Andre Richter <andre.o.richter@gmail.com>
//! Timer primitives.
#[cfg(target_arch = "aarch64")]
#[path = "_arch/aarch64/time.rs"]
mod arch_time;
pub use arch_time::*;
//--------------------------------------------------------------------------------------------------
// Public Definitions
//--------------------------------------------------------------------------------------------------
/// Timekeeping interfaces.
pub mod interface {
use core::time::Duration;
/// Time management functions.
///
/// The `BSP` is supposed to supply one global instance.
pub trait TimeManager {
/// The timer's resolution.
fn resolution(&self) -> Duration;
/// The uptime since power-on of the device.
///
/// This includes time consumed by firmware and bootloaders.
fn uptime(&self) -> Duration;
/// Spin for a given duration.
fn spin_for(&self, duration: Duration);
}
}
Loading…
Cancel
Save