# nldk/nos architecture

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

- Interactive diagram: https://gitdiagram.com/nldk/nos
- Repository: https://github.com/nldk/nos

## Overview

NOS is a small x86 operating system: its two-stage assembly bootloader selects and loads a kernel, which provides a shell, ext2 file operations, and ring-3 user processes with syscalls. The main workflow and filesystem/storage boundaries are supported by the README and sampled source. Some internal boot, shell, and syscall dispatch details are unsampled, so the graph avoids asserting uncertain links.

Main entry points: [`kernel/src/main.c`](https://github.com/nldk/nos/blob/main/kernel/src/main.c) (Kernel shell), [`kernel/src/process.c`](https://github.com/nldk/nos/blob/main/kernel/src/process.c) (Process management), [`kernel/src/ext2.c`](https://github.com/nldk/nos/blob/main/kernel/src/ext2.c) (Ext2 operations), [`kernel/src/syscall.c`](https://github.com/nldk/nos/blob/main/kernel/src/syscall.c) (Syscall services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot"]
  node_bootloader["Two-stage loader"]
  node_boot_headers["Kernel headers<br/>[header.asm]"]
end

subgraph group_kernel["Kernel"]
  node_kernel_entry["Kernel entry<br/>[entry.S]"]
  node_kernel_main["Kernel shell<br/>[main.c]"]
  node_interrupts["Interrupts and ring 3<br/>[interupts.c]"]
  node_syscall_entry["Syscall entry<br/>[syscall.S]"]
  node_syscall_dispatch["Syscall services<br/>[syscall.c]"]
  node_memory["Heap and paging<br/>[mem.c]"]
  node_vga["Text display<br/>[vga.h]"]
end

subgraph group_storage["Filesystem and storage"]
  node_ext2["Ext2 operations<br/>[ext2.c]"]
  node_ata["ATA sector I/O<br/>[storage.c]"]
end

subgraph group_userspace["User processes"]
  node_process["Process management<br/>[process.c]"]
  node_user_program["User program<br/>[hello.c]"]
  node_user_abi["User syscall API<br/>[syscall.h]"]
end

node_firmware(("Boot firmware"))
node_disk[("Disk device")]

node_firmware -->|"starts"| node_bootloader
node_boot_headers -->|"describes kernels"| node_bootloader
node_bootloader -->|"loads selected kernel"| node_kernel_entry
node_kernel_entry -->|"enters"| node_kernel_main
node_kernel_main -->|"runs shell file commands"| node_ext2
node_kernel_main -->|"prints output"| node_vga
node_kernel_main -->|"starts user process"| node_process
node_process -->|"reads program image"| node_ext2
node_process -->|"allocates and maps pages"| node_memory
node_process -->|"enters ring 3"| node_interrupts
node_user_program -->|"uses"| node_user_abi
node_user_abi -->|"issues syscalls"| node_syscall_entry
node_syscall_entry -->|"transfers control"| node_syscall_dispatch
node_syscall_dispatch -->|"serves file requests"| node_ext2
node_syscall_dispatch -->|"serves print requests"| node_vga
node_ext2 -->|"reads and writes sectors"| node_ata
node_ata -->|"transfers sectors"| node_disk
node_interrupts -->|"delivers keyboard input"| node_kernel_main

click node_bootloader "https://github.com/nldk/nos/tree/main/NBL"
click node_boot_headers "https://github.com/nldk/nos/blob/main/NBL/header.asm"
click node_kernel_entry "https://github.com/nldk/nos/blob/main/kernel/src/entry.S"
click node_kernel_main "https://github.com/nldk/nos/blob/main/kernel/src/main.c"
click node_interrupts "https://github.com/nldk/nos/blob/main/kernel/src/interupts.c"
click node_syscall_entry "https://github.com/nldk/nos/blob/main/kernel/src/syscall.S"
click node_syscall_dispatch "https://github.com/nldk/nos/blob/main/kernel/src/syscall.c"
click node_process "https://github.com/nldk/nos/blob/main/kernel/src/process.c"
click node_memory "https://github.com/nldk/nos/blob/main/kernel/src/mem.c"
click node_vga "https://github.com/nldk/nos/blob/main/kernel/src/vga.h"
click node_ext2 "https://github.com/nldk/nos/blob/main/kernel/src/ext2.c"
click node_ata "https://github.com/nldk/nos/blob/main/kernel/src/storage.c"
click node_user_program "https://github.com/nldk/nos/blob/main/user/hello.c"
click node_user_abi "https://github.com/nldk/nos/blob/main/user/syscall.h"

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_bootloader,node_boot_headers toneBlue
class node_kernel_entry,node_kernel_main,node_interrupts,node_syscall_entry,node_syscall_dispatch,node_memory,node_vga,node_disk toneAmber
class node_ext2,node_ata toneMint
class node_process,node_user_program,node_user_abi toneRose
class node_firmware toneIndigo
```

## Components

### Boot

- [Two-stage loader](https://github.com/nldk/nos/tree/main/NBL): `NBL`
- [Kernel headers](https://github.com/nldk/nos/blob/main/NBL/header.asm): `NBL/header.asm`

### Kernel

- [Kernel entry](https://github.com/nldk/nos/blob/main/kernel/src/entry.S): `kernel/src/entry.S`
- [Kernel shell](https://github.com/nldk/nos/blob/main/kernel/src/main.c): `kernel/src/main.c`
- [Interrupts and ring 3](https://github.com/nldk/nos/blob/main/kernel/src/interupts.c): `kernel/src/interupts.c`
- [Syscall entry](https://github.com/nldk/nos/blob/main/kernel/src/syscall.S): `kernel/src/syscall.S`
- [Syscall services](https://github.com/nldk/nos/blob/main/kernel/src/syscall.c): `kernel/src/syscall.c`
- [Heap and paging](https://github.com/nldk/nos/blob/main/kernel/src/mem.c): `kernel/src/mem.c`
- [Text display](https://github.com/nldk/nos/blob/main/kernel/src/vga.h): `kernel/src/vga.h`

### Filesystem and storage

- [Ext2 operations](https://github.com/nldk/nos/blob/main/kernel/src/ext2.c): `kernel/src/ext2.c`
- [ATA sector I/O](https://github.com/nldk/nos/blob/main/kernel/src/storage.c): `kernel/src/storage.c`

### User processes

- [Process management](https://github.com/nldk/nos/blob/main/kernel/src/process.c): `kernel/src/process.c`
- [User program](https://github.com/nldk/nos/blob/main/user/hello.c): `user/hello.c`
- [User syscall API](https://github.com/nldk/nos/blob/main/user/syscall.h): `user/syscall.h`

### Other components

- **Boot firmware**
- **Disk device**

## Connections

- Boot firmware → Two-stage loader: starts
- Kernel headers → Two-stage loader: describes kernels
- Two-stage loader → Kernel entry: loads selected kernel
- Kernel entry → Kernel shell: enters
- Kernel shell → Ext2 operations: runs shell file commands
- Kernel shell → Text display: prints output
- Kernel shell → Process management: starts user process
- Process management → Ext2 operations: reads program image
- Process management → Heap and paging: allocates and maps pages
- Process management → Interrupts and ring 3: enters ring 3
- User program → User syscall API: uses
- User syscall API → Syscall entry: issues syscalls
- Syscall entry → Syscall services: transfers control
- Syscall services → Ext2 operations: serves file requests
- Syscall services → Text display: serves print requests
- Ext2 operations → ATA sector I/O: reads and writes sectors
- ATA sector I/O → Disk device: transfers sectors
- Interrupts and ring 3 → Kernel shell: delivers keyboard input