Developer Guide

Prerequisites

  • Rust nightly (recommended: nightly-2024-10-01 or later)
  • cargo install bootimage
  • QEMU (qemu-system-x86_64)

Building and Running

  1. Clone the repository: 
    git clone https://github.com/daxo-developer/daxo_os
cd daxo_os
  2. Build the bootable image: 
    cargo bootimage
  3. Run in QEMU: 
    cargo run
    (Uses .cargo/config.toml to pass QEMU arguments.)
  4. To test: 
    cargo test
    (This runs the integration tests in tests/.)

Repository Structure

  • src/ – kernel source
  • src/allocator/ – heap allocators
  • src/task/ – async executor and keyboard handling
  • tests/ – integration tests (boot, heap, panic, stack overflow)
  • verification/ – Lean 4 formal proofs
  • user/ – example user‑space programs (future)
  • disk.bin – test disk image for ATA driver
  • x86_64-daxo_os.json – target specification

Adding a New Driver

Create a new module in src/ (e.g., my_driver.rs). Implement a struct with methods for port I/O or MMIO. Register it in lib.rs.

Example: follow the ATA driver structure – use Port from x86_64::instructions::port, implement a polling loop, and use a Mutex for global access.

Adding a System Call

  1. Define a new syscall number in src/syscall.rs.
  2. Write the handler function (e.g., fn handle_syscall(rax: u64, ...)).
  3. In the syscall interrupt handler, match on rax and call the corresponding function.
  4. Update the user‑space code to invoke syscall with the new number.

Debugging

  • Use serial_println! to output to the host terminal (QEMU shows serial output).
  • Run QEMU with -s -S and attach GDB: 
    gdb target/x86_64-daxo_os/debug/daxo_os
(gdb) target remote :1234
  • Enable QEMU’s internal logging with -d cpu_reset,page,mmu.

Running Tests

Use cargo test. The test framework uses QemuExitCode to signal success/failure via the isa‑debug‑exit device.

To run a specific test: cargo test --test basic_boot.