# arty3/lg-npu architecture

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

- Interactive diagram: https://gitdiagram.com/arty3/lg-npu
- Repository: https://github.com/arty3/lg-npu

## Overview

LG-NPU is an experimental INT8 neural-network inference accelerator, spanning host software and a modular hardware design. Its user-to-result workflow is to describe tensors and an operation, build a command descriptor, submit it through the device interface, and have the NPU execute it using shared memory and compute blocks. The README documents six kernels and the hardware/software split; the sampled excerpts do not show the RTL top-level wiring, so hardware execution links are marked unverified rather than inferred as direct calls.

Main entry points: [`rtl/core/npu_scheduler.sv`](https://github.com/arty3/lg-npu/blob/main/rtl/core/npu_scheduler.sv) (Execution scheduler), [`sw/driver/npu_drv.c`](https://github.com/arty3/lg-npu/blob/main/sw/driver/npu_drv.c) (Driver core), [`rtl/core/npu_shell.sv`](https://github.com/arty3/lg-npu/blob/main/rtl/core/npu_shell.sv) (NPU shell), [`rtl/memory/npu_mem_top.sv`](https://github.com/arty3/lg-npu/blob/main/rtl/memory/npu_mem_top.sv) (Memory subsystem)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host software"]
  node_tensor_api["Tensor descriptors<br/>[lgnpu_tensor.h]"]
  node_tensor_convert["Tensor conversion<br/>[tensor_desc.c]"]
  node_command_api["Command API<br/>[lgnpu_cmd.h]"]
  node_command_builder["Command builder<br/>[command_builder.c]"]
  node_runtime_api["Runtime API<br/>[liblgnpu.c]"]
  node_runtime_submit["Runtime submit<br/>[submit.c]"]
  node_runtime_mmio["Runtime MMIO<br/>[mmio_helpers.h]"]
  node_ioctl_api["Device API<br/>[lgnpu_ioctl.h]"]
  node_uapi_registers["Register contract<br/>[lgnpu_regs.h]"]
  node_shared_annotations["Shared annotations<br/>[annotations.h]"]
end

subgraph group_device["Device control"]
  node_driver_core["Driver core<br/>[npu_drv.c]"]
  node_driver_state["Driver state<br/>[lgnpu_drv.h]"]
  node_driver_mmio["Driver MMIO<br/>[npu_mmio.h]"]
  node_driver_queue["Command queue<br/>[npu_queue.c]"]
  node_driver_dma["Driver DMA<br/>[npu_dma.c]"]
  node_shell["NPU shell<br/>[npu_shell.sv]"]
  node_control["Command control<br/>[npu_cmd_fetch.sv]"]
  node_dispatch["Operation dispatch<br/>[npu_dispatch.sv]"]
  node_scheduler["Execution scheduler<br/>[npu_scheduler.sv]"]
  node_irq_perf["IRQ and counters<br/>[npu_irq_ctrl.sv]"]
end

subgraph group_compute["Compute engines"]
  node_conv["Convolution engine<br/>[conv_backend.sv]"]
  node_gemm["GEMM engine<br/>[gemm_backend.sv]"]
  node_vector["Vector engine<br/>[vec_backend.sv]"]
  node_softmax["Softmax composite"]
  node_lnorm["Layer norm composite<br/>[lnorm_composite.sv]"]
  node_pool["Pooling composite<br/>[pool_composite.sv]"]
  node_activation["Activation<br/>[activation.sv]"]
  node_postproc["Post-processing<br/>[postproc.sv]"]
end

subgraph group_memory["Memory and movement"]
  node_memory_top["Memory subsystem<br/>[npu_mem_top.sv]"]
  node_buffer_router["Buffer router"]
  node_dma_frontend["DMA frontend"]
  node_local_memory[("Local memories<br/>[npu_scratchpad.sv]")]
end

subgraph group_support["Platform support"]
  node_platform_memory["Memory wrappers<br/>[mem_macro_wrap.sv]"]
end

node_application(("Host application"))

node_application -.->|"describes tensors"| node_tensor_api
node_application -.->|"builds commands"| node_command_builder
node_tensor_api -->|"converts layouts"| node_tensor_convert
node_command_builder -->|"packs descriptors"| node_command_api
node_runtime_api -->|"uses helpers"| node_runtime_mmio
node_runtime_submit -->|"uses helpers"| node_runtime_mmio
node_runtime_submit -->|"uses contract"| node_ioctl_api
node_application -.->|"uses runtime"| node_runtime_api
node_runtime_api -.->|"submits to device"| node_driver_core
node_ioctl_api -.->|"defines operations"| node_driver_core
node_driver_core -->|"uses device state"| node_driver_state
node_driver_core -->|"submits commands"| node_driver_queue
node_driver_core -->|"starts transfers"| node_driver_dma
node_driver_mmio -->|"accesses registers"| node_driver_state
node_driver_core -.->|"controls accelerator"| node_shell
node_shell -.->|"routes commands"| node_control
node_control -.->|"dispatches operations"| node_dispatch
node_dispatch -.->|"schedules execution"| node_scheduler
node_scheduler -.->|"selects backend"| node_conv
node_scheduler -.->|"selects backend"| node_gemm
node_scheduler -.->|"selects backend"| node_vector
node_scheduler -.->|"selects composite"| node_softmax
node_scheduler -.->|"selects composite"| node_lnorm
node_scheduler -.->|"selects composite"| node_pool
node_conv -.->|"applies activation"| node_activation
node_conv -.->|"uses post-processing"| node_postproc
node_gemm -.->|"uses post-processing"| node_postproc
node_shell -.->|"uses shared memory"| node_memory_top
node_memory_top -.->|"routes accesses"| node_buffer_router
node_memory_top -.->|"accesses local SRAM"| node_local_memory
node_dma_frontend -.->|"moves data"| node_memory_top
node_driver_dma -.->|"requests transfers"| node_dma_frontend
node_local_memory -.->|"uses memory wrappers"| node_platform_memory
node_shell -.->|"reports completion and metrics"| node_irq_perf
node_driver_core -->|"uses register contract"| node_uapi_registers
node_command_api -->|"uses register definitions"| node_uapi_registers
node_command_api -->|"uses annotations"| node_shared_annotations
node_tensor_api -->|"uses annotations"| node_shared_annotations

click node_tensor_api "https://github.com/arty3/lg-npu/blob/main/sw/uapi/lgnpu_tensor.h"
click node_tensor_convert "https://github.com/arty3/lg-npu/blob/main/sw/runtime/tensor_desc.c"
click node_command_api "https://github.com/arty3/lg-npu/blob/main/sw/uapi/lgnpu_cmd.h"
click node_command_builder "https://github.com/arty3/lg-npu/blob/main/sw/runtime/command_builder.c"
click node_runtime_api "https://github.com/arty3/lg-npu/blob/main/sw/runtime/liblgnpu.c"
click node_runtime_submit "https://github.com/arty3/lg-npu/blob/main/sw/runtime/submit.c"
click node_runtime_mmio "https://github.com/arty3/lg-npu/blob/main/sw/runtime/mmio_helpers.h"
click node_ioctl_api "https://github.com/arty3/lg-npu/blob/main/sw/uapi/lgnpu_ioctl.h"
click node_driver_core "https://github.com/arty3/lg-npu/blob/main/sw/driver/npu_drv.c"
click node_driver_state "https://github.com/arty3/lg-npu/blob/main/sw/driver/lgnpu_drv.h"
click node_driver_mmio "https://github.com/arty3/lg-npu/blob/main/sw/driver/npu_mmio.h"
click node_driver_queue "https://github.com/arty3/lg-npu/blob/main/sw/driver/npu_queue.c"
click node_driver_dma "https://github.com/arty3/lg-npu/blob/main/sw/driver/npu_dma.c"
click node_shell "https://github.com/arty3/lg-npu/blob/main/rtl/core/npu_shell.sv"
click node_control "https://github.com/arty3/lg-npu/blob/main/rtl/control/npu_cmd_fetch.sv"
click node_dispatch "https://github.com/arty3/lg-npu/blob/main/rtl/core/npu_dispatch.sv"
click node_scheduler "https://github.com/arty3/lg-npu/blob/main/rtl/core/npu_scheduler.sv"
click node_conv "https://github.com/arty3/lg-npu/blob/main/rtl/backends/conv/conv_backend.sv"
click node_gemm "https://github.com/arty3/lg-npu/blob/main/rtl/backends/gemm/gemm_backend.sv"
click node_vector "https://github.com/arty3/lg-npu/blob/main/rtl/backends/vec/vec_backend.sv"
click node_softmax "https://github.com/arty3/lg-npu/blob/main/rtl/composites/softmax/softmax_composite.sv"
click node_lnorm "https://github.com/arty3/lg-npu/blob/main/rtl/composites/lnorm/lnorm_composite.sv"
click node_pool "https://github.com/arty3/lg-npu/blob/main/rtl/composites/pooling/pool_composite.sv"
click node_activation "https://github.com/arty3/lg-npu/blob/main/rtl/ops/activation/activation.sv"
click node_postproc "https://github.com/arty3/lg-npu/blob/main/rtl/ops/postproc/postproc.sv"
click node_memory_top "https://github.com/arty3/lg-npu/blob/main/rtl/memory/npu_mem_top.sv"
click node_buffer_router "https://github.com/arty3/lg-npu/blob/main/rtl/memory/npu_buffer_router.sv"
click node_dma_frontend "https://github.com/arty3/lg-npu/blob/main/rtl/memory/npu_dma_frontend.sv"
click node_local_memory "https://github.com/arty3/lg-npu/blob/main/rtl/memory/npu_scratchpad.sv"
click node_irq_perf "https://github.com/arty3/lg-npu/blob/main/rtl/control/npu_irq_ctrl.sv"
click node_platform_memory "https://github.com/arty3/lg-npu/blob/main/rtl/platform/mem_macro_wrap.sv"
click node_uapi_registers "https://github.com/arty3/lg-npu/blob/main/sw/uapi/lgnpu_regs.h"
click node_shared_annotations "https://github.com/arty3/lg-npu/blob/main/sw/shared/annotations.h"

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_tensor_api,node_tensor_convert,node_command_api,node_command_builder,node_runtime_api,node_runtime_submit,node_runtime_mmio,node_ioctl_api,node_uapi_registers,node_shared_annotations toneBlue
class node_driver_core,node_driver_state,node_driver_mmio,node_driver_queue,node_driver_dma,node_shell,node_control,node_dispatch,node_scheduler,node_irq_perf toneAmber
class node_conv,node_gemm,node_vector,node_softmax,node_lnorm,node_pool,node_activation,node_postproc toneMint
class node_memory_top,node_buffer_router,node_dma_frontend,node_local_memory toneRose
class node_platform_memory,node_application toneIndigo
```

## Components

### Host software

- [Tensor descriptors](https://github.com/arty3/lg-npu/blob/main/sw/uapi/lgnpu_tensor.h): `sw/uapi/lgnpu_tensor.h`
- [Tensor conversion](https://github.com/arty3/lg-npu/blob/main/sw/runtime/tensor_desc.c): `sw/runtime/tensor_desc.c`
- [Command API](https://github.com/arty3/lg-npu/blob/main/sw/uapi/lgnpu_cmd.h): `sw/uapi/lgnpu_cmd.h`
- [Command builder](https://github.com/arty3/lg-npu/blob/main/sw/runtime/command_builder.c): `sw/runtime/command_builder.c`
- [Runtime API](https://github.com/arty3/lg-npu/blob/main/sw/runtime/liblgnpu.c): `sw/runtime/liblgnpu.c`
- [Runtime submit](https://github.com/arty3/lg-npu/blob/main/sw/runtime/submit.c): `sw/runtime/submit.c`
- [Runtime MMIO](https://github.com/arty3/lg-npu/blob/main/sw/runtime/mmio_helpers.h): `sw/runtime/mmio_helpers.h`
- [Device API](https://github.com/arty3/lg-npu/blob/main/sw/uapi/lgnpu_ioctl.h): `sw/uapi/lgnpu_ioctl.h`
- [Register contract](https://github.com/arty3/lg-npu/blob/main/sw/uapi/lgnpu_regs.h): `sw/uapi/lgnpu_regs.h`
- [Shared annotations](https://github.com/arty3/lg-npu/blob/main/sw/shared/annotations.h): `sw/shared/annotations.h`

### Device control

- [Driver core](https://github.com/arty3/lg-npu/blob/main/sw/driver/npu_drv.c): `sw/driver/npu_drv.c`
- [Driver state](https://github.com/arty3/lg-npu/blob/main/sw/driver/lgnpu_drv.h): `sw/driver/lgnpu_drv.h`
- [Driver MMIO](https://github.com/arty3/lg-npu/blob/main/sw/driver/npu_mmio.h): `sw/driver/npu_mmio.h`
- [Command queue](https://github.com/arty3/lg-npu/blob/main/sw/driver/npu_queue.c): `sw/driver/npu_queue.c`
- [Driver DMA](https://github.com/arty3/lg-npu/blob/main/sw/driver/npu_dma.c): `sw/driver/npu_dma.c`
- [NPU shell](https://github.com/arty3/lg-npu/blob/main/rtl/core/npu_shell.sv): `rtl/core/npu_shell.sv`
- [Command control](https://github.com/arty3/lg-npu/blob/main/rtl/control/npu_cmd_fetch.sv): `rtl/control/npu_cmd_fetch.sv`
- [Operation dispatch](https://github.com/arty3/lg-npu/blob/main/rtl/core/npu_dispatch.sv): `rtl/core/npu_dispatch.sv`
- [Execution scheduler](https://github.com/arty3/lg-npu/blob/main/rtl/core/npu_scheduler.sv): `rtl/core/npu_scheduler.sv`
- [IRQ and counters](https://github.com/arty3/lg-npu/blob/main/rtl/control/npu_irq_ctrl.sv): `rtl/control/npu_irq_ctrl.sv`

### Compute engines

- [Convolution engine](https://github.com/arty3/lg-npu/blob/main/rtl/backends/conv/conv_backend.sv): `rtl/backends/conv/conv_backend.sv`
- [GEMM engine](https://github.com/arty3/lg-npu/blob/main/rtl/backends/gemm/gemm_backend.sv): `rtl/backends/gemm/gemm_backend.sv`
- [Vector engine](https://github.com/arty3/lg-npu/blob/main/rtl/backends/vec/vec_backend.sv): `rtl/backends/vec/vec_backend.sv`
- [Softmax composite](https://github.com/arty3/lg-npu/blob/main/rtl/composites/softmax/softmax_composite.sv): `rtl/composites/softmax/softmax_composite.sv`
- [Layer norm composite](https://github.com/arty3/lg-npu/blob/main/rtl/composites/lnorm/lnorm_composite.sv): `rtl/composites/lnorm/lnorm_composite.sv`
- [Pooling composite](https://github.com/arty3/lg-npu/blob/main/rtl/composites/pooling/pool_composite.sv): `rtl/composites/pooling/pool_composite.sv`
- [Activation](https://github.com/arty3/lg-npu/blob/main/rtl/ops/activation/activation.sv): `rtl/ops/activation/activation.sv`
- [Post-processing](https://github.com/arty3/lg-npu/blob/main/rtl/ops/postproc/postproc.sv): `rtl/ops/postproc/postproc.sv`

### Memory and movement

- [Memory subsystem](https://github.com/arty3/lg-npu/blob/main/rtl/memory/npu_mem_top.sv): `rtl/memory/npu_mem_top.sv`
- [Buffer router](https://github.com/arty3/lg-npu/blob/main/rtl/memory/npu_buffer_router.sv): `rtl/memory/npu_buffer_router.sv`
- [DMA frontend](https://github.com/arty3/lg-npu/blob/main/rtl/memory/npu_dma_frontend.sv): `rtl/memory/npu_dma_frontend.sv`
- [Local memories](https://github.com/arty3/lg-npu/blob/main/rtl/memory/npu_scratchpad.sv): `rtl/memory/npu_scratchpad.sv`

### Platform support

- [Memory wrappers](https://github.com/arty3/lg-npu/blob/main/rtl/platform/mem_macro_wrap.sv): `rtl/platform/mem_macro_wrap.sv`

### Other components

- **Host application**

## Connections

- Host application → Tensor descriptors: describes tensors (evidence: `README.md`)
- Host application → Command builder: builds commands (evidence: `README.md`)
- Tensor descriptors → Tensor conversion: converts layouts (evidence: `sw/uapi/lgnpu_tensor.h`)
- Command builder → Command API: packs descriptors (evidence: `sw/runtime/command_builder.c`)
- Runtime API → Runtime MMIO: uses helpers (evidence: `sw/runtime/liblgnpu.c`)
- Runtime submit → Runtime MMIO: uses helpers (evidence: `sw/runtime/submit.c`)
- Runtime submit → Device API: uses contract (evidence: `sw/runtime/submit.c`)
- Host application → Runtime API: uses runtime (evidence: `README.md`)
- Runtime API → Driver core: submits to device (evidence: `README.md`)
- Device API → Driver core: defines operations (evidence: `README.md`)
- Driver core → Driver state: uses device state (evidence: `sw/driver/npu_drv.c`)
- Driver core → Command queue: submits commands (evidence: `sw/driver/npu_drv.c`)
- Driver core → Driver DMA: starts transfers (evidence: `sw/driver/npu_drv.c`)
- Driver MMIO → Driver state: accesses registers (evidence: `sw/driver/npu_mmio.h`)
- Driver core → NPU shell: controls accelerator (evidence: `README.md`)
- NPU shell → Command control: routes commands
- Command control → Operation dispatch: dispatches operations
- Operation dispatch → Execution scheduler: schedules execution
- Execution scheduler → Convolution engine: selects backend
- Execution scheduler → GEMM engine: selects backend
- Execution scheduler → Vector engine: selects backend
- Execution scheduler → Softmax composite: selects composite
- Execution scheduler → Layer norm composite: selects composite
- Execution scheduler → Pooling composite: selects composite
- Convolution engine → Activation: applies activation
- Convolution engine → Post-processing: uses post-processing
- GEMM engine → Post-processing: uses post-processing
- NPU shell → Memory subsystem: uses shared memory (evidence: `README.md`)
- Memory subsystem → Buffer router: routes accesses
- Memory subsystem → Local memories: accesses local SRAM
- DMA frontend → Memory subsystem: moves data
- Driver DMA → DMA frontend: requests transfers (evidence: `README.md`)
- Local memories → Memory wrappers: uses memory wrappers
- NPU shell → IRQ and counters: reports completion and metrics (evidence: `README.md`)
- Driver core → Register contract: uses register contract (evidence: `sw/driver/npu_drv.c`)
- Command API → Register contract: uses register definitions (evidence: `sw/uapi/lgnpu_cmd.h`)
- Command API → Shared annotations: uses annotations (evidence: `sw/uapi/lgnpu_cmd.h`)
- Tensor descriptors → Shared annotations: uses annotations (evidence: `sw/uapi/lgnpu_tensor.h`)
