From 26ab71043d97c1b06bdd252378b64171cb95b1a9 Mon Sep 17 00:00:00 2001
From: Christian Cunningham <cc@localhost>
Date: Fri, 19 Aug 2022 21:22:18 -0700
Subject: Updated docs

---
 src/_arch/arm/asm.rs      | 16 ++++++++++------
 src/_arch/arm/cpu.rs      | 12 ++++++++++--
 src/_arch/arm/cpu/boot.rs | 16 ++++++++++++----
 3 files changed, 32 insertions(+), 12 deletions(-)

(limited to 'src/_arch')

diff --git a/src/_arch/arm/asm.rs b/src/_arch/arm/asm.rs
index c1af5b4..5d53aa0 100644
--- a/src/_arch/arm/asm.rs
+++ b/src/_arch/arm/asm.rs
@@ -1,6 +1,10 @@
-//! Wrapping ARMv7-A Instructions
+//! # Wrapping ARMv7-A Instructions
+//!
+//! This provides bindings for assembly instructions
+//! to be used in other rust functions without `unsafe`
+//! markers everywhere.
 
-/// WFE
+/// # Wait for event
 #[inline(always)]
 pub fn wfe() {
     unsafe {
@@ -8,7 +12,7 @@ pub fn wfe() {
     }
 }
 
-/// NOP
+/// # No Operation
 #[inline(always)]
 pub fn nop() {
     unsafe {
@@ -16,7 +20,7 @@ pub fn nop() {
     }
 }
 
-/// Store u32 to address
+/// # Store u32 to memory address
 #[inline]
 pub fn store32(addr: u32, value: u32) {
 	unsafe {
@@ -24,7 +28,7 @@ pub fn store32(addr: u32, value: u32) {
 	}
 }
 
-/// Read u32 value from address
+/// # Read u32 from memory address
 #[inline]
 pub fn load32(addr: u32) -> u32 {
 	unsafe {
@@ -32,7 +36,7 @@ pub fn load32(addr: u32) -> u32 {
 	}
 }
 
-/// Wait for n cycles
+/// # Spin CPU for `n` cycles
 #[inline]
 pub fn spin_for_n_cycles(n: u32) {
 	unsafe {
diff --git a/src/_arch/arm/cpu.rs b/src/_arch/arm/cpu.rs
index 1ca6fab..cd80151 100644
--- a/src/_arch/arm/cpu.rs
+++ b/src/_arch/arm/cpu.rs
@@ -1,8 +1,16 @@
-//! Architectural processor code.
+//! # Architectural processor code.
+//!
+//! This module provides the assembly instructions and higher level constructions
+//! for the rest of the kernel.
+
 mod asm;
+
+/// # Bare Assembly Instructions
+///
+/// Re-export bare ASM bindings.
 pub use asm::*;
 
-/// Pause execution
+/// # Halt until event
 pub fn wait_forever() -> ! {
     loop {
         asm::wfe()
diff --git a/src/_arch/arm/cpu/boot.rs b/src/_arch/arm/cpu/boot.rs
index 9ea2330..b81a16a 100644
--- a/src/_arch/arm/cpu/boot.rs
+++ b/src/_arch/arm/cpu/boot.rs
@@ -1,11 +1,19 @@
-//! Architectural boot code
-//!  # Boot code for ARM
-//!  crate::cpu::boot::arch_boot
+//! # Architectural boot code
+//!
+//! crate::cpu::boot::arch_boot
+//!
+//! ## Boot code for ARM
+//!
+//! Provides the initial handoff
+//! function from Assembly to Rust.
 
 use core::arch::global_asm;
 global_asm!(include_str!("boot.s"));
 
-/// The Rust entry of the `kernel` binary.
+/// # Rust entry of the `kernel` binary.
+///
+/// This function is unmangled so that the
+/// ASM boot code can switch to Rust safely.
 #[no_mangle]
 pub unsafe fn _start_rust() -> ! {
     crate::kernel_init()
-- 
cgit v1.2.1