# 0nera/bmosp architecture

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

- Interactive diagram: https://gitdiagram.com/0nera/bmosp
- Repository: https://github.com/0nera/bmosp

## Overview

#### Purpose and execution model
BMOSP is an educational, modular x86_64 platform rather than a general-purpose OS. It targets BIOS/UEFI boot and is intended primarily for QEMU. The kernel is built as a freestanding C/GAS image, booted through Limine, then extended with separately built runtime modules. Top-level build/run entry points are `build.sh`, `build_mods.sh`, and `run.sh`.

#### Boot and kernel initialization
Limine boot configuration and image layout are defined in `configs/limine.cfg` and `configs/linker.ld`. Kernel control begins in `kernel/start.c`, which establishes the platform runtime and coordinates early subsystem initialization. Architecture-specific setup is concentrated under `kernel/cpu/arch.c` and `kernel/cpu/cpu.c`.

#### CPU, interrupts, and scheduling boundary
The x86_64 hardware layer configures descriptor tables, interrupt handling, PIC/PIT timing, paging, and task switching. Key paths are `kernel/cpu/idt.c`, `kernel/cpu/idt_stubs.s`, and `kernel/cpu/paging.c`; task execution/switching spans `kernel/cpu/task.c` and `kernel/cpu/task_switch.s`. This layer is the boundary between raw processor events and kernel services.

#### Kernel services and shared interfaces
Core services include memory management, framebuffer output, logging, synchronization, buffered I/O, and general system calls/services. Their implementation resides in `kernel/mem.c`, `kernel/fb.c`, `kernel/log.c`, `kernel/lock.c`, `kernel/io_buf.c`, and `kernel/sys.c`. Public kernel-facing contracts are exposed through headers such as `include/mem.h`, `include/sys.h`, `include/fb.h`, and `include/mod.h`; modules should depend on these interfaces rather than internal kernel files.

#### Module loading and executable format
The platform’s defining extension mechanism is dynamically managed modules. `kernel/mod.c` owns module lifecycle/loading behavior, while `kernel/elf.c` handles ELF-format executable/module parsing. Module ABI and system-facing types are supplied by `modlib/modstd.h`, `modlib/system.h`, and `modlib/types.h`. The module linker layout is defined by `modules/link.ld`.

#### Modules and device/application functionality
Modules are independently compiled C components with their own `build.sh` entry points. They provide demonstrations and platform capabilities: example output (`modules/helloworld/main.c`), in-memory filesystem behavior (`modules/imfs/main.c`), PCI discovery (`modules/pci/main.c`), PS/2 input (`modules/ps2/main.c`), and a Doom workload (`modules/doom/main.c`). The module catalog is represented by `modules/modules.json`.

#### Build, SDK, and delivery infrastructure
Build scripts assemble the kernel, module artifacts, boot configuration, and image/runtime workflow. `build.sh` is the primary kernel build orchestrator; `scripts/build_sdk.sh` and `scripts/get_sdk.sh` manage the required SDK/toolchain; `scripts/modmanager.py` supports module management. CI, static analysis, and release automation run in GitHub Actions through `.github/workflows/build.yml`, `.github/workflows/codeql.yml`, and `.github/workflows/release.yml`.

Main entry points: [`kernel/start.c`](https://github.com/0nera/bmosp/blob/master/kernel/start.c) (Kernel startup), [`modules/helloworld/main.c`](https://github.com/0nera/bmosp/blob/master/modules/helloworld/main.c) (Runtime modules), [`build.sh`](https://github.com/0nera/bmosp/blob/master/build.sh) (Kernel build), [`build_mods.sh`](https://github.com/0nera/bmosp/blob/master/build_mods.sh) (Module builds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & Delivery"]
  node_sdk{{"SDK toolchain<br/>[build_sdk.sh]"}}
  node_kernel_build["Kernel build<br/>build script<br/>[build.sh]"]
  node_module_build["Module builds<br/>build script<br/>[build_mods.sh]"]
  node_module_manager["Module manager<br/>management tool<br/>[modmanager.py]"]
  node_ci_release["CI and releases<br/>GitHub Actions<br/>[build.yml]"]
  node_qemu_run(("QEMU runtime<br/>emulator launch<br/>[run.sh]"))
end

subgraph group_boot["Boot Image"]
  node_limine["Limine boot config<br/>boot configuration<br/>[limine.cfg]"]
  node_kernel_layout["Kernel linker layout<br/>linker script<br/>[linker.ld]"]
end

subgraph group_kernel["Kernel Runtime"]
  node_kernel_start["Kernel startup<br/>freestanding C entry<br/>[start.c]"]
  node_cpu_platform["CPU platform setup<br/>x86_64 layer<br/>[arch.c]"]
  node_interrupts_paging["Interrupts and paging<br/>hardware boundary<br/>[idt.c]"]
  node_scheduler["Tasks and switching<br/>scheduler<br/>[task.c]"]
  node_kernel_services["Kernel services<br/>core services<br/>[sys.c]"]
  node_kernel_api["Public kernel API<br/>header contracts<br/>[mod.h]"]
  node_module_loader["Module loader<br/>lifecycle manager<br/>[mod.c]"]
  node_elf_loader["ELF parser<br/>executable loader<br/>[elf.c]"]
end

subgraph group_modules["Module Ecosystem"]
  node_module_abi["Module ABI<br/>shared contracts<br/>[modstd.h]"]
  node_module_layout["Module linker layout<br/>linker script<br/>[link.ld]"]
  node_module_catalog["Module catalog<br/>module manifest<br/>[modules.json]"]
  node_runtime_modules["Runtime modules<br/>independent C modules<br/>[main.c]"]
end

node_sdk -->|"provides toolchain"| node_kernel_build
node_sdk -->|"provides toolchain"| node_module_build
node_kernel_build -->|"links with"| node_kernel_layout
node_kernel_build -->|"packages boot config"| node_limine
node_module_build -->|"links with"| node_module_layout
node_module_manager -->|"manages"| node_module_catalog
node_module_build -->|"builds"| node_runtime_modules
node_ci_release -.->|"automates"| node_kernel_build
node_ci_release -.->|"automates"| node_module_build
node_qemu_run -->|"boots image via"| node_limine
node_limine -->|"boots"| node_kernel_start
node_kernel_layout -->|"places image"| node_kernel_start
node_kernel_start -->|"initializes"| node_cpu_platform
node_cpu_platform -->|"configures"| node_interrupts_paging
node_interrupts_paging -->|"dispatches execution"| node_scheduler
node_kernel_start -->|"initializes"| node_kernel_services
node_kernel_services -->|"exports"| node_kernel_api
node_kernel_start -->|"starts"| node_module_loader
node_module_loader -->|"parses through"| node_elf_loader
node_module_loader -->|"loads"| node_runtime_modules
node_runtime_modules -->|"uses"| node_module_abi
node_runtime_modules -->|"calls"| node_kernel_api
node_module_catalog -->|"lists"| node_runtime_modules

click node_sdk "https://github.com/0nera/bmosp/blob/master/scripts/build_sdk.sh"
click node_kernel_build "https://github.com/0nera/bmosp/blob/master/build.sh"
click node_module_build "https://github.com/0nera/bmosp/blob/master/build_mods.sh"
click node_module_manager "https://github.com/0nera/bmosp/blob/master/scripts/modmanager.py"
click node_ci_release "https://github.com/0nera/bmosp/blob/master/.github/workflows/build.yml"
click node_limine "https://github.com/0nera/bmosp/blob/master/configs/limine.cfg"
click node_kernel_layout "https://github.com/0nera/bmosp/blob/master/configs/linker.ld"
click node_kernel_start "https://github.com/0nera/bmosp/blob/master/kernel/start.c"
click node_cpu_platform "https://github.com/0nera/bmosp/blob/master/kernel/cpu/arch.c"
click node_interrupts_paging "https://github.com/0nera/bmosp/blob/master/kernel/cpu/idt.c"
click node_scheduler "https://github.com/0nera/bmosp/blob/master/kernel/cpu/task.c"
click node_kernel_services "https://github.com/0nera/bmosp/blob/master/kernel/sys.c"
click node_kernel_api "https://github.com/0nera/bmosp/blob/master/include/mod.h"
click node_module_loader "https://github.com/0nera/bmosp/blob/master/kernel/mod.c"
click node_elf_loader "https://github.com/0nera/bmosp/blob/master/kernel/elf.c"
click node_module_abi "https://github.com/0nera/bmosp/blob/master/modlib/modstd.h"
click node_module_layout "https://github.com/0nera/bmosp/blob/master/modules/link.ld"
click node_module_catalog "https://github.com/0nera/bmosp/blob/master/modules/modules.json"
click node_runtime_modules "https://github.com/0nera/bmosp/blob/master/modules/helloworld/main.c"
click node_qemu_run "https://github.com/0nera/bmosp/blob/master/run.sh"

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_sdk,node_kernel_build,node_module_build,node_module_manager,node_ci_release,node_qemu_run toneBlue
class node_limine,node_kernel_layout toneAmber
class node_kernel_start,node_cpu_platform,node_interrupts_paging,node_scheduler,node_kernel_services,node_kernel_api,node_module_loader,node_elf_loader toneMint
class node_module_abi,node_module_layout,node_module_catalog,node_runtime_modules toneRose
```

## Components

### Build & Delivery

- [SDK toolchain](https://github.com/0nera/bmosp/blob/master/scripts/build_sdk.sh): toolchain · Installed and managed by SDK scripts. · `scripts/build_sdk.sh`
- [Kernel build](https://github.com/0nera/bmosp/blob/master/build.sh): build script · Builds the freestanding kernel and boot image. · `build.sh`
- [Module builds](https://github.com/0nera/bmosp/blob/master/build_mods.sh): build script · Independently builds runtime module artifacts. · `build_mods.sh`
- [Module manager](https://github.com/0nera/bmosp/blob/master/scripts/modmanager.py): management tool · `scripts/modmanager.py`
- [CI and releases](https://github.com/0nera/bmosp/blob/master/.github/workflows/build.yml): GitHub Actions · Build, analysis, and release automation. · `.github/workflows/build.yml`
- [QEMU runtime](https://github.com/0nera/bmosp/blob/master/run.sh): emulator launch · Runs the BIOS/UEFI bootable image. · `run.sh`

### Boot Image

- [Limine boot config](https://github.com/0nera/bmosp/blob/master/configs/limine.cfg): boot configuration · `configs/limine.cfg`
- [Kernel linker layout](https://github.com/0nera/bmosp/blob/master/configs/linker.ld): linker script · `configs/linker.ld`

### Kernel Runtime

- [Kernel startup](https://github.com/0nera/bmosp/blob/master/kernel/start.c): freestanding C entry · Establishes the runtime and initializes subsystems. · `kernel/start.c`
- [CPU platform setup](https://github.com/0nera/bmosp/blob/master/kernel/cpu/arch.c): x86_64 layer · Sets up processor architecture state. · `kernel/cpu/arch.c`
- [Interrupts and paging](https://github.com/0nera/bmosp/blob/master/kernel/cpu/idt.c): hardware boundary · Translates processor events and manages virtual memory. · `kernel/cpu/idt.c`
- [Tasks and switching](https://github.com/0nera/bmosp/blob/master/kernel/cpu/task.c): scheduler · Executes tasks and performs context switches. · `kernel/cpu/task.c`
- [Kernel services](https://github.com/0nera/bmosp/blob/master/kernel/sys.c): core services · Memory, framebuffer, logging, locks, buffered I/O, and system services. · `kernel/sys.c`
- [Public kernel API](https://github.com/0nera/bmosp/blob/master/include/mod.h): header contracts · Interfaces modules use instead of kernel internals. · `include/mod.h`
- [Module loader](https://github.com/0nera/bmosp/blob/master/kernel/mod.c): lifecycle manager · Loads and manages module lifecycle. · `kernel/mod.c`
- [ELF parser](https://github.com/0nera/bmosp/blob/master/kernel/elf.c): executable loader · Parses module executable format. · `kernel/elf.c`

### Module Ecosystem

- [Module ABI](https://github.com/0nera/bmosp/blob/master/modlib/modstd.h): shared contracts · System types and module-facing ABI. · `modlib/modstd.h`
- [Module linker layout](https://github.com/0nera/bmosp/blob/master/modules/link.ld): linker script · `modules/link.ld`
- [Module catalog](https://github.com/0nera/bmosp/blob/master/modules/modules.json): module manifest · `modules/modules.json`
- [Runtime modules](https://github.com/0nera/bmosp/blob/master/modules/helloworld/main.c): independent C modules · Hello world, IMFS, PCI, PS/2, and Doom capabilities. · `modules/helloworld/main.c`

## Connections

- SDK toolchain → Kernel build: provides toolchain
- SDK toolchain → Module builds: provides toolchain
- Kernel build → Kernel linker layout: links with
- Kernel build → Limine boot config: packages boot config
- Module builds → Module linker layout: links with
- Module manager → Module catalog: manages
- Module builds → Runtime modules: builds
- CI and releases → Kernel build: automates
- CI and releases → Module builds: automates
- QEMU runtime → Limine boot config: boots image via
- Limine boot config → Kernel startup: boots
- Kernel linker layout → Kernel startup: places image
- Kernel startup → CPU platform setup: initializes
- CPU platform setup → Interrupts and paging: configures
- Interrupts and paging → Tasks and switching: dispatches execution
- Kernel startup → Kernel services: initializes
- Kernel services → Public kernel API: exports
- Kernel startup → Module loader: starts
- Module loader → ELF parser: parses through
- Module loader → Runtime modules: loads
- Runtime modules → Module ABI: uses
- Runtime modules → Public kernel API: calls
- Module catalog → Runtime modules: lists