Theseus OS Documentation

The Theseus kernel execution follows a three-stage boot process: assembly initialization, the nano_core Rust bootstrap, and the captain main initialization routine.

1. Assembly Stage: The kernel starts in 32-bit protected mode via the start function in kernel/nano_core/src/boot/arch_x86_64/boot.asm. It transitions to 64-bit long mode, sets up a Global Descriptor Table (GDT), and jumps to the Rust entry point.
2. nano_core Stage: The nano_core_start() function performs minimal bootstrapping, including VGA text display initialization, CPU exception handler setup, virtual memory mapping, and mod_mgmt subsystem initialization.
3. captain Stage: The captain handles full OS initialization, including ACPI/APIC discovery, device drivers, graphics subsystems, and spawning the first user application.

Heaps in Theseus are used for dynamic memory allocation of chunks smaller than a single page. Their primary purpose is to support Rust's alloc types such as Box, Arc, and Vec.

To use a heap allocator as the backing for these types, the allocator must implement the Rust GlobalAlloc trait.

Important Note on Large Allocations: While you can request large allocations from the heap, Theseus backs them with an individually-created MappedPages object of newly-allocated pages and frames. For better efficiency, use MappedPages instead of the heap for large memory requests.

Theseus utilizes a Cargo workspace with a virtual manifest to group all main crates into a single top-level meta-project. This structure is designed to speed up build times.

All crates from the main repository folders (such as kernel/ and applications/) and their dependencies are compiled into a single unified target/ directory. The workspace members are defined in the root Cargo.toml manifest.

Theseus distinguishes between two types of third-party libraries:

• ports/: Contains libraries that have been specifically ported to use Theseus-specific functions and types. These libraries can depend directly on Theseus crates located in kernel/.
• libs/: Contains standalone third-party libraries that cannot depend on Theseus crates.

Many libraries in ports/ are managed as git submodules to preserve their original repository history and maintain links to the upstream source.

Cells are loaded and linked into a namespace (referred to as CellNamespace or CrateNamespace). A namespace represents the collection of all publicly-visible symbols exposed by the cells within it.

Namespaces serve two primary purposes:

1. Symbol Resolution: They enable quick dependency resolution during dynamic linking.
2. OS Personalities: They allow the system to efficiently realize multiple distinct OS personalities to serve different applications with different requirements.

Theseus follows the P.I.E. principle, which dictates the division of responsibilities between hardware and software:

1. Performance: Responsibility of the hardware.
2. Isolation: Responsibility of the software (via the language and compiler).
3. Efficiency: Responsibility of the hardware.

This is also referred to as the PHIS principle: Performance in Hardware, Isolation in Software. By moving isolation to the software layer (specifically through Rust's compile-time guarantees), Theseus avoids the security vulnerabilities and performance costs associated with hardware-enforced isolation (such as speculative execution exploits like Meltdown and Spectre).

In Theseus OS, window management is split between the application and the Window Manager to prevent deadlocks and manage ownership.

• Window: Owned by the application. It contains application-specific state like the window title, profile, a consumer for events, and a list of Displayable items. The application uses this to render content.
• WindowInner: Owned/managed by the Window Manager. It contains the framebuffer (supporting RGB or alpha channel pixels) and an event producer.

The application holds a strong reference (Arc) to the Window, while the Window Manager holds a weak reference (Weak) to the underlying WindowInner. This allows the Window Manager to manage window location and depth without owning the window itself.

The libs/ directory contains third-party libraries used by or customized for Theseus. These libraries are designed to be independent of the Theseus kernel and are intended to be refactorable into standalone projects.

Critical Constraint: Libraries located in libs/ must not depend on any crates within the Theseus kernel (kernel/).

The published documentation for Theseus OS, including the project book and source code documentation (rustdoc), is hosted online via GitHub Pages.

View the documentation at: https://theseus-os.github.io/Theseus

Theseus is currently supported on x86_64 architectures only. It can be run in the following environments:

Virtual Machine Emulators

• QEMU
• bochs
• VirtualBox
• VMware Workstation Player

Real Hardware

• Intel NUC devices
• Supermicro servers
• Various Thinkpad laptops
• PCs with Gigabyte motherboards

Note: Booting on real hardware is done at your own risk. Ensure you have backups of all important files before attempting to boot Theseus on physical devices.