How arty3/lg-npu works
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: npu_scheduler.sv Execution scheduler · npu_drv.c Driver core · npu_shell.sv NPU shell · npu_mem_top.sv Memory subsystem
Components 34
Host software
- Tensor descriptors
sw/uapi/lgnpu_tensor.h - Tensor conversion
sw/runtime/tensor_desc.c - Command API
sw/uapi/lgnpu_cmd.h - Command builder
sw/runtime/command_builder.c - Runtime API
sw/runtime/liblgnpu.c - Runtime submit
sw/runtime/submit.c - Runtime MMIO
sw/runtime/mmio_helpers.h - Device API
sw/uapi/lgnpu_ioctl.h - Register contract
sw/uapi/lgnpu_regs.h - Shared annotations
sw/shared/annotations.h
Device control
- Driver core
sw/driver/npu_drv.c - Driver state
sw/driver/lgnpu_drv.h - Driver MMIO
sw/driver/npu_mmio.h - Command queue
sw/driver/npu_queue.c - Driver DMA
sw/driver/npu_dma.c - NPU shell
rtl/core/npu_shell.sv - Command control
rtl/control/npu_cmd_fetch.sv - Operation dispatch
rtl/core/npu_dispatch.sv - Execution scheduler
rtl/core/npu_scheduler.sv - IRQ and counters
rtl/control/npu_irq_ctrl.sv
Compute engines
- Convolution engine
rtl/backends/conv/conv_backend.sv - GEMM engine
rtl/backends/gemm/gemm_backend.sv - Vector engine
rtl/backends/vec/vec_backend.sv - Softmax composite
rtl/composites/softmax/softmax_composite.sv - Layer norm composite
rtl/composites/lnorm/lnorm_composite.sv - Pooling composite
rtl/composites/pooling/pool_composite.sv - Activation
rtl/ops/activation/activation.sv - Post-processing
rtl/ops/postproc/postproc.sv
Memory and movement
- Memory subsystem
rtl/memory/npu_mem_top.sv - Buffer router
rtl/memory/npu_buffer_router.sv - DMA frontend
rtl/memory/npu_dma_frontend.sv - Local memories
rtl/memory/npu_scratchpad.sv
Platform support
- Memory wrappers
rtl/platform/mem_macro_wrap.sv
Other components
- Host application
Connections 38
- Host application → Tensor descriptors: describes tensors
README.md - Host application → Command builder: builds commands
README.md - Tensor descriptors → Tensor conversion: converts layouts
sw/uapi/lgnpu_tensor.h - Command builder → Command API: packs descriptors
sw/runtime/command_builder.c - Runtime API → Runtime MMIO: uses helpers
sw/runtime/liblgnpu.c - Runtime submit → Runtime MMIO: uses helpers
sw/runtime/submit.c - Runtime submit → Device API: uses contract
sw/runtime/submit.c - Host application → Runtime API: uses runtime
README.md - Runtime API → Driver core: submits to device
README.md - Device API → Driver core: defines operations
README.md - Driver core → Driver state: uses device state
sw/driver/npu_drv.c - Driver core → Command queue: submits commands
sw/driver/npu_drv.c - Driver core → Driver DMA: starts transfers
sw/driver/npu_drv.c - Driver MMIO → Driver state: accesses registers
sw/driver/npu_mmio.h - Driver core → NPU shell: controls accelerator
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
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
README.md - Local memories → Memory wrappers: uses memory wrappers
- NPU shell → IRQ and counters: reports completion and metrics
README.md - Driver core → Register contract: uses register contract
sw/driver/npu_drv.c - Command API → Register contract: uses register definitions
sw/uapi/lgnpu_cmd.h - Command API → Shared annotations: uses annotations
sw/uapi/lgnpu_cmd.h - Tensor descriptors → Shared annotations: uses annotations
sw/uapi/lgnpu_tensor.h