How git5345/yanix-os works
1. Project type and runtime
- yanix-os is a bare-metal x86_64 operating system, not an application running on top of another OS.
- The repo is organized around a direct boot path into low-level kernel code, with most hardware interaction done manually through architecture-specific modules.
2. Top-level execution flow
- The startup path is: bootloader assembly → kernel assembly entry → C kernel logic.
- This split suggests the assembly code handles early CPU/boot setup, then transfers control to the C kernel once a minimal execution environment exists.
3. Boot stage
- src/bootloader/main.asm is the first-stage entry point.
- Its role is likely to establish initial machine state and transition into the kernel load/entry sequence.
- Because it is in assembly, this boundary is where hardware/firmware-facing initialization begins.
4. Kernel entry and core
- src/kernel/kernel.asm provides the low-level kernel entry layer.
- src/kernel/ckernel.c contains the main kernel logic in C, so this is the central coordination layer for the OS after boot.
- The architecture implies a clean separation between startup mechanics and higher-level kernel behavior.
5. Hardware and platform support library
- The libs/ subtree is the main subsystem collection for low-level services used by the kernel.
- libs/heads/ contains headers for modules such as ata, keyboard, video, interrupts, pit, memory, console, time, ascii, string, ioport, and custom stdint.
- libs/src/ contains the matching implementations, indicating this repo uses a small internal kernel support library rather than external runtime dependencies.
6. Device and I/O subsystems
- ata is for storage access, likely direct disk I/O.
- keyboard handles input events from the keyboard controller.
- video and console provide display/output facilities, with console likely abstracting text rendering over video output.
- ioport is a foundational hardware access layer used by other drivers to read/write CPU I/O ports.
7. Interrupts, timing, and scheduling foundations
- interrupts is the subsystem for CPU interrupt handling and is probably central to asynchronous events.
- pit and time provide timer-related functionality, likely used for ticking, delays, or timekeeping.
- These modules form the timing/event backbone of the kernel, and other subsystems likely depend on them for basic responsiveness.
8. Memory and utility support
- memory likely covers early memory management or low-level memory routines.
- string, ascii, and custom stdint indicate the project supplies its own freestanding C support instead of relying on a hosted standard library.
- This is typical for kernel code, where libc is unavailable.
9. Subsystem interaction pattern
- The kernel core in ckernel.c likely orchestrates initialization in dependency order: low-level CPU/setup, interrupts, console/video, keyboard, timing, then storage or higher services.
- The library modules appear designed as direct service layers that the kernel calls, rather than as independent processes or daemons.
10. Build and integration
- builds/build.sh and builds/cbuild.sh are the build orchestration scripts.
- Their presence suggests a custom build pipeline for assembling bootloader/kernel objects and producing a bootable image, likely involving cross-compilation and linking of freestanding code.
- The build tooling is part of the architecture because it determines how assembly and C components are combined into the final OS artifact.
11. Likely architectural boundary map
- Firmware/boot boundary: bootloader assembly.
- CPU/early init boundary: kernel assembly.
- Kernel coordination boundary: ckernel.c.
- Platform services boundary: libs/src/* with matching headers in libs/heads/*.
- External world boundary: keyboard, disk, timer, and video hardware accessed through low-level drivers and I/O ports.
12. What to show in an architecture diagram
- A single boot chain entering the kernel.
- The kernel as the central controller.
- Shared library modules feeding the kernel for console output, interrupts, timers, input, storage, and basic utilities.
- Hardware devices at the edge, connected through the corresponding drivers and I/O access layer.
Main entry points: ckernel.c C kernel · build.sh build.sh · console.c Console · pit.h PIT
Components 20
Build
Scripts that assemble the freestanding OS image
Boot
Early entry and machine setup before the C kernel
- Boot entry · First-stage bootloader entry point
src/bootloader/main.asm
Kernel
Core kernel control flow and initialization
- Kernel entry · Low-level kernel entry and setup layer
src/kernel/kernel.asm - C kernel · Main kernel logic and coordination
src/kernel/ckernel.c
Platform libs
Freestanding low-level services shared by the kernel
- I/O ports · Hardware port access primitives
libs/heads/ioport.h - Interrupts · Interrupt handling interface
libs/heads/interrupts.h - PIT · Programmable interval timer interface
libs/heads/pit.h - Time · Timekeeping interface
libs/heads/time.h - Console · Text console implementation
libs/src/console.c - Video · Video output implementation
libs/src/video.c - Keyboard · Keyboard input implementation
libs/src/keyboard.c - ATA · Disk I/O implementation
libs/src/ata.c - Memory · Low-level memory routines and definitions
libs/heads/memory.h - String · Freestanding string helpers
libs/src/string.c
Hardware
External devices and platform interfaces
- Bus · CPU and device-facing low-level interface boundary
- Keyboard HW · Physical keyboard input source
- Disk HW · Storage device behind ATA access
- Display HW · Video/display hardware output
- Timer HW · Timer source used for ticks and delays
Connections 22
- build.sh → Boot entry: builds · Compiles and assembles boot code
- build.sh → Kernel entry: builds · Compiles and assembles kernel entry code
- build.sh → C kernel: builds · Compiles kernel C sources
- build.sh → Console: links · Packages platform services into the OS image
- cbuild.sh → build.sh: supports · Helper build step
- Boot entry → Kernel entry: jumps · Transfers control into kernel entry
- Kernel entry → C kernel: enters · Hands off to C kernel logic
- C kernel → Interrupts: uses · Sets up and coordinates interrupts
- C kernel → Console: uses · Writes kernel output through console
- C kernel → Keyboard: uses · Consumes keyboard input
- C kernel → PIT: uses · Initializes timer ticks
- PIT → Time: feeds · Provides timing foundation
- C kernel → ATA: uses · Initializes storage access
- Console → Video: renders on · Console output is backed by video
- Video → Display HW: drives · Writes to display hardware
- Keyboard → Keyboard HW: reads · Receives keyboard input from hardware
- ATA → Disk HW: accesses · Performs storage I/O
- Interrupts → Bus: routes through · Interrupt handling depends on low-level CPU/device interface
- I/O ports → Bus: accesses · Port I/O boundary for devices
- PIT → Timer HW: ticks from · Timer interrupts originate from hardware
- Console → String: uses · Formatting and text helpers
- C kernel → Memory: uses · Relies on low-level memory support