# git5345/yanix-os architecture

> Architecture diagram of the GitHub repository git5345/yanix-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/git5345/yanix-os
- Repository: https://github.com/git5345/yanix-os

## Overview

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: [`src/kernel/ckernel.c`](https://github.com/git5345/yanix-os/blob/main/src/kernel/ckernel.c) (C kernel), [`builds/build.sh`](https://github.com/git5345/yanix-os/blob/main/builds/build.sh) (build.sh), [`libs/src/console.c`](https://github.com/git5345/yanix-os/blob/main/libs/src/console.c) (Console), [`libs/heads/pit.h`](https://github.com/git5345/yanix-os/blob/main/libs/heads/pit.h) (PIT)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build"]
  node_build_sh["build.sh<br/>build script<br/>[build.sh]"]
  node_cbuild_sh["cbuild.sh<br/>build script<br/>[cbuild.sh]"]
end

subgraph group_boot["Boot"]
  node_boot_main["Boot entry<br/>asm boot<br/>[main.asm]"]
end

subgraph group_kernel["Kernel"]
  node_kernel_asm["Kernel entry<br/>asm entry<br/>[kernel.asm]"]
  node_ckernel_c["C kernel<br/>kernel core<br/>[ckernel.c]"]
end

subgraph group_libs["Platform libs"]
  node_ioport_h["I/O ports<br/>port access<br/>[ioport.h]"]
  node_interrupts_h["Interrupts<br/>interrupt api<br/>[interrupts.h]"]
  node_pit_h["PIT<br/>timer api<br/>[pit.h]"]
  node_time_h["Time<br/>[time.h]"]
  node_console_c["Console<br/>output driver<br/>[console.c]"]
  node_video_c["Video<br/>display driver<br/>[video.c]"]
  node_keyboard_c["Keyboard<br/>input driver<br/>[keyboard.c]"]
  node_ata_c["ATA<br/>storage driver<br/>[ata.c]"]
  node_memory_h["Memory<br/>[memory.h]"]
  node_string_c["String<br/>utility lib<br/>[string.c]"]
end

subgraph group_hw["Hardware"]
  node_hw_bus(("Bus"))
  node_kbd_hw(("Keyboard HW<br/>device"))
  node_disk_hw(("Disk HW<br/>device"))
  node_display_hw(("Display HW<br/>device"))
  node_timer_hw(("Timer HW<br/>device"))
end

node_build_sh -->|"builds"| node_boot_main
node_build_sh -->|"builds"| node_kernel_asm
node_build_sh -->|"builds"| node_ckernel_c
node_build_sh -->|"links"| node_console_c
node_cbuild_sh -.->|"supports"| node_build_sh
node_boot_main -->|"jumps"| node_kernel_asm
node_kernel_asm -->|"enters"| node_ckernel_c
node_ckernel_c -->|"uses"| node_interrupts_h
node_ckernel_c -->|"uses"| node_console_c
node_ckernel_c -->|"uses"| node_keyboard_c
node_ckernel_c -->|"uses"| node_pit_h
node_pit_h -->|"feeds"| node_time_h
node_ckernel_c -->|"uses"| node_ata_c
node_console_c -->|"renders on"| node_video_c
node_video_c -->|"drives"| node_display_hw
node_keyboard_c -->|"reads"| node_kbd_hw
node_ata_c -->|"accesses"| node_disk_hw
node_interrupts_h -->|"routes through"| node_hw_bus
node_ioport_h -->|"accesses"| node_hw_bus
node_pit_h -->|"ticks from"| node_timer_hw
node_console_c -->|"uses"| node_string_c
node_ckernel_c -->|"uses"| node_memory_h

click node_build_sh "https://github.com/git5345/yanix-os/blob/main/builds/build.sh"
click node_cbuild_sh "https://github.com/git5345/yanix-os/blob/main/builds/cbuild.sh"
click node_boot_main "https://github.com/git5345/yanix-os/blob/main/src/bootloader/main.asm"
click node_kernel_asm "https://github.com/git5345/yanix-os/blob/main/src/kernel/kernel.asm"
click node_ckernel_c "https://github.com/git5345/yanix-os/blob/main/src/kernel/ckernel.c"
click node_ioport_h "https://github.com/git5345/yanix-os/blob/main/libs/heads/ioport.h"
click node_interrupts_h "https://github.com/git5345/yanix-os/blob/main/libs/heads/interrupts.h"
click node_pit_h "https://github.com/git5345/yanix-os/blob/main/libs/heads/pit.h"
click node_time_h "https://github.com/git5345/yanix-os/blob/main/libs/heads/time.h"
click node_console_c "https://github.com/git5345/yanix-os/blob/main/libs/src/console.c"
click node_video_c "https://github.com/git5345/yanix-os/blob/main/libs/src/video.c"
click node_keyboard_c "https://github.com/git5345/yanix-os/blob/main/libs/src/keyboard.c"
click node_ata_c "https://github.com/git5345/yanix-os/blob/main/libs/src/ata.c"
click node_memory_h "https://github.com/git5345/yanix-os/blob/main/libs/heads/memory.h"
click node_string_c "https://github.com/git5345/yanix-os/blob/main/libs/src/string.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_build_sh,node_cbuild_sh toneBlue
class node_boot_main toneAmber
class node_kernel_asm,node_ckernel_c toneMint
class node_ioport_h,node_interrupts_h,node_pit_h,node_time_h,node_console_c,node_video_c,node_keyboard_c,node_ata_c,node_memory_h,node_string_c toneRose
class node_hw_bus,node_kbd_hw,node_disk_hw,node_display_hw,node_timer_hw toneIndigo
```

## Components

### Build

Scripts that assemble the freestanding OS image

- [build.sh](https://github.com/git5345/yanix-os/blob/main/builds/build.sh): build script · Main build orchestration script · `builds/build.sh`
- [cbuild.sh](https://github.com/git5345/yanix-os/blob/main/builds/cbuild.sh): build script · C build helper script · `builds/cbuild.sh`

### Boot

Early entry and machine setup before the C kernel

- [Boot entry](https://github.com/git5345/yanix-os/blob/main/src/bootloader/main.asm): asm boot · First-stage bootloader entry point · `src/bootloader/main.asm`

### Kernel

Core kernel control flow and initialization

- [Kernel entry](https://github.com/git5345/yanix-os/blob/main/src/kernel/kernel.asm): asm entry · Low-level kernel entry and setup layer · `src/kernel/kernel.asm`
- [C kernel](https://github.com/git5345/yanix-os/blob/main/src/kernel/ckernel.c): kernel core · Main kernel logic and coordination · `src/kernel/ckernel.c`

### Platform libs

Freestanding low-level services shared by the kernel

- [I/O ports](https://github.com/git5345/yanix-os/blob/main/libs/heads/ioport.h): port access · Hardware port access primitives · `libs/heads/ioport.h`
- [Interrupts](https://github.com/git5345/yanix-os/blob/main/libs/heads/interrupts.h): interrupt api · Interrupt handling interface · `libs/heads/interrupts.h`
- [PIT](https://github.com/git5345/yanix-os/blob/main/libs/heads/pit.h): timer api · Programmable interval timer interface · `libs/heads/pit.h`
- [Time](https://github.com/git5345/yanix-os/blob/main/libs/heads/time.h): time api · Timekeeping interface · `libs/heads/time.h`
- [Console](https://github.com/git5345/yanix-os/blob/main/libs/src/console.c): output driver · Text console implementation · `libs/src/console.c`
- [Video](https://github.com/git5345/yanix-os/blob/main/libs/src/video.c): display driver · Video output implementation · `libs/src/video.c`
- [Keyboard](https://github.com/git5345/yanix-os/blob/main/libs/src/keyboard.c): input driver · Keyboard input implementation · `libs/src/keyboard.c`
- [ATA](https://github.com/git5345/yanix-os/blob/main/libs/src/ata.c): storage driver · Disk I/O implementation · `libs/src/ata.c`
- [Memory](https://github.com/git5345/yanix-os/blob/main/libs/heads/memory.h): memory api · Low-level memory routines and definitions · `libs/heads/memory.h`
- [String](https://github.com/git5345/yanix-os/blob/main/libs/src/string.c): utility lib · Freestanding string helpers · `libs/src/string.c`

### Hardware

External devices and platform interfaces

- **Bus**: hardware bus · CPU and device-facing low-level interface boundary
- **Keyboard HW**: device · Physical keyboard input source
- **Disk HW**: device · Storage device behind ATA access
- **Display HW**: device · Video/display hardware output
- **Timer HW**: device · Timer source used for ticks and delays

## Connections

- 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