# nguyentrongphuc552003/kdal architecture

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

- Interactive diagram: https://gitdiagram.com/nguyentrongphuc552003/kdal
- Repository: https://github.com/nguyentrongphuc552003/kdal

## Overview

KDAL is both a Linux-kernel device abstraction runtime and a DSL/tooling ecosystem. The runtime workflow takes userspace requests through `/dev/kdal` into control dispatch and core device services, with pluggable hardware backends; debugfs exposes introspection. The language workflow compiles device descriptions into kernel C, while `kdality` also provides linting, simulation, Device Tree generation, and test generation, with a VS Code front end. Runtime links follow the README’s architecture description; compiler-stage links follow its documented pipeline. Some CLI and kernel implementation wiring is unsampled, so it is not expanded beyond documented behavior.

Main entry points: [`tools/kdality/main.c`](https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/main.c) (Unified CLI), [`src/core/kdal.c`](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/kdal.c) (Core Lifecycle), [`src/backends/qemu/qemubackend.c`](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/qemu/qemubackend.c) (QEMU Backend), [`editor/vscode/kdal-lang/src/commands.ts`](https://github.com/nguyentrongphuc552003/kdal/blob/main/editor/vscode/kdal-lang/src/commands.ts) (Editor Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Kernel Control Plane"]
  node_chardev["Control Device<br/>[chardev.c]"]
  node_debugfs["Debugfs Interface<br/>[debugfs.c]"]
end

subgraph group_runtime["Core Runtime"]
  node_core["Core Lifecycle<br/>[kdal.c]"]
  node_registry["Device Registry<br/>[registry.c]"]
  node_events["Event System<br/>[event.c]"]
  node_power["Power Management<br/>[power.c]"]
  node_demand["Device Demand<br/>[demand.c]"]
end

subgraph group_backend["Hardware Backends"]
  node_generic["Generic Platform<br/>[platdev.c]"]
  node_devicetree["Device Tree Backend<br/>[devicetree.c]"]
  node_socglue["SoC Glue<br/>[socglue.c]"]
  node_qemu["QEMU Backend<br/>[qemubackend.c]"]
  node_virtioio["Virtio I/O<br/>[virtioio.c]"]
  node_virtioaccel["Virtio Accelerator<br/>[virtioaccel.c]"]
end

subgraph group_language["DSL Toolchain"]
  node_kdality["Unified CLI<br/>[main.c]"]
  node_compile["Compile Frontend<br/>[compile.c]"]
  node_lexer["Lexer<br/>[lexer.c]"]
  node_parser["Parser<br/>[parser.c]"]
  node_sema["Semantic Analysis<br/>[sema.c]"]
  node_codegen["Kernel Codegen<br/>[codegen.c]"]
  node_lint["DSL Linter<br/>[lint.c]"]
  node_simulate["Simulator<br/>[simulate.c]"]
  node_dtgen["DT Generator<br/>[dtgen.c]"]
  node_testgen["Test Generator<br/>[testgen.c]"]
end

subgraph group_editor["Editor Integration"]
  node_vscode["VS Code Extension<br/>[extension.ts]"]
  node_commands["Editor Commands<br/>[commands.ts]"]
  node_toolchain["Toolchain Locator<br/>[toolchain.ts]"]
end

node_users(("Userspace Clients"))
node_dsluser(("DSL Author"))
node_kernel(("Linux Kernel"))
node_hardware(("Hardware"))

node_users -->|"issues ioctls"| node_chardev
node_chardev -->|"dispatches control"| node_core
node_users -->|"inspects state"| node_debugfs
node_core -->|"manages devices"| node_registry
node_core -->|"supports events"| node_events
node_core -->|"manages power"| node_power
node_core -.->|"coordinates demand"| node_demand
node_kernel -->|"hosts backend"| node_generic
node_kernel -->|"uses backend"| node_devicetree
node_generic -.->|"uses platform glue"| node_socglue
node_kernel -->|"hosts backend"| node_qemu
node_qemu -.->|"uses virtio I/O"| node_virtioio
node_qemu -->|"uses accelerator ops"| node_virtioaccel
node_dsluser -->|"runs commands"| node_kdality
node_kdality -->|"dispatches compile"| node_compile
node_compile -->|"starts compilation"| node_lexer
node_lexer -->|"produces tokens"| node_parser
node_parser -->|"produces AST"| node_sema
node_sema -->|"validates AST"| node_codegen
node_codegen -->|"generates kernel C"| node_kernel
node_kdality -->|"dispatches lint"| node_lint
node_kdality -->|"dispatches simulate"| node_simulate
node_kdality -->|"dispatches DT generation"| node_dtgen
node_kdality -->|"dispatches test generation"| node_testgen
node_vscode -->|"registers commands"| node_commands
node_vscode -->|"locates tools"| node_toolchain
node_commands -->|"runs tools"| node_toolchain
node_commands -->|"invokes CLI"| node_kdality

click node_chardev "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/chardev.c"
click node_debugfs "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/debugfs.c"
click node_core "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/kdal.c"
click node_registry "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/registry.c"
click node_events "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/event.c"
click node_power "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/power.c"
click node_demand "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/demand.c"
click node_generic "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/generic/platdev.c"
click node_devicetree "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/generic/devicetree.c"
click node_socglue "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/generic/socglue.c"
click node_qemu "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/qemu/qemubackend.c"
click node_virtioio "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/qemu/virtioio.c"
click node_virtioaccel "https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/qemu/virtioaccel.c"
click node_kdality "https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/main.c"
click node_compile "https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/compile.c"
click node_lexer "https://github.com/nguyentrongphuc552003/kdal/blob/main/compiler/lexer.c"
click node_parser "https://github.com/nguyentrongphuc552003/kdal/blob/main/compiler/parser.c"
click node_sema "https://github.com/nguyentrongphuc552003/kdal/blob/main/compiler/sema.c"
click node_codegen "https://github.com/nguyentrongphuc552003/kdal/blob/main/compiler/codegen.c"
click node_lint "https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/lint.c"
click node_simulate "https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/simulate.c"
click node_dtgen "https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/dtgen.c"
click node_testgen "https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/testgen.c"
click node_vscode "https://github.com/nguyentrongphuc552003/kdal/blob/main/editor/vscode/kdal-lang/src/extension.ts"
click node_commands "https://github.com/nguyentrongphuc552003/kdal/blob/main/editor/vscode/kdal-lang/src/commands.ts"
click node_toolchain "https://github.com/nguyentrongphuc552003/kdal/blob/main/editor/vscode/kdal-lang/src/toolchain.ts"

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_chardev,node_debugfs,node_users toneBlue
class node_core,node_registry,node_events,node_power,node_demand toneAmber
class node_generic,node_devicetree,node_socglue,node_qemu,node_virtioio,node_virtioaccel toneMint
class node_kdality,node_compile,node_lexer,node_parser,node_sema,node_codegen,node_lint,node_simulate,node_dtgen,node_testgen toneRose
class node_vscode,node_commands,node_toolchain,node_dsluser,node_kernel,node_hardware toneIndigo
```

## Components

### Kernel Control Plane

- [Control Device](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/chardev.c): `src/core/chardev.c`
- [Debugfs Interface](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/debugfs.c): `src/core/debugfs.c`

### Core Runtime

- [Core Lifecycle](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/kdal.c): `src/core/kdal.c`
- [Device Registry](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/registry.c): `src/core/registry.c`
- [Event System](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/event.c): `src/core/event.c`
- [Power Management](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/power.c): `src/core/power.c`
- [Device Demand](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/core/demand.c): `src/core/demand.c`

### Hardware Backends

- [Generic Platform](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/generic/platdev.c): `src/backends/generic/platdev.c`
- [Device Tree Backend](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/generic/devicetree.c): `src/backends/generic/devicetree.c`
- [SoC Glue](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/generic/socglue.c): `src/backends/generic/socglue.c`
- [QEMU Backend](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/qemu/qemubackend.c): `src/backends/qemu/qemubackend.c`
- [Virtio I/O](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/qemu/virtioio.c): `src/backends/qemu/virtioio.c`
- [Virtio Accelerator](https://github.com/nguyentrongphuc552003/kdal/blob/main/src/backends/qemu/virtioaccel.c): `src/backends/qemu/virtioaccel.c`

### DSL Toolchain

- [Unified CLI](https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/main.c): `tools/kdality/main.c`
- [Compile Frontend](https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/compile.c): `tools/kdality/compile.c`
- [Lexer](https://github.com/nguyentrongphuc552003/kdal/blob/main/compiler/lexer.c): `compiler/lexer.c`
- [Parser](https://github.com/nguyentrongphuc552003/kdal/blob/main/compiler/parser.c): `compiler/parser.c`
- [Semantic Analysis](https://github.com/nguyentrongphuc552003/kdal/blob/main/compiler/sema.c): `compiler/sema.c`
- [Kernel Codegen](https://github.com/nguyentrongphuc552003/kdal/blob/main/compiler/codegen.c): `compiler/codegen.c`
- [DSL Linter](https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/lint.c): `tools/kdality/lint.c`
- [Simulator](https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/simulate.c): `tools/kdality/simulate.c`
- [DT Generator](https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/dtgen.c): `tools/kdality/dtgen.c`
- [Test Generator](https://github.com/nguyentrongphuc552003/kdal/blob/main/tools/kdality/testgen.c): `tools/kdality/testgen.c`

### Editor Integration

- [VS Code Extension](https://github.com/nguyentrongphuc552003/kdal/blob/main/editor/vscode/kdal-lang/src/extension.ts): `editor/vscode/kdal-lang/src/extension.ts`
- [Editor Commands](https://github.com/nguyentrongphuc552003/kdal/blob/main/editor/vscode/kdal-lang/src/commands.ts): `editor/vscode/kdal-lang/src/commands.ts`
- [Toolchain Locator](https://github.com/nguyentrongphuc552003/kdal/blob/main/editor/vscode/kdal-lang/src/toolchain.ts): `editor/vscode/kdal-lang/src/toolchain.ts`

### Other components

- **Userspace Clients**
- **DSL Author**
- **Linux Kernel**
- **Hardware**

## Connections

- Userspace Clients → Control Device: issues ioctls
- Control Device → Core Lifecycle: dispatches control
- Userspace Clients → Debugfs Interface: inspects state
- Core Lifecycle → Device Registry: manages devices
- Core Lifecycle → Event System: supports events
- Core Lifecycle → Power Management: manages power
- Core Lifecycle → Device Demand: coordinates demand
- Linux Kernel → Generic Platform: hosts backend
- Linux Kernel → Device Tree Backend: uses backend
- Generic Platform → SoC Glue: uses platform glue
- Linux Kernel → QEMU Backend: hosts backend
- QEMU Backend → Virtio I/O: uses virtio I/O
- QEMU Backend → Virtio Accelerator: uses accelerator ops
- DSL Author → Unified CLI: runs commands
- Unified CLI → Compile Frontend: dispatches compile
- Compile Frontend → Lexer: starts compilation
- Lexer → Parser: produces tokens
- Parser → Semantic Analysis: produces AST
- Semantic Analysis → Kernel Codegen: validates AST
- Kernel Codegen → Linux Kernel: generates kernel C (evidence: `compiler/codegen.c`)
- Unified CLI → DSL Linter: dispatches lint
- Unified CLI → Simulator: dispatches simulate
- Unified CLI → DT Generator: dispatches DT generation
- Unified CLI → Test Generator: dispatches test generation
- VS Code Extension → Editor Commands: registers commands (evidence: `editor/vscode/kdal-lang/src/extension.ts`)
- VS Code Extension → Toolchain Locator: locates tools (evidence: `editor/vscode/kdal-lang/src/extension.ts`)
- Editor Commands → Toolchain Locator: runs tools (evidence: `editor/vscode/kdal-lang/src/commands.ts`)
- Editor Commands → Unified CLI: invokes CLI (evidence: `editor/vscode/kdal-lang/src/commands.ts`)