# abdelhalimyasser/lettuceos architecture

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

- Interactive diagram: https://gitdiagram.com/abdelhalimyasser/lettuceos
- Repository: https://github.com/abdelhalimyasser/lettuceos

## Overview

Lettuce is a research ARM64 microkernel. Its principal workflow is an EL0 service making a mediated call: the supervisor validates the caller’s capability and target, dispatches the operation, and switches protection context for execution. The graph also preserves the documented scheduling, POSIX-lite, memory-sharing, and Rust-runtime branches. Some subsystem links are based on README descriptions because their implementation files were not excerpted.

Main entry points: [`ipc/cross_layer/call.c`](https://github.com/abdelhalimyasser/lettuceos/blob/main/ipc/cross_layer/call.c) (Cross-Layer Gate), [`kernel/scheduler/scheduler.c`](https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/scheduler/scheduler.c) (Scheduler Mechanism), [`kernel/main/capability.c`](https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/main/capability.c) (Capability Table), [`ipc/same_layer/gate.c`](https://github.com/abdelhalimyasser/lettuceos/blob/main/ipc/same_layer/gate.c) (Same-Layer Gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ipc["Mediated IPC"]
  node_same_layer["Same-Layer Gate<br/>[gate.c]"]
  node_cross_layer["Cross-Layer Gate<br/>[call.c]"]
  node_elevator["Elevator Gate<br/>[elevator.c]"]
end

subgraph group_kernel["Supervisor Kernel"]
  node_capabilities[("Capability Table<br/>[capability.c]")]
  node_dispatch["Service Dispatch<br/>[dispatch.c]"]
  node_context["Execution Context<br/>[context.c]"]
  node_protection["Domain Protection<br/>[protection.c]"]
end

subgraph group_arm64["ARM64 Platform"]
  node_mmu["MMU and ASIDs<br/>[mmu.c]"]
  node_pac["Pointer Authentication<br/>[cpu.c]"]
  node_arm_init["Platform Initialization<br/>[main.c]"]
end

subgraph group_runtime["User Runtimes"]
  node_c_calls["C Call Wrappers<br/>[same_layer_call.c]"]
  node_rust_sdk["Rust SDK<br/>[service.rs]"]
  node_posix["POSIX-lite<br/>[posix.c]"]
end

subgraph group_resources["Memory and Scheduling"]
  node_shared_memory["Shared Buffers<br/>[buffer.c]"]
  node_allocator["Fixed Allocator<br/>[fixed.c]"]
  node_scheduler["Scheduler Mechanism<br/>[scheduler.c]"]
  node_rr["Round-Robin Policy<br/>[rr.c]"]
  node_eevdf["EEVDF Policy<br/>[eevdf.c]"]
end

node_service(("EL0 Service"))
node_hardware{{"ARM64 Hardware"}}

node_service -.->|"invokes"| node_c_calls
node_rust_sdk -->|"calls ABI"| node_c_calls
node_c_calls -.->|"requests call"| node_same_layer
node_service -.->|"requests call"| node_cross_layer
node_service -.->|"requests call"| node_elevator
node_same_layer -->|"checks rights"| node_capabilities
node_cross_layer -->|"checks rights"| node_capabilities
node_elevator -->|"authorizes first"| node_capabilities
node_same_layer -.->|"dispatches target"| node_dispatch
node_cross_layer -.->|"dispatches target"| node_dispatch
node_elevator -.->|"dispatches target"| node_dispatch
node_cross_layer -->|"preserves continuation"| node_context
node_context -->|"enters domain"| node_protection
node_protection -.->|"switches domain"| node_mmu
node_mmu -->|"configures translation"| node_hardware
node_pac -->|"signs continuations"| node_hardware
node_posix -->|"issues syscalls"| node_service
node_service -.->|"shares buffers"| node_shared_memory
node_shared_memory -->|"checks access"| node_capabilities
node_allocator -.->|"allocates memory"| node_hardware
node_arm_init -->|"initializes platform"| node_hardware
node_arm_init -->|"starts scheduling"| node_scheduler
node_scheduler -->|"selects policy"| node_rr
node_scheduler -->|"selects policy"| node_eevdf
node_scheduler -->|"enters task domain"| node_mmu

click node_c_calls "https://github.com/abdelhalimyasser/lettuceos/blob/main/runtime/c/same_layer_call.c"
click node_rust_sdk "https://github.com/abdelhalimyasser/lettuceos/blob/main/runtime/rust/src/service.rs"
click node_posix "https://github.com/abdelhalimyasser/lettuceos/blob/main/runtime/posix/src/posix.c"
click node_same_layer "https://github.com/abdelhalimyasser/lettuceos/blob/main/ipc/same_layer/gate.c"
click node_cross_layer "https://github.com/abdelhalimyasser/lettuceos/blob/main/ipc/cross_layer/call.c"
click node_elevator "https://github.com/abdelhalimyasser/lettuceos/blob/main/ipc/elevator/elevator.c"
click node_capabilities "https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/main/capability.c"
click node_dispatch "https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/main/dispatch.c"
click node_context "https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/main/context.c"
click node_protection "https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/main/protection.c"
click node_mmu "https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/arch/arm64/mmu.c"
click node_pac "https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/arch/arm64/cpu.c"
click node_shared_memory "https://github.com/abdelhalimyasser/lettuceos/blob/main/memory/shared/buffer.c"
click node_allocator "https://github.com/abdelhalimyasser/lettuceos/blob/main/memory/allocator/fixed.c"
click node_scheduler "https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/scheduler/scheduler.c"
click node_rr "https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/scheduler/rr.c"
click node_eevdf "https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/scheduler/eevdf.c"
click node_arm_init "https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/arch/arm64/main.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_same_layer,node_cross_layer,node_elevator toneBlue
class node_capabilities,node_dispatch,node_context,node_protection toneAmber
class node_mmu,node_pac,node_arm_init toneMint
class node_c_calls,node_rust_sdk,node_posix toneRose
class node_shared_memory,node_allocator,node_scheduler,node_rr,node_eevdf,node_service,node_hardware toneIndigo
```

## Components

### Mediated IPC

- [Same-Layer Gate](https://github.com/abdelhalimyasser/lettuceos/blob/main/ipc/same_layer/gate.c): `ipc/same_layer/gate.c`
- [Cross-Layer Gate](https://github.com/abdelhalimyasser/lettuceos/blob/main/ipc/cross_layer/call.c): `ipc/cross_layer/call.c`
- [Elevator Gate](https://github.com/abdelhalimyasser/lettuceos/blob/main/ipc/elevator/elevator.c): `ipc/elevator/elevator.c`

### Supervisor Kernel

- [Capability Table](https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/main/capability.c): `kernel/main/capability.c`
- [Service Dispatch](https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/main/dispatch.c): `kernel/main/dispatch.c`
- [Execution Context](https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/main/context.c): `kernel/main/context.c`
- [Domain Protection](https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/main/protection.c): `kernel/main/protection.c`

### ARM64 Platform

- [MMU and ASIDs](https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/arch/arm64/mmu.c): `kernel/arch/arm64/mmu.c`
- [Pointer Authentication](https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/arch/arm64/cpu.c): `kernel/arch/arm64/cpu.c`
- [Platform Initialization](https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/arch/arm64/main.c): `kernel/arch/arm64/main.c`

### User Runtimes

- [C Call Wrappers](https://github.com/abdelhalimyasser/lettuceos/blob/main/runtime/c/same_layer_call.c): `runtime/c/same_layer_call.c`
- [Rust SDK](https://github.com/abdelhalimyasser/lettuceos/blob/main/runtime/rust/src/service.rs): `runtime/rust/src/service.rs`
- [POSIX-lite](https://github.com/abdelhalimyasser/lettuceos/blob/main/runtime/posix/src/posix.c): `runtime/posix/src/posix.c`

### Memory and Scheduling

- [Shared Buffers](https://github.com/abdelhalimyasser/lettuceos/blob/main/memory/shared/buffer.c): `memory/shared/buffer.c`
- [Fixed Allocator](https://github.com/abdelhalimyasser/lettuceos/blob/main/memory/allocator/fixed.c): `memory/allocator/fixed.c`
- [Scheduler Mechanism](https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/scheduler/scheduler.c): `kernel/scheduler/scheduler.c`
- [Round-Robin Policy](https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/scheduler/rr.c): `kernel/scheduler/rr.c`
- [EEVDF Policy](https://github.com/abdelhalimyasser/lettuceos/blob/main/kernel/scheduler/eevdf.c): `kernel/scheduler/eevdf.c`

### Other components

- **EL0 Service**
- **ARM64 Hardware**

## Connections

- EL0 Service → C Call Wrappers: invokes
- Rust SDK → C Call Wrappers: calls ABI (evidence: `runtime/rust/src/service.rs`)
- C Call Wrappers → Same-Layer Gate: requests call
- EL0 Service → Cross-Layer Gate: requests call
- EL0 Service → Elevator Gate: requests call
- Same-Layer Gate → Capability Table: checks rights
- Cross-Layer Gate → Capability Table: checks rights (evidence: `ipc/cross_layer/call.c`)
- Elevator Gate → Capability Table: authorizes first
- Same-Layer Gate → Service Dispatch: dispatches target
- Cross-Layer Gate → Service Dispatch: dispatches target
- Elevator Gate → Service Dispatch: dispatches target
- Cross-Layer Gate → Execution Context: preserves continuation
- Execution Context → Domain Protection: enters domain (evidence: `kernel/main/context.c`)
- Domain Protection → MMU and ASIDs: switches domain
- MMU and ASIDs → ARM64 Hardware: configures translation
- Pointer Authentication → ARM64 Hardware: signs continuations
- POSIX-lite → EL0 Service: issues syscalls
- EL0 Service → Shared Buffers: shares buffers
- Shared Buffers → Capability Table: checks access (evidence: `memory/shared/buffer.c`)
- Fixed Allocator → ARM64 Hardware: allocates memory
- Platform Initialization → ARM64 Hardware: initializes platform
- Platform Initialization → Scheduler Mechanism: starts scheduling (evidence: `kernel/arch/arm64/main.c`)
- Scheduler Mechanism → Round-Robin Policy: selects policy (evidence: `kernel/scheduler/scheduler.c`)
- Scheduler Mechanism → EEVDF Policy: selects policy (evidence: `kernel/scheduler/scheduler.c`)
- Scheduler Mechanism → MMU and ASIDs: enters task domain (evidence: `kernel/scheduler/scheduler.c`)
