xenasm

xenasm is a Python toolkit for building and decoding Xenos shader microcode, the instruction format of the ATI Xenos GPU in the Xbox 360. It lets you author original Xenos shaders programmatically instead of hand-packing bit patterns or disassembling retail titles.

Rather than hard-coding instruction encodings, xenasm reads the authoritative field layouts and enums straight from the Xenia emulator's ucode.h, so its output stays aligned with the reference decoder. Shaders it emits round-trip cleanly through a Xenia shader compiler.

Status: alpha. xenasm builds the instruction shapes listed below (vertex fetch, ALU vector and scalar ops, control flow with exec / alloc, and memory export). It is not yet a complete assembler.

What xenasm Covers

• Build: emit vertex-fetch, ALU vector/scalar, control-flow, and memory-export instruction slots from Python.
• Pack: serialize to little-endian dwords and write ready-to-load shader binaries.
• Decode: inspect existing microcode with decode_alu, unpack, and enum_name.
• Layouts from Xenia: instruction layouts are parsed from Xenia's ucode.h at load time, not transcribed by hand.
• Errors: invalid input raises XenasmError rather than a bare assert, so checks still run under python -O.

Install

pip install .

Python 3.9+. No third-party dependencies.

The ucode.h Dependency

xenasm reads instruction layouts from Xenia's src/xenia/gpu/ucode.h. Supply that path from a local Xenia checkout. The header belongs to the Xenia project and is not redistributed here.

Quick Start

Print the bit widths of the core instruction layouts as a sanity check:

xenasm /path/to/xenia/src/xenia/gpu/ucode.h

AluInstruction: 96 bits
ControlFlowExecInstruction: 48 bits
ControlFlowAllocInstruction: 48 bits
VertexFetchInstruction: 96 bits

Use it as a library:

from xenasm import Shader

sh = Shader("/path/to/xenia/src/xenia/gpu/ucode.h")
# emit vertex-fetch / ALU / control-flow / memory-export slots, then:
sh.write("my_shader")   # writes the packed shader binaries

API surface

Call	Purpose
Shader(ucode_h)	Load instruction layouts and enums from a Xenia ucode.h.
.vfetch(...), .alu(...), .mov(...), .salu(...)	Emit instruction slots.
.cf_exec([...]), .cf_alloc('Memory' | 'VsPosition' | ...)	Control-flow blocks.
.emit() / .write(name)	Pack to dwords / write shader binaries.
decode_alu, unpack, enum_name	Decode and inspect existing microcode.

Verifying Output

Round-trip the shaders xenasm emits through a Xenia shader compiler; the compiled result should decode back to the intended microcode.

Attribution

Instruction field layouts and enum values are read from the Xenia project's ucode.h (BSD 3-Clause); see THIRD_PARTY_NOTICES.md. xenasm itself is original work under the MIT License.