d4r: official NVIDIA DLSS on AMD GPUs under Linux and Proton

docs/architecture.md

@@ -0,0 +1,90 @@
+# Architecture
+
+d4r keeps NVIDIA's DLSS library unmodified and gives it what it expects: an NGX D3D12 entry point in the game process, a CUDA driver underneath, and CUDA kernels that run. Everything between those points is translation.
+
+## Components
+
+| Piece | Where | Role |
+|---|---|---|
+| OptiScaler (in GE-Proton) | external | Hooks the game's upscaler call and forwards DLSS requests to an NGX DLL (`NvngxPath`) |
+| NGX shim `d4r_nvngx.dll` | `tools/d4r_nvngx_shim.cpp` | Implements the NGX D3D12 API. Moves inputs and output between the game's D3D12 resources and CUDA, and drives the official NGX core through its CUDA API |
+| NGX core + `nvngx_dlss.dll` | NVIDIA, supplied by you | The real DLSS: parameter handling, network selection, the CUDA kernels |
+| CUDA bridge `nvcuda.dll` | `tools/wine_nvcuda_bridge.c` | A Wine builtin whose Windows exports forward to ZLUDA's Linux `libcuda.so`, plus d4r helpers (Vulkan memory import, asynchronous 2D copies, GPU-side waits, output redirect, linear textures) |
+| ZLUDA | `patches/zluda` | CUDA driver API on HIP; compiles NVIDIA's PTX to AMDGPU code; serves native kernels in place of PTX kernels |
+| Native kernels | `kernels/` | RDNA3 implementations of the DLSS network layers and parts of texture kernels |
+| vkd3d-proton patch | `patches/vkd3d-proton` | Lets the shim split a D3D12 command list around the DLSS call |
+| NVAPI identity | `tools/d4r_nvapi_identity.c` | Reports an Ada (sm_89) GPU so NGX selects the network weights matching the PTX ZLUDA compiles |
+
+## One frame
+
+With VRAM interop and split frames (the defaults when the patched vkd3d-proton is present):
+
+1. **The game records DLSS.** Its `EvaluateFeature` call reaches the shim with the game's command list. Into that list the shim records:
+   - Vulkan commands (vkd3d-proton interop) that copy colour, depth and motion vectors into buffers exported to HIP. An R11G11B10 colour target is converted to RGBA16F on the way.
+   - A frame marker.
+   - A split. vkd3d-proton submits everything the game records after the DLSS call separately, gated on a timeline semaphore reaching this frame's number.
+   - At the start of that second part, a copy of the DLSS result into the game's output texture.
+2. **The CUDA worker queues DLSS.** A worker thread owns the CUDA context. For each frame it queues on the GPU, without waiting on the CPU:
+   - a wait for the marker (`GpuWait`);
+   - the input copies into CUDA arrays, or none when NGX samples the buffers in place (`LinearInputs`);
+   - NGX's evaluation (NGX's own CPU synchronisations are elided with `ElideNgxSync`);
+   - the result, written straight into the output buffer by the native output kernel (`DirectOutput`, preset K) or copied there.
+3. **Release.** When the GPU finishes, the worker signals the timeline semaphore and the rest of the game's frame runs, now with this frame's result.
+
+A watchdog releases any frame that never completes (for example a command list that is recorded but never executed), so the game cannot stall on DLSS.
+
+Without the vkd3d-proton patch the shim shows the newest finished result instead (one or more frames old). Without VRAM interop, inputs and output are staged through host memory.
+
+## Why each piece exists
+
+- **CUDA NGX instead of D3D12 NGX.** NVIDIA's D3D12 path needs NVIDIA's driver. The CUDA path only needs a CUDA driver API, which ZLUDA provides.
+- **The Ada identity.** NGX picks network weights by GPU architecture. The weights have to match the PTX that ZLUDA compiles, which is sm_89 for DLSS 310.
+- **Native kernels.** ZLUDA translates NVIDIA's warp-level matrix code faithfully but slowly (register pressure, lane shuffles, per-instruction mode switches). In the DLSS 4 transformer, ZLUDA's translation also produced non-finite outputs, which the final kernel masks, so the network had no effect. The native layers fix both.
+- **The GPU-side hand-offs.** With DLSS itself fast, most of the remaining gap to FSR 4 was the GPU idling while CPU threads waited on each other. Moving the waits onto the GPU raised GPU utilisation from about 95% to 99%.
+
+## Configuration
+
+`config/d4r.ini.default` documents every setting. `scripts/d4r_config.py` turns the file into environment variables for `scripts/run_game_d4r_optiscaler_proton.sh`, and an environment variable that is already set wins. The most useful switches:
+
+| d4r.ini | Environment | Effect |
+|---|---|---|
+| `[DLSS] Model` | `D4R_DLSS_PRESET` | DLSS network: `E` (CNN), `K` (DLSS 4), `M` (DLSS 4.5) |
+| `[Latency] FrameAge` | `D4R_SHIM_SPLIT_FRAME`, `D4R_SHIM_MAX_IN_FLIGHT` | 0 = same-frame results; higher values pipeline frames |
+| `[Kernels] NativeKernels` | `D4R_ZLUDA_NATIVE_DIR` | native kernel directory (`fast` / `exact` / `off`) |
+| `[Interop] VramInterop` | `D4R_SHIM_VRAM_INTEROP` | keep inputs and output in VRAM |
+| `[Interop] GpuWait` | `D4R_SHIM_GPU_WAIT` | GPU-side wait for the game's inputs |
+| `[Interop] LinearInputs` | `D4R_SHIM_LINEAR_INPUTS` | NGX samples the input buffers in place |
+| `[Interop] DirectOutput` | `D4R_SHIM_OUTPUT_DIRECT` | the output kernel writes the game-side buffer directly (preset K) |
+| `[Interop] ElideNgxSync` | `D4R_ELIDE_NGX_SYNC` | skip NGX's internal CPU waits |
+| `[Paths] JitCacheDir` | `XDG_CACHE_HOME` | where ZLUDA caches compiled kernels |
+
+## Portable installs (the release zip)
+
+The release zip (`scripts/package_release.sh`) is unpacked into the folder that holds a game's main `.exe`, like an OptiScaler release. Nothing in the Proton prefix or the system is changed.
+
+| File | Role |
+|---|---|
+| `dxgi.dll`, `OptiScaler.ini` | OptiScaler 0.9.4. Its INI sets DLSS as the DX12 upscaler and `OptiDllPath=d4r`, so OptiScaler loads the shim as `d4r\nvngx.dll`. |
+| `d3d12.dll`, `d3d12core.dll` | the d4r-patched vkd3d-proton. Proton loads DLLs from the game folder before `system32`. |
+| `d4r\nvngx.dll`, `d4r\nvcuda.dll` | the shim and the CUDA bridge |
+| `d4r\zluda\libcuda.so` | ZLUDA |
+| `d4r\kernels\<gfx target>\` | native kernels and their manifest `d4r-kernels.txt` |
+| `d4r\d4r.ini` | this game's settings |
+| `d4r\nvngx_dlss.dll`, `d4r\ngx\_nvngx.dll` | NVIDIA's files (the packager's `D4R_BUNDLE_NVIDIA=0` leaves them for the user to add) |
+
+**Settings.** When an `d4r.ini` sits next to the shim, the shim turns it into the same environment variables the developer launcher sets, with the release's defaults. A variable that is already set, for example in the launch options, wins. Settings for the Linux side (ZLUDA's and the bridge's) are handed to the bridge through `d4rSetEnv` right after it is loaded, before its first CUDA call.
+
+**Loading ROCm.** Steam runs GE-Proton 11 inside its container runtime (SteamLinuxRuntime_4), whose library search path has no ROCm. The bridge therefore:
+- loads HIP, HSA and comgr by path, from `RocmDir` (default `/opt/rocm`);
+- looks up any dependency they lack in the host's library directories, which the container mounts under `/run/host`;
+- sets `XDG_CACHE_HOME` only while ZLUDA initialises, so ZLUDA's kernel cache goes to `~/.cache/d4r` without affecting the rest of the game.
+
+**Native kernel checks.** For each kernel, `d4r-kernels.txt` lists the hash of the DLSS PTX module it was written for. ZLUDA is pointed at a per-process directory, and the bridge adds a kernel to it only when NGX loads a module with a matching hash. A DLSS version whose kernel changed therefore gets ZLUDA's compile of that kernel: slower, but correct. The bridge picks the `gfx` folder from the GPU's KFD topology entry. `DirectOutput` takes effect only while the bridge reports that NGX uses a native `hiluma_engine_output_*` kernel. That kernel is one of the texture kernels built from NVIDIA's PTX, and it is worth about 3 fps for DLSS 4 at Quality.
+
+**NGX identity and watermark.** A game that initialises NGX with a project ID (Unreal's DLSS plugin does) is passed to the NGX core's `NVSDK_NGX_CUDA_Init_ProjectID` with that ID. In this setup the DLSS library still stamps "DLSS SDK - DO NOT DISTRIBUTE" over its output. The shim sets the SDK's `Disable.Watermark` evaluation parameter unless `[DLSS] ShowWatermark = true` (`D4R_SHIM_WATERMARK=1`).
+
+**NVAPI.** The launch option `PROTON_FORCE_NVAPI=1` makes Proton enable dxvk-nvapi on the AMD driver and set `WINE_HIDE_AMD_GPU`, so Windows sees an NVIDIA PCI ID. OptiScaler's NVIDIA check accepts that, so the NVAPI identity bridge is only needed by the developer launcher. `DXVK_NVAPI_GPU_ARCH=AD100` is still required, because NGX picks its weights by GPU architecture.
+
+## Logs
+
+The launcher writes each run's logs to `~/.cache/d4r-dlss-captures/game-<exe>-<time>/`. `d4r_nvngx.log` holds the shim's log. With `[Debug] Profile = true` it also records one `D4R_PROFILE` line per frame, with the stage timings.

docs/building.md

@@ -0,0 +1,106 @@
+# Building d4r
+
+These steps produce the pieces the launcher needs: a patched ZLUDA, a patched vkd3d-proton, the NGX shim and CUDA bridge, a staged runtime directory with your NVIDIA files, and the native kernels. The versions below are the ones that were tested; others may need changes.
+
+| Component | Tested version |
+|---|---|
+| ZLUDA | `ee2f25a` (upstream), plus `patches/zluda/0002`, `0003`, `0004` in that order |
+| vkd3d-proton | `3dfc6f07` (the base GE-Proton11-3 ships), plus `patches/vkd3d-proton/0001` |
+| ROCm | 7.2 (HIP runtime, clang, device libraries) |
+| Proton | GE-Proton11-3 (with its OptiScaler integration) |
+| DLSS | `nvngx_dlss.dll` 310.7.0 |
+
+## 1. ZLUDA
+
+```sh
+git clone https://github.com/vosen/ZLUDA zluda && cd zluda
+git checkout ee2f25a
+git submodule update --init --recursive
+git lfs pull
+for p in 0002 0003 0004; do git apply /path/to/d4r/patches/zluda/$p-*.patch; done
+# rebuild the device helpers the patches changed (ptx/lib/zluda_ptx_impl*.bc)
+ZLUDA_SOURCE_ROOT=$PWD ROCM_ROOT=/opt/rocm /path/to/d4r/scripts/build_zluda_ptx_helpers.sh
+LIBRARY_PATH=/opt/rocm/lib cargo build --release -p zluda
+mkdir -p ~/.cache/d4r-zluda-current
+cp target/release/libnvcuda.so ~/.cache/d4r-zluda-current/
+ln -sf libnvcuda.so ~/.cache/d4r-zluda-current/libcuda.so
+```
+
+The launcher looks for ZLUDA in `D4R_ZLUDA_DIR` (default `~/.cache/d4r-zluda-current`, or `ZludaDir` in d4r.ini).
+
+What the patches add:
+
+- **0002**: the CUDA driver API surface NGX and DLSS use (arrays, textures, surfaces, 1010102 formats, launch parameter buffers), the PTX features DLSS kernels need, and module dumps for debugging (`D4R_ZLUDA_DUMP_DIR`).
+- **0003**: an implicit 256-thread launch bound for kernels without PTX bounds (removes massive register spilling, `D4R_ZLUDA_IMPLICIT_MAX_BLOCK`) and f16 tensor-core MMA on RDNA3 WMMA (`D4R_ZLUDA_WMMA`).
+- **0004**: the native kernel override hook (`D4R_ZLUDA_NATIVE_DIR`, see [native-kernels.md](native-kernels.md)), FP8 MMA on WMMA (`D4R_ZLUDA_WMMA_FP8`), optional elision of per-instruction denormal mode switches (`D4R_ZLUDA_IGNORE_DENORMAL`), inlined image helpers, and linking extra bitcode into a PTX module (`D4R_ZLUDA_EXTRA_BC`, used by the texture-kernel build).
+
+## 2. vkd3d-proton
+
+```sh
+scripts/build_vkd3d_proton_d4r.sh ~/.cache/d4r-vkd3d-d4r
+```
+
+The patch lets the shim split the game's command list at the DLSS call, so the rest of the frame waits (at queue level) for DLSS instead of showing the previous frame's result. Point `D4R_VKD3D_DIR` (or `VkD3DDir` in d4r.ini) at the output. Without it the shim falls back to showing a one-frame-old result.
+
+## 3. Shim, bridge and NVAPI identity
+
+```sh
+scripts/build_d4r_nvngx_shim.sh      # build/d4r_nvngx.dll   (needs x86_64-w64-mingw32-g++ and clang-cl)
+scripts/build_wine_nvcuda_bridge.sh  # build/wine-nvcuda/    (needs winegcc and winebuild)
+```
+
+The launcher builds the small NVAPI identity bridge (`scripts/build_d4r_nvapi_identity.sh`) itself.
+
+## 4. Runtime directory
+
+```sh
+scripts/install_d4r_runtime.sh /path/to/_nvngx.dll /path/to/nvngx_dlss.dll
+```
+
+This stages the shim, the bridge, the NGX core and the DLSS feature library in `D4R_RUNTIME_DIR` (default `~/.local/share/d4r-dlss`, or `RuntimeDir` in d4r.ini). The NVIDIA files come from your own sources, for example an NVIDIA driver package (NGX core) and a game or the DLSS SDK (feature library).
+
+## 5. Native kernels
+
+```sh
+D4R_ROCM_DIR=/opt/rocm \
+D4R_DLSS_DLL=/path/to/nvngx_dlss.dll \
+D4R_ZLUDA_BUILD=~/.cache/d4r-zluda-current \
+kernels/build.sh all kernels/out/native
+```
+
+`kernels/out/native` then holds one code object per replaced DLSS kernel; set `NativeKernelDirFast` in d4r.ini (or `D4R_ZLUDA_NATIVE_DIR`) to it. `kernels/build.sh k` or `m` builds only the network layers and needs neither the DLL nor ZLUDA. The texture kernels (`tex`) extract PTX from your DLL into `kernels/extracted/`; that directory and the build output are git-ignored and must not be redistributed.
+
+## 6. Configure and play
+
+The first launch copies `config/d4r.ini.default` to `~/.config/d4r/d4r.ini`. Set the `[Launch]` paths (Proton, the game's compatdata prefix and the game executable), the `[Paths]` above, and the model in `[DLSS]`, then run:
+
+```sh
+scripts/d4r_play.sh
+```
+
+In the game, pick DLSS as the upscaler (OptiScaler intercepts it). Every setting in the file can also be given as an environment variable, which takes precedence; `D4R_NO_CONFIG=1` ignores the file.
+
+## 7. Package a release
+
+```sh
+D4R_OPTISCALER=/path/to/OptiScaler_0.9.4.7z \
+D4R_DLSS_DLLS=/path/to/310.7/nvngx_dlss.dll:/path/to/310.9/nvngx_dlss.dll \
+D4R_BUNDLE_DLSS=/path/to/nvngx_dlss.dll D4R_BUNDLE_NGX=/path/to/_nvngx.dll D4R_BUNDLE_TEX=kernels/out/native \
+D4R_ZLUDA_DIR=~/.cache/d4r-zluda-current D4R_VKD3D_DIR=~/.cache/d4r-vkd3d-d4r D4R_ROCM_DIR=/opt/rocm \
+scripts/package_release.sh            # -> dist/d4r-<version>.zip
+```
+
+The script:
+- builds the shim, the bridge and the network-layer kernels;
+- writes the kernel manifest from the DLLs you list (it records hashes of their PTX, nothing else);
+- stages OptiScaler as `dxgi.dll` with the settings in `packaging/optiscaler.settings`;
+- adds NVIDIA's two DLLs and the texture kernels (built from NVIDIA's PTX by `kernels/build.sh tex`);
+- zips the result together with the ZLUDA and vkd3d-proton builds, `packaging/d4r.ini`, the licenses and the patches.
+
+The NVIDIA files are not covered by d4r's license; redistributing them is up to whoever publishes the zip. `D4R_BUNDLE_NVIDIA=0` builds `d4r-<version>-nonvidia.zip` without them and without the texture kernels. [architecture.md](architecture.md#portable-installs-the-release-zip) describes how the installed files work together.
+
+## Checks
+
+- `scripts/check_environment.sh` lists the tools, GPU and Proton builds it finds.
+- The D3D12 harness (`scripts/run_d3d12_dlss_harness_proton.sh`) drives DLSS outside a game.
+- Native kernels have their own validation path; see [native-kernels.md](native-kernels.md).

docs/native-kernels.md

@@ -0,0 +1,94 @@
+# Native kernels
+
+The native kernels are RDNA3 (gfx11) code objects that ZLUDA runs in place of specific DLSS kernels. Each one has the same name, launch shape and parameter block as the PTX kernel it replaces, and reads the same buffers, including the network weights inside NVIDIA's DLL. No weights or NVIDIA code are stored here.
+
+## The override hook (patches/zluda/0004)
+
+With `D4R_ZLUDA_NATIVE_DIR=DIR`, whenever NGX loads a PTX module and asks for kernel `NAME`, ZLUDA looks for `DIR/NAME.hsaco` and uses its kernel `NAME` instead. The code object can export:
+
+| Symbol | Meaning |
+|---|---|
+| `NAME_prep` kernel | launched first on the same stream, with the same parameters (typically re-lays out weights) |
+| `u32 d4r_prep_blocks` | grid size of the prep kernel (128 threads per block) |
+| `u32 d4r_prep_key_offset` | byte offset of a u64 in the parameter block; the prep is skipped while that value (the weights pointer) repeats |
+| `u32 d4r_block_z` | replaces the launch's block z dimension (more waves per window) |
+| `u32 d4r_grid_x` | replaces the grid (persistent kernels) |
+
+Kernels without a file in `DIR` are compiled from PTX as usual, so a partial set works.
+
+**Release directories.** A directory that holds `d4r-kernels.txt` (or `<gfx target>/d4r-kernels.txt`) is checked before use:
+- `kernels/tools/kernel_manifest.py DIR nvngx_dlss.dll...` writes the manifest. For each `NAME.hsaco` it records the FNV-1a 64 hash of the PTX module that defines `.entry NAME`, taken from each DLL given.
+- The CUDA bridge serves a kernel only after NGX has loaded a module with one of the listed hashes.
+- It picks the target folder from the GPU's KFD topology entry.
+
+The release is built this way, with hashes from DLSS 310.7.0 and 310.9.1. The PTX of every replaced kernel is identical in those two versions.
+
+## Families
+
+**DLSS 4, preset K (`kernels/k`, `dltss_pwin_*`).**
+- **Network:** a Swin-style U-Net of eleven layers over 8×8 token windows. There are encoders enc0–enc4 with 2×2 patch merging, a bottleneck dec5, and decoders dec4–dec0 with patch expansion and skip inputs. The window attention is either learned (query × key plus a bias table) or position-only (a fixed table times the values).
+- **Templates:**
+  - `pwin_layer.h`: four waves per window, each owning a 16-token tile.
+  - `pwin_pos.h`: position-only layers with two token tiles per wave, which halves weight traffic.
+  - `pwin_wide.h`: the deep layers, which have only 6–77 windows per frame. It uses 4·NG waves per window, split by token tile and channel group, so the GPU stays busy.
+- **Weights:** prep kernels expand the weights into WMMA operand images once.
+
+**DLSS 4.5, preset M (`kernels/m`, `rrlite_*`).**
+- **Network:** the Swin blocks of DLSS 4.5, whose weights are FP8. Their prep kernels expand the weights to f16 WMMA operands.
+- **Template:** `swin_block.h` covers encoders, the tube-shaped enc3 and decoders.
+
+**Texture kernels (`kernels/tex`).**
+- **The problem:** some DLSS kernels are mostly texture sampling and scalar maths that ZLUDA already compiles well, apart from a few slow parts.
+- **The approach:** for those, `make_ptx.py` edits NVIDIA's PTX (extracted from your DLL at build time):
+  - surface stores become calls into `tex_common.h`;
+  - the `roundf` idiom that forces ZLUDA into strict-FP mode is rewritten exactly;
+  - for M's enc0 and dec0, a range of the kernel is replaced by a native tail or head.
+- **Build:** ZLUDA compiles the edited PTX with the HIP bitcode linked in (`D4R_ZLUDA_EXTRA_BC`), and the resulting code object is saved.
+- **Output redirect:** the K output kernel (`hiluma_engine_output_*`) can also write its result straight into the shim's output buffer instead of a CUDA array. See `D4R_SHIM_OUTPUT_DIRECT` in [architecture.md](architecture.md).
+
+## Numerics
+
+NVIDIA's tensor-core code rounds its f16 accumulator after every 16-deep step. The native kernels either do the same (bit-exact against the reference models) or keep f32 accumulators through a chain (`PWIN_F32ACC`, `SWIN_F32ACC`). The f32 version is more accurate than NVIDIA's own rounding, and its replayed output differs from the exact one by about 66 dB PSNR, which is invisible.
+
+The installed K set uses f32 accumulation for enc0–enc2 and dec0–dec2 and exact rounding for the deep layers. The M set uses the fast numerics throughout.
+
+## Building
+
+```sh
+kernels/build.sh k          # DLSS 4 layers   (ROCm clang only)
+kernels/build.sh m          # DLSS 4.5 layers
+kernels/build.sh tex        # texture kernels (needs D4R_DLSS_DLL and D4R_ZLUDA_BUILD)
+kernels/build.sh all DIR    # everything into DIR (default kernels/out/native)
+```
+
+`D4R_GPU_ARCH` selects the target (default gfx1101). All kernels need gfx11 WMMA.
+
+## Validating a kernel
+
+1. **Capture launches.** Set `D4R_CUDA_REPLAY_DUMP_DIR` (with `D4R_CUDA_REPLAY_DUMP_FILTER=<kernel name>`) while running the D3D12 harness or a game. The bridge then writes each matching launch as `manifest.txt`, `args.bin` and one `alloc-N.bin` per buffer.
+2. **Run the native kernel on a capture.** Build `kernels/tools/dump_runner.cpp` with hipcc. Then run:
+
+   ```sh
+   PREP_GRID=<d4r_prep_blocks> dump_runner NAME.hsaco NAME <capture> <out> 30
+   ```
+
+   It runs the prep and main kernels, saves every buffer after the first launch, and times 30 launches.
+3. **Compare against a reference.** `kernels/tools/pwin_model.py` (K) and `swin_model.py` (M) are numpy models of the layers, written stage by stage against `ptxsim.py`, a small vectorised PTX interpreter that runs NVIDIA's kernels on the CPU. A bit-exact variant should match the model within f16 rounding; after any change, compare the new build's buffers with the previous build's.
+4. **Check the whole pipeline.** Replay captured frames through the harness with both kernel sets and compare the outputs with `kernels/tools/psnr.py`. `D4R_CUDA_KERNEL_PROFILE=1` makes the bridge time every kernel; `kernels/tools/kprof.py` summarises the log per frame.
+
+## Per-kernel cost
+
+GPU time per frame at Quality (1705×960 → 2560×1440, RX 7700 XT), from `D4R_CUDA_KERNEL_PROFILE`:
+
+| DLSS 4 (K) | ms | DLSS 4.5 (M) | ms |
+|---|---|---|---|
+| hiluma output (texture kernel) | 0.82 | enc3 tube (6 launches) | 1.42 |
+| dec0 | 0.30 | enc1 | 1.27 |
+| enc0 | 0.28 | dec1 | 1.18 |
+| dec1 | 0.24 | enc2 | 0.79 |
+| hiluma input (ZLUDA) | 0.24 | post (texture kernel) | 0.77 |
+| enc1 | 0.21 | dec2 | 0.69 |
+| enc2, dec2 | 0.10 each | enc0 (texture kernel) | 0.60 |
+| enc3, dec3, enc4, dec4, dec5 | 0.05–0.08 each | dec0 (texture kernel) | 0.46 |
+| NGX exposure and misc | 0.1 | downsample, NGX misc | 0.36 |
+| **total** | **2.8** | **total** | **7.5** |

docs/performance.md

@@ -0,0 +1,59 @@
+# Performance
+
+## Method
+
+- **Hardware and settings:** Radeon RX 7700 XT (RDNA3, 54 CUs), Ryzen 9 5900XT, Linux 6.18. SILENT HILL Townfall at 2560×1440 output.
+- **Route:** every run plays the same scripted 62-second walk through a street, with fog, wires, fences and signage.
+- **Frame rate:** from MangoHud's per-frame log over the walk, as frames divided by the sum of frame times.
+- **Pairing:** runs are compared back-to-back in one session, because repeated runs of an identical setup vary by about 1%.
+- **Screen recording:** it costs a few fps, so recorded videos show slightly lower numbers than the table.
+- **Latency:** all DLSS numbers are same-frame (frame age 0). Every frame shows its own DLSS result, as with a native upscaler.
+- **Other upscaler modes:** Balanced, Performance and Ultra Performance use OptiScaler's render-ratio override (1.72, 2.0, 3.0) on top of the game's Quality mode.
+
+## Results
+
+| Mode (render resolution) | DLSS 3 CNN (E) | DLSS 4 (K) | DLSS 4.5 (M) | FSR 4 |
+|---|---|---|---|---|
+| Quality (1705×960) | **72.4** | 69.4 | 51.5 | 76.0 |
+| Balanced (1488×837) | **80.5** | 76.6 | 59.6 | 84.5 |
+| Performance (1280×720) | **87.8** | 84.0 | 69.9 | 94.0 |
+| Ultra Performance (853×480) | 88.9 | **94.5** | 90.3 | 107.3 |
+| Native 2560×1440, no upscaling (TSR at 100%) | | 49.1 | | |
+
+DLSS 4's cost is almost constant across modes (about 2.8 ms of GPU time per frame). Its network runs on a grid set by the output resolution, not the render resolution, so the gap to FSR 4 widens as the render resolution drops. The CNN gets more expensive at the 3× ratio, so K is the better choice at Ultra Performance.
+
+## What each step contributed
+
+DLSS 4 (K) at Quality, frames per second on the walk:
+
+| Step | fps |
+|---|---|
+| ZLUDA only: the transformer's outputs were non-finite, so the network had no effect | 58.5\* |
+| All eleven K layers native | 65.0\* |
+| Wide deep layers, f32 accumulation, cheaper operand transposes | 66.0 |
+| NGX's CPU syncs removed, faster marker polling, no sync before the output copy | 66.7 |
+| DLSS queued behind a GPU-side wait for the inputs (GPU busy 95% → 99%) | 68.0 |
+| Native output kernel writes the game-side buffer directly | 68.4 |
+| NGX samples the input buffers in place (no array copies) | 69.4 |
+
+\* Measured from the shim's frame log on a similar stretch, before the MangoHud method was in use.
+
+DLSS 4.5 (M) at Quality went from 28 fps (ZLUDA only) to 42 with the first native Swin layers, 46 with more waves per window, 50 with fast numerics and the texture-kernel tails, and 51.5 with the hand-off changes.
+
+## What did not help
+
+- **Accumulating in f16 on the WMMA units.** The error grows about 20× and the image degrades.
+- **Occupancy tweaks** (VGPR caps, waves-per-EU hints) and **persistent work-groups.**
+- **Non-temporal hints** for activation traffic.
+- **Splitting the position-only layers by channel** instead of by token. It halves weight traffic but serialises the compute.
+- **Mapping the Vulkan buffers directly as HIP arrays.** ROCm 7.2 does not export `hipExternalMemoryGetMappedMipmappedArray`.
+- **Signalling the game's Vulkan timeline semaphore from HIP.** HIP does not import timeline semaphores, so the end of DLSS is still signalled from the CPU.
+
+## Where the time goes now
+
+For DLSS 4 at Quality the GPU spends about 2.8 ms per frame in DLSS kernels:
+- NVIDIA's output kernel: 0.82 ms. It is ALU-bound at close to the GPU's instruction rate.
+- The eleven network layers: 1.6 ms.
+- The input kernel, exposure and miscellaneous kernels: about 0.35 ms.
+
+The game-side input and output copies add about 0.3 ms. [native-kernels.md](native-kernels.md) lists every kernel.