yggdrasil-kernel
================

Rust Unix-like operating system.

![Yggdrasil OS](/etc/screenshot.png)

Main features
-------------

* Architecture support:
	* [aarch64](kernel/src/arch/aarch64)
	* [x86_64](kernel/src/arch/x86_64)
	* [i686](kernel/src/arch/i686) (Pentium Pro and later)
* 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
* Userspace features:
	* [Kernel-user ABI](lib/abi-def/yggdrasil.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/lib/ygglibc)
	* Userspace multithreading
	* Synchronization primitives through futex-like interface
	* Unix-like signals and exceptions
	* [Dynamic loader](userspace/dyn-loader) for linking with shared libraries
* Hardware features:
	* PCI Express devices
    	* NVMe drive support (read/write, currently x86_64 only, due to lack of MSI-X support on aarch64/i686).
    	* AHCI SATA drive support (read/write)
    	* xHCI USB host controller
		* VirtIO Network + GPU framebuffer support
	* USB HID keyboards

aarch64-specific:

* PSCI for SMP start-up and power control
* PL011 serial port
* ARM generic timer as system/monotonic timer
* GICv2 IRQ controller

x86-specific:

* Boot options:
	* x86_64: UEFI [yboot](https://git.alnyan.me/yggdrasil/yboot)
	* i686: multiboot/grub
* I/O and Local APIC IRQ controllers
* PS/2 keyboard
* HPET for x86_64
* i8253-based timer for i686 or as a fallback timer
* COM ports
* ACPI, [work in progress](https://github.com/rust-osdev/acpi), mostly broken
	on real hardware, so currently disabled
	* 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

	```bash
	### 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](https://rustup.rs/).

1. Clone this repo

	```bash
	$ 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
5. Run doom (?)

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

Navigation
----------

* Kernel: [`kernel`](kernel)
* Userspace: [`userspace`](userspace)
* ABI definitions: [`lib/abi-def`](lib/abi-def)