yggdrasil/README.md

yggdrasil-kernel

Rust Unix-like operating system.

Main features

• Architecture support:
  • aarch64
  • x86_64
  • riscv64
• Core features:
  • Kernel/userspace preemptive multithreading
  • Kernel-space multitasking with async/await runtime
  • Symmetric Multiprocessing
  • Rust-style interfaces for most of the stuff like memory management, devices etc.
• Filesystem features:
  • Unix-like virtual filesystem: files, directories, block/char devices, symlinks, mounts
  • In-memory read-write filesystem for tar-based initrd
  • sysfs
  • devfs
  • ext2
  • fat32 (read-only)
• Userspace features:
  • Kernel-user ABI generated from a rust-like description language
  • Sanitized system calls better suited for use in Rust
  • Binary formats: ELF + #!/... shebangs
  • C compatibility through a custom Rust libc
  • Userspace multithreading
  • Synchronization primitives through futex-like interface
  • Unix-like signals and exceptions
  • Dynamic loader for linking with shared libraries
  • Runs DOOM
• Hardware features:
  • PCI Express devices
    • NVMe drive support
    • AHCI SATA drive support
    • xHCI USB host controller
    • VirtIO Network + GPU framebuffer support
  • USB device support
    • Hub driver
    • HID keyboards and mice
    • Mass storage (BBB)
  • Partial hardware support for aarch64/riscv64 SBCs like StarFive VisionFive 2 and Raspberry Pi 4

aarch64-specific:

• PSCI for SMP start-up and power control
• PL011 serial port
• PL061 GPIO controller
• PL031 RTC
• ARM generic timer as system/monotonic timer
• GICv2 IRQ controller + GICv2m MSI interrupts

x86-specific:

• Boot via UEFI yboot
• I/O and Local APIC IRQ controllers
• PS/2 keyboard
• HPET for x86_64
• i8253 as a fallback timer
• COM ports
• ACPI, work in progress
  • ACPI shutdown
  • PCI IRQ pin routing
  • Events like power button, etc.

Building the OS

NOTE This project uses xtask-style build system. To see help, use cargo xtask --help.

Prerequisites:

• Decent CPU and a sizable amount of RAM
• ~40G of free disk space for a full build
• Patience

NOTE Full OS build requires you to build the *-unknown-yggdrasil Rust toolchain, which may take quite a while, so be prepared.

Steps:

0. Install the prerequisite software

   ### For Arch Linux based systems
   
   # pacman -Sy cmake ninja llvm dosfstools mtools
   
   ### For MacOS
   
   $ brew install cmake ninja llvm dosfstools mtools
   $ export PATH="$PATH:/opt/homebrew/Cellar/llvm/.../bin"
   

   NOTE Nightly Rust version and rustup are required, for details see the rustup page.

1. Clone this repo

   $ git clone https://git.alnyan.me/alnyan/yggdrasil
   $ cd yggdrasil
   # Optionally, checkout a release/snapshot branch
   

2. Run cargo xtask toolchain to fetch, build and link the toolchain

   NOTE if toolchain fetch fails for some reason, try cloning directly from https://git.alnyan.me/yggdrasil/yggdrasil-rust.git with appropriate branch.

3. Run cargo xtask to build the OS.

Once the OS has been built, you can run it in QEMU by executing cargo xtask qemu. For more xtask commands, see cargo xtask --help.

General plans (in no particular order)

1. Get it running on more real hardware
2. Get a full LLVM build to work
3. Get rustc to work
4. Get self-hosted

In addition to eternal code cleanup, I've been doing quite a lazy job at that lately...

Navigation

• Kernel: kernel
• Userspace: userspace
• ABI definitions: lib/abi-def