Repository navigation
Model K: softmax weight rounding in one v_fma_mix*_f16 (exact), with a probe and a logged fallback - #254
Merged
Conversation
…e-time probe and a logged round-to-odd fallback The softmax stages round each weight A = f16(w * inv) exactly once. They now form p = w * inv and its exact residual e = fma(w, inv, -p) and convert p + e through the driver's round-to-nearest fragment conversion, which the driver folds into v_fma_mixlo/hi_f16: a single rounding of the exact product, the same bits as the HIP reference, fewer instructions than the round-to-odd sequence it replaces. One helper (clean/k/dx12/hlsl/k_smx.hlsli) serves the narrow and wide stages. Guards: - build: clean/dx12/isa_checks.json and build_dx12.py isa_check() require the exact v_fma_mix*_f16 count in every mix-form port and none in the round-to-odd ports (WG_DX12_ISA_CHECK=0 skips it); - port check: family mixprobe (k_mix_probe / k_mix_probe__rodd) on adversarial records (FP16 midpoints with residuals of both signs, exact ties, FP16 subnormals) against the exact single rounding; the residual-dropped control K_SMX_MUT=1 must fail it; - runtime: the native D3D12 device runs k_mix_probe at create; if any result differs, every softmax stage takes its round-to-odd port (suffix __rodd, the same bits by another sequence). The switch is reported in the kernels line (smx=mix | smx=rodd(...)) and adds one note of create (wg_rt_notes, logged by the executor). WG_TEST_K_MIX_PROBE_FAIL=1 is the test hook; test_native_softmax_switch_is_logged checks both legs, each in its own process. Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…ectable stage shader The player's driver compiles each stage shader on its own, so neither the mix form (exact when the driver folds p + e into one v_fma_mix*_f16) nor the round-to-odd ports are taken on trust. At create the native D3D12 device now checks the shaders that will run: - k_mix_probe and k_mix_probe__rodd against the exact results of k_mix_probe.h; - every softmax stage kernel the runtime can select, in both forms (k_stage_e2, k_stagew2_e3, k_stagew4_e4, k_stagew4_m, k_stagew4_d4, k_stagew2_d3, k_stage_d2, k_stage2_d1 at a 512 x 384 base map, e4 / d4 on 8 data sets; k_stagew2_e4, k_stagew2_d4 and k_stagew4_m at 1536 x 1280), on the runtime's own synthetic inputs and weights; the outputs' hashes must equal the HIP reference's (clean/k/runtime/k_smx_selfcheck.h, written by clean/k/dx12/gen_k_smx_selfcheck.py). The mix form is used when its probe and all its stages match, else the round-to-odd ports when theirs do (one note of create), else create fails in one line naming the first stage that differs. Launching every stage kernel of both forms at create also loads, verifies and prepares their shaders, so a missing or corrupt one fails create. network() and the self-check share the block parameters (block_params) and the kernel-name rule (stage_kernel_base). The test hook is now the runtime option k_smx_test (mix_fail, both_fail, rodd_unchecked, report), compiled only into developer builds (WG_DEV_DIAGNOSTICS); a release build refuses it. The environment variable hook is gone. K_SMX_RODD_MUT=1 is the round-to-odd ports' negative control (never shipped). Tests (test_k_runtime_d3d12.py, each create leg in its own process): the switch and its note; refusals (both forms failed, a corrupt __rodd shader); the forced-fallback frames against HIP at 1440p Quality (NG = 4) and 4K Performance (NG = 2) with every softmax stage on its __rodd port. Native launches are counted by their trace tag "d3d12". Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…ame and self-check) and the kernel list Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…rnel prepared at create, reference bound to its sources Offsets: the self-check cases now run at the window offsets this model's frames use, computed with the frames' own rule (k_stage_offsets over the eight entries of the model's window table): e2, e3, d3, d2 and d1 at (4, 4), e4 and d4 at (2 t - 4) mod 8, m at the table's entries. k_smx_selfcheck.h holds the HIP reference for every offset any table can give (133 cases), so any model is covered; a case without a reference refuses create. K_SMX_MUT4 is a negative control that drops the residual only at window offset 4. Prepare: native create now prepares (loads, verifies against the manifest SHA-256, compiles) every kernel the context can select, through the new Device::prepare: the fixed-weight stages e0, e1 and d0 included, so a missing or corrupt stage shader refuses create in one line naming it instead of failing the first frame. Stale reference: k_smx_selfcheck.h records kSourceDigest, a SHA-256 over the self-check kernels' @wg-kernel lines, their sources' include closure, the runtime regions marked SMX-SELFCHECK-SOURCE (the cases, the synthetic data, the block parameters, the kernel-name and window-offset rules) and a build's extra defines (clean/k/dx12/smx_selfcheck_digest.py). build_dx12.py (when it builds a self-check kernel) and build.py (the runtime with model K) refuse a header whose digest differs; WG_DX12_SMX_DIGEST=0 lets a negative-control DXIL build through. gen_k_smx_selfcheck.py writes the digest and takes the case names from the reference. Tests: test_k_smx_selfcheck_digest.py (host: the committed header is current; a changed byte in a shader source, a definition line or a runtime region, and an extra define, are caught; build_dx12 refuses a stale header); test_native_softmax_refusals also corrupts the fixed-weight stage k_stage2_e0. smx_probe frees its first buffer when the second allocation fails. Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…venance per entry, refused by build.py and the packager - build_dx12.py: WG_DX12_SMX_DIGEST=0 builds past a stale softmax self-check reference only with the new --test-only flag (else refused). The manifest says "test_only" (set by --test-only, any --define, or a bypass; a partial build keeps it, a full normal build clears it); bypassed entries say "smx_bypass". Every entry records "source_digest" (source_digest(): declaration, source file and #include closure, extra defines) and "defines". - clean/runner/build.py: before embedding the D3D12 kernels (check_dx12_kernels / dx12_manifest_problems) refuses a test-only manifest and any bypassed, define-built, unprovenanced, undeclared or stale entry (its source digest recomputed from this tree); the build manifest records "dx12_kernels" (manifest SHA-256, entries, provenance "checked"; null when nothing is embedded). - clean/tests/check_no_dev_diagnostics.py: the packager accepts a runtime library only when its build manifest records dx12_kernels (null or checked); a loose D3D12 kernel manifest that is test-only or holds a bypassed, define-built or unprovenanced entry fails the payload and the package check. - Tests (CPU): test_dev_diagnostics_off.py Dx12KernelProvenance (a real build_dx12 run with the compiler stubbed: the bypass without --test-only refused; a bypass build followed by an ordinary runtime build refused before compiling; define builds test-only; stale / unprovenanced / undeclared entries refused; a normal build passes) and packager cases (unchecked or missing dx12_kernels, test-only loose manifests refused; controls pass); test_k_smx_selfcheck_digest.py: the bypass needs test_only. The installer suite's stand-in manifest records dx12_kernels null. Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
phantoslayer21
force-pushed
the
clean/k-mix-softmax
branch
from
November 16, 2026 08:33
8fdcdb4 to
b518f4e
Compare
phantoslayer21
marked this pull request as ready for review
November 16, 2026 09:28
This was referenced Nov 16, 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.
What
Model K's softmax stages round each weight
A = f16(w * inv)exactly once. This change formsp = w * invand its exact residuale = fma(w, inv, -p)and convertsp + ethrough the driver's round-to-nearest fragment conversion, which the driver folds intov_fma_mixlo/hi_f16: one rounding of the exact product, the same bits as the HIP reference, with fewer instructions than the round-to-odd sequence it replaces. One helper (clean/k/dx12/hlsl/k_smx.hlsli) serves the narrow and wide stages. Exact: the D3D12 output stays byte-identical to HIP.The round-to-odd sequence stays as the
__roddports (the same bits by another sequence).Neither form is taken on trust
The player's driver compiles each stage shader on its own, so a fold that happens in one shader is no proof for another. At create the native D3D12 device checks the shaders that will run (
runtime_k.cpp, "create-time self-check"):Probes:
k_mix_probeandk_mix_probe__roddrun against the exact results ofk_mix_probe.h(FP16 midpoints with residuals of both signs, exact ties, FP16 subnormals).Stages: every softmax stage kernel the runtime can select runs in both forms, at the window offsets this model's frames use (
k_stage_offsetsover the eight entries of its window table), on the runtime's own synthetic inputs and weights:k_stage_e2,k_stagew2_e3,k_stagew2_d3,k_stage_d2,k_stage2_d1at (4, 4), andk_stagew4_e4,k_stagew4_d4(8 data sets) at their table offsets, on a 512 × 384 base map;k_stagew2_e4,k_stagew2_d4andk_stagew4_mat 1536 × 1280, at their table offsets.The outputs' hashes must equal the HIP reference's (
clean/k/runtime/k_smx_selfcheck.h, written byclean/k/dx12/gen_k_smx_selfcheck.pyfor every offset any window table can give: 133 cases). A case without a reference refuses create.Decision:
__roddports when theirs do (kernels linesmx=rodd(...)and one note of create,wg_rt_notes, which the executor logs);Every selectable kernel is prepared at create: native create calls
Device::prepareon every kernel the context can select (loaded, checked against the manifest SHA-256, compiled), the fixed-weight stages e0, e1 and d0 included, so a missing or corrupt shader refuses create in one line naming it.The reference is bound to its sources: the header records
kSourceDigest, a SHA-256 over the self-check kernels'@wg-kernellines, their sources' include closure, the runtime regions markedSMX-SELFCHECK-SOURCE(cases, synthetic data, block parameters, kernel-name and window-offset rules) and a build's extra defines (clean/k/dx12/smx_selfcheck_digest.py).build_dx12.py(building a self-check kernel) andbuild.py(the runtime with model K) refuse a header whose digest differs;WG_DX12_SMX_DIGEST=0lets a negative-control DXIL build through only with--test-only.Test builds never ship: a
build_dx12.pybuild with--test-only, any--defineor the bypass writes a test-only manifest (test_only; bypassed entries saysmx_bypass), and every entry records itssource_digest(declaration, source file and include closure, extra defines) anddefines.build.pyrefuses to embed a test-only manifest or any bypassed, define-built, unprovenanced, undeclared or stale entry (digest recomputed from the tree) and records the check in the library's.build.json(dx12_kernels); the payload packager refuses a library whose build manifest lacks that record, and a loose test-only D3D12 manifest fails the payload and package checks (clean/tests/test_dev_diagnostics_off.py: a bypass build followed by an ordinary runtime build is refused, and so is the packaged artifact).Shared code:
network()and the self-check share the block parameters (block_params) and the kernel-name rule (stage_kernel_base).Test hook: the runtime option
k_smx_test(mix_fail,both_fail,rodd_unchecked,report) is compiled only into developer builds (build.py --dev-diagnostics). A release build refuses it.The build's ISA check (
clean/dx12/isa_checks.json: the exactv_fma_mix*_f16count in every mix-form port, none in the__roddports) and the port check familymixprobestay.Evidence
One-stage mutants (one kernel each; probes and every other kernel unchanged; cases at the frames' offsets). All 20 are caught (record
mutants-254.json):K_SMX_MUT=1)__rodd, naming the case__roddport, inexact bit dropped (K_SMX_RODD_MUT=1)Offset-4-only control (
K_SMX_MUT4=1onk_stage_e2: a second, residual-dropped conversion whose result is taken only at window offset 4; recordsmutants-254.json,mut4-redo.json):__rodd, namingk_stage_e2@512x384/o4,4;Earlier, smaller case sizes missed 2 of 20 (
mutants-254-round1.json,-round2.json), which is why the cases were enlarged.Fallback frame test and its negative control.
test_native_fallback_frames_1440p_quality(NG = 4) and_4k_performance(NG = 2) pass. They compare raw outputs and intermediates against HIP, and every softmax stage ran its__roddport.__rodd-only mutant, the test fails because create refuses.k_smx_test=rodd_unchecked, the HIP comparison catches the mutant: 88,848 of 7,372,800 output words differ. Record:negframe-254.json.Test suite.
test_k_runtime_d3d12.pypasses 24 / 24, each test in its own process:k_stagew2_e3__rodd.dxil; a corrupt fixed-weightk_stage2_e0.dxil);Source binding:
test_k_smx_selfcheck_digest.py(host, runs in CI) checks that the committed header belongs to the committed sources; that one changed byte in a shader source, a definition line or a runtime region, or an extra define, is reported stale; and thatbuild_dx12.pyrefuses a stale header. After the last shader-text edit (a negative-control branch behind a define that is off), the 20 self-check kernels were rebuilt through the digest check, and their DXIL is byte-identical to that of the build the reference came from.Port check (unchanged kernels):
test_k_port_check_nan.py).Create time. Native create at 1440p Quality goes from 271.8 to 733.1 ms (median of 4 alternating runs, record
create-time-254.json). That is once per context, not per frame.Speed: Model K, 1440p Quality, harness: network 0.700 -> 0.677 ms. Interleaved A/B on the direct route (8 + 7 runs, medians 0.6997 / 0.6770 ms). Record:
kmix-speed.json, beside this PR's diff in the lane folder.Tests
python -m unittest clean.k.tests.test_k_mix_probe_table: the probe table against an exact Fraction oracle and numpy's FP16 conversion.python clean/k/dx12/gen_k_mix_probe.py --checkalso verifies the committed header against its generator.python clean/k/dx12/k_port_check.py --family mixprobe,narrow,wide: GPU.python -m unittest clean.k.tests.test_k_runtime_d3d12: GPU. The softmax tests need a runtime built with--dev-diagnosticsand skip on another build.python clean/k/dx12/gen_k_smx_selfcheck.py --build <developer build>: GPU, regenerates the reference table from the HIP reference.