Skip to content

Model K on D3D12: the runtime on the hybrid and native devices, byte-identical to HIP frame by frame - #215

Merged
phantoslayer21 merged 11 commits into
mainfrom
k/runtime-d3d12
Nov 15, 2026
Merged

phantoslayer21 merged 11 commits into
mainfrom
k/runtime-d3d12

Conversation

@phantoslayer21

@phantoslayer21 phantoslayer21 commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Refs #15. Based on main (the K stack through #211 is merged): PR 9 of the Preset K port.

Preset K's runtime on the Direct3D 12 devices. The exact default path runs on the D3D12 ports (#201 to #210 and this PR) and its frames are byte-identical to the HIP backend's. The native executor (the game's own D3D12 device, which reads the game's textures) runs model K with its own direct forms; there is no HIP route for K in a game: a context the D3D12 executor cannot take is refused at create with one log line and the game keeps its own upscaler, and a frame it does not take goes to the front end's own upscaler (executor=hip and the frame capture stay opt-in diagnostics with a loud log line).

What changes

  • New D3D12 ports (byte-identical to HIP, evidence below):
  • runtime_k.cpp, runtime_k.h:
    • backend 2 (hybrid device) and backend 3 (native device) run the tiled input stage, or the legacy input kernels where the tiled guard does not apply, k_out_color, the eleven stage kernels as network() names them (including the NG choice of e4 / d4) and k_out_pixel_c / k_out_pixel; a native direct frame takes the _direct form of each kernel that reads the inputs or writes the output;
    • d3d12_kernels() lists every kernel a context can select (tiled, legacy, direct forms, stages, output, k_warm, timing_barrier); on backend 3 create checks all of them against dx12/manifest.json and refuses a context with an option that leaves the exact path (network=fused16 / fused8, k_fast=1, k_fast_in=1, k_in_exact=0, k_diag), naming the cause, before the model is loaded. An input-copy frame (raw_inputs, the interop's HIP copies) is refused on the D3D12 devices;
    • options that change no value: k_color_at, k_warm / k_warm_to / k_warm_line / k_warm_groups.
  • model_select.h, runtime.cpp: Model K is a native-D3D12 model; create_k makes the native device on backend 3 and passes the direct-frame flag; direct_preflight asks K (finite jitter and a render size within the configured maximum; every ratio up to 1.0 runs).
  • executor_select.h, backend.cpp, executor_d3d12.cpp (model K never runs on HIP in a game):
    • auto on an RDNA 4 adapter is the D3D12 executor, always; K's timing marks are described; motion_outres=point for K on the D3D12 executor;
    • the sparkle guard (HIP only) is turned off for K with one log line and never moves K to HIP; the frame capture and executor=hip are opt-in diagnostics that select HIP with a loud line ("diagnostic: ..."); executor=hip is a loud diagnostic for every model;
    • hip_switch is ignored for K (one line when it is set); a frame the D3D12 executor does not take (no output texture, a render size outside the configured maximum, an output texture without unordered access, any "frame not taken") is answered WG_ERROR_UNSUPPORTED, exactly like model M's refused frames with hip_switch=off: no K-only state, and the front end gives the frame an upscaler (AMD FSR when it exists, else its stand-in). K never goes to HIP and never to the bilinear fallback, by default and with executor=dx12;
    • when the D3D12 executor cannot take a K context at create, create fails with one error line (dx12_refused_line_k): the fall-back to the HIP executor is removed for K;
    • unchanged and shared with the other models: auto on an adapter that is not an RDNA 4 Radeon (or not identified) picks HIP with one log line (the owner's RDNA 2 / 3 question, in the R1 audit).
  • NG = 4 forms of e3 and d3 (k_stagew4_e3, k_stagew4_d3) are not ported because no context can reach them. wide_ng in runtime_k.cpp gives e3 and d3 NG = 2 on the exact network whatever the window count, the sizes or the options (only e4 and d4 look at the window count); the FP16 networks take other kernels and are refused on the native device. clean/k/tests/test_k_wide_ng.py pins the rule, the two places that build kernel names and the declared kernel set, so a change that makes the form reachable fails until it is ported and checked.
  • Runtime test hook: option k_fill=<0..255> fills every buffer a frame writes and both history copies with that byte after allocation (documented in clean/k/README.md; it changes no value a frame writes).
  • Front end test: test_frontend.cpp TestRefusedFrames runs the real refused-frame policy (executor_select.h) through the front end for model K and, as the control, model M, with and without AMD's FSR: every frame has an upscaler (with AMD, it takes the context at the first refusal as for M; without it each refused frame, five in a row included, goes to the stand-in and the next frame the network can take is the network's) and no HIP runtime is started. The shared front-end path needed no change.
  • Tests: test_k_runtime_d3d12.py (GPU), raw_compare.py / test_k_raw_compare.py (CPU), test_k_wide_ng.py (CPU), test_k_port_check_nan.py (CPU); test_k_runtime_gpu.py takes a backend; test_executor_select.cpp follows the refusal rule; two source-inspection tests follow the shared header.
  • Port check (clean/k/dx12/k_port_check.py): families legacy, direct (now with k_out_pixel_direct) and directleg; kernel_replay binds the textures of a direct frame in a chain.
  • Docs: clean/k/README.md, clean/k/dx12/README.md.

Accepted exceptions (review decision, 2026-11-14)

  • NaN sign: with NaN in the inputs, the decoder stages produce NaN at exactly the same elements on D3D12 and HIP, but the NaN sign can differ. Every non-NaN byte is identical. A NaN sign carries no value (NaN propagates), so this is accepted as a documented exception to raw-byte identity; the port check keeps counting these elements separately. The check masks the sign bit only: the exponent, the quiet bit and the payload must be equal (test_k_port_check_nan.py).
  • FP32 denormals: D3D12 flushes FP32 denormals where HIP keeps them, the same accepted behaviour as the Model M ports. The check inputs avoid denormals.

Tested

  • Port checks against HIP on the hardware (raw bytes, per-run sentinels HIP 0xA5 / D3D12 0x5A, 64 slack bytes, a half-grid negative control caught in every family, special values including NaN, Model M's scale_rgb as a control; 2 seeds; record direct-r1-s2.json, a first 1-seed run direct-r1.json and legacy1.json of the legacy family alone):
    • legacy: 32 of 32 cases raw-byte identical (the inputs, the intermediates cpre / cpre2 and x0; every fourth case at render size = output size or with a jitter outside the guard);
    • direct: 60 of 60 raw-byte identical (kx/k_in_tiled_direct, k_out_color_direct + k_out_pixel_c_direct / k_out_pixel_direct in RGBA16F and RGBA32F outputs, k_expo_scalars_direct; real textures bound as a direct frame, reference = HIP's raw-buffer route KIO_C16 / KIO_M16 with the motion scale and offset folded);
    • directleg: 32 of 32 raw-byte identical (kx/k_in_color_direct + kx/k_in_base_direct, and kx/k_in_reset as a direct frame runs it; DLAA 1.0 and jitter outside the guard included).
  • Front end: test_frontend.cpp 1319 checks, 0 failures (built with clang++ here; in CI through ctest), including the refused-frame cases for K and M.
  • Port check re-run with the sign-only NaN rule (same hardware, 2 seeds, records recheck-1.json, recheck-2.json): input, legacy, output, directleg 32 of 32 and direct 60 of 60 raw-byte identical, the half-grid negative controls caught; narrow 120 of 120 (111 raw-byte identical, 9 differing only in the NaN sign) and wide 84 of 84 (72 raw-byte identical, 12 differing only in the NaN sign); every difference is a NaN-sign difference.
  • Frame by frame against HIP (test_k_runtime_d3d12.py, a synthetic model K, the same frames through the HIP backend and a D3D12 device; before each frame the output and the intermediates k.x0, k.S0 to k.S4, k.A, k.B, k.ctap, k.ctapT, the head buffer, exposure.pair and k.scalars are filled with a sentinel (HIP 0xA5, D3D12 0x5A); after it the output (the RGBA16F rows as stored, or the dense RGB, no float conversion), those buffers, exposure.measured and the histories k.Hc, k.L, k.Hh are compared as raw 4-byte words, k_fill gives HIP 0xA5 and D3D12 0x5A in every frame-written buffer and in the histories before the first frame, a word that neither side wrote fails, a missing buffer fails, and a dropped write in the real output is checked to be caught). Each test in its own GPU slot; 22 of 22 pass:
    • hybrid device: HDR with a value, with the game's exposure texel (dense output), with auto-exposure, LDR, k_head=full, k_in_uniforms=0, 1440p Quality, 4K Performance, DLAA 1.0 (HDR rows and LDR dense), a jitter outside [-0.5, 0.5], input_tiled=0; every kernel of the frame must have run on D3D12 in the launch trace and no model K kernel on HIP;
    • native device: HDR value (rows), HDR auto-exposure (dense), LDR (rows), 1440p Quality, DLAA 1.0, jitter outside the guard, input_tiled=0;
    • the k_fill hook reaches both backends (the runtime's unused input copy keeps 0xA5 / 0x5A);
    • refusals: an approximation option (network=fused16, k_fast=1, k_in_exact=0) on the native device ends create with one line naming HIP; an input-copy frame is refused on both D3D12 devices with one line.
  • HIP regression: test_k_runtime_gpu.py 20 of 20 on the same build.
  • CPU: all non-GPU K tests (133, 43 skipped for lack of a GPU or the Linux emulator), test_kernel_sets, test_executor_select (built with clang++; the routing rules of model K, one test per refusal path and per option) pass; the model-K-free and the model-select tests are unchanged.
  • public_gates.py: must-pass gates pass, LOOK counts equal main's.

Not tested

  • The D3D12 executor in a game with these forms (the Cyberpunk record is a separate step, the release lead's K3, and states which executor ran).
  • k_warm / k_color_at effect on speed (they change no value; no timing is claimed here).
  • k_in_tiled_uniform is covered through the hybrid device (the host's frame values), k_in_tiled through k_in_uniforms=0; the native executor has no host frame values and runs k_in_tiled_direct.
  • exposure_auto_diet_direct is Model M's kernel (its own port evidence); K's use of it is covered by the native auto-exposure frame test through the buffer form and by the in-game record only.
  • Real model weights.

… byte-identical to HIP frame by frame

Refs #15. runtime_k.cpp: the exact default path runs on backend 2 (hybrid) and backend 3 (native): the tiled input kernels (with the host's frame values, or computed on the GPU: k_in_uniforms=0), k_out_color, the stage kernels as network() names them, k_out_pixel_c / k_out_pixel; on backend 3 create refuses, before the model is loaded, a context with an option that leaves the exact path or a kernel without a port in dx12/manifest.json (the HIP executor then runs it). Latency options that change no value: k_color_at, k_warm (k_warm, k_warm_to, k_warm_line, k_warm_groups). Model K is a native-D3D12 model in the model table; runtime.cpp makes the native device for it and gives K the direct-frame preflight; the executor choice takes K on RDNA 4 by default (kernels checked at create); the D3D12 executor describes K's timing marks; the backend names motion_outres=point for K. The forms that read the game's textures (_direct) are in the sources and not declared yet, so the D3D12 executor refuses K at create until they are.

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
@phantoslayer21
phantoslayer21 marked this pull request as ready for review November 14, 2026 23:19
Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…and checked

Ports of kx/k_in_color, kx/k_in_reset and kx/k_in_base (the legacy exact input
stage the runtime takes above 0.68 x the output size, up to 1.0, and for a
jitter outside [-0.5, 0.5]) and of their direct forms kx/k_in_color_direct and
kx/k_in_base_direct. The shared input-stage helpers move into
hlsl/k_in_common.hlsli (kx/k_in_tiled's DXIL is unchanged). The direct forms
kx/k_in_tiled_direct, k_out_color_direct, k_out_pixel_c_direct and
k_out_pixel_direct are declared.

k_port_check.py: families legacy, direct (now with k_out_pixel_direct) and
directleg; kernel_replay.cpp binds the textures of a direct frame in a chain
(output texture, queued copies synchronised before release). The NG = 4 forms
of e3 and d3 are unreachable: test_k_wide_ng.py pins wide_ng, the two places
that build kernel names and the declared kernel set.

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…on the D3D12 executor

A native direct frame names the _direct form of k_in_color / k_in_base when the
tiled input stage does not apply; k_in_reset reads buffers. d3d12_kernels()
lists every kernel a context can select (tiled, legacy, direct forms, stages,
output, k_warm, timing_barrier) and create checks all of them. input_copy
frames (raw_inputs) are refused on the D3D12 devices.

When the D3D12 executor cannot take a model K context, create ends with one
error line and the game keeps its own upscaler: no fall-back to the HIP
executor for K (executor=hip stays an opt-in diagnostic).

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…controls

The frame parity tests fill the output and every compared intermediate with a
sentinel before each frame (HIP 0xA5, D3D12 0x5A), compare raw 4-byte words
(the RGBA16F rows as stored, no float conversion), fail on a missing buffer,
and check that a dropped write is caught. New cases: render size = output size
(DLAA 1.0), jitter outside the tiled guard, input_tiled=0, the refusals of an
approximation option and of an input-copy frame.

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…IEW-215b)

Executor selection for model K (executor_select.h, backend.cpp): auto on RDNA 4
is the D3D12 executor always; the sparkle guard (HIP only) is turned off for K
with one line and never moves K to HIP; the frame capture and executor=hip are
opt-in diagnostics with a loud line; hip_switch is ignored for K (one line when
set). A frame the D3D12 executor does not take goes to the front end's own
upscaler (WG_ERROR_UNSUPPORTED), never to HIP and never to the bilinear
fallback, by default and with executor=dx12; three in a row end the context
with one line. Tests for each path (no output texture, render size outside the
maximum, unsupported frame, hip_switch=on) in test_executor_select.cpp.

k_port_check.py: the NaN exception masks the sign bit only (exponent, quiet bit
and payload must be equal); test_k_port_check_nan.py.

Runtime option k_fill=<byte> (test hook): every frame-written buffer and both
history copies start with it after allocation; the frame tests give HIP 0xA5 and
D3D12 0x5A, so first-frame and reset-only writes are proven, and a test checks
that the hook reaches both backends.

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…REVIEW-215c)

Drop the model K three-refusal counter and its WG_ERROR end of the context:
every refused K frame is answered WG_ERROR_UNSUPPORTED, exactly like model M's
refused frames with hip_switch=off (refused_frame_action has no K state), and the
front end gives the frame an upscaler (AMD FSR when it exists, else its
stand-in). K never goes to HIP and never to the bilinear fallback.

test_frontend.cpp: TestRefusedFrames drives the real policy through the front end
for model K and, as the control, model M, with and without AMD's FSR: every frame
has an upscaler (the stand-in for each refused frame, five in a row included),
and no HIP runtime is started. test_executor_select.cpp follows the policy.

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