# RK1 runtime and hardware diagnostics

This directory installs the local RKNN C runtime and supplies the two commands
used to qualify an RK3588 media image. It does not install RKNN Toolkit's model
conversion environment, Python wheels, or `rknn_server`.

## Pinned RKNN runtime

`rknn-version.env` locks RKNN Toolkit2 v2.3.2 to commit
`42aa1d426c0a9e0869b6374edba009f7208a1926`. The installer verifies the SHA-256
of the ARM64 runtime, C header, RK3588 MobileNet model, demo image, and license
before installing anything. A tag move or damaged download therefore fails the
image build.

Run the installer inside the target chroot:

```sh
runtime/install-rknn-runtime.sh
```

Or install into a mounted root filesystem from an ARM64 build host:

```sh
runtime/install-rknn-runtime.sh --rootfs /path/to/rootfs
```

For an offline/reproducible build, provide the pinned checkout explicitly:

```sh
runtime/install-rknn-runtime.sh \
  --rootfs /path/to/rootfs \
  --source-dir /path/to/rknn-toolkit2-v2.3.2
```

The build host needs Bash, Git when downloading, an ARM64 C compiler,
`coreutils`, and standard install utilities. Native compilation on the RK1 is
the supported default; a cross-build can select a compiler with `--cc`.

Files are installed below `/opt/rknn/2.3.2`, with `/opt/rknn/current` as the
stable link. The runtime path is registered in `/etc/ld.so.conf.d/rknn.conf`,
and the inference test also embeds that path as an ELF rpath. The test uses a
deterministic synthetic tensor and verifies model initialization, selected-core
submission, and finite output. It is a hardware/runtime smoke test, not a
MobileNet accuracy benchmark.

## Hardware self-test

The installed command inventories HDMI/EDID, Panthor or Mali, DRM render
nodes, RKMPP decoder and encoder bindings, AV1, RGA2/RGA3, RKNN, HDMI ALSA,
Ethernet link state, eMMC, NVMe, and the root filesystem:

```sh
rk1-media-selftest
rk1-media-selftest --quick
rk1-media-selftest --json
```

The normal run adds short Vulkan, H.264/HEVC/MJPEG encode, and NPU core
0/1/2/combined workloads when their tools are installed. `--quick` performs no
active workloads. To test 4K decoding and RKMPP-to-RGA zero-copy scaling, place
licensed samples in a directory with names containing `h264`, `hevc`, `vp9`,
and `av1`, then run:

```sh
rk1-media-selftest --media-dir /usr/share/rk1-media/samples
```

Missing tools and tests that cannot apply are `SKIP`; absent or disconnected
hardware is normally `WARN`; an advertised capability whose active workload
fails is `FAIL`. The exit status is zero unless a check fails. `--strict` also
makes warnings return status 1. Invocation errors return status 2.

## Diagnostic bundle

Create a local archive suitable for troubleshooting a blank display or missing
accelerator:

```sh
sudo rk1-media-diagnostics
sudo rk1-media-diagnostics --include-active-tests \
  --media-dir /usr/share/rk1-media/samples
```

The collector records the JSON quick test, DRM connectors, decoded EDID,
drivers, filtered kernel messages, relevant packages, ALSA devices, link state,
and storage topology. It does not upload anything. It omits raw EDID, disk
serials and UUIDs, addresses, user files, SSH material, and unfiltered journals,
and applies basic redaction; review the bundle before sharing it.

## Tests

```sh
runtime/tests/run-tests.sh
RKNN_SOURCE_DIR=/path/to/rknn-toolkit2-v2.3.2 \
  runtime/tests/run-tests.sh
```

The first form tests syntax, absent-hardware handling, JSON, synthetic sysfs,
and diagnostic collection. Supplying `RKNN_SOURCE_DIR` also compiles and stages
the pinned runtime into a temporary root filesystem.