Skip to content

Model L: the hybrid form as the native D3D12 default (hybrid_full) - #256

Merged
phantoslayer21 merged 5 commits into
mainfrom
kspeed/hyb-fast-l
Nov 16, 2026
Merged

phantoslayer21 merged 5 commits into
mainfrom
kspeed/hyb-fast-l

Conversation

@phantoslayer21

@phantoslayer21 phantoslayer21 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Model L runs the hybrid block form by default on native D3D12 (hybrid_full; no form variable needed, and WG_L_FORM=hybrid gives the same bytes). The form keeps FP8 matrix chains accumulated in float32, with one FP16 rounding at each chain end. The original's FP16 norm, softmax and GELU steps are computed by exact tables and FP16 forms. The HIP twins (hybrid_twin, developer builds) are the byte reference.

The form change (by design)

What is in it

  • Hybrid kernels on D3D12:
    • the C32 blocks, with the two input linears as the encoder block's prologue (q from the q20 input encoder) and the pack12 coefficient store as the decoder block's epilogue;
    • the shared-stage blocks, merges and expands;
    • the bottleneck b0 ... b5 in one persistent-queue launch, swin_bneck6_hyb. It uses bneck.hlsl's schedule around swin_block_c128_hyb's body, and b5's bytes equal six block launches.
  • Bottleneck wait timeout: a stuck frame shows a simple upscale of the game's image for that frame.
    • A wait that runs out sets an abort word and a timeout count. Every other wait of the launch then stops at once.
    • The whole hybrid frame runs under a D3D12 predication guard on that word. The guard is read again right after the bottleneck. When it is set, every later launch and copy of that frame, and of the frames queued after it, is skipped on the GPU: no output, no history.
    • The runtime reads the count back without waiting. When it has moved, the runtime refuses the next frame, starts the frame after it over (reset) and clears the word.
    • In a game, the executor's own output pass (the proxy copy or output draw into the game's output texture) runs under the same predication as the network. Under the inverse predication on the same word, a fallback writes a bilinear upscale of that frame's colour into that frame's output texture, by the same output route. It runs only when the frame was skipped, needs no CPU wait, and covers every timed-out or queued frame, the very first frame included, whatever output texture the game passes.
    • The refused frame (the one whose start sees the timeout count move) records nothing that writes. The backend logs one line and answers WG_ERROR_NOT_READY, the interface's documented one-frame result: the front end's stand-in renders that frame (AMD's FSR for that frame only when there is no stand-in), it never takes the context over, and the next frame goes to the network again. That frame starts over as a newly created context's first frame (byte for byte a fresh context's first frame on the same inputs). WG_ERROR_UNSUPPORTED keeps its permanent handoff for frames the upscaler can never take.
    • The game's own predicate on its command list is kept. The front end reports it through a new appended service (WgFrontEndServices::command_list_predication, from the state its hooks track). Our recording lifts it, runs unconditionally, and sets it again exactly as it was, so the game's conditional work after ours stays conditional.
    • Model L hybrid needs the front end's predication service, otherwise the stand-in renders the frame. Such a frame is answered WG_ERROR_NOT_READY too (that frame only, no takeover), so a later frame whose predicate is known runs the network again.
    • The service is appended to WgFrontEndServices. The backend checks an older version 2 table only up to split_command_list (by offset) and the new field by its own size at dispatch, so an older front end's shorter table is still taken.
    • A front end WG_ERROR_NOT_READY that the stand-in cannot take (none, or it failed) is one frame's matter too (AMD's FSR for that frame), never a failed upscaler.
    • The motion history written by enc0 before the bottleneck is never read: the next accepted frame is a reset.
  • Arena tables (GELU16 with 16-bit entries, rsqrt, rcp) are reserved for Model L hybrid contexts only. Model M and K keep their arena layout. If the range cannot be reserved, create is refused in one line.
    • The tables are generated in round-to-nearest whatever the caller's rounding mode, and the caller's mode is restored.
  • No silent fallback. Every kernel the route launches is required by name at create. A refused route is refused, never replaced by another route (q7 reference, M-form or HIP). The frame-time guard refuses a frame that would mix in an M-form Swin kernel.
  • One launch geometry. A Swin / GEMM geometry override (threads, windows per workgroup, nt) is refused at create for every hybrid context, before anything is allocated.
  • Release builds.
    • The check routes (WG_L_FORM=hybrid_mutant, hybrid_twin, WG_M_FORM=hybrid_mutant) exist only in developer builds; a release build refuses them at create.
    • WG_AB_FUSION / WG_AB_BLOCK and the barrier and kernel substitution hooks cannot switch the release hybrid route. They are not even read there (an invalid value cannot refuse create), and the kernels text says they were ignored.
    • A release build does not know the check routes' names at all; any other form value is refused in one generic line.
    • Release builds neither build nor embed mutants, probes or HIP twins. The ISA rules' mutants are built into a temporary folder of their own, never into the build output. build.py refuses to embed any check kernel in the D3D12 manifest, also after a partial --only build. The release gate (check_no_dev_diagnostics.py) refuses their names (architecture-prefixed ones included) and each check route's selector text.
    • The barrier and kernel-substitution hooks on the release Model M route are deferred to 0.6.6.
    • l_q7__hyb.co, l_q7w__hyb.co and l_post__lc12.co are built into the runtime library, so a deployed library alone creates the default route.
  • Driver contraction barrier. The norm's FP16 squares pass an OR with a zero the compiler cannot prove, because precise alone did not stop the driver fusing a square into the tree's adds.

Checks (all run on this branch's kernels)

  • ISA rules (hyb_isa_scan.py, inside build_dx12.py on every hybrid kernel; a finding fails the build):
    • rule 1: no fused multiply-add of a square, including a square through a copied register and the dual-issue forms;
    • rule 2: both sources of every FP8 conversion are FP16 values on every path (no RN16 dropped or folded into the FP8 pack). A scalar register counts as a constant only when a literal was moved into it on every path; an unknown scalar is not an FP16 value.
    • Fail-closed negative controls: every model hybrid kernel has its *_scanmut (no barrier, no RN16 before the FP8 pack). The build fails when one is missing, or passes rule 2, or passes rule 1 in a kernel with a norm tree. The merges and expands have no norm tree, so their mutants need to fail rule 2 only.
    • The C96 blocks keep per-lane selects in their norm tree, so no square ever feeds an add there. Their mutants also bypass the selects, so they show that rule 1 can see a fused square in C96 code; they do not test the C96 barrier itself.
    • test_hyb_isa_scan.py checks both rules on constructed ISA, including a copied-register square, a removed widening and an unknown scalar source.
    • The rules read one offline ISA (RGA, gfx1201). A later driver can compile differently, so the byte legs below stay the deciding check.
  • Oracle comparison per stage (clean/l/runner/l_hyb_stage_check.py, dump kernels; sets c32, s3, fused).
  • D3D12 == HIP bytes. Raw bytes for every C32 block (l_hyb_block_check.py) and every shared-stage block, merge and expand (l_hyb_shared_check.py).
    • --mutant fails unless every order mutant is caught, and --mutant-unchanged (the mutant leg on unmodified kernels) must fail.
  • Bottleneck queue (l_hyb_bneck_check.py). b5's bytes equal six swin_block_c128_hyb launches:
    • over 5 grids, both parities, and 1, 7, 128 and 300 workgroups;
    • the sync words return to zero, with no wait timeouts;
    • an order mutant must differ;
    • timeout control swin_bneck6_hyb_tmo (a wait gives up at its first poll): the launch completes, the abort word and the count are set and equal, every other sync word is reset.
  • Timeout refuses the frame (l_hyb_bneck_guard_check.py). A developer-only hook forces a timeout in frame 2:
    • no output write and no history write: its display, output, history and latent state keep a sentinel fill byte for byte;
    • the guard is lifted before the recording ends: work after that frame runs while the abort word is still set;
    • frame 3 is refused with exactly one log line;
    • frame 4 is a clean reset that writes them again.
    • Without the hook nothing is refused and frame 2 writes them. Both with and without a form variable.
    • A release runtime with the hook variable set behaves as without it: the hook is not in release builds, and check_no_dev_diagnostics.py refuses a library that carries it.
  • Timeout through the game path (test_interop_d3d12.exe bnecktimeout, developer runtime, the exported game interface on a game list). The game passes a different output texture on each frame and copies a sentinel into it before our dispatch. Three frames:
    • the timed-out frame: WG_OK, its output is the bilinear upscale of its own colour (within FP16 rounding), and the game's own copy after our dispatch in the same list runs;
    • the refused frame: WG_ERROR_NOT_READY, exactly one captured log line, no failure or fallback line, nothing of ours in its output (the stand-in's frame);
    • the reset frame: the network's output, byte for byte a fresh context's first frame on the same inputs.
    • Also pipelined, with up to 4 frames in flight (every frame from the timed-out one to the one before the refusal shows its own upscale), with an output texture without unordered access (the RGBA16F texture and copy route), and with a timeout on the very first frame.
  • The game's predicate (test_interop_d3d12.exe callerpred, release and developer runtimes). The game predicates its list before our dispatch and records a conditional copy after it. Predicate false: our output written, the copy runs. Predicate true: our output written, the copy is skipped. Predicate not known to the front end: WG_ERROR_NOT_READY, nothing of ours written. Then false again: the network runs.
  • Through the real front end (test_dll_d3d12.exe bneck_real: the built front-end DLL, the developer runtime with Model L, AMD's FSR available as the test double, so a takeover would show). The bottleneck times out on frame 2: frame 3 is the stand-in's, frame 4 and 5 run the network. Frame 6 is recorded into a list the front end has not tracked since its Reset: the stand-in's. Frame 7 runs the network. Every frame OK, exactly two stand-in frames, no AMD FSR line, one network context throughout.
  • An older front end's services table (test_interop_d3d12.exe oldservices): a version 2 table that ends after split_command_list is taken at create, its frames split, and the appended predicate service is never called through it.
  • Real-data runs stay private (test_l_private_out.py, test_l_mm8_private.py). l_hyb_stage_check.py --real-inputs, l_q7_check.py --real, l_q7w_check.py --real and l_mm8_f32_check.py --real write their intermediates only to --private-out, a resolved folder outside the repository. Each real-input path refuses a missing folder or one inside the repository before it reads anything. A cases file prepared from real data carries a provenance marker; every run path checks the marker and its private folder before it opens the file (the tests replace the loader with one that fails if called). A real run's --json inside the repository is refused.
  • Deployed library alone (l_hyb_deployed_check.py). The built runtime library in an otherwise empty folder creates the default Model L route and runs frames, on native D3D12 and on HIP; the folder holds only the library before and after.
  • Network byte leg. The HIP twins' unfused route against the fused D3D12 route on the recorded 1440p-Quality fixture sets: every frame is byte-identical. The same holds with no form variable set.
  • Default leg (standing rule). Every release-path check also runs once with no model or form variable, byte-identical to the explicit run. The runtime library links the CRT statically and reads its environment at load, so each environment case runs in its own process.
  • Model M and K are unchanged. Every shared code object and DXIL is byte-identical to main's, and native-D3D12 M and K frames are byte-identical to main's.
  • CPU recorder frame tests (clean/l/runtime/tests/test_l_runtime_frame.py, clean/tests/test_runtime_frame_trace.py):
    • launch order and arguments by role; mixups must fail;
    • refusal when a required kernel or the tables are missing, and of geometry overrides and release check routes;
    • the timeout guard: the launches after the bottleneck skipped, the next frame refused, the one after it a reset;
    • default vs explicit; a deployed library alone creates.
      The dev-diagnostics tests pass and the release library is clean.

Real-model data

  • Tests and fixtures use synthetic values only. The checkers are synthetic by default. Their real-data modes (l_hyb_stage_check.py --real-inputs, l_q7_check.py --real, l_q7w_check.py --real, l_mm8_f32_check.py --real) write a real run's intermediates only to --private-out, a resolved folder outside the repository; a missing folder or one inside the repository is refused before anything is read. A prepared real cases file has a provenance marker next to it and is opened only from its private folder (checked before the read), and a real run's --json goes outside the repository. Every record a real run writes is aggregate-only (counts, rates, margins, hashes). test_l_private_out.py and test_l_mm8_private.py check this.

Speed

Model L, 1440p Quality, harness, D3D12 (record: clean/l/records/l_time_1440q_hybrid_d3d12.json; median of 5 interleaved rounds):

configuration total (ms) enc0 Swin dec0 post
this branch, no form variable (release default) 4.851 1.032 1.825 0.903 1.081
this branch, WG_L_FORM=hybrid 4.853 1.032 1.825 0.903 1.082
main (Model L's previous native route; older form, see above) 3.886 0.826 1.252 0.661 1.141

The bottleneck's frame guard, its inverse-predicated fallback pass included, costs 0.0045 ms per frame: the release default against the same build with the guard compiled out, median of the per-round differences in the same interleaved rounds (in the record). Every configuration ran on the same harness, built from this branch.

Tested

  • build_dx12.py --model-l --model-k with both ISA rules, every mutant, and the VGPR limits.
  • l_hyb_stage_check.py, l_hyb_block_check.py --mutant and --mutant-unchanged, l_hyb_shared_check.py, l_hyb_bneck_check.py, l_hyb_bneck_guard_check.py, l_hyb_deployed_check.py, l_hyb_default_check.py, l_hyb_refuse_check.py, test_interop_d3d12.exe bnecktimeout, callerpred and oldservices, test_dll_d3d12.exe bneck_real.
  • The network byte leg on two fixture sets, both legs.
  • Model M and K: artifact hashes and native-D3D12 frames against main.
  • test_l_runtime_frame.py, test_runtime_frame_trace.py, test_dev_diagnostics_off.py, test_hyb_tables_cpp.py, test_hyb_isa_scan.py, test_l_mm8_kernel.py, test_l_mm8_private.py.
  • check_no_dev_diagnostics.py on the release library.

Not tested

  • In-game runs with Model L on this branch.
  • Hardware other than the one RDNA4 test card.
  • Linux / Wine.

@phantoslayer21
phantoslayer21 force-pushed the kspeed/hyb-fast-l branch 2 times, most recently from c324785 to 3524adf Compare November 16, 2026 03:42
…ith its checks and speed levers

Model L runs the hybrid block form by default on native D3D12 (no form variable needed; WG_L_FORM=hybrid
gives the same bytes): FP8 matrix chains accumulated in float32 with one FP16 rounding at each chain end,
the original's FP16 norm, softmax and GELU steps by exact tables and FP16 forms. The HIP twins
(hybrid_twin) are the byte reference.

- Kernels: the hybrid C32 blocks with the input linears as their prologue and the pack12 store as their
  epilogue; the shared-stage hybrid blocks, merges and expands; the bottleneck b0 ... b5 in one
  persistent-queue launch (swin_bneck6_hyb, bneck.hlsl's schedule around swin_block_c128_hyb's body).
- Tables: GELU16 with 16-bit entries, rsqrt and rcp, reserved in the arena for Model L hybrid contexts
  only (Model M and K keep their arena layout); a missing table range refuses create in one line.
- No silent fallback: every kernel the route launches is required by name at create; a refused route is
  never replaced by another one.
- Driver contraction barrier: the norm's squares pass an OR with a zero the compiler cannot prove;
  build_dx12.py's fused-square scan fails a build where a hybrid kernel's ISA has a fused square, and each
  hybrid kernel's scan mutant (no barrier; for the C96 blocks a substitute mutant) must fail it.
- Checks: per-stage oracle comparison with dump kernels (random weights with finite codes plus one
  NaN-input leg reported separately, and real weights), D3D12 == HIP bytes for every block, merge and
  expand, the network byte leg (HIP twins vs D3D12, both legs), default leg (each environment case in its
  own process), CPU recorder frame tests.

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
… check routes, ISA scalar sources, private real runs

- Bottleneck wait timeout in a game: the device keeps the frame guard's predicate on a caller's list until the end of
  our recording, so the executor's output pass (proxy copy or output draw) is skipped with a timed-out or queued frame;
  the refused frame travels as its own result ("refused, keep previous output": one log line, no fallback, WG_OK, the
  context kept) and the frame after it is a reset. The developer hook writes its words with fills (any list).
  Interop test (test_interop_d3d12 bnecktimeout): timed-out, refused and reset frames through the game interface,
  synchronous and pipelined.
- Release builds: the A/B hooks are not read on the hybrid route; the check routes' names are not in a release build;
  the ISA rules' mutants are built into a temporary folder, never into the build output; build.py refuses to embed a
  check kernel; the release gate refuses each selector text and architecture-prefixed check names.
- Deployed library check (l_hyb_deployed_check.py): the default Model L route from the built library alone.
- ISA rule 2: scalar registers are constants only when a literal was moved in on every path.
- l_mm8_f32_check.py: synthetic by default; --real writes intermediates only outside the repository and records only
  aggregates (test_l_mm8_private.py).

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
… stand-in, the game's predicate kept, private real-data folders

- Bottleneck wait timeout in a game: under the inverse predication on the frame guard's word, the executor writes a
  bilinear upscale of each timed-out or queued frame's colour into that frame's output texture (every output route;
  no CPU wait; the very first frame included). The refused frame takes the path of a frame not taken
  (WG_ERROR_UNSUPPORTED: the front end's stand-in renders it); the context is kept and the next frame is a reset.
- The game's predicate on its list: WgFrontEndServices::command_list_predication (appended; the front end answers from
  the state its hooks track). A guarded frame lifts it while it records and sets it again exactly at the end; a Model L
  hybrid frame whose predicate the front end cannot report goes to the stand-in.
- Interop tests: bnecktimeout with a different output texture on each frame (sentinel before the dispatch), the timeout
  on the very first frame, an output without unordered access, and the reset frame against a fresh context made in a
  child process; callerpred (predicate false, true, not known).
- Real-data modes of l_hyb_stage_check, l_q7_check, l_q7w_check and l_mm8_f32_check write only to --private-out, a
  resolved folder outside the repository (l_private.py; test_l_private_out.py).
- Speed record re-timed on the harness built from this branch (frame guard with its fallback pass: +0.0045 ms).

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…vices table taken, real cases checked before the read

- The frame after a bottleneck wait timeout, and a Model L hybrid frame whose game predicate the front end cannot
  report, answer WG_ERROR_NOT_READY, the interface's one-frame result: the front end's stand-in renders that frame,
  no takeover, and the next frame goes to the network again (the reset). WG_ERROR_UNSUPPORTED keeps its permanent
  handoff. Front end: a WG_ERROR_NOT_READY the stand-in cannot take is one frame's matter (AMD's FSR for that frame),
  never a failed upscaler.
- WgFrontEndServices: an older version 2 table is checked up to split_command_list by offset (the appended predicate
  service keeps its own size check at dispatch). Interop test oldservices.
- Real-data cases (l_q7_check, l_q7w_check, l_mm8_f32_check): a provenance marker next to every prepared real cases
  file, checked with its private folder outside the repository before the file is opened; a real run's --json is
  refused inside the repository (test_l_private_out.py: the loader fails the test if called).
- test_dll_d3d12 bneck_real: the one-frame refusals through the real front end with the developer runtime (stuck,
  stand-in, network; unknown predicate, stand-in, network; no AMD FSR takeover).

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…akeover; the stage checker marks its real cases

- DispatchWithFallback keeps WG_ERROR_NOT_READY when the stand-in cannot be created or fails its frame (never the
  stand-in's own error). The front end then gives that frame to AMD's FSR only (takeOver = false), else skips it; no
  Fail, no broken mark, no bad-frame count, and the next frame goes to the upscaler again with a reset
  (test_frontend TestNotReadyStandInFails: a stand-in that fails to create and one that fails to dispatch, with and
  without AMD's FSR).
- l_hyb_stage_check: a --real-inputs run writes the provenance marker next to its private cases.txt before any real
  file; every run checks the marker and its private folder before anything in the case folder is read
  (test_l_private_out.py StageCheckMarker).

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
@phantoslayer21
phantoslayer21 marked this pull request as ready for review November 16, 2026 08:08
@phantoslayer21
phantoslayer21 merged commit 3913cbf into main Nov 16, 2026
10 checks passed
@phantoslayer21
phantoslayer21 deleted the kspeed/hyb-fast-l branch November 16, 2026 08:08
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