# hawkw/mycelium architecture

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

- Interactive diagram: https://gitdiagram.com/hawkw/mycelium
- Repository: https://github.com/hawkw/mycelium

## Overview

##### Main Components

a. Kernel Core (Central Component)
- WebAssembly Runtime (/src/wasm/)
- WASI Implementation (/src/wasm/wasi.rs)
- Shell Interface (/src/shell.rs)
- Runtime Services (/src/rt.rs)

b. Hardware Abstraction Layer (HAL)
- HAL Core Interface (hal-core/)
- x86_64 Implementation (hal-x86_64/)
- Hardware-specific components:
- Interrupt handling
- Memory management
- CPU management
- Device drivers

c. Core Libraries
- Cordyceps (Intrusive data structures)
- Maitake (Async runtime)
- Memory Allocation (alloc/)
- Utility Layer (util/)

d. Device Drivers Layer (/src/drivers/)
- PCI
- IDE
- PS/2 Keyboard

##### Component Relationships

- HAL layer directly below the kernel core
- Core Libraries to the left side, showing their support role
- Device Drivers above the HAL layer
- WebAssembly/WASI interface at the top level

##### Specific Design Elements

Use the following visual elements:
- Rectangle blocks for major components
- Hexagons for hardware interfaces
- Rounded rectangles for libraries
- Double lines for API boundaries

##### Layer Organization

From top to bottom:

##### Important Details

- Async Runtime Flow: Show how Maitake integrates with the kernel
- Memory Management: Illustrate the buddy allocator's position
- Interrupt Handling: Show the flow from hardware through HAL to kernel
- Driver Interface: Demonstrate PCI and device management
- WebAssembly Integration: Show module execution flow

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef kernel fill:#a8d1f0,stroke:#333
    classDef hal fill:#90EE90,stroke:#333
    classDef driver fill:#FFE4B5,stroke:#333
    classDef library fill:#DDA0DD,stroke:#333
    classDef wasm fill:#FFA07A,stroke:#333
    classDef hardware fill:#D3D3D3,stroke:#333
    
    %% User Space Layer
    subgraph UserSpace
        WASM[WebAssembly Modules]:::wasm
        WASI["WASI Interface"]:::wasm
    end

    %% Kernel Core Layer
    subgraph KernelCore
        Runtime["WebAssembly Runtime"]:::kernel
        Shell["Shell Interface"]:::kernel
        RTServices["Runtime Services"]:::kernel
    end

    %% Core Libraries
    subgraph CoreLibs
        Cordyceps["Cordyceps Data Structures"]:::library
        Maitake["Maitake Async Runtime"]:::library
        MemAlloc["Memory Allocator"]:::library
        Utils["Utility Layer"]:::library
    end

    %% Device Drivers
    subgraph Drivers
        PCI["PCI Driver"]:::driver
        IDE["IDE Driver"]:::driver
        PS2["PS/2 Keyboard Driver"]:::driver
    end

    %% HAL Layer
    subgraph HAL
        HALCore["HAL Core Interface"]:::hal
        X86HAL["x86_64 HAL Implementation"]:::hal
        IntHandler["Interrupt Handling"]:::hal
        MemMgmt["Memory Management"]:::hal
        CPUMgmt["CPU Management"]:::hal
    end

    %% Hardware Layer
    subgraph Hardware
        CPU["CPU"]:::hardware
        Memory["Physical Memory"]:::hardware
        Devices["Hardware Devices"]:::hardware
    end

    %% Testing and Build
    TestInfra["Testing Infrastructure"]:::library
    BuildTools["Build Tools"]:::library

    %% Relationships
    WASM --> WASI
    WASI --> Runtime
    Runtime --> RTServices
    RTServices --> Shell
    
    Cordyceps --> KernelCore
    Maitake --> KernelCore
    MemAlloc --> KernelCore
    Utils --> KernelCore
    
    KernelCore --> HALCore
    HALCore --> X86HAL
    X86HAL --> IntHandler
    X86HAL --> MemMgmt
    X86HAL --> CPUMgmt
    
    Drivers --> HALCore
    
    IntHandler --> CPU
    MemMgmt --> Memory
    Drivers --> Devices
    
    TestInfra -.-> KernelCore
    BuildTools -.-> KernelCore

    %% Click Events
    click Runtime "https://github.com/hawkw/mycelium/tree/main/src/wasm/"
    click WASI "https://github.com/hawkw/mycelium/blob/main/src/wasm/wasi.rs"
    click Shell "https://github.com/hawkw/mycelium/blob/main/src/shell.rs"
    click RTServices "https://github.com/hawkw/mycelium/blob/main/src/rt.rs"
    click HALCore "https://github.com/hawkw/mycelium/tree/main/hal-core/"
    click X86HAL "https://github.com/hawkw/mycelium/tree/main/hal-x86_64/"
    click MemAlloc "https://github.com/hawkw/mycelium/tree/main/alloc/"
    click Cordyceps "https://github.com/hawkw/mycelium/tree/main/cordyceps/"
    click Maitake "https://github.com/hawkw/mycelium/tree/main/maitake/"
    click Utils "https://github.com/hawkw/mycelium/tree/main/util/"
    click PCI "https://github.com/hawkw/mycelium/blob/main/src/drivers/pci.rs"
    click IDE "https://github.com/hawkw/mycelium/blob/main/src/drivers/ide.rs"
    click PS2 "https://github.com/hawkw/mycelium/blob/main/src/drivers/ps2_keyboard.rs"
    click IntHandler "https://github.com/hawkw/mycelium/tree/main/hal-x86_64/src/interrupt/"
    click MemMgmt "https://github.com/hawkw/mycelium/blob/main/hal-x86_64/src/mm.rs"
    click CPUMgmt "https://github.com/hawkw/mycelium/tree/main/hal-x86_64/src/cpu/"
    click TestInfra "https://github.com/hawkw/mycelium/tree/main/mycotest/"
    click BuildTools "https://github.com/hawkw/mycelium/tree/main/inoculate/"
```
