Skip to content

docs: document the Android NEON/JNI kernel backend; fix a real Panama-on-Android bug - #972

Merged
michalharakal merged 1 commit into
developfrom
docs/android-neon-jni-kernels
Aug 13, 2026
Merged

michalharakal merged 1 commit into
developfrom
docs/android-neon-jni-kernels

Conversation

@michalharakal

Copy link
Copy Markdown
Contributor

Summary

skainet-backend-jni-cpu has shipped since 0.39.0 (real, benchmarked
NEON acceleration for Android) but had essentially zero Antora
coverage — only a bare native-jni cell in the generated kernel matrix,
no prose anywhere, and the architecture reference's own ADR read as if
JNI had been rejected in favor of FFM, when the real story is
FFM-where-available / JNI-where-ART-has-no-FFM.

  • New explanation/perf/android-neon-jni-kernels.adoc: why Android
    needs its own provider, the two .so tiers (/proc/cpuinfo-gated
    armv8-a vs armv8.2+dotprod), the JNI-done-carefully details
    (GetPrimitiveArrayCritical, eager library load, no-underscore method
    names), the smoke-test availability probe, and the real benchmark
    numbers (~24 tok/s vs ~3.8 tok/s scalar, Pixel 8a).
  • architecture.adoc: added skainet-backend-jni-cpu to the module
    table and a new "Native (JNI) provider" note box; converted the ASCII
    kernel-SPI diagram to Mermaid and added the JNI provider box;
    corrected the ADR row that read as "JNI rejected" to state what was
    actually decided (FFM over JNI for the JVM provider, not a blanket
    rejection).

A real bug, found by cross-checking claims against generated output

While writing this I checked every claim against the machine-generated
kernel-support-matrix.adoc rather than just prose, and found
KernelSupportMatrixTest hardcoded panama-vector as available on
{JVM, Android} — but jdk.incubator.vector cannot run on ART at all;
PlatformCpuOpsFactory.android only ever registers ServiceLoader-discovered
providers + the scalar floor. Android's Float32/BFloat16 cells were
wrongly showing panama-vector; fixed to scalar. Same investigation
also caught an unrelated inaccuracy repeated in two places: Q6_K has no
FFM kernel, so its JVM cell is panama-vector, not native-ffm — fixed
in the architecture.adoc note box and the eager-backends mindmap.
Regenerated kernel-support-matrix.adoc via ./gradlew generateKernelMatrix.

Also updated

docs/eager-execution-backends-and-kernels.md (the hand-authored
mindmap referenced from the README, not part of Antora): added Native JNI and Native cinterop nodes it was missing entirely, fixed the same
Panama-on-Android inaccuracy, fixed a stale "#708 not done" status
(Q5_1/Q5_0 FFM shipped in 0.39.1), and split the kernel × provider table
by platform instead of conflating JVM and Android under one column.

Test plan

  • ./gradlew :skainet-backends:skainet-backend-native-cpu:jvmTest --tests '*KernelSupportMatrixTest*' — passes with the corrected tier declaration
  • Full local Antora build (docker build docs/.docker + antora-playbook.yml) — new page renders, Mermaid diagram renders as inline SVG, nav entry resolves. (One pre-existing, unrelated error: architecture.adoc's image::SKaiNET-compiler.svg[] — the file is .png not .svg on develop already, not introduced by this PR.)

…-on-Android bug

skainet-backend-jni-cpu has shipped since 0.39.0 (real benchmarks in the
CHANGELOG: ~24 tok/s vs ~3.8 tok/s scalar on a Pixel 8a) but had essentially
zero Antora coverage — only a bare "native-jni" cell in the generated kernel
matrix, no prose anywhere, and the architecture reference's own ADR read as
if JNI had been rejected in favor of FFM everywhere, when the real story is
FFM-where-available/JNI-where-ART-has-no-FFM.

- New docs/modules/ROOT/pages/explanation/perf/android-neon-jni-kernels.adoc:
  why Android needs its own provider, the two .so tiers (cpuinfo-gated
  armv8-a vs armv8.2+dotprod), the JNI-done-carefully details
  (GetPrimitiveArrayCritical, eager library load, no-underscore method
  names), the smoke-test availability probe, and the real benchmark numbers.
- architecture.adoc: added skainet-backend-jni-cpu to the module table and a
  new "Native (JNI) provider" note box; converted the ASCII kernel-SPI
  diagram to Mermaid and added the JNI provider box; corrected the ADR row
  that read as "JNI rejected" to state what was actually decided (FFM over
  JNI for the JVM provider specifically, not a blanket rejection).

Also found and fixed a real bug while cross-checking these claims against
the generated kernel-support-matrix, not just prose: KernelSupportMatrixTest
hardcoded panama-vector as available on {JVM, Android}, but jdk.incubator.vector
cannot run on ART at all — PlatformCpuOpsFactory.android only ever registers
ServiceLoader-discovered providers + the scalar floor. Android's Float32/
BFloat16 cells were wrongly showing "panama-vector"; fixed to "scalar" (also
corrected an unrelated inaccuracy the same investigation surfaced: Q6_K has
no FFM kernel, so its JVM cell is panama-vector, not native-ffm — the note
box's kernel list and the eager-backends mindmap both repeated that error).
Regenerated kernel-support-matrix.adoc via ./gradlew generateKernelMatrix.

Also updated docs/eager-execution-backends-and-kernels.md (the hand-authored
mindmap, not Antora but referenced from the README): added Native JNI and
Native cinterop nodes it was missing entirely, fixed the same Panama-on-
Android inaccuracy, fixed the stale "SKaiNET#708 not done" status (Q5_1/Q5_0
FFM shipped in 0.39.1), and split the kernel x provider table by platform
instead of conflating JVM and Android under one column.

Verified: both the corrected KernelSupportMatrixTest and a full local
Antora build (docker build docs/.docker + antora-playbook.yml) pass —
new page renders, Mermaid diagram renders as inline SVG, nav entry resolves.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

📖 Documentation Preview

The documentation has been built successfully for this PR.

Generated Files:

  • Operator documentation: docs/modules/operators/_generated_/
  • JSON schema output: operators.json

Artifacts:

  • Download the documentation-preview-972 artifact to view the complete documentation locally.

This comment will be updated automatically when the PR is updated.

@michalharakal
michalharakal requested a review from aharakal August 13, 2026 09:54
@michalharakal
michalharakal merged commit c66be1d into develop Aug 13, 2026
18 checks passed
@michalharakal
michalharakal deleted the docs/android-neon-jni-kernels branch August 13, 2026 11:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants