rust-kernel

//! The kernel as a library.
//!
//! Everything lives here so that both the bootable binary (src/main.rs) and
//! the integration tests (tests/*.rs, each its own tiny kernel) can use it.
//!
//! Testing: Rust's normal test harness needs `std`, so we use the nightly
//! `custom_test_frameworks` feature. `cargo test` builds each test kernel,
//! boots it in QEMU (see `test-args` in Cargo.toml), results go to serial,
//! and the kernel exits QEMU through the `isa-debug-exit` device.

#![no_std]
#![cfg_attr(test, no_main)] // when testing the lib itself, it is a kernel too
#![feature(custom_test_frameworks)] // nightly: our own test runner
#![cfg_attr(target_arch = "x86_64", feature(abi_x86_interrupt))] // nightly: `extern "x86-interrupt" fn`
#![test_runner(crate::test_runner)]
#![reexport_test_harness_main = "test_main"] // name the generated test entry fn

// `alloc` = the heap-using half of the standard library (Box, Vec, Rc, ...).
// It works once we register a global allocator (see allocator.rs).
extern crate alloc;

#[cfg(target_arch = "x86_64")]
use core::panic::PanicInfo;

// Stage 22: the per-CPU-family code (src/arch/). Everything else below is
// still PC-only for now, so it is behind `cfg(target_arch = "x86_64")`;
// the arm64 kernel (src/arch/aarch64/main.rs) only uses `arch`.
pub mod arch;

#[cfg(target_arch = "x86_64")]
pub mod acpi; // ACPI tables: just enough to list the CPUs (MADT)
#[cfg(target_arch = "x86_64")]
pub mod allocator; // heap: maps heap pages + the #[global_allocator]
#[cfg(target_arch = "x86_64")]
pub mod apic; // local APIC: per-CPU timer, inter-processor interrupts
#[cfg(target_arch = "x86_64")]
pub mod boot; // stage 21: boot contract v2 -- pid 1 from the root partition
#[cfg(target_arch = "x86_64")]
pub mod block; // block devices: BlockDevice trait, virtio-blk, partitions
#[cfg(target_arch = "x86_64")]
pub mod dev; // /dev: null, random, hvc0, fb0, tty, ptmx, pts/N
#[cfg(target_arch = "x86_64")]
pub mod elf; // ELF64 loader for user programs
#[cfg(target_arch = "x86_64")]
pub mod errno; // Linux-compatible error numbers
#[cfg(target_arch = "x86_64")]
pub mod fbcon; // text console drawn on the framebuffer
#[cfg(target_arch = "x86_64")]
pub mod fpu; // FPU/SSE/AVX registers: per-thread save/restore (XSAVE or FXSAVE)
#[cfg(target_arch = "x86_64")]
pub mod font; // 8x16 bitmap font (Spleen) for fbcon
#[cfg(target_arch = "x86_64")]
pub mod futex; // futexes: user-space locks' sleep/wake (threads)
#[cfg(target_arch = "x86_64")]
pub mod fs; // VFS: Inode/FileSystem/File traits, mount table, ramfs
#[cfg(target_arch = "x86_64")]
pub mod gdt; // GDT (kernel + user segments) + TSS (RSP0, double-fault stack)
#[cfg(target_arch = "x86_64")]
pub mod interrupts; // IDT, exception handlers, PIC, timer + keyboard
#[cfg(target_arch = "x86_64")]
pub mod net; // networking: virtio-net driver + smoltcp TCP/IP, sockets
#[cfg(target_arch = "x86_64")]
pub mod memory; // paging, frame allocator, page tables, shared-frame counts
#[cfg(target_arch = "x86_64")]
pub mod mm; // a process's memory map: regions, demand paging, copy-on-write
#[cfg(target_arch = "x86_64")]
pub mod pci; // PCI bus enumeration (config space via ports 0xCF8/0xCFC)
#[cfg(target_arch = "x86_64")]
pub mod poll; // poll, select, epoll: waiting for many files at once
#[cfg(target_arch = "x86_64")]
pub mod process; // processes: fork, execve, exit, wait4, process groups
#[cfg(target_arch = "x86_64")]
pub mod serial; // COM1 serial port
#[cfg(target_arch = "x86_64")]
pub mod signal; // signals: kill, handlers, signal frames, default actions
#[cfg(target_arch = "x86_64")]
pub mod smp; // multi-core: start the other CPUs, per-CPU data
#[cfg(target_arch = "x86_64")]
pub mod stack; // kernel stacks with guard pages
#[cfg(target_arch = "x86_64")]
pub mod syscall; // syscall/sysret entry + system call implementations
#[cfg(target_arch = "x86_64")]
pub mod syscall_ext; // stage 17's syscalls for coreutils/busybox: links, owners, statfs, ids, timers...
#[cfg(target_arch = "x86_64")]
pub mod task; // cooperative multitasking: async tasks + executor
#[cfg(target_arch = "x86_64")]
pub mod trap; // TrapFrame: saved user registers, the common return to ring 3
#[cfg(target_arch = "x86_64")]
pub mod time; // nanosecond clock (TSC calibrated against the PIT)
#[cfg(target_arch = "x86_64")]
pub mod timer; // alarm, setitimer, POSIX timers: signals at a deadline (stage 17)
#[cfg(target_arch = "x86_64")]
pub mod thread; // threads + the multi-core scheduler (sleep/wake, wait queues)
#[cfg(target_arch = "x86_64")]
pub mod tty; // terminals: line discipline, termios, console/hvc0/ptys
#[cfg(target_arch = "x86_64")]
pub mod vdso; // stage 19: the vDSO + vvar page, time without a syscall
#[cfg(target_arch = "x86_64")]
pub mod vga_buffer; // the console: VGA text mode, or fbcon on a GPU
#[cfg(target_arch = "x86_64")]
pub mod virtio; // modern virtio transport + virtio-rng, -console, -gpu

/// Set up everything interrupt-related. Order matters:
/// GDT/TSS first (the IDT refers to the IST stack), then the IDT, then the
/// PICs, and only then enable interrupts (`sti`).
#[cfg(target_arch = "x86_64")]
pub fn init() {
    gdt::init();
    fpu::init_cpu(); // before any CPU starts: smp.rs copies our CR0/CR4
    syscall::init();
    interrupts::init_idt();
    unsafe { interrupts::PICS.lock().initialize() };
    x86_64::instructions::interrupts::enable();
}

/// Paging + heap + the global frame allocator, in one call (what the test
/// kernels need; src/main.rs does the same steps one by one with demos).
#[cfg(target_arch = "x86_64")]
pub fn init_memory(boot_info: &'static bootloader::BootInfo) {
    let phys_mem_offset = x86_64::VirtAddr::new(boot_info.physical_memory_offset);
    let mut mapper = unsafe { memory::init(phys_mem_offset) };
    let mut frame_allocator = unsafe { memory::BootInfoFrameAllocator::init(&boot_info.memory_map) };
    allocator::init_heap(&mut mapper, &mut frame_allocator).expect("heap initialization failed");
    memory::init_frame_allocator(frame_allocator);
}

/// Multi-core bring-up: the local APIC and its timer (preemption), CPU 0's
/// idle thread, and every other CPU the ACPI tables list (see smp.rs).
/// Needs `init` and `init_memory`. Returns the number of running CPUs.
#[cfg(target_arch = "x86_64")]
pub fn init_smp() -> usize {
    smp::init()
}

/// Storage bring-up: scan the PCI bus, start the disk drivers, read the
/// partition tables and mount FAT volumes under /mnt. Needs the heap, the
/// frame allocator and `fs::init()`. Returns (PCI devices, log lines).
#[cfg(target_arch = "x86_64")]
pub fn init_storage() -> (alloc::vec::Vec<pci::PciDevice>, alloc::vec::Vec<alloc::string::String>) {
    let devices = pci::scan();
    let mut log = block::init(&devices);
    log.extend(fs::mount_disks());
    (devices, log)
}

/// The stage-13 virtual devices: virtio-rng, virtio-console (hvc0) and
/// virtio-gpu. With a GPU the text console moves onto its framebuffer.
/// Call before `init_net` (smoltcp's random seed comes from the rng).
/// Returns boot log lines.
#[cfg(target_arch = "x86_64")]
pub fn init_drivers() -> alloc::vec::Vec<alloc::string::String> {
    let mut log = virtio::init(&pci::scan());
    if let Some(fb) = virtio::gpu::framebuffer() {
        let (cols, rows) = vga_buffer::use_framebuffer(fb);
        log.push(alloc::format!("fbcon: text console on the framebuffer, {}x{} characters", cols, rows));
    }
    log
}

/// Networking: loopback, plus the virtio-net card if there is one (smoltcp,
/// DHCP and the netd thread). Needs the scheduler (call after `init_smp`).
/// Returns the boot log lines.
#[cfg(target_arch = "x86_64")]
pub fn init_net() -> alloc::vec::Vec<alloc::string::String> {
    net::init(&pci::scan())
}

/// Print a line to *both* the VGA screen and the serial port.
#[cfg(target_arch = "x86_64")]
#[macro_export]
macro_rules! kprintln {
    ($($arg:tt)*) => {{
        $crate::println!($($arg)*);
        $crate::serial_println!($($arg)*);
    }};
}

/// Sleep the CPU until the next interrupt, forever (cheaper than `loop {}`,
/// which would keep a host CPU core at 100%).
#[cfg(target_arch = "x86_64")]
pub fn hlt_loop() -> ! {
    loop {
        x86_64::instructions::hlt();
    }
}

/// Exit codes for QEMU's `isa-debug-exit` device. QEMU exits with
/// status `(value << 1) | 1`, so Success = 0x10 -> shell exit code 33.
#[cfg(target_arch = "x86_64")]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u32)]
pub enum QemuExitCode {
    Success = 0x10,
    Failed = 0x11,
}

/// Write to I/O port 0xf4 (where we put `isa-debug-exit`) to quit QEMU.
#[cfg(target_arch = "x86_64")]
pub fn exit_qemu(exit_code: QemuExitCode) {
    use x86_64::instructions::port::Port;
    unsafe {
        let mut port = Port::new(0xf4);
        port.write(exit_code as u32);
    }
}

// ---------------------------------------------------------------------------
// Test framework
// ---------------------------------------------------------------------------

/// Anything callable as a test: prints its name, runs it, prints [ok].
/// (If it panics, the panic handler prints [failed] instead.)
#[cfg(target_arch = "x86_64")]
pub trait Testable {
    fn run(&self);
}

#[cfg(target_arch = "x86_64")]
impl<T: Fn()> Testable for T {
    fn run(&self) {
        serial_print!("{}...\t", core::any::type_name::<T>());
        self();
        serial_println!("[ok]");
    }
}

/// Called with every `#[test_case]` function in the crate being tested.
#[cfg(target_arch = "x86_64")]
pub fn test_runner(tests: &[&dyn Testable]) {
    serial_println!("Running {} tests", tests.len());
    for test in tests {
        test.run();
    }
    exit_qemu(QemuExitCode::Success);
}

/// Panic handler for test kernels: report the failure and exit QEMU.
#[cfg(target_arch = "x86_64")]
pub fn test_panic_handler(info: &PanicInfo) -> ! {
    serial_println!("[failed]\n");
    serial_println!("Error: {}\n", info);
    exit_qemu(QemuExitCode::Failed);
    hlt_loop();
}

// When running `cargo test --lib`, the library itself is booted as a kernel:
#[cfg(test)]
bootloader::entry_point!(test_kernel_main);

#[cfg(test)]
fn test_kernel_main(boot_info: &'static bootloader::BootInfo) -> ! {
    init();
    init_memory(boot_info); // a heap, for unit tests that use Vec (btrfs, lzo)
    init_smp();
    test_main();
    hlt_loop();
}

#[cfg(test)]
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    test_panic_handler(info)
}

#[cfg(target_arch = "x86_64")]
#[test_case]
fn trivial_assertion() {
    assert_eq!(1 + 1, 2);
}