code wiki / (root) / nx_placement.nx

nx_placement.nx

buildroot/runtime/nx_placement.nx

9464 B253 linesdepth 6pulls 8 transitivereach 28 importersview sourcekind library
docsdependenciesstructsconstsfunctions

about

nx_placement.nx -- multi-tier tensor placement + lazy materialization. L1.5 brick. The smallest demonstrable step toward the conductor cardinal (2026-05-19): tensors aren't FORCED into VRAM-equivalent storage at load time; they can live "where they already are" (mmap'd GGUF buffer) and only materialize per-use. Without this brick: nx_gguf_load_tensor allocates a full Q10 i64 buffer for every tensor at load. A real Llama-70B Q4_K file has ~40GB of weights; materializing all of them into i64 Q10 would require ~320GB of RAM. Infeasible on any consumer device. With this brick: tensors live as NxPlacedTensor with placement tag. Lazy (MMAP) tensors hold a (buf, offset, ggml_type) handle and only materialize a Q10 i64 NxTensor on first access -- callers that stream weights by layer can demote earlier layers, keeping working set bounded. This is Phase A of the multi-phase conductor arc: A) [this brick] Placement tag + lazy materialization B) Lazy GGUF loader (nx_gguf_load_tensor that returns lazy) C) Dispatcher (per-op hardware routing) D) Resource arbiter (multi-tier budget tracking) E) Async DMA primitives Bits-up composition: nx_tensor.nx -- NxTensor (the materialized form) nx_gguf.nx -- GGML type tags nx_gguf_load.nx -- dequant routing for materialization genealogy_id: numpy_memmap_pattern + mmap_lazy_load_canonical lineage_id: substrate_placement_v1_lazy_promote_demote

dependencies 6 imports · 27 importers

nx_syscalls.nx nx_tier.nx nx_loop.nx nx_tensor.nx nx_gguf.nx nx_gguf_load.nx nx_placement.nx nx_companion_compose_test.nx nx_dispatcher.nx nx_gguf_load_lazy.nx nx_gguf_load_lazy_test.nx nx_live_fire_gguf.nx nx_live_fire_gguf_test.nx nx_placement_test.nx nx_q4k_dot_simd.nx nx_q4k_gemm_mt.nx nx_q4k_linear.nx

diagram shows first 10 each side; +0 more imports, +17 more importers in the complete lists below.

imports: nx_syscalls.nxnx_tier.nxnx_loop.nxnx_tensor.nxnx_gguf.nxnx_gguf_load.nx

imported by: nx_companion_compose_test.nxnx_dispatcher.nxnx_gguf_load_lazy.nxnx_gguf_load_lazy_test.nxnx_live_fire_gguf.nxnx_live_fire_gguf_test.nxnx_placement_test.nxnx_q4k_dot_simd.nxnx_q4k_gemm_mt.nxnx_q4k_linear.nxnx_q4k_linear_hp.nxnx_q4k_real_gemm.nxnx_q4k_speed_bench.nxnx_q5k_dot_simd.nxnx_qwen_blk0_types.nxnx_qwen_hybrid_attn.nxnx_qwen_hybrid_ffn.nxnx_qwen_hybrid_qkv.nxnx_real_gguf_test.nxnx_zimage_dequant_block.nxnx_zimage_gguf_arch.nxnx_zimage_gguf_probe.nxnx_zimage_layout.nxnx_zimage_real_op.nxnx_zimage_real_proj.nxnx_zimage_real_qkv.nxnx_zimage_weights.nx

structs

95struct NxPlacedTensor

consts

63const NX_PLACE_OWNED: nx_int = 0 // caller already materialized; no source
64const NX_PLACE_MMAP: nx_int = 1 // backed by raw bytes in a buffer (GGUF)
65const NX_PLACE_VRAM: nx_int = 2 // (future) GPU-resident; not yet implemented
66const NX_PLACE_NETWORK: nx_int = 3 // (future) on a peer device
67const NX_PLACE_N: nx_int = 4
77const NX_PT_OK: nx_int = 0
78const NX_PT_ERR_BAD_PLACEMENT: nx_int = 1
79const NX_PT_ERR_NO_SOURCE: nx_int = 2
80const NX_PT_ERR_BAD_TYPE: nx_int = 3
81const NX_PT_ERR_ALREADY_LIVE: nx_int = 4
82const NX_PT_ERR_NOT_LIVE: nx_int = 5
83const NX_PT_N_VERDICTS: nx_int = 6
109const NX_PT_STRUCT_BYTES: nx_int = 88 // 11 * 8

functions

69func nx_place_is_valid(p: nx_int) -> nx_int
called by 1: main
85func nx_pt_verdict_is_valid(v: nx_int) -> nx_int
called by 1: main
116func nx_placed_tensor_new_lazy(src_buf: *u8, src_off: i64,
143func nx_placed_tensor_new_owned(t: *NxTensor) -> *NxPlacedTensor
called by 2: mainmain calls 1: sys_mmap
174func nx_placed_tensor_is_live(p: *NxPlacedTensor) -> nx_int
called by 4: mainmainmainmain
179func nx_placed_tensor_storage_bytes(p: *NxPlacedTensor) -> i64
called by 4: mainmainmainmain
187func _pt_materialize(p: *NxPlacedTensor) -> *NxTensor
219func nx_placed_tensor_materialize(p: *NxPlacedTensor) -> nx_int
230func nx_placed_tensor_demote(p: *NxPlacedTensor) -> nx_int
called by 2: mainmain
247func nx_placed_tensor_get(p: *NxPlacedTensor) -> *NxTensor