docs: document the Android NEON/JNI kernel backend; fix a real Panama-on-Android bug - #972
Merged
Merged
Conversation
…-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>
|
📖 Documentation Preview The documentation has been built successfully for this PR. Generated Files:
Artifacts:
This comment will be updated automatically when the PR is updated. |
aharakal
approved these changes
Aug 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
skainet-backend-jni-cpuhas shipped since 0.39.0 (real, benchmarkedNEON acceleration for Android) but had essentially zero Antora
coverage — only a bare
native-jnicell 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.
explanation/perf/android-neon-jni-kernels.adoc: why Androidneeds its own provider, the two
.sotiers (/proc/cpuinfo-gatedarmv8-avsarmv8.2+dotprod), the JNI-done-carefully details(
GetPrimitiveArrayCritical, eager library load, no-underscore methodnames), the smoke-test availability probe, and the real benchmark
numbers (~24 tok/s vs ~3.8 tok/s scalar, Pixel 8a).
architecture.adoc: addedskainet-backend-jni-cputo the moduletable 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.adocrather than just prose, and foundKernelSupportMatrixTesthardcodedpanama-vectoras available on{JVM, Android}— butjdk.incubator.vectorcannot run on ART at all;PlatformCpuOpsFactory.androidonly ever registers ServiceLoader-discoveredproviders + the scalar floor. Android's
Float32/BFloat16cells werewrongly showing
panama-vector; fixed toscalar. Same investigationalso caught an unrelated inaccuracy repeated in two places: Q6_K has no
FFM kernel, so its JVM cell is
panama-vector, notnative-ffm— fixedin the architecture.adoc note box and the eager-backends mindmap.
Regenerated
kernel-support-matrix.adocvia./gradlew generateKernelMatrix.Also updated
docs/eager-execution-backends-and-kernels.md(the hand-authoredmindmap referenced from the README, not part of Antora): added
Native JNIandNative cinteropnodes it was missing entirely, fixed the samePanama-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 declarationdocker 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'simage::SKaiNET-compiler.svg[]— the file is.pngnot.svgondevelopalready, not introduced by this PR.)