On-target loader: .npub Vela blob -> ra8_npu_job_t (RA8P1-only). More...

#include <stdint.h>
#include "ra8_device.h"
#include "ra8_err.h"
#include "ra8_npu.h"

Include dependency graph for ra8_npu_loader.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ra8_npu_arena_t
	Caller-provided runtime arena for a model's RUNTIME regions. More...

Functions
ra8_err_t	ra8_npu_load (const void blob, uint32_t blob_bytes, const ra8_npu_arena_t arena, ra8_npu_job_t *out_job)
	Validate a .npub blob and map it into an ra8_npu_job_t.

Detailed Description

On-target loader: .npub Vela blob -> ra8_npu_job_t (RA8P1-only).

Tag: [Ring 3 / HAL] {World: S}

The FRONT HALF of the Ethos-U55 model loader. The offline Vela build step (tools/vela/src/vela_gen.py) compiles a quantized .tflite model and distills the ethos-u custom operator's command stream plus its tensor region layout into a lean, linkable .npub container (ra8_npu_blob.h). This loader validates that container and maps it into an ra8_npu_job_t so ra8_npu_submit() / ra8_npu_run() can execute it – WITHOUT parsing a TFLite flatbuffer on the MCU.

For every region the blob declares, the loader produces a BASEPn base address:

a BAKED region (weights / const inputs) points at the region's bytes inside the blob itself (which lives in flash / MRAM, readable by the NPU over AXI);
a RUNTIME region (scratch / output activations) is carved out of a caller-provided arena in NPU-visible SRAM, 16-byte aligned.

Scope

This is the LOADER only. It does not run inference (that is ra8_npu_run() plus the follow-up runtime) and does not itself compile a model (that is Vela, run offline). It has no board dependency and is fully host-tested.

Threading

Re-entrant: the loader keeps no state and only reads the blob and writes the caller's ra8_npu_job_t. The NPU serialisation contract is owned by ra8_npu.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file ra8_npu_loader.h.

Function Documentation

◆ ra8_npu_load()

ra8_err_t ra8_npu_load	(	const void *	blob,
		uint32_t	blob_bytes,
		const ra8_npu_arena_t *	arena,
		ra8_npu_job_t *	out_job )

nodiscard

Validate a .npub blob and map it into an ra8_npu_job_t.

Checks the container magic, version, declared sizes, region count, and payload checksum, then fills out_job: cmd_stream / cmd_stream_bytes point at the blob's command stream, and each region_base[i] is resolved to the blob (BAKED regions) or to arena (RUNTIME regions, 16-byte aligned in descriptor order). The job is programmed but NOT submitted; the caller runs it via ra8_npu_submit() + ra8_npu_run().

Parameters

[in]	blob	Base of the .npub container in NPU-visible memory.
[in]	blob_bytes	Length of `blob` in bytes (>= the header size).
[in]	arena	Runtime arena for RUNTIME regions (non-NULL; may be 0 sz).
[out]	out_job	Filled job descriptor on success; untouched on failure.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	The blob is valid and `out_job` is fully populated.
k_ra8_err_null_ptr	`blob`, `arena`, or `out_job` was nullptr.
k_ra8_err_invalid_size	`blob_bytes` is below the header size, or the command stream length is zero.
k_ra8_err_invalid_arg	Bad magic, unsupported version, or a region count above k_ra8_npu_region_count.
k_ra8_err_out_of_range	A declared offset/size falls outside `blob`.
k_ra8_err_checksum_mismatch	The payload checksum did not match.
k_ra8_err_no_mem	The RUNTIME regions do not fit in `arena`.

Precondition: blob, arena, and out_job are non-NULL.; blob is resident in memory the NPU can read over AXI.

Postcondition: On k_ra8_ok out_job describes a runnable job (regions resolved).; On any error out_job is left unmodified.

Note: Re-entrant; keeps no state. Not an NPU-hardware call (touches no register).

See also: ra8_npu_submit; ra8_npu_arena_t

Since: 0.1.0

NASA Power of 10 Compliance:

Rule 5: 2 preconditions, 2 postconditions
Rule 7: returns ra8_err_t, marked [[nodiscard]]

Referenced by internal_npu_vela_run_job().

Data Structures

Functions

Detailed Description

Scope

Threading

Function Documentation

◆ ra8_npu_load()