# Native runtime

This runtime owns the fixed YOLO26n topology and execution schedule. It builds
the model's nineteen XNNPACK graphs when a runtime instance is created.

## File layout

- `arm_yolo26n.h` defines the public C API.
- `arm_yolo26n.cpp` owns the lifetime of a loaded model, its graphs, worker
  threads, and scratch memory.
- `model_contract.h` defines supported resolutions, tensor alignment, and
  output dimensions.
- `model_store.cpp` validates `model.bin` and resolves its weight slots.
- `fixed_graph.cpp` and the `fixed_graph_*.inc` files define the backbone,
  neck, detection, and early-projection graphs.
- `fixed_schedule.cpp` executes the graphs and performs data movement between
  them.
- `fixed_memory_plan.cpp` assigns intermediate tensors to the shared
  activation arena.
- `preprocess.cpp` pads and converts packed RGB, BGR, or BGRX images into the
  planar floating-point input expected by the runtime. It does not resize.
- `projection_optimization.cpp` avoids two intermediate tensors and
  transposes by writing two early 1x1 projections directly into the layout
  consumed by the next graph. It is the only runtime source permitted to use
  private XNNPACK interfaces.
- `patches/` contains the project-owned XNNPACK and pthreadpool changes.
- `tests/` contains the public C API behavior test.
- `CMakeLists.txt` owns native dependency acquisition and patching,
  compilation, testing, ABI verification, installation, and packaging.

## Building

From the `yolo26-raspberry-pi-5/` runtime directory, run:

```sh
make runtime
```

The top-level Make target configures CMake, builds and tests the native runtime,
and installs it under `dist/runtime/`. CMake fetches the pinned native
dependencies and includes their license notices from `licenses/` in the
installed runtime.

## Runtime details

### Fixed runtime topology

YOLO26n builds progressively smaller feature maps in its backbone, combines
them from coarse to fine in its neck, then predicts boxes and classes at three
scales in its detection head. This runtime uses conventional pyramid names for
those feature levels:

| Level | Spatial size for resolution `R` | Role |
| --- | --- | --- |
| P2 | `R / 4` | Early backbone features used by the split-projection optimization. |
| P3 | `R / 8` | Finest detection scale; preserves the most spatial detail. |
| P4 | `R / 16` | Middle backbone, neck, and detection scale. |
| P5 | `R / 32` | Coarsest backbone and detection scale; contains the attention blocks. |

The topology is divided into nineteen XNNPACK subgraphs. These partitions are
not independently configurable models; together they form one fixed YOLO26n
program. Boundaries occur where the runtime performs explicit data movement
for attention reshaping, upsampling, output conversion, or split-projection
optimization.

### Memory planning

The standard 640-pixel, 80-class model uses a compact placement benchmarked on
Raspberry Pi 5. Other supported resolutions or class counts use an aligned
sequential placement calculated from their tensor sizes, with one reuse where
`P3Fusion` takes over the no-longer-needed `BackboneP3` storage. This uses
more memory but avoids applying size-specific offsets to incompatible tensor
shapes.

### Runtime lifecycle and buffers

`y26_native_create` copies and validates caller-provided `model.bin` bytes,
derives tensor sizes, allocates scratch memory, creates a four-worker thread
pool, and builds the nineteen graphs. The caller can release its byte buffer
after creation returns. This work happens once per runtime instance; the native
runtime does not access the filesystem.

The public input and output buffers contain FP32 values; most intermediate
tensors use FP16. Callers query exact byte counts from the runtime before
calling `y26_native_execute`.

Concurrent inference requires one instance per caller. A caller must not destroy
an instance while a call is using it. `y26_native_destroy` releases the
complete instance.

`y26_native_preprocess_image_no_resize` accepts images whose longer side
already matches the model resolution. It normalizes pixels, separates color
channels, and pads the shorter side, but deliberately does not resize.