Skip to content

Model K: softmax weight rounding in one v_fma_mix*_f16 (exact), with a probe and a logged fallback - #254

Merged
phantoslayer21 merged 5 commits into
mainfrom
clean/k-mix-softmax
Nov 16, 2026
Merged

phantoslayer21 merged 5 commits into
mainfrom
clean/k-mix-softmax

Conversation

@phantoslayer21

@phantoslayer21 phantoslayer21 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

What

Model K's softmax stages round each weight A = f16(w * inv) exactly once. This change forms p = w * inv and its exact residual e = fma(w, inv, -p) and converts p + e through the driver's round-to-nearest fragment conversion, which the driver folds into v_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 __rodd ports (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_probe and k_mix_probe__rodd run against the exact results of k_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_offsets over 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_d1 at (4, 4), and k_stagew4_e4, k_stagew4_d4 (8 data sets) at their table offsets, on a 512 × 384 base map;
    • k_stagew2_e4, k_stagew2_d4 and k_stagew4_m at 1536 × 1280, at their table offsets.

    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 for every offset any window table can give: 133 cases). A case without a reference refuses create.

  • Decision:

    • the mix form when its probe and all its stages match;
    • else the __rodd ports when theirs do (kernels line smx=rodd(...) and one note of create, wg_rt_notes, which the executor logs);
    • else create fails in one line naming the first stage that differs.
  • Every selectable kernel is prepared at create: native create calls Device::prepare on 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-kernel lines, their sources' include closure, the runtime regions marked SMX-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) 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 only with --test-only.

  • Test builds never ship: a build_dx12.py build with --test-only, any --define or the bypass writes a test-only manifest (test_only; bypassed entries say smx_bypass), and every entry records its source_digest (declaration, source file and include closure, extra defines) and defines. build.py refuses 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 exact v_fma_mix*_f16 count in every mix-form port, none in the __rodd ports) and the port check family mixprobe stay.

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):

Mutant What create does Kernels caught
Mix form, residual dropped (K_SMX_MUT=1) Picks __rodd, naming the case 10 / 10
__rodd port, inexact bit dropped (K_SMX_RODD_MUT=1) Keeps mix with a note; with the fallback forced, refuses naming the case 10 / 10

Offset-4-only control (K_SMX_MUT4=1 on k_stage_e2: a second, residual-dropped conversion whose result is taken only at window offset 4; records mutants-254.json, mut4-redo.json):

  • with these cases, create picks __rodd, naming k_stage_e2@512x384/o4,4;
  • with the previous offset-2 cases, create keeps the mix form: the defect really fires only at offset 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 __rodd port.
  • With a __rodd-only mutant, the test fails because create refuses.
  • With 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.

  • Developer build: test_k_runtime_d3d12.py passes 24 / 24, each test in its own process:
    • the switch and its note;
    • the refusals (both forms failed; a corrupt k_stagew2_e3__rodd.dxil; a corrupt fixed-weight k_stage2_e0.dxil);
    • the fallback frames;
    • every earlier frame test.
  • Release build: the hook is refused (the softmax tests skip) and the native frame tests pass with the self-check on.

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 that build_dx12.py refuses 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):

  • mixprobe: 0 / 0 values differ (2 seeds × 2,048 values); a second rounding through FP32 would differ in 611 / 609 of them.
  • narrow: 120 / 120 cases pass (9 NaN-sign-only).
  • wide: 84 / 84 cases pass (12 NaN-sign-only).
  • Negative controls are caught. NaN-sign-only means NaN on both sides, differing only in the sign bit, which IEEE 754 leaves undefined (README NaN rule, 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 --check also 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-diagnostics and 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.

…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>
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.

1 participant