# bravinevans/kernec architecture

> Architecture diagram of the GitHub repository bravinevans/kernec, 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/bravinevans/kernec
- Repository: https://github.com/bravinevans/kernec

## Overview

Kernec is an early-stage x86_64 operating-system kernel. Its current boot workflow initializes serial output, CPU descriptor and interrupt state, the legacy PIC, and a periodic timer before entering an idle loop. The kernel also has a small system-call path: dispatch by number through a table to the null handler. The tree names broader OS areas, but their directories contain no implementation files here. Relationships are limited to shown calls and indexed references; the README supplied no content, and unsampled assembly wiring is not inferred.

Main entry points: [`kernel/main.c`](https://github.com/bravinevans/kernec/blob/main/kernel/main.c) (Kernel entry), [`kernel/arch/x86_64/interrupts.c`](https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/interrupts.c) (Interrupt handling), [`kernel/arch/x86_64/serial.c`](https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/serial.c) (Serial console), [`kernel/arch/x86_64/pic.c`](https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/pic.c) (8259 PIC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Kernel startup"]
  node_kmain["Kernel entry<br/>[main.c]"]
end

subgraph group_arch["x86_64 platform"]
  node_serial["Serial console<br/>[serial.c]"]
  node_gdt["GDT setup<br/>[gdt.c]"]
  node_interrupts["Interrupt handling<br/>[interrupts.c]"]
  node_pic["8259 PIC<br/>[pic.c]"]
  node_timer["PIT timer<br/>[timer.c]"]
  node_cpu["CPU control<br/>[cpu.c]"]
end

subgraph group_syscalls["System calls"]
  node_syscall_entry["Syscall entry<br/>[entry.S]"]
  node_dispatcher["Syscall dispatcher<br/>[dispatcher.c]"]
  node_syscall_table["Syscall table<br/>[table.c]"]
  node_null_handler["Null handler<br/>[null.c]"]
end

subgraph group_core["Kernel core"]
  node_panic["Kernel panic<br/>[panic.c]"]
end

node_limine(("Limine bootloader"))

node_limine -.->|"enters"| node_kmain
node_kmain -->|"initializes and writes"| node_serial
node_kmain -->|"initializes"| node_gdt
node_kmain -->|"initializes"| node_interrupts
node_kmain -->|"initializes"| node_pic
node_kmain -->|"unmasks IRQ"| node_pic
node_kmain -->|"initializes"| node_timer
node_kmain -->|"idles or halts"| node_cpu
node_interrupts -->|"sends EOI"| node_pic
node_interrupts -->|"reports fatal events"| node_serial
node_interrupts -->|"halts on fatal event"| node_cpu
node_panic -->|"writes panic"| node_serial
node_panic -->|"halts"| node_cpu
node_syscall_entry -.->|"dispatches to"| node_dispatcher
node_dispatcher -->|"indexes handler"| node_syscall_table
node_syscall_table -->|"registers"| node_null_handler

click node_kmain "https://github.com/bravinevans/kernec/blob/main/kernel/main.c"
click node_serial "https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/serial.c"
click node_gdt "https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/gdt.c"
click node_interrupts "https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/interrupts.c"
click node_pic "https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/pic.c"
click node_timer "https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/timer.c"
click node_cpu "https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/cpu.c"
click node_panic "https://github.com/bravinevans/kernec/blob/main/kernel/core/panic.c"
click node_syscall_entry "https://github.com/bravinevans/kernec/blob/main/kernel/syscall/arch/x86_64/entry.S"
click node_dispatcher "https://github.com/bravinevans/kernec/blob/main/kernel/syscall/dispatcher.c"
click node_syscall_table "https://github.com/bravinevans/kernec/blob/main/kernel/syscall/table.c"
click node_null_handler "https://github.com/bravinevans/kernec/blob/main/kernel/syscall/handlers/null.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_kmain toneBlue
class node_serial,node_gdt,node_interrupts,node_pic,node_timer,node_cpu toneAmber
class node_syscall_entry,node_dispatcher,node_syscall_table,node_null_handler toneMint
class node_panic toneRose
class node_limine toneIndigo
```

## Components

### Kernel startup

- [Kernel entry](https://github.com/bravinevans/kernec/blob/main/kernel/main.c): `kernel/main.c`

### x86_64 platform

- [Serial console](https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/serial.c): `kernel/arch/x86_64/serial.c`
- [GDT setup](https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/gdt.c): `kernel/arch/x86_64/gdt.c`
- [Interrupt handling](https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/interrupts.c): `kernel/arch/x86_64/interrupts.c`
- [8259 PIC](https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/pic.c): `kernel/arch/x86_64/pic.c`
- [PIT timer](https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/timer.c): `kernel/arch/x86_64/timer.c`
- [CPU control](https://github.com/bravinevans/kernec/blob/main/kernel/arch/x86_64/cpu.c): `kernel/arch/x86_64/cpu.c`

### System calls

- [Syscall entry](https://github.com/bravinevans/kernec/blob/main/kernel/syscall/arch/x86_64/entry.S): `kernel/syscall/arch/x86_64/entry.S`
- [Syscall dispatcher](https://github.com/bravinevans/kernec/blob/main/kernel/syscall/dispatcher.c): `kernel/syscall/dispatcher.c`
- [Syscall table](https://github.com/bravinevans/kernec/blob/main/kernel/syscall/table.c): `kernel/syscall/table.c`
- [Null handler](https://github.com/bravinevans/kernec/blob/main/kernel/syscall/handlers/null.c): `kernel/syscall/handlers/null.c`

### Kernel core

- [Kernel panic](https://github.com/bravinevans/kernec/blob/main/kernel/core/panic.c): `kernel/core/panic.c`

### Other components

- **Limine bootloader**

## Connections

- Limine bootloader → Kernel entry: enters
- Kernel entry → Serial console: initializes and writes (evidence: `kernel/main.c`)
- Kernel entry → GDT setup: initializes (evidence: `kernel/main.c`)
- Kernel entry → Interrupt handling: initializes (evidence: `kernel/main.c`)
- Kernel entry → 8259 PIC: initializes (evidence: `kernel/main.c`)
- Kernel entry → 8259 PIC: unmasks IRQ (evidence: `kernel/main.c`)
- Kernel entry → PIT timer: initializes (evidence: `kernel/main.c`)
- Kernel entry → CPU control: idles or halts (evidence: `kernel/main.c`)
- Interrupt handling → 8259 PIC: sends EOI (evidence: `kernel/arch/x86_64/interrupts.c`)
- Interrupt handling → Serial console: reports fatal events (evidence: `kernel/arch/x86_64/interrupts.c`)
- Interrupt handling → CPU control: halts on fatal event (evidence: `kernel/arch/x86_64/interrupts.c`)
- Kernel panic → Serial console: writes panic (evidence: `kernel/core/panic.c`)
- Kernel panic → CPU control: halts (evidence: `kernel/core/panic.c`)
- Syscall entry → Syscall dispatcher: dispatches to
- Syscall dispatcher → Syscall table: indexes handler (evidence: `kernel/syscall/dispatcher.c`)
- Syscall table → Null handler: registers (evidence: `kernel/syscall/table.c`)
