docs(architecture): add missing building blocks (kernel dispatch, ternary, AOT) - #1216
Merged
Merged
Conversation
…nary, AOT) The arc42 building block view (§5) hadn't kept up with several subsystems that shipped since it was last touched: - View-based kernel dispatch (KernelDispatch/ViewKernel/KernelKey/ OperandKey/LayoutClass, #1189-#1193) was already used by §6's runtime-view flowchart but never introduced as a building block. New §5.3 covers it, including MappedCapableKernel and the mapped-encoding derivation/guard-test cross-check (#1193). - The memory planning layer (AllocationResolver/StorageCapabilities/ PlannerProfile/WeightForm) that decides Storage before dispatch reaches it was mentioned only in passing. §5.4 gets a subsection naming it explicitly. - Ternary/BitNet weights (off-heap Storage #1202, zero-copy mmap for SEQUENTIAL #1203, the closed #1205 native-grouped-kernel decision, the I2sAotConverter) had no building-block coverage at all. New §5.5. - The external SKaiNET-IREE-tools repo (#1207) and skainet-io-gguf's export/ AOT capability weren't reflected in §3's "read-only" I/O claim or §5.1's module table. Also: §9 gains decision rows for the above (dated, with rationale, matching the table's existing convention); §11 drops the now-resolved "packed weights still reach the heap" risk and adds the two that replaced it (ternary repack cost, mapped-format coverage is a maintained set); §12 glossary gains KernelKey/ViewKernel, MappedCapableKernel, WeightForm/WeightResidency, and AOT conversion. Validated with `asciidoctor` (renders cleanly, no warnings, no broken xrefs/tables) since the repo's Antora mermaid extension isn't available outside CI.
|
📖 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. |
5 tasks
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
1 participant
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
The arc42 building block view (
docs/modules/ROOT/pages/reference/architecture.adoc, §5) hadn't kept up with several subsystems that shipped since it was last touched:KernelDispatch/ViewKernel/KernelKey/OperandKey/LayoutClass, Packed-tensor mapped staging: serve Q4_K/Q6_K/ternary blocks straight from the mmap on Android #1189-Kernel SPI: make weight addressing order and byte source declared contract dimensions #1193) was already used by §6's runtime-view flowchart but never introduced as a building block. New §5.3 covers it, includingMappedCapableKerneland the mapped-encoding derivation/guard-test cross-check (Kernel SPI: make weight addressing order and byte source declared contract dimensions #1193, feat(#1193): derive mapped-serving encodings from kernel registrations #1215).AllocationResolver/StorageCapabilities/PlannerProfile/WeightForm) that decidesStoragebefore dispatch reaches it was mentioned only in passing. §5.4 gets a subsection naming it explicitly.StorageOff-heap storage for packed ternary/quantized weights (fixes #1198's OOM path) #1202, zero-copy mmap forSEQUENTIALSkip the I2_S repack copy for SEQUENTIAL-layout GGUFs, enable true mmap #1203, the closed [Deferred] Native decode kernel for BitNet.cpp's GROUP_128 layout (no-repack mmap) #1205 native-grouped-kernel decision,I2sAotConverter) had no building-block coverage at all. New §5.5.SKaiNET-IREE-toolsrepo (AOT GGUF converter for I2_S repack (eager-exec) — done; IREE leg moved out of core #1207) andskainet-io-gguf's export/AOT capability weren't reflected in §3's "read-only" I/O claim or §5.1's module table.Also:
KernelKey/ViewKernel,MappedCapableKernel,WeightForm/WeightResidency, and AOT conversion.No code changes — documentation only.
Test plan
asciidoctorlocally (clean, no warnings, all 18 section anchors generated correctly, no broken xrefs/tables) — the repo's Antora mermaid extension isn't available outside CI, so a full Antora build wasn't possible locally.