docs: more docssssss

src/alloca.rs

@@ -1,16 +1,23 @@
+//! Wires rust up to the kheap, so that `alloc::` works.
+
 use spin::Mutex;
 use linked_list_allocator::Heap;
 use alloc::allocator::{Alloc, Layout, AllocErr};
 
+/// Base location of the kheap.
 pub const HEAP_START: usize = 0o_000_001_000_000_0000;
+/// Size of the kheap.
 pub const HEAP_SIZE: usize = 100 * 1024; // 100 KiB
 
+/// Locked ownership of an optional kheap. Initialized on boot; is `None` before then.
 static HEAP: Mutex<Option<Heap>> = Mutex::new(None);
 
+/// Initialize the kheap. Called at boot.
 pub unsafe fn heap_init(start: usize, size: usize) {
     *HEAP.lock() = Some(Heap::new(start, size));
 }
 
+/// Wraps whatever allocator backend we're using, and implements `alloc::allocator::Alloc`.
 pub struct Allocator;
 
 unsafe impl<'a> Alloc for &'a Allocator {

src/arch/x86_64/mod.rs

@@ -1,6 +1,9 @@
+//! Hardware support and boot for 64-bit Intel x86 processors.
+
 pub mod device;
 pub mod memory;
 
+/// Turn on no-execute page protection.
 pub fn enable_nxe_bit() {
     use x86::shared::msr;
 
@@ -11,6 +14,7 @@ pub fn enable_nxe_bit() {
     }
 }
 
+/// Turn on page write-protect enforcement.
 pub fn enable_wrprot_bit() {
     use x86::shared::control_regs::{cr0, cr0_write, CR0_WRITE_PROTECT};
     unsafe {

src/lib.rs

@@ -39,9 +39,13 @@ use arch::x86_64::memory::FrameAllocator;
 use alloca::Allocator;
 use alloc::boxed::Box;
 
+/// Our globally-visible allocator. Plugs into whatever allocator we set up in [`alloca`].
+//
+/// [`alloca`]: alloca/index.html
 #[global_allocator]
 static GLOBAL_ALLOC: Allocator = Allocator;
 
+/// Kernel main function. Called by the bootstrapping assembly stub.
 #[no_mangle]
 pub extern fn kernel_main(multiboot_info_pointer: usize) {
     vga_console::WRITER.lock().clear_screen();
@@ -53,15 +57,17 @@ pub extern fn kernel_main(multiboot_info_pointer: usize) {
 
     memory::init(boot_info);
     info!("* memory::init(): success! *");
-
     info!("kheap: smoke test (boxing): {:?}", Box::new("hello world"));
 
     loop {}
 }
 
+/// Related to stack landing pads. Don't care, do nothing.
 #[lang = "eh_personality"]
 #[no_mangle]
 pub extern fn eh_personality() {}
+
+/// Dumps panics to the console.
 #[lang = "panic_fmt"]
 #[no_mangle]
 pub extern fn panic_fmt(fmt: core::fmt::Arguments, file: &'static str, line: u32) -> ! {
@@ -73,6 +79,7 @@ pub extern fn panic_fmt(fmt: core::fmt::Arguments, file: &'static str, line: u32
     unsafe{loop{x86::shared::halt();}};
 }
 
+/// Stack unwinding. Don't care, just halt.
 #[allow(non_snake_case)]
 #[no_mangle]
 pub extern "C" fn _Unwind_Resume() -> ! {

src/logger.rs

@@ -4,6 +4,7 @@ use log;
 use log::{Log, LogRecord, LogLevel, LogLevelFilter, LogMetadata};
 use log::{SetLoggerError};
 
+/// Initializes the VGA console logger at kernel boot.
 pub fn init() -> Result<(), SetLoggerError> {
     unsafe {
         log::set_logger_raw(|max_log_level| {
@@ -14,6 +15,7 @@ pub fn init() -> Result<(), SetLoggerError> {
     }
 }
 
+/// A `log` logger, which dumps to the VGA console.
 struct ConsoleLogger;
 impl ConsoleLogger {
     fn filter(&self) -> LogLevelFilter {

src/macros.rs

@@ -10,6 +10,10 @@ macro_rules! print {
     });
 }
 
+/// Helper function to print to the console.
+///
+/// # TODO
+/// abstract this.
 pub fn print(args: fmt::Arguments) {
     use core::fmt::Write;
     let _ = ::arch::x86_64::device::vga_console::WRITER.lock().write_fmt(args);

src/misc.rs

@@ -2,6 +2,8 @@
 
 use log::LogLevel;
 
+/// The crate version.
 pub const VERSION: &'static str = env!("CARGO_PKG_VERSION");
 
+/// The highest log level to dump to the console. Baked in at compile time for now.
 pub const LOG_LEVEL: LogLevel = LogLevel::Info;