Skip to content

Latest commit

 

History

History
383 lines (322 loc) · 108 KB

design.md

File metadata and controls

383 lines (322 loc) · 108 KB

Design notes

Groundwork for running the Xbox Series build of GTA VI natively on Windows. The work that does not need the executable is in place; booting can start as soon as game_scarlett_master.exe is available.

Ground rules

  • Everything here runs from your own copy and stays on your PC. Game files, generated code, shader caches and reports that quote game data are never committed, uploaded or shared. reports/ is git-ignored for this reason.
  • Nothing in this folder decrypts, unpacks or works around Xbox package protection. The tools only read files that are already plain on disk.

Why a loader before a recompiler

The Xbox Series CPU is x86-64, the same as a PC. Unlike Hookshot, where ARM64 code has to be translated, most of the game's code can run as-is. The work is everything around it:

Layer Approach Folder
CPU code Map the PE image and run it natively. Patch only what can't run on desktop (privileged instructions, console-only intrinsics). Each mapped image's .pdata is checked (in bounds, sorted, non-overlapping; zero-length entries allowed, as in System32's symcryptk.dll) and registered with RtlAddFunctionTable, so SEH/C++ exceptions and stack walks unwind through its frames. The loader also installs static TLS for the calling thread. runtime/src
Imports (GameOS / GDK / Xbox DLLs) Every imported dll!function goes to a shim. Unimplemented ones log once and return a failure, so the missing surface shows up at runtime. runtime/shims
Graphics Xbox D3D12 (d3d12_xs) to Vulkan. Shaders ship as compiled RDNA2 machine code; tools\rdna2spirv.py translates all 26,503 to SPIR-V. The D3D12 layer is still to do. tools\ (translator), later (D3D12)
Assets .rpf archives (RPF9) read through the runtime's file layer. later

Layout

tools/       Python analysis tools (no game data inside)
  pe_inspect.py   PE headers, sections, entropy, imports sorted by where they resolve, .pdata, TLS
  rpf_probe.py    RPF header survey of a game folder
  manifest.py     SHA-256 manifest of a game folder, plus a --verify mode
scripts/
  first_look.ps1  run once the exe arrives: the full report set for it
runtime/     C++ native loader (CMake + Ninja, MSVC)
  src/            PE mapper, relocations, import binding, TLS
  shims/          per-DLL shim tables
reports/     generated output (git-ignored)
docs/        notes

Day one, when the exe is here

.\scripts\first_look.ps1 -Exe "<game>\game_scarlett_master.exe"

This writes reports/exe/ (JSON plus a readable summary). Check it in this order:

  1. Section entropy. Sections near 8.0 bits/byte are still encrypted or compressed. If .text is one of them, nothing else can be done yet.
  2. Import table. Each DLL is marked bundled (in the game folder), system (present on this Windows), or shim (needs a reimplementation). The shim list is the real to-do list.
  3. .pdata function count. This gives function boundaries for patching and later analysis.

Then runtime\build\gta6rt.exe --dry-run <exe> maps the image and binds every import to the shim table without running any game code. It reports what it couldn't bind.

Reproduce the shader tests

Build the hand-written tests where LLVM supports AMDGPU and SPIRV-Tools is available. Run the generated shaders with the Vulkan test tools on the target GPU. Use the same output folder in both commands.

python -I runtime/test/shaders/build.py <out>
python -I runtime/test/shaders/check.py <out> [runtime-build-directory]

The wave-mask fixture checks every lane and the wave64 ballot fixture checks mask counts and first-set lanes across both halves of a wave. Rebuild vk_compute_test before running check.py. It uses a full 64-wide compute subgroup for these two checks, and the summary reports them as skipped if the device cannot provide one. cs_exec64 still checks per-lane EXEC writes on 32-wide subgroups. With LEONIDA_W64_EMULATE=1 in the environment of both commands, build.py translates with --wave64-emulate and check.py runs every wave64 check without asking for a 64-wide subgroup, so a 32-wide GPU runs them all (scripts/run_gpu_tests.py honours the same variable). Pick one of several GPUs with the Vulkan loader, e.g. VK_LOADER_DRIVERS_SELECT='*nv*' or '*amd*'. The flat-input fixture checks both integer IDs and interpolated UVs. The corpus comparison is a separate test and uses shader files from the local build.

On macOS the test tools default to MoltenVK. To test another Vulkan driver, set LEONIDA_VULKAN_LOADER to the standard loader dylib and VK_DRIVER_FILES to the driver's ICD manifest, for example LEONIDA_VULKAN_LOADER=/path/to/libvulkan.1.dylib VK_DRIVER_FILES=/path/to/lvp_icd.json. These tools do not request portability enumeration, so use the default for MoltenVK.

Run python -I scripts/run_gpu_tests.py --filter ms_v5_workgroup to check the mesh workgroup index. The synthetic shader exports its incoming v5 from lanes 0, 1 and 31 in the RGB channels of a full-screen triangle. One vkCmdDrawMeshTasksEXT(2, 3, 4) produces 24 triangles. A stencil countdown lets pixel i record only triangle i in Vulkan rasterization order. For g = x + 2*y + 6*z, the CPU compares each pixel with (32*g, 32*g + 1, 32*g + 31, 1) (the 32-thread fixture's g * NumThreads + lane values). This checks the translator's register mapping on the host GPU. SPIRV-Tools 2026.1 validates this fixture. Version 2025.1 reports a known error on CullPrimitiveEXT. Vulkan mesh rasterization order · Validator fix.

Build the runtime

.\scripts\build_runtime.ps1

It sets up MSVC through vcvars64.bat and builds at BelowNormal priority on half the cores, writing to runtime\build\. If VS's "C++ CMake tools" component is installed, it uses CMake and Ninja. Otherwise it calls cl directly. That component may not be installed, and the devkitPro MSYS cmake on PATH can't build MSVC projects. When you add a source file, add it to runtime\CMakeLists.txt and to the file list in build_runtime.ps1.

Asset status (no exe needed)

Asset State Where
Archive data Carved without the encrypted tables of contents. Most archives are 93–99% plain zlib (levels.rpf 98.3%, 1.1M files; full census 23,535 placement maps / 1,670,442 entities). Not zlib: audio.rpf (99.9%), about half of story000.rpf and shared_minigame000.rpf. <work>\carve\<archive>\, coverage.json; world_census.md
Videos 797 Bink 2 files (KB2n), cut out whole. *.bk2 in the carve folders
Shaders 26,503 carved from shaders.rpf, native RDNA2 code unpacked (FSSM), disassembled, and translated to SPIR-V; all validate (see Translator status). <work>\shaders\ (.dxbc, fssm\, disasm\, spirv\)
Textures Solved. Headers are in CPU segments: GPU pointer at q[k], u16 width/height/depth and DXGI format at q[k+4], mip count at byte 2 of q[k+5]. Data is AMD SW_4K_S tiled, largest mip first. The GPU segment is the blob run after the CPU blob. On 200 samples, 173 decode at least 1.5× smoother detiled than untiled (median 2.56×). Exports the top mip, slice 0, as DDS. 22,342 exported (1.23 GiB): every header whose GPU data follows its CPU blob. World and model textures are handled by the TXD and TTPF exporters below. GPU offsets must be 256-byte aligned, which drops the false headers in navmeshes/anim. tools\tex_headers.py, tools\tex_export.py, <work>\textures\
Models Done: 350,248 models at the 917e9b9 pin (levels.rpf 314,000, story000 7,460, packs 24,034, data 2,581, shared_minigame000 1,288, core_restofworld 885; 0 decode failures in the re-count). The c3708fb export was 190,792; the new entries are 159,483 drawable-dictionary children (levels 130,225, packs 23,720, story 4,156, data 268, shared 317, core 797) plus raw-tail/mixed-block pages. The standalone total is 190,765. Triangle totals were not re-run. Exported with tools\rpf9dump (built on breadbbbb/rpf9-explorer's Core; see below). Resources are found at page offset +16 after 16 zero bytes, followed by a zlib system blob with a drawable/fragment header and then the following zlib blocks as graphics data. Positions are quantized: bias + scale * ((q >> 8) & 0xFFFFFF). Output is OBJ (positions, UVs, indices) plus a manifest with real model names (e.g. cvar_int_grg2b_toys_1), bounds, per-mesh shader index and material texture references (parameter hash, name hash, 64-bit asset key). My earlier 0x1380/0x1601 descriptor notes stand, but the "data not located" blocker was wrong. Character skeletons are separate: the shared 597-name .#ft table and its model-side bone-hash mapping are in character_skeleton.md. <work>\assets\<archive>\models\
Texture dictionaries Same tool: TXD resources become DDS per texture. <work>\assets\<archive>\textures\
World textures (TTPF) Done: 308,895 textures from all 57 pools, 0 failures, 48,220 entries skipped by the original exporter (33,507 BCPack, 14,030 compact mapping, 678 arrays/volumes, 5 unsupported format, 0 unmapped). The compact-tail tool resolves 14,011 of the 14,030 layouts and reconstructs 305,264 complete chains (206,661 newly complete, 1,100,865 mips, 4.59 GiB). BCPack was the hard blocker: the clean-room decoder in tools/bcpack.py (#312) rebuilds BC1, BC3, BC4 and BC5 blocks, which tools/ttpf_mips.py projects to 47,882 more complete chains; BC6H/BC7 rebuilders and the port into rpf9dump's C# TtpfReader, which still takes the zlib/raw path, are open (textures.md). An array/volume pass resolves all 678 allocation spans exactly; tile mode 9 is validated 90/90 as six 4 KiB slices, while 588 other arrays/volumes remain layout-unresolved. 46 pools are in data\ttdb\**, 11 in pack\<name>\data\ttdb\** (exported under ttpf_pack\<pack>\). data\ttdb\**\*.ttpf (57 pools, 58 GiB) are loose RDS5 texture pools, not inside RPFs. rpf9-explorer's TtpfReader reads the catalog and detiles them; checked visually (ttdb_graphics: scope reticles, clean lines). Names are generated (texture_N_<assetkey>); models reference textures by asset key. Some rows are skipped; the measured breakdown and the BCPack next step are in textures.md. <work>\assets\ttpf\<pool>\ + manifest.json
Animation Indexed without the TOC: 130,470 zlib streams (4,203,762,662 stored / 11,593,460,132 inflated), 95.4% readable. New RAGE page directories (0DRP, version 122), MoVE (version 19), 273 pack:/ name tables (2,298 paths), and a tail RBF0 rig-set manager (rage__crRigSetManager: 1,126 rig sets, 6,677 source→rig entries, 3,669 distinct rigs; 56 empty). Bone data: one standalone 28-name table and 3 motion-matcher streams with embedded bone tables (30-name union, 19 joaat32 hashes present, 4 motionmatcher paths); no rig→skeleton link was found. Two named clips are followed to page-0 payloads with durations and 0x48-byte track arrays; the page→packed-stream join is still missing. No YCD/RSC7 at any stream start. The rpf9_carve tail overread is measured in docs/animation.md. tools\anim_index.py, <work>\anim-index\
Audio audio.rpf holds raw (not zlib) AWC banks: Opus (codec 0x0B) and XMA2 streams. Exported as whole .awc files plus audio_manifest.json (stream ids, codec, channels, rate, duration). Done: 7,162 banks, 27 GiB, 1,603,231 streams, about 1,324 hours (codec 0x0B Opus 1,601,167; 5: 1,818; 2: 227; 0 PCM: 19). tools/awc_opus.py repackages every Opus stream losslessly into a standard Ogg Opus file (no re-encode; PCM streams become .wav). The AWC framing is 2048-byte blocks of [u16 length][packet], with a zero length padding the block (as rpf9-explorer's OpusPreview reads it). The final granule is trimmed to the declared sample count. Checked: 300 random streams decode with ffmpeg with no errors, lengths match the declared counts. XMA2 streams (codec 5, 1,818) are written as RIFF XMA2 files by rpf9dump xma (rpf9-explorer's AwcRecovery.WriteXmaWave) and decoded to PCM WAV by ffmpeg: all 1,818 decode. Streamed music (tag 0x48: chunks with a per-channel record table, each channel's 2048-byte subblocks after the aligned header, and a repeated-prefix skip per chunk) becomes one Ogg Opus per descriptor channel (3,008 banks contain music). The Opus TOC stereo bit gives the packet channel count; a 1-channel descriptor can carry stereo packets, whose interleaved sample count is halved for the end granule. Checked: a 4-channel bank gives four 42.0 s mono channels; 1-channel stereo banks export at the config duration. Output: <work>\assets\audio\ogg\<bank>\<stream id>.ogg. Done: 1,598,051 Opus streams + 3,116 music channels as Ogg Opus (22 GB), 19 PCM16 and 227 codec-2 streams (32-bit float PCM, 4 bytes per sample; values can exceed ±1) as WAV, 1,818 XMA2 as WAV. Every audio stream is converted; all WAVs decode. make_game.py --wav also decodes the Ogg Opus output to 16-bit PCM WAV with tools/audio_wav.py (ffmpeg required; existing WAVs are skipped on resume). <work>\assets\audio\awc\
World placement Full census of levels.rpf: 23,535 map resources / 1,670,442 entities; all maps/entities exact, 36/36 shards, 98.32% stream coverage. Map files occupy a continuous band from ~7.5 to ~62.9 GiB; the earlier 9,918 / 680,228 sample was a 55% lower bound. 0x7a resources: CMapData root, 0x90-byte CEntityDef with position/quaternion/scale/archetype/flags/per-entity id/per-archetype key/LOD fields; names and most archetypes are hash-only. Archetype and map names are lower-cased joaat, confirmed by a MurmurHash3 x64 low-64 key; see world_names.md. tools\world_index.py, tools\world_census.py, tools\world_names.py; world.md, world_census.md, world_names.md
Navmeshes navmeshes.rpf: 90,295 zlib streams (6,540,238,392 stored / 20,551,068,624 inflated), 97.5% readable; 9,603 0DRP pages and 27,644 0x00010015 pages, no NAVM/CNavMesh/NVMS magic. 0DRP is generic RPF paging, not a navmesh container. tools\navmesh_index.py; navmesh.md
BVH core_bvh4.rpf: 565,596 streams, 271,627 complete BVH4 streams + 10 eight-MiB split continuations, 269,106 instance records. Header 0x81020006 at +0x100, 64-byte node units, 208-byte instances with a 3x4 transform; prebuilt acceleration data, not source meshes or shaders. tools\bvh_index.py; bvh.md
RBF0 1,263 data.rpf resources, 475,461 elements, 44,887 descriptors and 340,859 strings. Inline record stream with no section table; UI/Scaleform (rage__fwui*, screens, subtitles, settings). The anim.rpf tail uses the same format (rage__crRigSetManager). tools/rbf0_tree.py decodes every resource to a strict JSON/CSV/XML element, value and text tree. tools\rbf0_index.py, tools\rbf0_tree.py; rbf0.md
Gamedata common.rpf: 954 streams (5,647,255 stored / 50,231,123 inflated), 85.5% readable; 266 XML documents / 118 roots (time/weather, vehicles/handling, peds/schedules, tuning, manifests, world/navigation); tools/gamedata_xml.py catalogs 267 payloads / 259 well-formed / 118 roots / 428,611 elements. No RBF0/PSIN. tools\gamedata_index.py, tools\gamedata_xml.py; gamedata.md
PSIN script.rpf: 671 streams start with PSIN, 670 complete; sections LSCH, LENM, LSNS, LGID, LRSC, CHKS. data.rpf: 2,281 streams, 1,045 complete after joining. LSCH (type schema: structs and members) and LENM (enums) are decoded on all 17,664 / 17,641 whole sections across every archive, names as case-sensitive joaat. LSNS is high-entropy; no plaintext scripts or names. tools/psin_index.py; psin.md
Audio config audio.rpf first 19.5 MiB: 837 zlib streams / 54,143,493 inflated bytes. 1,589 music records, 1,589 distinct ids, exact milliseconds; hash & 0x1fffffff is the AWC stream id. 1,584/1,589 durations match the AWC manifest / 2; no per-track start offsets. tools/audio_config.py; audio_config.md
Page directory 0DRP: fixed 0x60-byte header, version 122; q38 at +0x38 gives 16-byte records {u32 hash, u32 size, u64 0x50000000 + target}. data.rpf: 15,768 pages / 60,880 records; targets tile with zero overlaps. Names still need the TOC. tools/page_index.py; page_directory.md
Story / minigame story000.rpf (18.65 GiB) is mixed: 264 Bink 2 streams (3.33 GB), 225,281 raw RSC8 headers (v8001), 442 nested RPF9 headers and zlib resource pages. story000_script.rpf is 2,309 PSIN streams (2,118 complete), not a named script container; shared_minigame000 mixes pages, PSIN and XML. tools/story_index.py; story.md
Rest-of-world / script Six archives, 1.57 GB total: core_restofworld 1.21 GB (11 Bink 2 streams / 1.24 GB, 37 decoded models, 958 graphics pages, 6 PSIN), story000_restofworld 189 MB, story000_script 74 MB (2,309 PSIN, 2,118 complete), small appdata0/licences. No maps; no validated script container. tools/restofworld_index.py; restofworld.md
Audio stations Audio config 0x762160: 19 station blocks of {station hash, u32 boundary, ordered u32 content ids}; the boundary is a byte offset, not a count. VCRR content ids 0x28F2-0x2941 map exactly to records 0xBD73-0xBDC2 (80/80); other clusters are context-dependent or shared. Title-keyed stream ids resolve 702/800 resolved titles exactly and 746/800 with case/punctuation/feature variants. No per-track start offsets. radio_stations.md
D3D12 command objects Measured command queue / command list / fence / PresentX surface, split into verified exports and slots, prior-art claims, and open questions. Queue/list/fence creation and barriers are scoped; PresentX signature/slot and exact swapchain/plane parameters remain open until the executable is available. d3d12_command_objects.md

rpf9dump (bulk export)

tools\rpf9dump is a small CLI over the Core library from https://github.com/breadbbbb/rpf9-explorer (a friend's tool; source at third_party\rpf9-explorer, audited: no keys, no network, no custom build targets). It decrypts nothing. It carves validated resources, as rpf9_carve.py does, but with working model and texture decoders.

dotnet build tools\rpf9dump\rpf9dump.csproj -c Release -o <work>\tools\rpf9dump
rpf9dump models|textures <archive.rpf> <work>\assets
rpf9dump ttpf <pool.ttpf> <work>\assets\ttpf
rpf9dump audio <audio.rpf> <work>\assets
python -I make_game.py --stages assets   # everything, in order; skips what is done

Full-scan indexes are also saved to %LOCALAPPDATA%\RpfPreview\Indexes, so the rpf9-explorer GUI opens these archives with complete listings instead of its 16 MiB preview scan.

Other prepared pieces

  • tools\shader_profile.py writes the instruction profile to <work>\shaders\profile.json. An earlier corpus run reported 551 distinct mnemonics, with 204 accounting for 99% of instructions. Those counts predate the filter for assembler directives and comments.
  • tools\shader_ir.py: parses every disassembled instruction into opcode, typed operands (s/v registers and ranges, NSA register lists, constants, literals, export targets, interpolation attributes), modifiers and encoding bytes. On 1,000 shaders, 12 of 2.2M operands were left untyped before the last fix. This is the front end for an RDNA→SPIR-V translator.
  • tools\rtti_scan.py: MSVC x64 RTTI scanner (class names, bases, vtables). Tested on the bundled DLLs; run it on the exe first.
  • tools\hashdict.py: joaat hash→name dictionary (<work>\hashes.json, 1.9M entries, checked against adder = 0xB779A091). On day one, rerun with --extra <exe> so PSO field and type names resolve. Without the exe only about 1% do.
  • Runtime shims: all of xmem.dll is shimmed with the measured argument shapes (XMemAlloc, XMemFree, XMemVirtualQuery(process, address, out64), XMemGetWorkingSetStatistics(out)). The d3d12_xs root-signature serializer forwards to the PC d3d12.dll after clearing the Xbox flag byte; the deserializer forwards unchanged. D3D12XboxCreateDevice returns an Xbox-ABI proxy over the PC device: every PC vtable slot is forwarded with this adjusted, Xbox slot 62 is CreateComputePipelineState, and Xbox slot 76 maps resource creation to CreateCommittedResource with the Xbox 0x101/0x1 layout word replaced by the PC layout. Slots 9/10 are ID3D12DescriptorHeap methods, not device methods. The PC heap getters take a hidden return pointer (RDX), while Xbox expects the 8-byte handle in RAX, so slot 14 wraps the heap and slots 9/10 convert it. The heap holds a reference to the device proxy and its GetDevice returns that same proxy. Queues, fences, command lists and PresentX extensions remain unimplemented.
  • PSO metadata is a new variant (PSIN, LSCH schema, LENM, LSNS, LGID, LRSC, CHKS, little-endian). CodeWalker's parser reads the container but not the new schema; dump it once the exe gives the field names.

Shader translation (RDNA → SPIR-V)

tools\rdna2spirv.py (needs spirv-as/spirv-val on PATH: Vulkan SDK, or spirv-tools in WSL) translates parsed RDNA code to SPIR-V assembly, assembles it with spirv-as, and validates it with spirv-val (Vulkan 1.2). It runs one lane per invocation and keeps VGPRs and SGPRs as uint arrays with exact bit patterns. Version 0 treated EXEC as all-ones and covered only branch-free vertex and pixel shaders with no memory loads: common float and integer ALU ops and exports to gl_Position, params and MRTs. Unsupported instructions are reported by name, never guessed. In that version, VS_Passthrough and VS_BlurFilter translated and validated. Coverage across the corpus and the blocking instructions are in <work>\shaders\spirv_run.log; the former next steps, structured branches (EXEC masks) and the descriptor/binding model for s_load, s_buffer_load, buffer_* and image_*, are now implemented. Current coverage is in Translator status below.

Also handled: 64-bit scalar moves, per-invocation EXEC reads, whole-quad mode on EXEC, m0, SCC, vector and scalar compares, v_mul_hi_u32, v_cvt_pkrtz_f16_f32 (now exact round-toward-zero; the earlier round-to-nearest version could overflow to inf), and pixel interpolation (v_interp_p1/p2/mov become fragment inputs at their attribute's location). The float MODE register (s_setreg) is skipped, so Vulkan's default denormal and rounding behaviour applies.

GPU tests (RTX 4060 Ti)

runtime\test\vk_harness.cpp (build: runtime\build\test\build_harness.cmd, MSVC + the Vulkan 1.4 headers from Hookshot's CPM cache, loading vulkan-1.dll at runtime) draws one triangle with a given VS + FS into an RGBA32F target and dumps the floats. Test shaders are in <work>\gputest.

  • VS_Passthrough (translated) is bit-exact. All 64×64 pixels are written, and param0.xy = (u, 1 − v) with max error 0, with zw = (0, 1) as exported. This covers the VertexIndex input, integer/float ALU, inline constants, and position/param exports.
  • 400 arithmetic-only translated pixel shaders (no buffers, descriptors or subgroup ops), driven by a generic full-screen VS feeding locations 0–15: the driver compiled every pipeline, every draw completed, and every output was finite. This is a stability check, not a value check (there's no reference for these).
  • Texture path is exact (runtime\test\vk_texture_test.cpp): translated PS_PassthroughCopy gives max error 0.0 over all 64×64 pixels against the expected nearest-sampled 8×8 test texture. That covers push-constant user data, a heap-relative s_load_dwordx8 of the T#, the hash-table lookup of the T# and of the shader's literal S#, bindless sampling, v_interp, and the f16 compressed export. It also caught a translator bug that validation can't: compressed exports read the wrong register pair (LLVM prints v4, v4, v5, v5), giving (r,g,r,g). That's fixed.
  • After the export fix, 2 of the 400 smoke-test shaders (PS_ImposterShadow variants) gave non-finite red values. The cause was round-to-nearest pkrtz overflowing to inf, fixed with exact RTZ. One variant is now fully finite. The other still has 1 inf and 4 NaN in red, and RTZ can't create those from finite values, so they come from the shader's own maths on the synthetic test inputs (hardware would pass them through too). That's consistent with hardware, but unconfirmed without a reference.

Translator status and runtime contract

Full corpus (verified pixel-shader inputs incl. front face, ACO-confirmed 16-bit semantics, vcc_hi as an SGPR, code-embedded data via s_getpc_b64, global memory, exact packed-f16 modifiers): All 26,503 shaders translate and pass spirv-val (Vulkan 1.2 target, --allow-offset-texture-operand): 2,236 VS, 12,101 PS, 2,689 CS, 9,282 mesh, 195 geometry. spirv/index.json lists each one's requirements. Output: <work>\shaders\spirv\ (.spvasm + .spv), and the log is <work>\shaders\spirv_run.log.

How the generated SPIR-V expects the runtime to work:

Piece Contract
Execution model One invocation = one lane. A wave = a subgroup, so cross-lane ops (ds_swizzle, v_permlane*, v_readlane/v_writelane, v_mbcnt) become subgroup shuffles. Requires subgroup size == wave size (wave32 maps directly onto NVIDIA GPUs; wave64 shaders need a 64-wide subgroup or emulation). v_readlane_b32/v_writelane_b32 mask the lane select with 63 in wave64 (S1[5:0]) and 31 in wave32 (S1[4:0]); until SHADER-52 both used 63, so a wave32 select ≥ 32 pointed past a 32-wide subgroup. GPU-checked with cs_w32_lane_wrap.asm (lane 40 → 8).
EXEC A per-invocation active flag. VALU writes and exports are masked by it, scalar ops aren't, and v_cmpx, saveexec and EXEC writes update it. A pixel lane still inactive at the end is discarded.
Control flow Reducible graphs use structured branches and natural loops. Irreducible graphs use the dispatch-loop form, which can also be forced with --dispatch-loop for comparisons. The control-flow unit test checks 18,228 generated graphs. AMD A/B checks compare the two forms for selected pixel shaders with defined test inputs. For shaders that never export colour, the comparison checks pixel coverage.
User data Push constants, 144 bytes: dwords 0–31 = initial s0–s31 (the user SGPRs the console driver loads from the root signature: descriptor-table pointers, constants and so on), dwords 32–33 = the 64-bit heap base, dwords 34–35 = the code base: the Xbox VA where the runtime uploaded this shader's whole FSSM blob. The runtime has to reproduce the console driver's root-signature-to-user-SGPR mapping; that comes from the exe or driver behaviour.
Xbox GPU addresses Shaders build Xbox GPU virtual addresses, and some force the high dword to 0 (descriptor tables in the low 4 GB). Every memory access goes to heap base + Xbox VA, so the runtime maps the console's GPU address window into one host buffer-device-address allocation.
Code-embedded data 155 VS/PS had "undecodable words". They're constant tables inside the code range (float values like 0x3EF7…, plus zeros), read through s_getpc_b64 + s_add_u32/s_addc_u32 + s_load (147 of 155). The translator re-anchors each instruction to its true FSSM offset by matching encodings, translates only code reachable from entry (a branch into data is rejected), and turns s_getpc_b64 into code base + next-instruction offset. The runtime uploads each shader's FSSM blob into the heap and passes that VA as the code base. Re-anchoring compares bytes exactly, except that VOP3P op_sel_hi[2] (bit 14) is ignored on two-source packed ops: the compiler stores 0 there, and LLVM prints its default of 1. Unused VOP3/VOP3P SRC1 (bits 49:41) and SRC2 (bits 58:50) fields are also ignored when stored as 0 and printed as 0x80: LLVM 23 re-encodes a source it doesn't read as inline constant 0 (one-source v_rcp/v_log/v_sqrt_f32_e64, two-source v_sub_f32_e64/v_cmp_*_e64/v_mul_lo_u32/v_pk_mul_f16). A source it does read prints as decoded (raw 0 is s0), so this can't hide a real difference. Confirmed by a count over the corpus with LLVM 23.1.5: without it, 1,471 of the 1,473 shaders with embedded data are rejected ("reachable instruction with normalized encoding"); with it, all 1,473 translate and pass spirv-val. Runs with LLVM 21 already translated all of them, so older LLVMs presumably print the stored 0 (not re-checked). Data words that decode with ignored fields set are printed re-encoded (e.g. 0xbe8d2242 as s_rfe_b64 0xbe802242), so they can never match. Since the decoder consumed the same length, they are anchored in sequence and marked. A shader that can reach a marked word is rejected; none of the corpus does. All 155 now translate.
Global memory global_load/store_dword*: address = (64-bit SGPR base + zero-extended 32-bit VGPR offset, or a 64-bit VGPR address) + the instruction offset, translated through the heap base. Inactive lanes don't access memory, and loads merge their previous values with OpPhi. The offset is the signed 12-bit byte value as llvm-mc prints it, -2048..2047 (offset:-4 is the field 0xffc; llvm-mc rejects offset:0xffc and disassembles that field as offset:-4, so no repo path delivers the raw unsigned field), added to the address as is; a tool that printed the raw field (0xffc) would mean the same offset, and a value outside 12 bits is rejected. Measured on an AMD Radeon RX 6800 (gfx1030) running global_load_dword as a raw compute kernel, wave32 and wave64 alike, with the dword at byte n = 0x10000000+n and the pointer at 0x1000: offset 0 reads 0x10001000, -4 0x10000ffc, -2048 0x10000800, 2044 0x100017fc, -1024 0x10000c00. The translator used to subtract 0x1000 from an already negative value (4096 bytes too low). Checked by tests/semantic/test_global_mem_offset.py (both addressing modes, dword/x2/x4, byte/short loads and stores at -4, -2048, 2047 and 0) and the GPU test runtime/test/shaders/cs_global_neg_offset.asm (vk_compute_test ... 40 dump).
Literal samplers Some shaders build their S# from immediates (for example 0x92, 0xC00000, 0x14500000, 0). The runtime registers those in the descriptor hash table too, by scanning the translated shaders' constant S# values, not only S#s the game binds.
Scalar/buffer memory s_load*, s_buffer_load*, buffer_load* and buffer_store* use buffer device addresses (PhysicalStorageBuffer64). The base comes from the 64-bit SGPR pointer or the V# (dword0 | dword1[15:0] << 32), and the stride is V# dword1[29:16]. The runtime must put the game's GPU heap in buffer-device-addressable memory at the same addresses the game writes into descriptors (or remap them). s_load* and s_buffer_load* take an immediate or an SGPR offset, or both at once (llvm-mc prints sOFF offset:IMM): the address is base + sOFF + IMM + 4·i for dword i. Measured on AMD Radeon RX 6800 (gfx1030) by running the instructions as a raw compute kernel: soffset 8 + imm 4 reads +12 (s_buffer_load_dword, x2, x4, x8); s_load_dword* with both offsets wasn't measured and gets the same rule because it shares the SMEM encoding. The translator used to drop the immediate of that form. The translator's arithmetic is checked by tests/semantic/test_scalar_mem_smem.py (SmemSoffsetImmTranslatorTests); a GPU test, runtime/test/shaders/cs_smem_soffset_imm.asm, is in check.py and scripts/run_gpu_tests.py. Known remaining differences, from the same measurement of s_buffer_load*: the hardware truncates base, sOFF and IMM each to a multiple of 4 and returns 0 past NUM_RECORDS; the translator does neither yet. See Buffer bounds checking below for the MUBUF num_records checks.
Typed buffer loads The format is V# word3[18:12] (GFX10_FORMAT, from Mesa's gfx10-rsrc.json, saved as tools\gfx10_formats.json). Supported: f32 ×1–4, u32 ×1/2/4, f16 ×1/2/4, unorm8 ×1/2/4, snorm8 ×4, uint8 ×4, unorm16 ×1/2/4, snorm16 ×2/4, 10-10-10-2 and 2-10-10-10 unorm. Others give 0. DST_SEL swizzle is applied (0→0, 1→1.0f for float/norm or integer 1 for UINT/SINT, 4..7→X..W). Missing channels repeat the format's own (component c = c mod n), measured on an RX 6700 (SHADER-86). UNORM/SNORM decode with correctly rounded OpFDiv by (2ⁿ−1), not a reciprocal multiply (0 mismatches vs hardware over 395,776 conversions on that GPU). Format names list the channel widths from the top bit, so 2_10_10_10 (50) is R10G10B10A2 and 10_10_10_2 (44) has a 2-bit x (Mesa gfx10_format_table.py, ac_formats.c). Until 2026-11-22 the two were swapped, in stores too. Until 2026-11-21 an element that started mid-dword re-read dword 0 for its tail (need was ceil(size/4) and only the first dword was shifted); loads now take need = ceil((byte_shift + size) / 4) dwords and shift the whole window so the packed stream starts at the element (FUZZ-5, leftover from #234). The 10:10:10:2 order is checked by cs_fmt_1010102 in tests/semantic/test_value_semantics.py (the shader decodes the format, so a GPU run can't check it). Mid-dword spanning elements are checked by tests/semantic/test_buffer_load_format.py (CrossingDwordBoundary); repeat / UNORM / DST_SEL 1 by the SHADER-86 cases in the same file.
Images and samplers image_sample_l on 2D arrays used to read its LOD from the array layer; it now reads the LOD after all coordinates. image_get_lod and image_gather4_lz also work on 2D arrays. With d16 every sample result is f16, packed two to a VGPR from the low half (the packed D16 of GFX10, as LLVM returns D16 image data); image_sample_c_lz/_c_lz_o follow it too, and until 2026-11-21 their compare result was written as f32 bits, which read as 0 in the low half. Checked by tests/test_translate.py (test_depth_compare_sample_result_width) and GPU-checked with runtime/test/shaders/ps_sample_c_lz.asm (vk_texture_test dref: a D32 texture and a LESS_OR_EQUAL compare sampler) on an NVIDIA GeForce RTX 2060 SUPER (Linux, driver 620.70.06): 4096/4096 pixels exact for f32 and d16; with the old translator the d16 result read 0 in the 2048 pixels whose compare passes.
Typed buffer loads The format is V# word3[18:12] (GFX10_FORMAT, from Mesa's gfx10-rsrc.json, saved as tools\gfx10_formats.json). Supported: f32 ×1–4, u32 ×1/2/4, f16 ×1/2/4, unorm8 ×1/2/4, snorm8 ×1/2/4, uint8 ×4, unorm16 ×1/2/4, snorm16 ×1/2/4, 10-10-10-2 and 2-10-10-10 unorm. Others give 0. DST_SEL swizzle is applied (0→0, 1→1.0f for float/norm or integer 1 for UINT/SINT, 4..7→X..W). Missing channels repeat the format's own (component c = c mod n), measured on an RX 6700 (SHADER-86). UNORM/SNORM give the correctly rounded quotient by (2ⁿ−1), as the hardware does (0 mismatches vs hardware over 395,776 conversions on that GPU). It is built with integer ops (Gen.norm_bits): x/(2ⁿ−1) in binary is x's bits repeated, so a 64-bit multiply by the repeat pattern, FindUMsb and the round bit give the f32 exactly (the tail never ends, so there are no ties). OpFDiv is not enough on the GPU: Vulkan allows it 2.5 ULP, and on an RX 6700 (AMD Windows 26.11.2) and an RTX 5090 it returned the reciprocal-multiply bits (8_UNORM 130/256 exact, #599). Checked against exact values in tests/semantic/test_norm_decode.py (every value up to 8 bits, edges and the reciprocal-multiply misses for 10, 15 and 16 bits). 8_SNORM (2), 16_SNORM (8) and 8_8_SNORM (15) were missing until 2026-11-22 and decoded to 0. Format names list the channel widths from the top bit, so 2_10_10_10 (50) is R10G10B10A2 and 10_10_10_2 (44) has a 2-bit x (Mesa gfx10_format_table.py, ac_formats.c). Until 2026-11-22 the two were swapped, in stores too. Until 2026-11-21 an element that started mid-dword re-read dword 0 for its tail (need was ceil(size/4) and only the first dword was shifted); loads now take need = ceil((byte_shift + size) / 4) dwords and shift the whole window so the packed stream starts at the element (FUZZ-5, leftover from #234). The 10:10:10:2 order is checked by cs_fmt_1010102 in tests/semantic/test_value_semantics.py (the shader decodes the format, so a GPU run can't check it). Mid-dword spanning elements are checked by tests/semantic/test_buffer_load_format.py (CrossingDwordBoundary); repeat / UNORM / DST_SEL 1 by the SHADER-86 cases in the same file.
Images and samplers image_sample_l on 2D arrays used to read its LOD from the array layer; it now reads the LOD after all coordinates. image_get_lod and image_gather4_lz also work on 2D arrays. With d16 every sample result is f16, packed two to a VGPR from the low half (the packed D16 of GFX10, as LLVM returns D16 image data); image_sample_c_lz/_c_lz_o follow it too, and until 2026-11-21 their compare result was written as f32 bits, which read as 0 in the low half. Checked by tests/test_translate.py (test_depth_compare_sample_result_width).
Images and samplers (core) Bindless. Set 0: binding 0 = 2D sampled images, 1 = samplers, 2 = descriptor hash table (storage buffer), 3 = 2D-array images (cube textures are bound here as 6-layer 2D-array views, cube arrays as 6N layers: the shader already selected the face with v_cube*), 4 = r32ui storage images, 5 = 1D, 6 = 3D. A cube sample's s and t come in [1, 2] and its third coordinate is 8·slice + face, as the hardware takes them (Mesa ac_nir_lower_tex_coords.c, LLPC ImageBuilder.cpp); the view is read at (s − 1, t − 1), layer 6·slice + face. GPU-checked with runtime/test/shaders/ps_cube_sample.asm (vk_texture_test cube).
Descriptor hash table uint mask; entries[mask+1] of 10 uints: key[0..7], index, pad. The key is a T# or a padded S#. FNV-1a over the eight key words selects the first slot. The shared SPIR-V lookup probes up to eight slots and returns index 0 on a miss. The runtime supplies a fallback at index 0 and maps live descriptor keys to bindless indices.
Packed sample addresses GFX10 image_sample_d with a16 keeps the non-G16 gradients as f32 and packs the following coordinates as f16 pairs, following LLVM's GFX10 operand layout. test_a16_sample_gradients_use_full_vgprs checks the emitted gradient operands, and ps_texture_grad_a16 checks coordinate selection with a single-mip texture on RTX 5080. The same holds for every extra argument before the coordinates (LLVM getAddrSizeMIMGOp: one word each, then the gradients, then the packed halves; llvm-mc takes v[0:2] for a 2D image_sample_c_b ... a16): an image_sample_b bias keeps its VGPR with the f16 in the low half, an image_sample_c_lz z-compare its f32 VGPR, and image_sample_d_cl its four f32 gradients, with the clamp the half right after the coordinates (an f16 pad may follow it). Until 2026-11-21 those were unpacked as pairs too, and the clamp was taken from the last half. GPU-checked on an NVIDIA GeForce RTX 2060 SUPER (Linux, driver 620.70.06) with ps_texture_bias_a16, ps_sample_c_lz_a16 (vk_texture_test dref_a16) and ps_texture_grad_cl_a16, which draws on the --two-mip texture with the clamp 0 on the left half and 1 on the right: 4096/4096 pixels exact each. The old reading got 4,032 bias pixels and both depth-compare results in 2,048 pixels wrong, a clamp taken from the pad read mip 1 on the left half, and the sample without its clamp mip 0 on the right half (2,048 pixels each).
Vertex fetch s_swappc_b64 at the start of a VS calls a driver-generated fetch program that isn't in the blob. It's replaced by Vulkan vertex inputs: each ISG1 input-signature element (DXBC container) becomes an input at location = its D3D input register, typed by its component type, and is written to v(4 + 4·register + component). That rule was checked over all 788 fetch-calling shaders: in 783 every read-before-write VGPR is predicted by it (715 exact). Reads of components the element doesn't declare (e.g. .w of an xyz position, 3 VS) are allowed: the fetch returns the format defaults (0, 0, 1), and Vulkan fills a vec4 input from a narrower format the same way. Inputs are declared as vec4. The runtime must bind vertex buffers by the game's D3D12 input layout, location = input register.
PS system inputs v0–v1 = barycentrics (consumed by v_interp, which becomes attribute inputs). v2.. = the SV_Position components the shader reads, packed in order. Verified on 2,531 of 3,000 PS: the VGPRs they read before writing equal exactly the position components their input signature reads. Filled from FragCoord: xy/z directly, and w directly too, because AMD's position-w register holds 1/w (Mesa lowers load_frag_coord_w_rcp straight to frag_pos[3], ac_nir_lower_intrinsics_to_args.c), the same as Vulkan's FragCoord.w. Front face follows the used position components when the signature declares SV_IsFrontFace, as ±1.0 (Mesa: load_front_face = front_face > 0). Only enabled inputs are packed, in hardware order (Mesa radv_shader_args.c: barycentric pairs, POS_X/Y/Z/W, FRONT_FACE, ANCILLARY, SAMPLE_COVERAGE, POS_FIXED_PT). That explains the earlier "unverified" shaders: 102 read pos.xy + front face, and 76 read pos.x/y/w + front face. Raw barycentric reads (321 PS, e.g. v_readfirstlane_b32 s41, v1): AMD interpolates P = P0 + i(P1 − P0) + j(P2 − P0), so i/j are the weights of vertices 1/2, which is BaryCoordKHR.y/.z (VK_KHR_fragment_shader_barycentric). GPU-checked with runtime/test/shaders/ps_bary.asm: raw i/j equal the interpolated weights on every pixel. This assumes the pair is perspective-center, the only pair this layout models. A PS that reads any other unexplained register inside the system-input range is still rejected (none left in the corpus). Reads past the last hardware input are values undefined on some path, so zero stands in for them. All register arrays start at zero, so translated shaders are deterministic.
Inputs and outputs VS: v0 = VertexIndex (unverified: if the console runs vertex shaders as NGG, the input VGPR layout differs). exp pos0 → Position, exp pos1..pos3 → ClipDistance / CullDistance (and Layer/ViewportIndex in VS when pos1 is the misc vector), exp paramN → location N. RDNA2/GFX10 packs clip distances before cull distances contiguously across 4-component pos exports (up to 8 floats total), starting at pos2 when a misc vector (PointSize, EdgeFlag, ShadingRate, Layer, ViewportIndex; GFX9+ packs Layer in z[10:0] and ViewportIndex in z[19:16]) occupies pos1, and at pos1 otherwise (Mesa src/amd/common/nir/ac_nir_prerast_utils.c: ac_nir_export_position; AMD LLPC lgc/lowering/LowerInOut.cpp: LowerInOut::visitReturnInst). Slot assignment follows the DXBC OSG1 signature (SV_ClipDistance = 2, SV_CullDistance = 3, SV_RenderTargetArrayIndex = 4, SV_ViewportArrayIndex = 5, SV_ShadingRate = 23), ordered by (semantic_index, register, component) with clip before cull; when OSG1 is absent (or declares none of those system values), pos1..pos3 exports are discarded. PS: v_interp_* attribute N → input location N. exp mrtN → location N, exp mrtz x → FragDepth when x is on and the export isn't compr (RGBA = Z, stencil, sample mask, alpha: Mesa ac_get_spi_shader_z_format; the 16-bit compressed mrtz holds stencil and sample mask and never Z, ac_nir_lower_ps_late.c emit_ps_mrtz_export). Until 2026-11-22 an mrtz export without a depth wrote one anyway (0.0, or an f16 half of the stencil word) and declared DepthReplacing. Checked by tests/test_translate.py (test_mrtz_depth_only_from_an_enabled_x). Stencil, sample mask and alpha exports aren't modelled.
16-bit results From Mesa ACO (aco_ir.cpp: instr_is_16bit, can_use_opsel) for GFX10: f16 VOP1/VOP2 ops (v_add/sub/subrev/mul/max/min_f16, v_fmac_f16, v_cvt_f16_f32, f16 unary) and opsel-capable VOP3 ops (v_fma_f16, _e64 forms of the 16-bit integer ops) are partial writes that keep the high half. The VOP2 (_e32) 16-bit integer ops (v_lshrrev_b16…) define the whole register, so the high half is modelled as zero. An op_sel destination bit writes the high half. The translator used to clear the high half on f16 ops; that's fixed. op_sel on f16 VOP3 ops (v_fma_f16, v_med3_f16, v_add/sub/subrev/mul/max/min_f16, f16 unary, v_fmac_f16): bit i (i < number of sources) reads the high half of source i, the last bit writes the high half of the destination; neg/abs apply to the selected half. Source: Mesa ACO can_use_opsel and the RDNA2 ISA VOP3 OP_SEL field. Checked by the structural tests in tests/test_f16_op_sel.py (which half is read, where the result goes) and the value tests in tests/test_f16_op_sel_values.py. Hardware-verified on an AMD RX 6800 (gfx1030), the instructions run as a raw compute kernel in wave32 and in wave64 (IEEE off, DX10 clamp on, denormals kept, round to nearest; the bytes assemble identically for gfx1013 and gfx1030): v_med3_f16 with all 16 op_sel patterns, with neg/abs on a selected high half, with clamp, and with the destination also a source; the plain forms v_add/sub/mul/max/min_f16 (_e32, and _e64 with neg/abs/clamp), v_fmac_f16 (_e32, and _e64 with neg/abs; the accumulator is the low half of the destination), v_rndne/floor/ceil/trunc/fract/sqrt/rcp/rsq_f16 (_e32 and _e64) and v_cvt_f16_f32: low halves in, low half out, high half of the destination kept. 336 words per wave size (plus v_rsq_f16_e64 and v_ceil_f16_e64 in a later run), all as the rule says and as the translator computes. Vulkan (AMD Radeon RX 6800, Windows, driver 26.11.2; the nine ps_f16_* fixtures also pass on an NVIDIA RTX 4050 Laptop and an AMD Radeon 740M (RADV), both Linux): ps_f16_med3_opsel, ps_f16_med3_mods, ps_f16_vop2, ps_f16_vop2b, ps_f16_vop1, ps_f16_vop1b, whose expected words are the hardware ones (tests/test_f16_hw_words.py checks them against the rule and the translator without a GPU). Not expressible, so not verified: op_sel on the VOP2 and VOP1 ops in VOP3 encoding (v_add/sub/mul/max/min_f16_e64, v_fmac_f16_e64, the unary _e64 forms, v_cvt_f16_f32_e64): llvm-mc 21 rejects the modifier for gfx1013 and gfx1030, and its disassembler prints bytes that have those bits set without it (03 08 32 d5 01 05 02 00 comes back as v_add_f16_e64 v3, v1, v2). The translator's op_sel handling for these forms is therefore never reached from a disassembly listing and rests on the ISA field description alone; whether the hardware honours the bits there is unknown, and a blob that set them would be translated as if they were clear. Also unverified: v_exp_f16/v_log_f16, NaN and denormal operands, other rounding and IEEE modes.
f16 inline constants An inline float constant (0.5, 1.0, 2.0, 4.0, their negatives, 0.15915494) in an operand of a 16-bit float op is the f16 value in the low half with a zero high half, not f32 bits (the translator used to unpack the f32 pattern, whose low half is 0, so v_add_f16 d, 1.0, v added 0.0). Measured on an AMD RX 6800 (gfx1030) raw kernel, wave32 and wave64: v_add/mul/max_f16, v_sub_f16_e64, v_fma_f16, v_fmac_f16, v_rcp_f16, v_med3_f16, v_cmp_lt_f16, v_cvt_f32_f16 (0.5 gives 0x3f000000), v_cos_f16, v_pk_add_f16/v_pk_mul_f16 (the high result half sees 0.0), v_pack_b32_f16; 0.15915494 is 0x3118; the high half op_sel selects from a constant reads +0.0 (v_med3_f16, v_fma_f16, v_pack_b32_f16, v_pk_add_f16 with swapped halves). GPU tests ps_f16_const, ps_f16_const2 and ps_f16_pack (Vulkan: AMD Radeon RX 6800, Windows, driver 26.11.2; all three fail without the fix). Not measured, left as they were: constants in v_fma_mix_f32/v_fma_mixlo/mixhi_f16 operands.
v_med3_f32 output modifiers The translator applies mul:2, mul:4 or div:2 to the median before clamping to [0, 1], following LLVM’s modifier order. The finite-input fixture ps_med3_mods.asm produced 4,096 exact pixels on an Apple M3 Max with MoltenVK and on Mesa llvmpipe (software Vulkan); it also passes (4,096/4,096) on an NVIDIA RTX 4050 Laptop and an AMD Radeon 740M (RADV), both Linux, and on an RTX 2060 SUPER per #634. This uses the existing float MODE assumptions described above.
POPS Primitive-ordered pixel shading (10 PS, src_pops_exiting_wave_id wait loop, s_sleep, MSG_ORDERED_PS_DONE) becomes fragment-shader interlock (PixelInterlockOrderedEXT). It begins at the end of the entry block and ends at shader exit: a longer critical section with the same ordering. src_pops_exiting_wave_id reads 0, and the runtime must put 0 (no collision, bit 31 clear) in the POPS collision SGPR, so the hardware wait loop is skipped. Needs VK_EXT_fragment_shader_interlock (fragmentShaderPixelInterlock).
Texel offsets image_sample*_o: the first address dword packs signed 6-bit offsets (x [5:0], y [13:8], z [21:16]), which become the SPIR-V Offset operand. A non-constant Offset outside gather needs VK_KHR_maintenance8, and is validated with spirv-val --allow-offset-texture-operand. The operand is always a run-time value: the translator extracts the fields from the register, also when the shader loaded the dword from an immediate, so every _o sample needs the extension. image_gather4_lz_o / _l_o read x and y the same way; a gather Offset needs shaderImageGatherExtended, not maintenance8. GPU-tested with runtime/test/shaders/ps_texoff.asm on vk_texture_test (in check.py and scripts/run_gpu_tests.py; SKIP on a device without the extension), on an AMD Radeon RX 6800, Windows driver 26.11.2, maintenance8 enabled: an 8×8 texture whose texels are all different, a point sampler that clamps to the edge, 2D targets, mip 0. image_sample_lz_o with an offset computed per pixel (all 64 pairs of x, y in −4..3, none clamped), image_sample_l_o with (−3, +2) and image_sample_lz_o with (+16, −32) from immediates, and image_gather4_lz_o of red and of green with the per-pixel offset gave, on all 4096 pixels, the texels worked out by hand from this rule (derivation in the .asm header). Run with a sabotaged translator, the test fails when the sample offset is dropped, has x and y swapped, takes y from bit 6, or uses 4-bit or 5-bit fields, and when the gather offset is dropped, has x and y swapped or takes y from bit 6; 4-bit and 5-bit gather fields pass, because the gather offsets stay in −4..3. What it shows is that the translated SPIR-V implements this rule on Vulkan; it does not measure the field layout on the hardware. It cannot see the sign extension on this driver: with the fields read unsigned the same texels come back: Offset 60..63 sampled as −4..−1 and +32 as −32 (the device reports texel offset limits −64..63, gather −32..31). The sign extension and the gather field width are therefore pinned by the structural test tests/test_texel_offsets.py (signed, bit 8k, 6 bits, for _lz_o, _l_o, _o, 3D and gather) and are not GPU-tested through Vulkan. The x field is measured on hardware: image_sample_lz_o run as a raw compute kernel on the same RX 6800 (gfx1030, wave32 and wave64), on a 64×1 R32_FLOAT image whose texel i holds i, with a point sampler that clamps to the last texel: from texel 40, offset dword 0x20 reads texel 8 and 0x3c reads texel 36 (unsigned would clamp both to 63); from texel 10, 0x1f reads 41 and 0x20 clamps to 0; 0x40, 0x80 and 0xc0 read the centre texel (bits 6–7 are ignored); and a non-zero y field, z field or top byte leaves x alone. All 36 rows fit x = sign-extended bits [5:0]. The y and z fields' own signs were not measured (the image was one texel high). The (+16, −32) sample is outside Vulkan's guaranteed −8..7 and is judged only where the device limits cover it. Not GPU-tested: image_sample_o, _b_o, _c_lz_o, image_gather4_l_o, the z field (3D), 1D, 2D-array and cube targets (offset next to an array layer), wrap or mirror addressing, linear filtering, mips other than 0, other vendors' drivers, and a device without maintenance8 (the test skips there; the translator has no fallback for it).
Optional device features Shaders may need fragmentShaderBarycentric, fragmentShaderPixelInterlock and maintenance8. All three are present on an RTX 4060 Ti, and runtime/test/vk_harness.cpp enables them when available. (It is guarded by the header macro VK_KHR_MAINTENANCE_8_EXTENSION_NAME, so older Vulkan headers build without it. vk_texture_test enables it too, and shaderImageGatherExtended.)
Wave size Most of the game's shaders are wave64: 21,545 of 26,503. An earlier marker scan (s_mov_b64 exec, -1, exec_hi, s_and/or_saveexec_b64 and 64-bit masks) counted 9,930 of 12,101 PS, 8,666 of 9,282 mesh shaders, 1,115 of 2,236 VS and 923 of 2,689 CS. The translator maps a wave to a subgroup, and NVIDIA subgroups are 32 wide. What that means: (1) lane-independent code, which is most pixel-shader math, is exact; (2) wave-wide branch decisions and reductions are made per 32-lane half, which is exact unless scalar state computed for one half is later consumed by the other; (3) lane indices from v_mbcnt_lo/hi and wave IDs from the merged-wave SGPR must be 64-lane values. Mesh and compute shaders build thread IDs as wave_id·64 + mbcnt, so those need a mapping from LocalInvocationIndex (lane = index & 63, wave = index >> 6). Full fidelity needs either 64-wide subgroups (AMD GPUs, via VK_EXT_subgroup_size_control requiredSubgroupSize = 64) or emulating cross-half ops (ballot, readlane, shuffles across halves) through workgroup memory.
Mesh shaders NGG wave64 programs → VK_EXT_mesh_shader (MeshEXT). PSV0 (DXBC) gives NumThreads (128×1×1 in the corpus), MaxOutputVertices/Primitives (128/128) and the topology (triangles). System inputs, from Mesa's RADV setup for mesh as NGG on GFX10.3: v5 = first launch vertex ID of the lane (the "vertex_id" slot), linearGroupIndex * NumThreads + LocalInvocationIndex with the linear index from WorkgroupId/NumWorkgroups; all 9,282/9,282 corpus mesh shaders read v5 once with v_readfirstlane_b32 sX, v5 and use sX only via s_lshr_b32 D, sX, 7 to recover the group index (NumThreads is 128 in the corpus), matching TomBox's mesh ABI (gid.x * numThreads + gi) on 1D launches. GPU-checked with runtime/test/shaders/ms_v5_workgroup.asm (24/24 groups exact on RTX 4060 Ti and RTX 3080, and on an RTX 4050 Laptop and an AMD Radeon 740M (RADV)); still unverified on Xbox hardware: the low 7 bits of v5 on lanes 1..127 and whether 3D DispatchMesh flattens XYZ or uses X only. The merged-wave-info SGPR (s3 in this ABI) = wave ID << 24, from LocalInvocationIndex >> 6; v_mbcnt lanes = LocalInvocationIndex & 63; user data in s16.. as usual. 1,473 of 1,500 sampled mesh shaders read exactly v5, and the rest only add loop-carried registers. Exports: on NGG, thread t exports vertex t (pos0, paramN) and primitive t (prim). They're staged per invocation; an all-off export is the dummy a wave with no vertices must issue, and writes nothing. s_sendmsg GS_ALLOC_REQ (m0 = prims << 12 | verts, sent by thread 0) stores the counts in a workgroup variable. At shader end, in uniform control flow: workgroup barrier, OpSetMeshOutputsEXT(min(verts, max), min(prims, max)), then each thread writes its staged vertex (Position + Location N) and primitive (PrimitiveTriangleIndicesEXT = bits [8:0], [18:10], [28:20]; CullPrimitiveEXT = bit 31). pos1..pos3 clip/cull distances are staged per invocation and emitted in a per-vertex Block output struct (Position + ClipDistance/CullDistance arrays, VK_EXT_mesh_shader) when used, keeping the standalone %ms_out_pos layout unchanged for shaders without pos1+. GPU-checked with runtime/test/shaders/ms_tri.asm (VKH_MESH=1 vk_harness), built from the game's own idioms (thread ID from s3 and mbcnt across two waves, thread-0 ALLOC_REQ, per-thread exports): 0 error on every pixel.
Geometry shaders All 195 are $GS_VoxelizeGeneric permutations: legacy (merged ES/GS) wave32 programs on LDS rings, with no exp. Inputs: vertex i sits at the dword offset in v0 lo / v0 hi / v1 lo; an LDS read at vertex base + 4·(4·reg + comp) is input-signature register reg, component comp (checked: SV_Position xyz in dwords 0–2 and TEXCOORD0.xy in 4–5, as ISG1 declares). Outputs: emitted vertex k is dwords [k·4·nreg, (k+1)·4·nreg) of the lane's GSVS area, dword = 4·reg + comp of the output signature (20 dwords = 5 OSG1 registers; every write matches a declared mask). Translation: synthetic offsets (vertex i at dword 64·i), LDS reads → gl_in[i] inputs, LDS writes → staged slots, MSG_GS EMIT → copy slot (emit count) to the outputs + OpEmitVertex, CUT → OpEndPrimitive, GS_DONE → nothing. The prologue's s_bfm_b64/s_cselect EXEC setup is fed s3 = 64 << 8. GPU-checked with runtime/test/shaders/gs_tri.asm (VKH_GS=… vk_harness): 0 error.
Integer clamp The VOP3 clamp bit on v_add_nc_u32, v_sub_nc_u32, v_subrev_nc_u32 saturates the result to [0, 0xFFFFFFFF], and on v_add_nc_i32/v_sub_nc_i32 to [0x80000000, 0x7FFFFFFF]; without it they wrap. GFX9+ semantics: LLVM selects uaddsat/usubsat and saddsat/ssubsat to exactly these ops with clamp set. Until this change clamp was silently ignored on the unsigned ops (and the signed ones were Unsupported). Checked on the CPU by tests/semantic/test_alu_add_nc_clamp.py, not yet GPU-verified.
s_absdiff_i32, s_mul_hi_i32 s_absdiff_i32: D = |S0 − S1| with the 32-bit difference wrapped first (0x7FFFFFFF − 0x80000000 → 1; a difference of −2³¹ stays 0x80000000), SCC = D ≠ 0. s_mul_hi_i32: high word of the signed 64-bit product, SCC kept. From the RDNA2 ISA pseudocode; checked on the CPU by tests/semantic/test_salu_absdiff_mul_hi.py, not yet GPU-verified.
SCC from scalar ALU s_and/or/xor/andn2/orn2/nand/nor/xnor_b32 and s_lshl/lshr_b32 set SCC = result ≠ 0, s_add/sub_i32 and s_addk_i32 set it to signed overflow, s_min_u32/s_max_u32 to S0 < S1 / S0 > S1, and s_min_i32/s_max_i32 to the same compared signed: SCC is 1 when S0 is the one chosen, and a tie chooses S1 (RDNA2 ISA, S_MIN_I32: D = S0 < S1 ? S0 : S1, SCC = 1 if S0 is chosen). Before this fix these ops left SCC unchanged, so a following s_cbranch_scc* read a stale flag, and until 2026-11-21 s_min_i32/s_max_i32 set SCC on a tie. 32-bit scalar shifts now mask the amount to 5 bits. GPU-checked with runtime/test/shaders/ps_scc.asm and ps_scc_minmax.asm (NVIDIA GeForce RTX 2060 SUPER, Linux, driver 620.70.06: 4096/4096 pixels exact, and all 4096 differ with the old translator). On lane masks in a wave32 program (a source is EXEC, VCC or a mask SGPR, or the result goes to EXEC) the 32-bit bitwise ops' result is the whole wave's mask, so SCC is a subgroup vote (OpGroupNonUniformAny), as for the _b64 forms. Until 2026-11-22 each lane took its own bit: s_and_b32 s0, vcc_lo, exec_lo; s_cbranch_scc0 skipped the block in lanes whose bit was 0, and a loop closed by s_andn2_b32 exec_lo, ...; s_cbranch_scc1 let each lane leave early. Found and checked by tools/cf_diff.py (FUZZ-8, CPU differential against the ISA model); GPU test runtime/test/shaders/ps_scc_mask32.asm passes (s5 == 8 on 2,048 pixels, 192 of them with bit 0, and s5 == 7 on 2,048) on an NVIDIA RTX 4050 Laptop (Linux, driver 620.73.04, natively and under LEONIDA_W64_EMULATE=1) and an AMD Radeon 740M (RADV, Mesa 26.3.1), and on an RTX 2060 SUPER per #634. A 32-bit op on one half of a wave64 mask still takes the lane's bit (its SCC would be a vote of that half).
Far branches s_getpc_b64; s_add_u32 K; s_addc_u32 0/−1; s_setpc_b64 on the same pair is a branch beyond s_branch's ±32K-dword range. It's folded into one branch to (address after s_getpc) + K before CFG construction.
Buffer format stores buffer_store_format_* and _d16_* encode every format the loads decode (the same FORMATS table: f32/u32, f16, unorm/snorm 8/16/10-10-10-2, uint 8/16). 1–2-byte elements are merged into their dword with atomic and/or so neighbours are kept. The atomics use element 0 of the array at the aligned dword address, which also compiles on MoltenVK 1.4.0 (checked with cs_store on an Apple M3 Max and Mesa llvmpipe). d16 data is unpacked first (f16 → float for float kinds, 16-bit integers for integer kinds). Before this, only four f32 formats, rgba16f and rgba8 unorm were stored, and everything else silently stored nothing. GPU-checked with runtime/test/shaders/cs_store.asm (rgba8 unorm, R10G10B10A2 (2_10_10_10), two r16f halves of one dword, d16 rgba16f: exact, neighbours untouched). buffer_load_format_d16_* packs pairs the same way.
s_lshl1..4_add_u32 D = (S0 << N) + S1. SCC = the sum taken in 64 bits is ≥ 2³², so a bit shifted out of S0 sets it as well as a carry out of the add (RDNA ISA pseudocode: tmp = (64'U(S0) << N) + 64'U(S1)). Checked on the CPU by tests/semantic/test_salu_lshl_add.py, not yet GPU-verified.
Other additions image_gather4_l(_o): no explicit-LOD gather in core Vulkan, so four OpImageFetch at mip round(LOD) in gather order. Each of the four texel coordinates goes through the S#'s own address mode, read from S# word0 (CLAMP_X = bits [2:0], CLAMP_Y = [5:3]; fields from Mesa src/amd/registers/gfx10-rsrc.json, values SQ_TEX_* in Mesa gfx6.json, matching RADV's radv_tex_wrap mapping of Vulkan address modes): 0 wrap (c mod n), 1 mirror (c mod 2n, reflected), 2 clamp to the last texel, 3 mirror-once (-1-c for negative c, then clamped), as in Vulkan's address-mode definitions. A literal S# (s_mov_b32 earlier in the block) is decoded at translation time; otherwise the mode is read from the SGPR at run time. A literal S# with a border mode (4-7: half-border, border colour) or FORCE_UNNORMALIZED is Unsupported; a run-time S# can't be judged, so modes 4-7 act as clamp-to-edge there and FORCE_UNNORMALIZED (word0 bit 15) is not applied (coordinates are still scaled by the image size). Those two are the remaining approximations; the unnormalized rules (texel-unit coordinates, mip 0) weren't confirmed on hardware, so they were not guessed. GPU-checked with runtime/test/shaders/ps_gather_wrap.asm (vk_texture_test; expected values derived by hand in its header; six border cases, three literal and three run-time S#) on AMD (Radeon 880M, wave64) and NVIDIA RTX 5070. image_gather4_lz_o: OpImageGather … Offset. image_store on 1D (bindings 17–19, Image1D) and with a16 coordinates. ds_swizzle BITMASK_PERM ("pippi" masks; GPU-checked). v_add_f64, v_cvt_f32_f64 (Float64). v_mul/mad_i32_i24, v_alignbyte_b32, v_xnor_b32, v_ffbh_i32, v_swap_b32, s_abs_i32, s_bfm_b32/b64, 64-bit ordered and v_cmpx compares, 16-bit compares, 8/16-bit global loads, neg(…) constant operands (GPU-checked where listed in runtime/test/shaders).
v_mad_u64_u32, v_mad_i64_i32 {sdst, D} = S0 × S1 + S2 as a 65-bit result (RDNA ISA pseudocode), the product unsigned or signed. sdst (a lane mask) gets bit 64: the carry out for u64, and for i64 the sign of the exact sum (bit 64 of a 65-bit two's-complement value), not a signed-overflow flag. clamp is rejected. Checked on the CPU by tests/semantic/test_alu_mad64.py, not yet GPU-verified.
Ray tracing image_bvh_intersect_ray / image_bvh64_intersect_ray (64 CS: RT shadows) are one traversal step against AMD's hardware BVH node format. The traversal loop lives in the game's shader. The step is emulated over buffer reads following Mesa RADV's software path (radv_nir_rt_common.c, intersect_ray_amd_software_box/_tri; node layouts from bvh_defines.h). Node id = address >> 3 | type (0–3 triangle, 4 box16, 5 box32). Box nodes give the four child ids, with misses and NaN boxes = 0xFFFFFFFF, sorted by entry distance when descriptor bit 63 (box_sort_enable) is set. Triangle nodes use the watertight test with RADV's shared edge/vertex tie-breaks and give (t/|det|, sign(det), v/|det|, w/|det|), or (inf, 1, 0, 0) on a miss. The game's code divides by .y exactly as for the hardware's numerator/denominator. Address = descriptor base + ((node & ~7) << 3), base = descriptor bits [39:0] in 256-byte units (assumption: RADV only uses base 0). The runtime must build the game's acceleration structures in this AMD node format (RADV's GPU BVH builder produces it) wherever the game's D3D12 calls build them. Far branches with s_sub_u32/s_subb_u32 (backward) are folded too. GPU-checked with runtime/test/shaders/cs_bvh.asm: sorted box children and the triangle result are exact.
Coverage Every shader in the corpus translates. The remaining fidelity gap is wave64 cross-half code on 32-wide subgroups in VS/PS/GS; compute and mesh shaders are exact there with --wave64-emulate (see the wave-size and wave64 rows).
Flat pixel inputs A pixel input location read only by v_interp_mov_f32 is declared Flat. Locations read with v_interp_p1/p2 remain interpolated. The ps_flat GPU test passes integer IDs through the first vertex alongside interpolated UVs.
Pixel-shader interpolants When a sidecar fssm/<name>.fssm holds a pixel-input table (tools/fssm_header.py: 8-byte records from 0x138 while the first byte is 6; table position = v_interp attr number), every position 0..count−1 is declared as a fragment input at that Location, including positions the code never reads (the table overcounts the code's distinct v_interp attrs in 775 of 12,101 PS: 300 by one, 475 by two or more; only the 10 records starting with kind 7 undercount). A 32-bit v_interp read (p1/p2/mov) of a 16-bit-flagged position (flag bit 4; 11,199 such inputs corpus-wide, matching the *_f16 interpolation opcodes in 99.7%) sees the value rounded to f16 (round to nearest, f16 denormals flushed to signed zero, back to f32) via a single OpQuantizeToF16 (a PackHalf2x16/UnpackHalf2x16 round-trip is folded to a no-op by at least one Vulkan driver, RTX 5080); reads through the *_f16 opcodes already narrow and are unchanged, and reads past the table still declare an input (the value is undefined on hardware). Without a sidecar, or with an empty table, the output is byte-identical to the code-driven path. Confirmed by synthetic fixtures plus mini-interpreter agreement (tests/test_rdna2spirv_pixelinput.py: an f32 read of a flagged slot with input 1.1 yields the f16-rounded 1.099609375; unflagged and table-less controls yield exact 1.1), no GPU needed. The index.json entry records ps_interpolants (count) and ps_fp16_interpolants (flagged positions).
Whole-wave masks tools/lane_masks.py tracks per-lane mask bits through scalar registers, vector operations and saved EXEC spills. Whole-mask counts, first-set-lane queries and equality use subgroup operations. cs_wavemask checks all 64 lanes with a partially active EXEC mask. A physical 32-lane subgroup cannot directly exchange mask bits with the other half of a wave64, so cs_wavemask and the cs_wave64_ballot / cs_wm_* tests are exact only on 64-wide subgroups (AMD): on an RTX 4090 (subgroup 32) s_bcnt1_i32_b64 of lanes 16–47 counts 16, one half (#101). check.py skips them where the GPU has no 64-wide compute subgroup.
Floating-point operations Separate floating-point instructions carry NoContraction so the driver preserves their individual rounding. Instructions that explicitly fuse multiply-add still emit Fma.
v_cvt_f32_f64 output modifiers Convert to f32, apply mul:2, mul:4, or div:2 if present, then apply clamp to [0, 1] if requested. LLVM GFX10 assembler tests confirm the modifier encodings. tests/test_f64_conversion.py checks the resulting SPIR-V data flow.
v_add_f64 output modifiers The double sum is scaled by mul:2, mul:4 or div:2 if present, then clamped to [0, 1] if clamp is set, as for f32 (clamp_mods_f64, GLSL.std.450 FClamp on the double, so a NaN result and the sign of a -0 result are left to the driver, also as for f32). Until 2026-11-22 both were ignored. Source: LLVM AMDGPU defines it as VOP3Inst<"v_add_f64", VOP3_Profile<VOP_F64_F64_F64>> (VOP3Instructions.td), and VOPProfile sets HasClamp (f64 is a modifier type) and HasOMod (floating-point destination) (SIInstrInfo.td). It is the only f64 arithmetic the translator handles; v_cvt_f32_f64 has the row above. tests/test_f64_output_modifiers.py checks the SPIR-V data flow; runtime/test/shaders/ps_f64_mods.asm is the GPU test (needs shaderFloat64, which vk_harness now enables when the fragment shader declares Float64), passed on an NVIDIA RTX 6000 Ada (driver 615.71.09, Linux; 4096/4096 pixels exact, and the main translator gives the predicted old words).
Floating-point class compare v_cmp_class_f32 writes the selected class to a lane mask. v_cmpx_class_f32 intersects the existing EXEC with that same predicate and preserves VCC, as specified in AMD's RDNA2 ISA §12.9. cs_cmpx_class_f32 checks both encodings with quiet NaN, positive infinity and signed zero, and verifies that a previously inactive lane stays inactive. GPU-checked on an RTX 4070 SUPER (driver 616.92).
Multiply-add with a literal v_fmamk_f32/v_madmk_f32 are D = S0 × K + S1 and v_fmaak_f32/v_madak_f32 are D = S0 × S1 + K, K being the 32-bit literal. LLVM prints them vdst, src0, K, vsrc1 and vdst, src0, vsrc1, K, so in print order all four are a[1] × a[2] + a[3] (fused for fmamk/fmaak). Until 2026-11-21 fmamk and madmk computed S0 × S1 + K. Source: RDNA2 ISA (V_FMAMK_F32, V_MADMK_F32) and the operand fields of the llvm-mc encoding. Checked by tests/semantic and GPU-checked with runtime/test/shaders/ps_fma_literal.asm on an NVIDIA GeForce RTX 2060 SUPER (Linux, driver 620.70.06): 4096/4096 pixels exact, and 4096/4096 differ with the old translator.
Multiply-add and output modifiers v_mac_f32 is the VOP2 form of v_mad_f32, not of v_fma_f32: the product is rounded before the add (OpFMul + OpFAdd, both NoContraction). It used to emit Fma, one ULP off on some inputs. Source: LLVM SIInstrInfo.cpp getNewFMAInst (V_MAC_F32 -> V_MAD_F32_e64, V_FMAC_F32 -> V_FMA_F32_e64). VOP3 clamp and mul:2/mul:4/div:2 now apply to v_cvt_f32_i32/u32/ubyte0..3, v_cvt_f32_f16 and v_rcp_iflag_f32 (they were dropped). Source: LLVM VOPProfileI2F (Ins64 = $src0, $clamp, $omod) and the float-source profiles. Found by tools/f32_fuzz.py (FUZZ-3: an exact-arithmetic model against the translated SPIR-V; 0 mismatches over 10,000 seeded programs after the fix) and pinned by runtime/test/shaders/ps_f32_mods.asm (tests/semantic/test_f32_valu.py); not yet GPU-verified. Still open: on some inputs the ISA defines a result but the emitted SPIR-V is undefined: v_rcp_f32(±0) (OpFDiv by zero), v_rsq_f32/v_log_f32 of ±0 or a negative, v_sqrt_f32 of a negative, v_cvt_pk_u8_f32(NaN) (FClamp).
Wave64 handling Wave size is detected per shader from the code (64-bit EXEC writes, exec_hi, v_mbcnt_hi, *_saveexec_b64/*_wrexec_b64, and 64-bit lane-mask SOP ops s_bcnt[01]_i32_b64 / s_ff[01]_i32_b64 / s_wqm_b64 / s_bfm_b64 even when the mask is an ordinary SGPR pair; mesh shaders are always wave64). Until 2026-11-21 a mask-only wave64 program with no EXEC markers was translated as wave32, so s_bcnt1_i32_b64 counted one half (#210). GPU-checked with runtime/test/shaders/cs_w64_mask_detect.asm (48 set bits of (lane & 5) != 0) on NVIDIA GeForce RTX 5060 under LEONIDA_W64_EMULATE=1. The hardware lane is exact in compute and mesh shaders (LocalInvocationIndex mod 64 or 32) and is used by v_mbcnt and EXEC writes. In other stages it's the subgroup lane. Constant EXEC writes (s_mov_b32 exec_lo/exec_hi, K) set each lane from its own bit of K; before, any non-zero constant turned every lane on. A register written to exec_hi sets lanes 32–63 only. GPU-checked with runtime/test/shaders/cs_exec64.asm: lanes 16–47 enabled from two constants, exact on a 32-wide-subgroup GPU. Still approximate on 32-wide subgroups: cross-lane ops between the two halves of a wave64 (readlane/permlane/DPP/shuffles across lane 31/32, wave-wide reductions). The metadata index marks every wave64 shader so a runtime can request requiredSubgroupSize = 64 where supported (AMD), which makes those exact too.
Wave64 emulation (--wave64-emulate) Wave64 compute and mesh shaders exact on any subgroup size (32-wide NVIDIA, Intel, AMD in wave32 mode), with no subgroup operation at all. One invocation is still one lane. Everything a lane needs from the rest of its wave goes through a Workgroup buffer %x_buf: votes (s_cbranch_vccz/vccnz/execz/execnz, SCC of mask ops, s_cmp of masks), whole-mask words (s_bcnt1, s_ff1, v_mbcnt), v_readlane, v_readfirstlane, ds_bpermute, ds_swizzle, v_permlane16/x16. The program runs in rounds: in each round every wave that is neither done nor waiting at s_barrier runs one segment of its program (a basic block, cut at each cross-lane op), then the whole workgroup meets at one OpControlBarrier (Workgroup, AcquireRelease, workgroup + uniform + image memory) that sits in uniform control flow, because every invocation runs every round. A cross-lane op ends its segment after the lane has stored its value (per-lane data, double-buffered by round parity) or ORed its bit (two mask words per wave, three slots by round mod 3, each slot cleared two rounds after it was read); the code after it runs one round later, when all 64 lanes have written. SSA values live across a cut go through Function variables. s_barrier is a scheduler state: the wave stops running segments until every wave that isn't done is waiting, which is also how hardware counts finished waves. A memory access that conflicts with an earlier one in the same segment (read after write, write after read, write after write; LDS and buffer/image memory separately) starts a new round, so two halves of a wave in different subgroups access memory in instruction order, as the lanes of one hardware wave do; not ordered: scalar loads of memory the wave wrote, and sampling an image it wrote. The missing lanes of a partial last wave read as 0. Without the flag the output is unchanged, apart from two fixes that apply to every wave64 compute/mesh shader: v_writelane_b32 selects the lane by the wave lane (on a 32-wide subgroup writes to lanes 32–63 were lost; cs_w64x_writelane), and ds_bpermute_b32 (see the LDS row). Fewer rounds, same results: a whole-mask read (s_bcnt1, v_mbcnt_lo/hi, ...) of the value of the same register (or EXEC) that an earlier read in the block already exchanged reuses that exchange (the value's identity is the SSA id last stored to the register, forgotten at block start and at any label); and a block that ends in a voted branch (s_cbranch_vccz/vccnz/execz/execnz) runs its successor in the round that reads the vote, since that segment only reads the vote and picks the next block (an inner loop in the scheduler, flag %x_chain). Both rules are pinned by cs_w64x_mask_reuse (a mask register and EXEC rewritten between reads), cs_w64x_mask_reuse2 (EXEC read twice, a read after a buffer store, one half of a mask pair rewritten while the other is kept, a voted branch whose successor starts with a load of the other half's earlier store) and cs_w64x_chain_barrier (a voted branch whose successor starts with s_barrier, two waves): expected values from the ISA, first run on the AMD 880M with its native 64-wide subgroup, then emulated on both GPUs; tests/test_translate.py counts the exchanges in the SPIR-V (one per value, a new one after a rewrite of the register or EXEC), and the translator refuses (Unsupported) a voted branch whose segment was not started by the vote's own round. scripts/bench_wave64.py times cs_bench_mix native and emulated and checks the emulated output bytes against the native AMD run. Cost: one workgroup barrier per segment, and %x_buf = (2·L + 6·W + 7) dwords for L invocations in W waves, counted in lds_bytes. GPU-checked on NVIDIA GeForce RTX 5070 Laptop (subgroup 32, driver 617.42) and AMD Radeon 880M (subgroup 64, AMD driver 26.11.2 LLPC): check.py 38/39 (the mesh test runs in the other script) and scripts/run_gpu_tests.py 40/40 on both with LEONIDA_W64_EMULATE=1, including every wave64 test (cs_wavemask, cs_wave64_ballot, cs_wm_*) and the cross-half suite cs_w64x_* / ms_w64x_ballot: readlane and writelane at lanes ≥ 32, readfirstlane with only upper lanes active, branches voted by one lane of either half, ballot + v_mbcnt_lo/hi compaction over 64 lanes (also in a mesh shader, 4096/4096 pixels), a 128-thread workgroup whose two waves take different branches, s_barrier between waves with different loop counts, LDS read-after-write and write-after-read across the halves without a barrier, a load, ballot and load in one block, and a partial wave (group 40). Without the flag the same RTX 5070 passes 19/37 (the wave64 tests skip there). Not covered: VS/PS/GS (no workgroup memory or barrier there).
Metadata index spirv/index.json: one entry per translated shader with its stage, wave64 / subgroup_size, SPIR-V capabilities and extensions, the Vulkan features to enable (barycentrics, interlock, mesh, geometry, Float64, Int64, buffer device address, write-without-format, …), needs_maintenance8, the descriptor bindings it uses (set 0), push-constant size, local_size, user_sgprs (CS), lds_bytes, mesh max_vertices/max_primitives/params, geometry inputs/outputs, vertex-input locations and types, full vertex_input_signature (ISG1 register/mask/system-value/component-type, for PSO lookup), wave64_emulated (true for VS/PS/GS wave64: 64-wide subgroups can only be requested for compute/mesh, so graphics wave64 stays emulated 2x32 until cross-half ops go through LDS; also true for compute/mesh translated with --wave64-emulate, which then carry wave64_exchange: "workgroup" and subgroup_size: null: any subgroup size is exact, request none), dynamic_format (runtime V# FORMAT: codes outside FORMATS decode to 0) / fixed_format_codes, src_sha256 and optional fssm_sha256 (via --fssm-dir), PS system inputs, and input/output locations. A runtime can create every pipeline at load time from it without parsing SPIR-V.
Full-corpus pipeline build vk_pipeline_check <spirv dir> pipeline_cache.bin --jobs 4 on an RTX 4060 Ti (NVIDIA 595 driver): all 26,503 shaders become real pipelines, 0 failures (cs 2,689, ps 12,101, ms 9,282, vs 2,236, gs 195; graphics stages with generated stub partners). Compile time 40,784 s of CPU (2.84 h wall on 4 threads): cs 23,633 s (mean 8.8 s; the ray-tracing ScreenProbes/RTShadowTrace shaders take 2-19 min each), ps 11,481 s, ms 5,395 s, vs 275 s. The resulting VkPipelineCache is 3.81 GB; seeding a run with it makes those pipelines instant, which is what a fast first boot needs. The cache is per driver and GPU, and a shader whose SPIR-V changes compiles again (the checker resumes from the file). Neither register storage (one variable per register) nor smaller SPIR-V cut NVIDIA compile time: the big ray-tracing shaders are expensive as such, so the runtime should compile them in the background rather than block on them.
Wave-uniform branches VCC and EXEC are wave-wide registers, but one invocation holds only its own lane's bit. s_cbranch_vccz/vccnz/execz/execnz therefore reduce the condition across the subgroup (OpGroupNonUniformAny), so the whole wave takes the branch together, as on hardware. Before this, each lane decided alone. A lane could skip scalar instructions that the hardware wave executes (its SGPRs went stale for later code), and cross-lane ops or barriers inside the block saw a split wave. v_cmp/v_cmp_class/64-bit compares now write 0 for inactive lanes (hardware VOPC behaviour), so the reduction sees the true mask. GPU-checked with runtime/test/shaders/ps_uniform_branch.asm: lanes whose own VCC bit is 0 run the block's scalar add when their wave has any set bit. s_cbranch_scc0/1 stay per lane; SCC is uniform as long as the SGPRs feeding it are.
Compute shaders FSSM header word 0x138 = COMPUTE_PGM_RSRC2: USER_SGPR [5:1], TGID_X/Y/Z_EN [9:7], TG_SIZE_EN [10], TIDIG_COMP_CNT [12:11], LDS_SIZE [23:15] in 512-byte units. Words 0x13C/0x140/0x144 = thread-group size. This was checked against what all 2,689 CS read before writing: 2,281 match exactly, and the rest overshoot only through loop-carried registers in the straight-line check. 0x110, which looked similar, doesn't match. Layout: s0..user−1 = user data (push constants), then the enabled workgroup IDs (WorkgroupId), and v0/v1/v2 = thread ID x/y/z (LocalInvocationId, separate VGPRs on GFX10). Example: the 1,013 shaders with RSRC2 0x998 have 12 user SGPRs, group ID x/y in s12/s13, and compute x = s12·32 + v0. Shaders with TG_SIZE_EN are rejected for now. GPU-checked with runtime/test/shaders/cs_lds.asm through runtime/test/vk_compute_test.cpp: 4 groups × 64 threads, LDS exchange between the two waves of a group behind s_barrier, store through a V# into the device-address heap, 0 mismatches.
Workgroup barriers s_barrier (cs/ms) is one OpControlBarrier (workgroup scope, workgroup memory). On RDNA every s_barrier counts against the same workgroup barrier and a wave that has ended no longer counts, while Vulkan requires a barrier to be reached by every invocation in uniform control flow. Under --wave64-emulate the round loop keeps a single barrier at the top level, so this holds. On the native path it is not proven: the barrier stays where s_barrier is, and in the 1.0.2.1 corpus it sits inside a selection or loop construct in 43 of the 55 wave32 cs shaders with s_barrier (always native) and in every ms and most wave64 cs shaders when they run natively (AMD). Branches are scalar, so whole waves take the same path. No hang has been seen: cs_barrier_divergent.asm (two barrier sites in different branches), an early end of the other waves and a per-wave loop count all pass on NVIDIA RTX 4070 Ti (drivers 610.88 and 621.24) and RTX 5090 (Linux 595.99). SHADER-91 tracks this; a barrier-only round scheduler (the emulated loop without its cross-lane part) is the fix if a hang shows up.
LDS A Workgroup uint array sized from LDS_SIZE, rounded up to a power of two that also covers every constant offset (15 of 486 shaders index past LDS_SIZE). Covers ds_read/write_b32..b128, read2/write2 (+st64), u16/i16/u8/i8 reads (also ds_read_u16_d16/_d16_hi and, since SHADER-85, ds_read_u8_d16/_d16_hi and ds_read_i8_d16/_d16_hi: the byte is zero- or sign-extended 8→16 into one half of the destination VGPR and the other half is kept, per the RDNA2 ISA DS opcode descriptions (opcodes 162–165) and as for the u16 d16 reads; GPU-checked with cs_w32_lds_u8_d16.asm, byte values 0x80/0xFF/0x7F with a non-zero offset:), b16/b8 writes (atomic and/or, so neighbouring lanes don't race), the add/sub/min/max/and/or/xor atomics with and without return, wrxchg, cmpst (OpAtomicCompareExchange with DATA as comparator and DATA2 as value), and ds_bpermute_b32 as a subgroup shuffle. ds_permute_b32, its forward (scatter) form, has no Vulkan equivalent: each source lane that is on in EXEC publishes ((vAddr + offset) >> 2) mod 32 and each destination lane scans the 32 sources of its half and keeps the last one that targets it (a shuffle of target and data per source lane; under --wave64-emulate two buffer rounds and a Function variable instead). Per the ISA pseudocode (tmp[0..63] = 0; next if !EXEC[i] on the source; VGPR[VDST][i] = tmp[i] only if EXEC[i]): a destination lane nobody targets gets 0, an off source sends nothing, an off destination keeps its VDST, and the half rule above applies as for ds_bpermute_b32. When several sources target one lane the ISA leaves the winner unpredictable ("the value from one of the writers"; its pseudocode says the highest-numbered); the translator takes the highest, and nothing may depend on it. Confirmed by the GPU tests cs_w32_permute.asm and, per half of a wave64, cs_w64x_permute.asm (SHADER-90: rotation, offset, unwritten lane = 0, off destination keeps its value, off source does not win) and tests/semantic/test_ds_permute.py. In wave64 the permute runs as two wave32s (RDNA ISA §10.4.4): each half reads lanes of its own half, and a source lane that is off in EXEC reads 0. Until 2026-11-21 lanes 32–63 of a 64-wide subgroup read the low half and inactive sources kept their value (cs_w64x_bpermute, AMD Radeon 880M). A source lane that doesn't exist, in the missing lanes of a partial wave, also reads 0: the shuffle result is kept only where a ballot of the running invocations has the source lane, since SPIR-V leaves a shuffle from an invocation that isn't running undefined. Before this, RADV returned stale register values that changed between runs (cs_w64x_partial, a 40-thread group, native wave64 on AMD RX 6700 XT, RADV Mesa 26.3.1). Writes and atomics run only in active lanes. Indices wrap at the array size, where hardware would return 0 for out-of-range reads. s_barrier = OpControlBarrier Workgroup/Workgroup, AcquireRelease + WorkgroupMemory.
Compute workgroup IDs Y/Z With four user SGPRs and only TGID_Y and TGID_Z enabled (RSRC2 0x308), s4 receives Y and s5 receives Z. The synthetic cs_workgroup_yz.asm fixture checks a 2 × 3 × 4 dispatch and each of its 24 origins against a CPU reference.
Typed image stores image_store (2D, 2D array, 3D) writes the dmask components (missing ones = 0). The image's numeric type lives in the T# (word 1 FORMAT [28:20], 512 GFX10 formats), so it is decided at run time. A 512-bit table built from tools/gfx10_formats.json (30 UINT and 15 SINT formats) picks a sint, uint or float view (bindings 8 + 3·dim + class; dim 0 = 2D, 1 = 2D array, 2 = 3D; class 0 float, 1 uint, 2 sint). Views have Unknown format (shaderStorageImageWriteWithoutFormat). The runtime binds every storage image into all three arrays of its dimension, or at least the one matching its format. The earlier path wrote only component 0 as r32ui, which was wrong for every other format. GPU-checked with runtime/test/shaders/cs_imgstore.asm through runtime/test/vk_store_test.cpp: rgba8 unorm, r32 uint and r32 sint images, every texel correct.
Typed image loads image_load on 1D/2D/2D-array/3D images uses the same T# FORMAT tables as stores: UINT/SINT formats are read with OpImageRead through the uint/sint storage views (shaderStorageImageReadWithoutFormat), everything else with OpImageFetch through the float sampled view as before. Results are the raw bits of the dmask components. The runtime binds integer-format images into the uint/sint storage arrays of their dimension (bindings 8–19), as for stores. Before this, every load went through the float view, which is undefined for integer formats. GPU-checked with runtime/test/shaders/cs_imgload.asm (r32 uint read back exactly).
SDWA _sdwa forms: each source is narrowed to src0_sel/src1_sel (BYTE_n/WORD_n, zero-extended, or sign-extended under sext()) before neg/abs and the op. A VGPR result goes to dst_sel, with dst_unused setting the other bits: PAD = 0, SEXT = sign copies above the field, PRESERVE = old bits kept. VOPC has no dst_sel, and GFX10 v_cmpx has no written destination. Until 2026-11-20 the selects were silently ignored. That affected 3,826 of the 13,926 translated shaders: they passed spirv-val but computed wrong values. GPU-checked with runtime/test/shaders/ps_sdwa.asm and ps_ops.asm (also v_pk_fma_f16, v_min3_u32, v_max3_i32, v_bfe_i32): byte/word source selects, sext(), UNUSED_PRESERVE into WORD_1 and UNUSED_SEXT at BYTE_2 all match on every pixel.
Byte permute v_perm_b32: result byte i = BYTE_PERMUTE({src0, src1}, selector byte i), src1 = bytes 0–3 (AMD "RDNA 2" ISA reference, VOP3 opcode 836 V_PERM_B32, byte_permute pseudocode, page 189 of the PDF). Selector 0–7 picks that byte; 8, 9, 10, 11 give 0xff if bit 7 of byte 1, 3, 5, 7 is set, else 0x00; 12 gives 0x00; 13 and above give 0xff. Until 2026-11-21 selectors 8–11 gave 0x00 regardless of the sign bit. In the 26,503-shader disassembled corpus (measured via tools/feature_scan.py), 0 of 10,500 shaders (11,930 v_perm_b32 instructions) use selectors 8–11 or >= 13: all 11,258 immediate and 672 constant-register selectors (0 unresolved) use only bytes 0–7 (36,234) and 12 (11,486). GPU-checked with runtime/test/shaders/ps_ops7.asm (also v_alignbit_b32 with a shift of 36, v_med3_i32 vs v_med3_u32) and ps_ops8.asm (v_mul_hi_u32/i32, v_bcnt_u32_b32, v_ffbl_b32, v_ffbh_u32 of 0, v_xad_u32, v_add3_u32), 4096/4096 pixels on an AMD Radeon iGPU (Ryzen 7 9800X3D, RDNA2, AMD driver 25.10.36) and an NVIDIA GeForce RTX 5070 (driver 621.24); before the fix ps_ops7 gave 0x00000000 for the sign-selector word on both. Also executed by tests/semantic/test_value_semantics.py.
Sum of absolute differences (v_sad_u8, v_sad_hi_u8, v_sad_u16, v_sad_u32, v_msad_u8) Unsigned, wrapping at 32 bits, with ABSDIFF(x, y) = UMax − UMin: v_sad_u8 = S2 + the sum over the four bytes; v_sad_hi_u8 = (that byte sum << 16) + S2; v_sad_u16 = S2 + the sum over the two halves; v_sad_u32 = |S0 − S1| + S2; v_msad_u8 skips a byte where S1's byte is 0. clamp raises Unsupported: the ISA pseudocode doesn't say what it does to these ops. Source: RDNA2 ISA VOP3 opcodes 346–349 and 369 (pseudocode re-read for this row). CPU-checked by tests/semantic/test_alu_sad.py (#544): a 9×9 grid of edge words per op, 40 seeded cases, masked bytes, an SGPR source, clamp rejected; the PR also reports a 300-case differential run per op with 0 mismatches. None of them is in the translated corpus, and none is GPU-checked.
s_sext_i32_i8, s_sext_i32_i16, s_flbit_i32 The first two sign-extend the low byte or the low half of S0 to 32 bits (OpBitFieldSExtract). s_flbit_i32 counts how many bits in a row from the MSB equal the sign bit, and gives −1 when all bits are the same (0 and −1); it is the scalar form of v_ffbh_i32 and goes through the same code. None of the three writes SCC. Source: RDNA2 ISA SOP1 opcodes 23, 25 and 26. CPU-checked by tests/semantic/test_salu_sext_flbit.py (#549): edge words with SCC starting at 0 and at 1, and 30 seeded values with long runs of sign bits. Not in the translated corpus, not GPU-checked.
v_lerp_u8 Per byte i: D.b[i] = (S0.b[i] + S1.b[i] + (S2.b[i] & 1)) >> 1, an unsigned average where bit 0 of S2's byte decides whether 0.5 rounds up. The 9-bit sum shifted right by 1 fits back in its byte, so nothing carries between bytes. clamp raises Unsupported (the ISA doesn't define it for this op). Source: RDNA2 ISA VOP3 opcode 333. CPU-checked by tests/semantic/test_alu_lerp_u8.py (#577): a 9×9×5 grid of edge and rounding words, 40 seeded cases, an SGPR source with an inline S2, clamp rejected. Not in the translated corpus, not GPU-checked.
Relative VGPR moves (v_movrel*) The VGPR file is a Function-scope uint array, so v_movrels_b32/v_movreld_b32/v_movrelsd_b32 become dynamic array accesses at reg + M0 (the whole of M0, as the RDNA2 ISA's opcode descriptions say). v_movrelsd_2_b32 (VOP1 opcode 72) offsets each side by its own field: VGPR[D + M0[25:16]] = VGPR[S0 + M0[9:0]], other M0 bits ignored (RDNA2 ISA §12.8 opcode description and the RDNA3 ISA; the RDNA2 §6.6 summary table prints M0[7:0] for the source). The write keeps inactive lanes. Not modelled: the hardware's range check against the wave's VGPR allocation (an out-of-range source reads VGPR0, an out-of-range write is dropped). CPU-checked by tests/semantic/test_alu_movrelsd_2.py (including set ignored M0 bits); GPU-checked with runtime/test/shaders/cs_movrelsd_2.asm (the ISA's own example, v25 ← v17 with M0 = (20 << 16) | 10) on NVIDIA RTX 4050 Laptop (Ada) and AMD Radeon 740M (RADV).
Float-to-int saturation v_cvt_u32_f32 and v_cvt_i32_f32 truncate toward zero, saturate out-of-range values (including infinities) to the destination bounds, and return zero for NaN. The conversion operand is kept in range before emitting SPIR-V OpConvertFToU/OpConvertFToS. Source: AMD RDNA 2 ISA reference, §12.8, VOP1 opcodes 7 and 8. The synthetic cs_cvt_f32_sat.asm fixture is checked bit-for-bit by tests/semantic/test_float_to_int.py.
v_cvt_flr_i32_f32, v_cvt_rpi_i32_f32 RDNA ISA pseudocode: f32_to_i32(floor(S0)) and f32_to_i32(floor(S0 + 0.5)), the + 0.5 rounded in binary32 like any f32 add (so 0.49999997 gives 1, where an exact round-half-up would give 0). f32_to_i32 saturates as in the row above: INT_MAX / INT_MIN at or past ±2³¹ and for ±inf, 0 for NaN. Source neg/abs apply first. Checked on the CPU by tests/semantic/test_alu_cvt_flr_rpi.py, not yet GPU-verified.
f16 rounding (SHADER-55, SHADER-56) Narrowing to f16 uses integer ops, not PackHalf2x16. Every f16 ALU result (v_*_f16 VOP1/VOP2/VOP3, v_pk_*_f16, v_cvt_f16_f32, v_interp_p2_f16, v_fma_mix*) and v_cvt_pkrtz_f16_f32 go through Gen.f16_bits (round to nearest even, or round toward zero for pkrtz; f16 denormals kept, f32 denormal inputs give ±0, NaN stays a quiet NaN). GLSL.std.450 leaves PackHalf2x16's rounding to the implementation, and drivers fold a PackHalf2x16 → UnpackHalf2x16 round trip to a no-op, so the next f16 op saw the unrounded f32: #513 (RTX 6000 Ada, --wave64-emulate, v_pk_add_f16 → v_pk_mul_f16 1 ulp off), and pkrtz giving round-to-nearest on llvmpipe. f16 FMAs round once (v_fma_f16, v_fmac_f16, v_pk_fma_f16): x·y is exact in f32, TwoSum gives the exact error of the f32 sum, and round-to-odd at f32 then rounds correctly to f16. An RX 6700 matched a correctly rounded f16 FMA in 12,612 of 12,612 cases (#374); Fma then narrowing double-rounded. Checked by tests/semantic/test_f16_int_convert.py (edges + seeded sweep against Python's binary16), tests/semantic/test_f16_fma_rounding.py (exact rational reference; built near-tie cases fail on the old translation) and tools/valu_fuzz.py --family f16 on an RTX 6000 Ada. Image/buffer d16 packing (#489) and the 16-bit interpolant quantize (#512) are separate. v_fma_mix* with f32 sources still uses Fma.
v_interp_p2_f16 clamp The VOP3 clamp bit on v_interp_p2_f16 clamps its f16 result to [0, 1], applied before the narrowing like the other f16 results (Mesa ACO aco_opcodes.py declares the op dst(F16), which takes output modifiers; llvm-mc encodes clamp on it but no omod). Until 2026-11-22 the translator dropped it. Checked by tests/semantic/test_interp_f16.py: attributes 1.5 and -0.25 read with clamp give 1.0 and +0.0, and without it 1.5 and -0.25. No GPU test: vs_ids gives attributes in [0, 1) only.
Known approximations v_cvt_pkrtz_f16_f32 is now exact round-toward-zero (finite overflow gives ±65504, not inf). The GPU smoke test caught the old round-to-nearest version producing inf in PS_ImposterShadow. The other f16 packs (v_cvt_f16_f32, d16 results, mix ops) round to nearest, which matches the default mode (ALU sites: see the f16 rounding row). The MODE register (s_setreg) is ignored, so denormal and rounding behaviour is Vulkan's default. v_mul_legacy_f32 now keeps the 0 × anything = 0 rule like v_mad_legacy_f32 (GPU-checked with runtime/test/shaders/ps_legacy_mul.asm on AMD Radeon RX 9070 XT).
Known approximations v_cvt_pkrtz_f16_f32 is now exact round-toward-zero (finite overflow gives ±65504, not inf). The GPU smoke test caught the old round-to-nearest version producing inf in PS_ImposterShadow. The other f16 packs (v_cvt_f16_f32, d16 results, mix ops) round to nearest, which matches the default mode (ALU sites: see the f16 rounding row). The MODE register (s_setreg) is ignored, so denormal and rounding behaviour is Vulkan's default. Not modelled: v_mad_f32, v_mac_f32 and v_mad_legacy_f32 flush f32 denormals on RDNA2 (a subnormal operand or result becomes zero, whatever the MODE register says). Source: LLVM AMDGPU SIISelLowering.cpp, SITargetLowering::isFMADLegal (llvm-project 1922c0c), which forms these instructions only when f32 denormals are flushed. The translator emits OpFMul + OpFAdd with Vulkan's default denormal handling, so e.g. v_mad_f32(2^-80, 2^-70, 2^-149) gives 2^-149 where RDNA2 gives +0, and v_mad_legacy_f32(2^-149, +inf, -1) gives +inf where RDNA2 gives -1.0. tests/semantic/test_valu_f32_min3_max3_mad.py (DenormalDivergenceTests) pins both columns; not GPU-verified on RDNA2. v_mul_legacy_f32 now keeps the 0 × anything = 0 rule like v_mad_legacy_f32 (GPU-checked with runtime/test/shaders/ps_legacy_mul.asm on AMD Radeon RX 9070 XT).
Whole-quad mode (s_wqm_b64 / s_wqm_b32) A lane mask register holds only this lane's bit, so WQM on one (EXEC, VCC, an SGPR the mask analysis found) ORs the bit of the lane's quad, lanes 4n..4n+3 of the wave: two OpGroupNonUniformQuadSwap (horizontal, then vertical; capability GroupNonUniformQuad) in the default mode in fragment and compute shaders (quad operations are only guaranteed there; vertex, geometry and mesh shaders shuffle from the quad's four lanes), or the four lanes' values read through %x_buf under --wave64-emulate (no subgroup operation there). A quad never crosses lane 31/32, so the mask bits are exact per half on a 32-wide subgroup; SCC is a wave vote, so on wave64 it needs a 64-wide subgroup or --wave64-emulate (as every wave-wide mask op). The result goes to EXEC, VCC or an SGPR pair as a mask, SCC = the wave-wide any of it (same vote as the other mask ops). A 32-bit form in wave64 (exec_lo/exec_hi, vcc_lo/vcc_hi, a half-mask SGPR) writes only its own half (exec_half_write) and votes SCC over that half only (cs_wqm_w64_half). A source that is not a lane mask (a value loaded from memory, a literal) is data: `((x
Buffer bounds checking MUBUF buffer_load*, buffer_store*, and buffer_atomic* enforce num_records (V# word 2): raw buffers (stride == 0) check the starting byte offset (offset < num_records; per-dword tail bounds on multi-dword accesses aren't split yet), and structured buffers (stride != 0) check index < num_records (idxen) or offset < num_records * stride. Out-of-bounds stores/atomics skip memory access completely and out-of-bounds loads return 0. GPU-checked with runtime/test/shaders/cs_bounds.asm on AMD Radeon RX 9070 XT.
Wave64 mask ballot tools/lane_masks.py tracks per-lane masks (including 32-bit MASK_LO/MASK_HI halves, vcc_lo/vcc_hi, and s_bfm_b64 bitfields). s_bcnt1_i32_b64/b32, s_bcnt0_i32_b64/b32, s_ff1_i32_b64/b32, s_ff0_i32_b64/b32, and s_bitcmp0/1_b32/b64 reconstruct the 64-bit wave mask via OpGroupNonUniformBitwiseOr (GroupNonUniformArithmetic), restricting 32-bit half ops and s_cmp_eq/lg_u32 (wave_equal) to the known 32-bit half in wave64. Opposite-half s_cmp_*_u32/i32 comparisons (lo vs hi), ordering comparisons on mask halves, and s_cmp_*_u32/i32/u64 comparing a lane mask against an arbitrary scalar or immediate reconstruct the exact 32/64-bit mask words via wave_mask. GPU-checked with runtime/test/shaders/cs_wave64_ballot.asm and cs_wm_*.asm on AMD Radeon RX 9070 XT (64-wide subgroup); semantic test coverage in tests/semantic/test_scalar_bitcmp.py and tests/semantic/test_scalar_alu_shifts.py.
Mesh/compute input registers (historical measurement) An early read-before-write analysis over all compute and mesh shaders found compute v0 (880), v0–v1 (614), v0–v2 (50), consistent with AMD's local thread ID x/y/z in v0/v1/v2, and scalar inputs centred on a pointer at s[4:5] and s6/s7. Mesh: every one of 2,969 reads exactly v5, plus s3 (always arithmetic), s[16:17] and s19–s23. The early pass also read FSSM 0x13C as the group width and compared the first SGPR multiply against it (82 match, 151 don't, 1,447 no simple multiply) and wrongly concluded that 0x13C was not the group width; the matching register varied by shader (s6/s10/s7/s9…). PSV0 gave the real thread-group sizes (32×1×1 for 1,253, 8×8×1 for 416, …). Superseded: 0x13C/0x140/0x144 are the thread-group size, COMPUTE_PGM_RSRC2 at 0x138 gives the per-shader user-SGPR count and enabled workgroup IDs, and mesh takes NumThreads, limits and topology from PSV0 with v5 = linearGroupIndex * NumThreads + LocalInvocationIndex. All 2,689 CS and 9,282 mesh shaders translate now (see the Compute shaders and Mesh shaders rows).
Formerly untranslated Mesh (9,282), geometry (195) and compute (2,689) now translate; s_swappc_b64 is replaced by Vulkan vertex inputs (see Vertex fetch) and the tbuffer_load_format_* forms use the instruction's format. A few rare ops are still reported by name rather than guessed.

System values confirmed on the corpus (SHADER-4)

Counted with scripts/audit_shader4_regs.py on the disassembled game shaders (counts only):

  • Compute shaders: Confirmed by corpus counts across all 2,689 CS (TIDIG_COMP_CNT 0/1/2/3 = 724/1,786/179/0; TGID X/Y/Z 100/110/111 = 724/1,786/179; TG_SIZE_EN = 0, SCRATCH_EN = 0, TRAP_PRESENT = 0; RBW VGPRs: v0 in 2,602, v1 in 893, v2 in 57) + GPU tests cs_lds.asm and #186's cs_workgroup_yz.asm (Y/Z WorkgroupId).
  • Mesh shaders: Confirmed by corpus counts (all 9,282 MS are 128×1×1 in PSV0, 100% read v5 once, through v_readfirstlane_b32 followed only by s_lshr_b32 D, sX, 7, 100% read s3 exclusively via s_bfe_u32 D, s3, 0x40018 for bits [27:24]; 0 read s3 [31:28], [23:16], or [15:0]; audited with scripts/audit_shader4_regs.py) + GPU tests ms_tri.asm, ms_wave_info_s3.asm (s3[27:24] across both waves), and #219 (mesh v5 workgroup index on a 2 × 3 × 4 grid).
  • Geometry shaders: Confirmed by corpus counts (all 195 GS read only v0 and v1; 0 read v2, v3, or v4) + GPU test gs_tri.asm.

Main blocker at the time (superseded): descriptor loads. On a 3,000-shader sample, s_load_dwordx4/x8 stop over half of them. Shaders load texture, buffer and sampler descriptors through user-data SGPR pointers, and how the game's root signatures map onto those SGPRs is set up by game code. Reading that mapping from the exe (root signature creation plus the FSSM user-data metadata) before building the binding layer was the next step; guessing it would give silent rendering bugs. The translator now handles those loads against the push-constant user-data contract (User data, Scalar/buffer memory and the descriptor rows); the D3D12 layer still has to supply the root-signature mapping. The other blockers listed then (mesh, the vertex-fetch call, geometry, compute and compressed exports) are closed for the corpus: all 26,503 shaders translate (see Translator status). The remaining fidelity gap is wave64 cross-half code on 32-wide subgroups.

Day one, in order

  1. scripts\first_look.ps1 -Exe ... checks the exe is plain, lists the imports to shim, and does a dry run.
  2. Find the RPF9 table-of-contents key and decryption in the exe, then add a table reader to rpf9_carve.py. Carved blobs then get real names and types, and the remaining unread data shows what it is.
  3. Find the texture and mesh resource structures in the exe (their loaders give exact field layouts), which turns carved blobs into named textures and meshes.
  4. Shader translation: already complete for all 26,503 shaders (see Translator status); the day-one work is validating them through the runtime.

Disassembling shaders

The AMDGPU disassembler needs LLVM 21+ built with the AMDGPU target (llvm-mc; on Linux the llvm-21 package installs it at /usr/lib/llvm-21/bin/llvm-mc). The official Windows LLVM build has no AMDGPU target and ships no llvm-mc.exe. On Windows, either build a native one or run it from WSL.

Native: scripts\build_llvm_mc.ps1 fetches the LLVM sources the tool needs (sparse, shallow), builds llvm-mc alone with LLVM_TARGETS_TO_BUILD=AMDGPU, static CRT and the DIA SDK off (its headers need ATL, which the C++ build tools don't always include), checks it disassembles an s_endpgm for gfx1013, keeps only llvm-mc.exe (by default in %LOCALAPPDATA%\Leonida\llvm-mc) and sets LLVM_MC for the user. It needs git, Python and Visual Studio with the C++ x64 tools, about 2 GB of temporary space and 20-40 minutes. -Dest, -NoEnv, -Keep and -Version change the defaults.

powershell -ExecutionPolicy Bypass -File scripts\build_llvm_mc.ps1
python -I make_game.py --game "D:\path\to\your\package" --stages shaders

WSL: install llvm-21 and give LLVM_MC the whole command:

set LLVM_MC=wsl -d Ubuntu -e /usr/lib/llvm-21/bin/llvm-mc
python -I make_game.py --game "D:\path\to\your\package" --stages shaders

The same form works in every tool that reads LLVM_MC. tools/mc_command.py splits it for shader_disasm.py, the tests, runtime/test/shaders/build.py and scripts/run_gpu_tests.py; the assembler callers pass the assembly on stdin, so a WSL command never receives a Windows file path.

shader_disasm.py disassembles one s_endpgm before starting, so a missing tool or AMDGPU target stops the run with that reason instead of writing empty .s files. To disassemble by hand inside WSL:

LLVM_MC=/usr/lib/llvm-21/bin/llvm-mc python3 -I <repo>/tools/shader_disasm.py <work>/shaders/fssm

Code starts at the u32 at FSSM offset 0xC0 (the code-section offset) plus 0x28 bytes into that section, and ends at the last s_endpgm. Use --mcpu gfx1013. On 300 random shaders it decoded 284 cleanly (134 invalid words in total), against 201 clean and 6,560 invalid for gfx1030 and 283 clean for gfx1010–1012.

Pixel-shader inputs

tools/fssm_header.py decodes the FSSM input table: 8-byte records from 0x138 while the first byte is 6. Byte 1 is the semantic id, byte 2 the component mask, byte 3 the running index, byte 6 the parameter slot, and byte 7 holds flags (bit 4 = 16-bit interpolant). The record's position is the v_interp attr number. interpolants() returns the count and a fp16 bitmask by position; a translator can use both, but rdna2spirv.py does not yet. Measured on the 26,503-blob corpus: 25,643 satisfy u32[0x120] + u32[0x12C] == u32[0x130] (the 860 that do not store 0xDEADBEEF at 0x130); 12,101 are PS, 10,307 with a non-empty table (55,791 records, 11,199 of them 16-bit). The count equals the number of distinct v_interp attr numbers in 11,316/12,101 PS (93.5%); 300 more declare one unread input, 475 declare two or more, and the 10 undercounts are one family whose first record at 0x138 has kind 7. A 200-PS spot check agreed on 187/200. Flag bit 4 matches the *_f16 interpolation opcodes in 12,067/12,101 (99.7%).

Baseline already recorded

  • reports/manifest.json: SHA-256 of all 108 files in Documents\GTA6 (208.5 GiB). Run python -I tools\manifest.py verify <game> to check a copy against it.
  • reports/rpf_probe.json: all 22 archives are RPF9. Five have tables that look packed or encrypted (levels, movies, core_bvh4, navmeshes, data).
  • reports/pe/: the 16 bundled DLLs are plain x86-64 PE with no encrypted sections. Through the loader their xmem.dll imports and two d3d12_xs.dll root-signature calls bind to shims. Every other import resolves on desktop Windows. The proxy covers the measured device slots and forwards the rest in PC vtable order; the Xbox queue/fence/command-list extensions and PresentX remain unknown.