# cirosantilli/x86-bare-metal-examples architecture

> Architecture diagram of the GitHub repository cirosantilli/x86-bare-metal-examples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cirosantilli/x86-bare-metal-examples
- Repository: https://github.com/cirosantilli/x86-bare-metal-examples

## Overview

This repository is an educational catalog of minimal x86 bare-metal programs, not one operating system. The main workflow is to choose an example and launch it in QEMU or Bochs; the README also describes writing images to hardware and booting a combined GRUB image. Examples cover BIOS services, CPU modes and interrupts, and alternate Multiboot and UEFI entry points. The excerpts show selected C examples and shared assembly macros; most individual examples and alternate boot configurations are represented only by their paths and README descriptions, so their internal calls are not inferred.

Main entry points: [`run`](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/run) (Example runner), [`bios_hello_world.S`](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/bios_hello_world.S) (BIOS programs), [`bios_putc.S`](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/bios_putc.S) (BIOS display and input), [`bios_disk_load.S`](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/bios_disk_load.S) (BIOS disk loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bios["BIOS examples"]
  node_bios_collection["BIOS programs<br/>[bios_hello_world.S]"]
  node_bios_io["BIOS display and input<br/>[bios_putc.S]"]
  node_bios_disk["BIOS disk loading<br/>[bios_disk_load.S]"]
  node_c_hello["C BIOS hello<br/>[main.c]"]
end

subgraph group_cpu["CPU and interrupts"]
  node_cpu_modes["Protected mode<br/>[protected_mode.S]"]
  node_segmentation["Segmentation<br/>[segmentation.S]"]
  node_paging["Paging<br/>[paging.S]"]
  node_interrupts["Interrupt handling<br/>[interrupt.S]"]
  node_keyboard["Keyboard interrupts"]
  node_timers["PIT and RTC<br/>[pit.S]"]
end

subgraph group_boot["Alternate boot"]
  node_multiboot_hello["Multiboot hello<br/>[main.c]"]
  node_osdev_kernel["Multiboot OS kernel<br/>[kernel.c]"]
  node_uefi_app["UEFI application<br/>[main.c]"]
  node_grub_chainloader["GRUB chainloader<br/>[grub.cfg]"]
  node_grub_linux["GRUB Linux boot<br/>[grub.cfg]"]
end

subgraph group_support["Shared runtime"]
  node_common["Assembly macros<br/>[common.h]"]
end

node_learner(("Learner"))
node_run["Example runner"]

node_learner -->|"chooses example"| node_run
node_run -->|"launches example"| node_bios_collection
node_run -->|"launches example"| node_bios_io
node_run -->|"launches example"| node_bios_disk

click node_run "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/run"
click node_bios_collection "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/bios_hello_world.S"
click node_bios_io "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/bios_putc.S"
click node_bios_disk "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/bios_disk_load.S"
click node_c_hello "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/c_hello_world/main.c"
click node_cpu_modes "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/protected_mode.S"
click node_segmentation "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/segmentation.S"
click node_paging "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/paging.S"
click node_interrupts "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/interrupt.S"
click node_keyboard "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/interrupt_keyboard.S"
click node_timers "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/pit.S"
click node_multiboot_hello "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/multiboot/hello-world/main.c"
click node_osdev_kernel "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/multiboot/osdev/kernel.c"
click node_uefi_app "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/uefi/main.c"
click node_grub_chainloader "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/grub/chainloader/iso/boot/grub/grub.cfg"
click node_grub_linux "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/grub/linux/iso/boot/grub/grub.cfg"
click node_common "https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/common.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_bios_collection,node_bios_io,node_bios_disk,node_c_hello toneBlue
class node_cpu_modes,node_segmentation,node_paging,node_interrupts,node_keyboard,node_timers toneAmber
class node_multiboot_hello,node_osdev_kernel,node_uefi_app,node_grub_chainloader,node_grub_linux toneMint
class node_common toneRose
class node_learner toneIndigo
class node_run toneTeal
```

## Components

### BIOS examples

- [BIOS programs](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/bios_hello_world.S): `bios_hello_world.S`
- [BIOS display and input](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/bios_putc.S): `bios_putc.S`
- [BIOS disk loading](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/bios_disk_load.S): `bios_disk_load.S`
- [C BIOS hello](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/c_hello_world/main.c): `c_hello_world/main.c`

### CPU and interrupts

- [Protected mode](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/protected_mode.S): `protected_mode.S`
- [Segmentation](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/segmentation.S): `segmentation.S`
- [Paging](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/paging.S): `paging.S`
- [Interrupt handling](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/interrupt.S): `interrupt.S`
- [Keyboard interrupts](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/interrupt_keyboard.S): `interrupt_keyboard.S`
- [PIT and RTC](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/pit.S): `pit.S`

### Alternate boot

- [Multiboot hello](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/multiboot/hello-world/main.c): `multiboot/hello-world/main.c`
- [Multiboot OS kernel](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/multiboot/osdev/kernel.c): `multiboot/osdev/kernel.c`
- [UEFI application](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/uefi/main.c): `uefi/main.c`
- [GRUB chainloader](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/grub/chainloader/iso/boot/grub/grub.cfg): `grub/chainloader/iso/boot/grub/grub.cfg`
- [GRUB Linux boot](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/grub/linux/iso/boot/grub/grub.cfg): `grub/linux/iso/boot/grub/grub.cfg`

### Shared runtime

- [Assembly macros](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/common.h): `common.h`

### Other components

- **Learner**
- [Example runner](https://github.com/cirosantilli/x86-bare-metal-examples/blob/master/run): `run`

## Connections

- Learner → Example runner: chooses example (evidence: `README.adoc`)
- Example runner → BIOS programs: launches example (evidence: `README.adoc`)
- Example runner → BIOS display and input: launches example (evidence: `README.adoc`)
- Example runner → BIOS disk loading: launches example (evidence: `README.adoc`)
