---

Voted French law aimed at criminalizing free culture. No to authoritarianism! No to fascism! Support your local sound systems!

🇫🇷 French citizens — SIGN THE PETITION

Cosmos gen3

A bare-metal C# kernel framework built on NativeAOT. Cosmos gen3 is the next generation of the Cosmos operating system project, replacing the IL2CPU transpiler with the official .NET ahead-of-time compiler. The result is an ordinary dotnet build that produces a bootable kernel ELF for x64 or ARM64, linked with an integrated runtime, plugged with the Cosmos plug system, and packaged into an ISO with the Limine bootloader.

Originally based on Zarlo's NativeAOT patcher. See CosmosOS/Cosmos#3088 for the design discussion behind the gen3 effort.

Why gen3?

Cosmos gen2 (the current public Cosmos OS) compiles C# IL to x86 assembly through IL2CPU, a custom transpiler. IL2CPU is powerful but maintains its own JIT-like backend separate from the .NET ecosystem. Gen3 replaces it with NativeAOT, the official .NET ahead-of-time toolchain, so kernels benefit from the same optimizer used in the wider .NET ecosystem and stay aligned with upstream as it evolves. This also makes it possible to support modern .NET features and additional architectures (currently ARM64 and RISC-V in the future) without re-implementing them in the toolchain.

Features

• NativeAOT compilation
• x64 and ARM64
• Limine boot protocol
• Cosmos plug system
• Native runtime stubs
• .NET runtime support (String, Collections, List, Dictionary, Math, Console, Date Time, Random, Bit Operations, Threading, Generics)
• Mark-and-sweep Garbage Collector
• Priority-based Stride Scheduler
• Exception handling
• Interrupts (APIC on x64, GIC on ARM64)
• ACPI (via LAI)
• PCI and MMIO drivers
• UART serial
• Cosmos Graphics Subsystem, double-buffered Canvas API (shapes, text fonts, images) on the UEFI GOP framebuffer
• Keyboard and Mouse input
• Network stack, standard System.Net.Sockets TCP/UDP over ARP, IPv4, DHCP and DNS (no HTTPS yet)
• Storage drivers (AHCI/SATA, NVMe) with MBR, GPT and EBR partitioning
• FAT12/16/32 filesystem on a Unix-style VFS (mount, superblocks, inodes), exposed through the standard System.IO API
• Timer / Clock

Documentation

Documentation site — split into a User Guide (build your own OS with Cosmos) and Developer Docs (contribute to Cosmos itself / architecture internals).

User Guide

• Installation Guide
• Kernel Startup
• File System
• Network
• Graphics
• Debugging with VS Code and QEMU

Developer Docs

• Dev Container Setup
• Kernel Project Layout
• Coding Guidelines
• Plugs
• Testing
• Garbage Collector, Precise Stack Scan (GCInfo)
• Scheduler
• Kernel Compilation Steps
• Cosmos.Build.Asm, .GCC, .Patcher, .Ilc

Getting Help

1. Check the documentation site — installation, debugging, and subsystem guides
2. Search existing issues — your problem may already be known
3. Ask on Discord — quickest way to get unblocked or sanity-check a setup problem
4. File a new issue — the bug report template walks you through the details we need (versions, exact command, serial log, symbolicated stack trace)

Reporting a kernel crash? CONTRIBUTING.md shows how to capture the serial log and turn the raw crash addresses into function names — with those two things most crashes can be diagnosed directly.

Related resources

• Cosmos Gen3: The NativeAOT Era and the End of IL2CPU?
• NativeAOT Developer Workflow
• NativeAOT Limitations
• Limine Boot Protocol

Contributors

Thanks to everyone who has contributed code, reviews, plugs, and bug reports:

• @zarlo
• @valentinbreiz
• @Guillermo-Santos
• @kumja1
• @AzureianGH
• @warquys
• @ascpixi
• @Demiomad
• @ilobilo
• @spectradevv
• All Cosmos gen2 contributors

See the live list on the Contributors page.

License

MIT — Copyright (c) 2024 Kaleb McGhie (zarlo) and contributors.