# redox-os/kernel architecture

> Architecture diagram of the GitHub repository redox-os/kernel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/redox-os/kernel
- Repository: https://github.com/redox-os/kernel

## Overview

##### Project Type and Purpose
- This is an operating system’s kernel (microkernel) designed for Redox OS. Its purpose is to provide low-level services (e.g., process management, memory management, interrupt handling, device I/O, and system calls) while offering support for multiple hardware architectures.

##### Analyzing the File Structure
- There are clearly defined directories for architecture-specific implementations (src/arch/aarch64, src/arch/riscv64, src/arch/x86, src/arch/x86_64, and shared x86 code). These indicate that a significant abstraction layer exists to support different CPU architectures.
- The src directory contains distinct submodules for:
– ACPI handling (src/acpi): Managing Advanced Configuration and Power Interface details.
– Memory managers and allocators (src/allocator, src/memory, slab_allocator): Essential for kernel space memory management.
– Interrupt handling (found in arch directories and elsewhere in src/arch/[…]/interrupt): Indicates the kernel’s treatment of hardware/software interrupts.
– Process and context management (src/context): Managing process states, switching, and signals.
– System call infrastructure (src/syscall) and scheme (src/scheme): Providing system call mechanisms and abstraction schemes.
– Device drivers and related functions (src/devices): For interfacing with hardware like UART, graphical debugging, etc.
– Boot and startup sequences (src/startup), assembly routines (src/asm), and other initialization code.

- Boot/Startup: Represent the boot process, which begins with initialization (including assembly-level trampolines found in src/asm) and then moves into higher level startup routines (src/startup).
- ACPI & DTB: Create a block for ‘ACPI’ (src/acpi) and possibly ‘DTB’ (src/dtb) to handle hardware configuration and device tree management.
- Process/Context Management: Include a component for context/process management (src/context) that interacts with the scheduler and system call interface.
- System Call Interface: Highlight the syscall module (src/syscall) which handles user-to-kernel requests and interacts with device schemes.
- Device Drivers and External Interfaces: Components for devices (src/devices) including UART and graphical debug interfaces.
- Interrupt Handling: For handling exceptions, system calls, and external interrupts – depicted within both architecture-specific directories and possibly a unified interrupt manager.
- Scheduler and System Schemes: The “scheme” folder (src/scheme) indicates resource abstraction (filesystems, process schemes, and others) that might interface with the syscall layer.

##### Relationships and Interactions
– Boot/Startup initializes and hands off to the Architecture layer.
– The Architecture layer (which selects the appropriate arch-specific routines) initializes devices, memory, interrupts, and the process manager.
– The Memory management, ACPI/DTB, and interrupt handling modules interact closely with both the architecture layer and the higher-level system call manager.
– The system call interface is the main bridge between user-level operations and lower-level kernel functions (process management, IO, etc.).
- That architecture-specific implementations provide the abstraction needed for the core kernel modules to remain portable across different hardware targets.

##### Architectural Patterns & Design Principles
- Modularity: The breakdown into separate directories (arch, acpi, memory, context, devices) demonstrates a design that clearly separates concerns.
- Abstraction layers: The kernel isolates architecture-specific details from core functionality.
- Safety and reliability: Guidelines in the README (avoid panics in kernel space) suggest thorough error handling and careful memory management.

##### Instructing the Principal Software Engineer
- Annotations where necessary, such as mentioning which directories contribute to each subsystem (e.g., “ACPI logic from src/acpi”, “interrupt handling split across src/arch/*/interrupt”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Boot/Startup Subgraph
    subgraph "Boot/Startup"
        Boot["Boot/Startup"]:::startup
    end

    %% Architecture Abstraction Layer
    subgraph "Architecture Abstraction Layer"
        Arch["Arch Abstraction"]:::arch
        A_aarch64["aarch64"]:::arch_sub
        A_riscv64["riscv64"]:::arch_sub
        A_x86["x86"]:::arch_sub
        A_x86_64["x86_64"]:::arch_sub
        A_shared["x86_shared"]:::arch_sub
        Arch --> A_aarch64
        Arch --> A_riscv64
        Arch --> A_x86
        Arch --> A_x86_64
        Arch --> A_shared

        %% Interrupt handling within each architecture
        A_aarch64 -->|"handlesInterrupts"| A_aarch64_int["Interrupt (aarch64)"]:::interrupt
        A_riscv64 -->|"handlesInterrupts"| A_riscv64_int["Interrupt (riscv64)"]:::interrupt
        A_x86 -->|"handlesInterrupts"| A_x86_int["Interrupt (x86)"]:::interrupt
        A_x86_64 -->|"handlesInterrupts"| A_x86_64_int["Interrupt (x86_64)"]:::interrupt
        A_shared -->|"handlesInterrupts"| A_shared_int["Interrupt (x86_shared)"]:::interrupt
    end

    %% ACPI & DTB Subgraph
    subgraph "ACPI & DTB"
        acpi["ACPI"]:::acpi
        dtb["Device Tree (DTB)"]:::acpi
    end

    %% Memory Management Subgraph
    subgraph "Memory Management"
        allocator["Allocator"]:::memory
        memory["Memory Manager"]:::memory
        slab["Slab Allocator"]:::memory
    end

    %% Process/Context Management Subgraph
    subgraph "Process/Context Management"
        context["Process/Context"]:::context
    end

    %% System Call Interface Subgraph
    subgraph "System Call Interface"
        syscall["Syscall"]:::syscall
        scheme["Scheme"]:::syscall
    end

    %% Device Drivers Subgraph
    subgraph "Device Drivers and Interfaces"
        devices["Devices"]:::devices
    end

    %% Connections: Initialization and interactions
    Boot -->|"init"| Arch
    Arch -->|"initSubsystems"| acpi
    Arch -->|"initSubsystems"| allocator
    Arch -->|"setup"| context
    Arch -->|"setup"| syscall
    Arch -->|"initDevices"| devices

    %% Cross interactions between subsystems
    acpi ---|"configures"| memory
    allocator ---|"supports"| context
    syscall ---|"invokes"| devices
    syscall ---|"interacts"| context

    %% Interrupts signal process management
    A_aarch64_int ---|"signals"| context
    A_riscv64_int ---|"signals"| context
    A_x86_int ---|"signals"| context
    A_x86_64_int ---|"signals"| context
    A_shared_int ---|"signals"| context

    %% Click Events for Component Mapping
    click Boot "https://github.com/redox-os/kernel/tree/master/src/asm"
    click Boot "https://github.com/redox-os/kernel/tree/master/src/startup"
    click Arch "https://github.com/redox-os/kernel/tree/master/src/arch"
    click A_aarch64 "https://github.com/redox-os/kernel/tree/master/src/arch/aarch64"
    click A_riscv64 "https://github.com/redox-os/kernel/tree/master/src/arch/riscv64"
    click A_x86 "https://github.com/redox-os/kernel/tree/master/src/arch/x86"
    click A_x86_64 "https://github.com/redox-os/kernel/tree/master/src/arch/x86_64"
    click A_shared "https://github.com/redox-os/kernel/tree/master/src/arch/x86_shared"
    click acpi "https://github.com/redox-os/kernel/tree/master/src/acpi"
    click dtb "https://github.com/redox-os/kernel/tree/master/src/dtb"
    click allocator "https://github.com/redox-os/kernel/tree/master/src/allocator"
    click memory "https://github.com/redox-os/kernel/tree/master/src/memory"
    click slab "https://github.com/redox-os/kernel/tree/master/slab_allocator"
    click context "https://github.com/redox-os/kernel/tree/master/src/context"
    click syscall "https://github.com/redox-os/kernel/tree/master/src/syscall"
    click scheme "https://github.com/redox-os/kernel/tree/master/src/scheme"
    click devices "https://github.com/redox-os/kernel/tree/master/src/devices"
    click A_aarch64_int "https://github.com/redox-os/kernel/tree/master/src/arch/aarch64/interrupt"
    click A_riscv64_int "https://github.com/redox-os/kernel/tree/master/src/arch/riscv64/interrupt"
    click A_x86_int "https://github.com/redox-os/kernel/tree/master/src/arch/x86/interrupt"
    click A_x86_64_int "https://github.com/redox-os/kernel/tree/master/src/arch/x86_64/interrupt"
    click A_shared_int "https://github.com/redox-os/kernel/tree/master/src/arch/x86_shared/interrupt"

    %% Styling Classes
    classDef startup fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef arch fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef arch_sub fill:#FFE4B5,stroke:#000,stroke-width:2px;
    classDef acpi fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef memory fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef context fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef syscall fill:#DA70D6,stroke:#000,stroke-width:2px;
    classDef devices fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef interrupt fill:#FF6347,stroke:#000,stroke-width:2px;
```
