# sagi21805/learnixos architecture

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

- Interactive diagram: https://gitdiagram.com/sagi21805/learnixos
- Repository: https://github.com/sagi21805/learnixos

## Overview

LearnixOS is an educational Rust operating system. Its visible boot workflow starts in the first-stage bootloader, which loads the second stage and kernel, gathers the BIOS memory map, and transfers control; the kernel then initializes memory and interrupts, sets up interactive console input, reports PCI and CPU information, and enters its console loop. The repository also contains x86 primitives, memory allocators, device drivers, and shared support crates. The second-stage-to-kernel handoff and several subsystem internals are not evidenced by the sampled source, so those links are omitted.

Main entry points: [`kernel/src/main.rs`](https://github.com/sagi21805/learnixos/blob/master/kernel/src/main.rs) (Kernel Entry), [`crates/memory/slab/src/lib.rs`](https://github.com/sagi21805/learnixos/blob/master/crates/memory/slab/src/lib.rs) (Slab Allocator), [`crates/arch/x86/src/structures/global_descriptor_table.rs`](https://github.com/sagi21805/learnixos/blob/master/crates/arch/x86/src/structures/global_descriptor_table.rs) (Global Descriptor Table), [`bootloader/first_stage/src/main.rs`](https://github.com/sagi21805/learnixos/blob/master/bootloader/first_stage/src/main.rs) (First Stage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot"]
  node_first_stage["First Stage<br/>[main.rs]"]
  node_disk_io["Disk Loading<br/>[disk.rs]"]
  node_second_stage["Second Stage<br/>[main.rs]"]
end

subgraph group_kernel["Kernel"]
  node_kernel_entry["Kernel Entry<br/>[main.rs]"]
  node_kernel_memory["Memory Setup<br/>[memory.rs]"]
  node_interrupts["Interrupt Setup<br/>[mod.rs]"]
  node_exceptions["Exception Handlers<br/>[exceptions.rs]"]
  node_console["Console Loop<br/>[console.rs]"]
  node_timer["Timer<br/>[timer.rs]"]
end

subgraph group_arch["x86 Platform"]
  node_x86_instructions["CPU Instructions<br/>[port.rs]"]
  node_memory_map["Memory Map<br/>[memory_map.rs]"]
  node_gdt["Global Descriptor Table"]
  node_idt["Interrupt Descriptor Table"]
  node_segments["Segment Structures<br/>[segments.rs]"]
end

subgraph group_memory["Memory"]
  node_bitmap["Bitmap<br/>[bitmap.rs]"]
  node_page_allocator["Page Allocator<br/>[arena.rs]"]
  node_buddy_allocator["Buddy Allocator<br/>[lib.rs]"]
  node_buddy_metadata["Buddy Metadata<br/>[meta.rs]"]
  node_slab_allocator["Slab Allocator<br/>[lib.rs]"]
  node_slab_cache["Slab Cache<br/>[cache.rs]"]
  node_slab_descriptor["Slab Descriptor<br/>[descriptor.rs]"]
end

subgraph group_devices["Devices And Support"]
  node_common_types["Address Types<br/>[address_types.rs]"]
  node_keyboard["Keyboard Driver<br/>[lib.rs]"]
  node_vga["VGA Display<br/>[console.rs]"]
  node_pci["PCI Scanner<br/>[lib.rs]"]
  node_ahci["AHCI Driver<br/>[hba.rs]"]
  node_bitfields["Bitfield Macro<br/>[bitfields.rs]"]
  node_sync["Synchronization<br/>[rwlock.rs]"]
end

node_bios(("BIOS"))

node_bios -->|"starts"| node_first_stage
node_first_stage -->|"loads from"| node_disk_io
node_first_stage -->|"jumps to"| node_second_stage
node_kernel_entry -->|"initializes"| node_kernel_memory
node_kernel_entry -->|"initializes"| node_interrupts
node_interrupts -.->|"uses handlers"| node_exceptions
node_kernel_entry -->|"runs"| node_console
node_kernel_entry -->|"scans"| node_pci
node_kernel_entry -->|"queries CPU"| node_x86_instructions
node_gdt -->|"loads with"| node_x86_instructions
node_gdt -->|"uses selectors"| node_segments
node_memory_map -->|"uses address types"| node_common_types
node_bitmap -->|"uses addresses"| node_common_types
node_buddy_allocator -->|"organizes blocks"| node_buddy_metadata
node_slab_allocator -->|"requests pages"| node_buddy_allocator
node_slab_allocator -->|"allocates through"| node_slab_cache
node_slab_allocator -->|"creates"| node_slab_descriptor
node_console -.->|"initializes input"| node_keyboard
node_console -.->|"writes display"| node_vga
node_gdt -->|"uses generated fields"| node_bitfields
node_slab_allocator -.->|"uses locking"| node_sync

click node_first_stage "https://github.com/sagi21805/learnixos/blob/master/bootloader/first_stage/src/main.rs"
click node_disk_io "https://github.com/sagi21805/learnixos/blob/master/bootloader/first_stage/src/disk.rs"
click node_second_stage "https://github.com/sagi21805/learnixos/blob/master/bootloader/second_stage/src/main.rs"
click node_kernel_entry "https://github.com/sagi21805/learnixos/blob/master/kernel/src/main.rs"
click node_kernel_memory "https://github.com/sagi21805/learnixos/blob/master/kernel/src/memory.rs"
click node_interrupts "https://github.com/sagi21805/learnixos/blob/master/kernel/src/idt/mod.rs"
click node_exceptions "https://github.com/sagi21805/learnixos/blob/master/kernel/src/idt/exceptions.rs"
click node_console "https://github.com/sagi21805/learnixos/blob/master/kernel/src/console.rs"
click node_timer "https://github.com/sagi21805/learnixos/blob/master/kernel/src/timer.rs"
click node_x86_instructions "https://github.com/sagi21805/learnixos/blob/master/crates/arch/x86/src/instructions/port.rs"
click node_memory_map "https://github.com/sagi21805/learnixos/blob/master/crates/arch/x86/src/memory_map.rs"
click node_gdt "https://github.com/sagi21805/learnixos/blob/master/crates/arch/x86/src/structures/global_descriptor_table.rs"
click node_idt "https://github.com/sagi21805/learnixos/blob/master/crates/arch/x86/src/structures/interrupt_descriptor_table.rs"
click node_segments "https://github.com/sagi21805/learnixos/blob/master/crates/arch/x86/src/structures/segments.rs"
click node_common_types "https://github.com/sagi21805/learnixos/blob/master/crates/common/src/address_types.rs"
click node_bitmap "https://github.com/sagi21805/learnixos/blob/master/crates/common/src/bitmap.rs"
click node_page_allocator "https://github.com/sagi21805/learnixos/blob/master/crates/memory/page/src/arena.rs"
click node_buddy_allocator "https://github.com/sagi21805/learnixos/blob/master/crates/memory/buddy/src/lib.rs"
click node_buddy_metadata "https://github.com/sagi21805/learnixos/blob/master/crates/memory/buddy/src/meta.rs"
click node_slab_allocator "https://github.com/sagi21805/learnixos/blob/master/crates/memory/slab/src/lib.rs"
click node_slab_cache "https://github.com/sagi21805/learnixos/blob/master/crates/memory/slab/src/cache.rs"
click node_slab_descriptor "https://github.com/sagi21805/learnixos/blob/master/crates/memory/slab/src/descriptor.rs"
click node_keyboard "https://github.com/sagi21805/learnixos/blob/master/crates/drivers/keyboard/src/lib.rs"
click node_vga "https://github.com/sagi21805/learnixos/blob/master/crates/drivers/vga-display/src/console.rs"
click node_pci "https://github.com/sagi21805/learnixos/blob/master/crates/drivers/pci/src/lib.rs"
click node_ahci "https://github.com/sagi21805/learnixos/blob/master/crates/drivers/ahci/src/hba.rs"
click node_bitfields "https://github.com/sagi21805/learnixos/blob/master/crates/macros/bitfields/src/bitfields.rs"
click node_sync "https://github.com/sagi21805/learnixos/blob/master/crates/sync/src/rwlock.rs"

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_first_stage,node_disk_io,node_second_stage toneBlue
class node_kernel_entry,node_kernel_memory,node_interrupts,node_exceptions,node_console,node_timer toneAmber
class node_x86_instructions,node_memory_map,node_gdt,node_idt,node_segments toneMint
class node_bitmap,node_page_allocator,node_buddy_allocator,node_buddy_metadata,node_slab_allocator,node_slab_cache,node_slab_descriptor toneRose
class node_common_types,node_keyboard,node_vga,node_pci,node_ahci,node_bitfields,node_sync,node_bios toneIndigo
```

## Components

### Boot

- [First Stage](https://github.com/sagi21805/learnixos/blob/master/bootloader/first_stage/src/main.rs): `bootloader/first_stage/src/main.rs`
- [Disk Loading](https://github.com/sagi21805/learnixos/blob/master/bootloader/first_stage/src/disk.rs): `bootloader/first_stage/src/disk.rs`
- [Second Stage](https://github.com/sagi21805/learnixos/blob/master/bootloader/second_stage/src/main.rs): `bootloader/second_stage/src/main.rs`

### Kernel

- [Kernel Entry](https://github.com/sagi21805/learnixos/blob/master/kernel/src/main.rs): `kernel/src/main.rs`
- [Memory Setup](https://github.com/sagi21805/learnixos/blob/master/kernel/src/memory.rs): `kernel/src/memory.rs`
- [Interrupt Setup](https://github.com/sagi21805/learnixos/blob/master/kernel/src/idt/mod.rs): `kernel/src/idt/mod.rs`
- [Exception Handlers](https://github.com/sagi21805/learnixos/blob/master/kernel/src/idt/exceptions.rs): `kernel/src/idt/exceptions.rs`
- [Console Loop](https://github.com/sagi21805/learnixos/blob/master/kernel/src/console.rs): `kernel/src/console.rs`
- [Timer](https://github.com/sagi21805/learnixos/blob/master/kernel/src/timer.rs): `kernel/src/timer.rs`

### x86 Platform

- [CPU Instructions](https://github.com/sagi21805/learnixos/blob/master/crates/arch/x86/src/instructions/port.rs): `crates/arch/x86/src/instructions/port.rs`
- [Memory Map](https://github.com/sagi21805/learnixos/blob/master/crates/arch/x86/src/memory_map.rs): `crates/arch/x86/src/memory_map.rs`
- [Global Descriptor Table](https://github.com/sagi21805/learnixos/blob/master/crates/arch/x86/src/structures/global_descriptor_table.rs): `crates/arch/x86/src/structures/global_descriptor_table.rs`
- [Interrupt Descriptor Table](https://github.com/sagi21805/learnixos/blob/master/crates/arch/x86/src/structures/interrupt_descriptor_table.rs): `crates/arch/x86/src/structures/interrupt_descriptor_table.rs`
- [Segment Structures](https://github.com/sagi21805/learnixos/blob/master/crates/arch/x86/src/structures/segments.rs): `crates/arch/x86/src/structures/segments.rs`

### Memory

- [Bitmap](https://github.com/sagi21805/learnixos/blob/master/crates/common/src/bitmap.rs): `crates/common/src/bitmap.rs`
- [Page Allocator](https://github.com/sagi21805/learnixos/blob/master/crates/memory/page/src/arena.rs): `crates/memory/page/src/arena.rs`
- [Buddy Allocator](https://github.com/sagi21805/learnixos/blob/master/crates/memory/buddy/src/lib.rs): `crates/memory/buddy/src/lib.rs`
- [Buddy Metadata](https://github.com/sagi21805/learnixos/blob/master/crates/memory/buddy/src/meta.rs): `crates/memory/buddy/src/meta.rs`
- [Slab Allocator](https://github.com/sagi21805/learnixos/blob/master/crates/memory/slab/src/lib.rs): `crates/memory/slab/src/lib.rs`
- [Slab Cache](https://github.com/sagi21805/learnixos/blob/master/crates/memory/slab/src/cache.rs): `crates/memory/slab/src/cache.rs`
- [Slab Descriptor](https://github.com/sagi21805/learnixos/blob/master/crates/memory/slab/src/descriptor.rs): `crates/memory/slab/src/descriptor.rs`

### Devices And Support

- [Address Types](https://github.com/sagi21805/learnixos/blob/master/crates/common/src/address_types.rs): `crates/common/src/address_types.rs`
- [Keyboard Driver](https://github.com/sagi21805/learnixos/blob/master/crates/drivers/keyboard/src/lib.rs): `crates/drivers/keyboard/src/lib.rs`
- [VGA Display](https://github.com/sagi21805/learnixos/blob/master/crates/drivers/vga-display/src/console.rs): `crates/drivers/vga-display/src/console.rs`
- [PCI Scanner](https://github.com/sagi21805/learnixos/blob/master/crates/drivers/pci/src/lib.rs): `crates/drivers/pci/src/lib.rs`
- [AHCI Driver](https://github.com/sagi21805/learnixos/blob/master/crates/drivers/ahci/src/hba.rs): `crates/drivers/ahci/src/hba.rs`
- [Bitfield Macro](https://github.com/sagi21805/learnixos/blob/master/crates/macros/bitfields/src/bitfields.rs): `crates/macros/bitfields/src/bitfields.rs`
- [Synchronization](https://github.com/sagi21805/learnixos/blob/master/crates/sync/src/rwlock.rs): `crates/sync/src/rwlock.rs`

### Other components

- **BIOS**

## Connections

- BIOS → First Stage: starts (evidence: `bootloader/first_stage/src/main.rs`)
- First Stage → Disk Loading: loads from (evidence: `bootloader/first_stage/src/main.rs`)
- First Stage → Second Stage: jumps to (evidence: `bootloader/first_stage/src/main.rs`)
- Kernel Entry → Memory Setup: initializes (evidence: `kernel/src/main.rs`)
- Kernel Entry → Interrupt Setup: initializes (evidence: `kernel/src/main.rs`)
- Interrupt Setup → Exception Handlers: uses handlers
- Kernel Entry → Console Loop: runs (evidence: `kernel/src/main.rs`)
- Kernel Entry → PCI Scanner: scans (evidence: `kernel/src/main.rs`)
- Kernel Entry → CPU Instructions: queries CPU (evidence: `kernel/src/main.rs`)
- Global Descriptor Table → CPU Instructions: loads with (evidence: `crates/arch/x86/src/structures/global_descriptor_table.rs`)
- Global Descriptor Table → Segment Structures: uses selectors (evidence: `crates/arch/x86/src/structures/global_descriptor_table.rs`)
- Memory Map → Address Types: uses address types (evidence: `crates/common/src/address_types.rs`)
- Bitmap → Address Types: uses addresses (evidence: `crates/common/src/bitmap.rs`)
- Buddy Allocator → Buddy Metadata: organizes blocks (evidence: `crates/memory/buddy/src/lib.rs`)
- Slab Allocator → Buddy Allocator: requests pages (evidence: `crates/memory/slab/src/lib.rs`)
- Slab Allocator → Slab Cache: allocates through (evidence: `crates/memory/slab/src/lib.rs`)
- Slab Allocator → Slab Descriptor: creates (evidence: `crates/memory/slab/src/lib.rs`)
- Console Loop → Keyboard Driver: initializes input
- Console Loop → VGA Display: writes display
- Global Descriptor Table → Bitfield Macro: uses generated fields (evidence: `crates/arch/x86/src/structures/global_descriptor_table.rs`)
- Slab Allocator → Synchronization: uses locking
