Decoding instructions with the machine-readable AMD GPU ISA specifications

We recently released a machine-readable specification for our GPU Instruction Set Architecture (ISA), provided as a set of XML files detailing its RDNA™ and CDNA™ Instruction Set Architectures. While you can manually parse these files using the XML schema documentation, the easiest way to get started is using the  IsaDecoder  API. This API reads and parses the XML files and can decode individual instructions or entire kernels in both binary and textual formats.

Here is a simple program demonstrating how easy it is to decode a single MI-300/CDNA™ 3 instruction using the API. This program loads the specification XML file from a hardcoded path and decodes a hardcoded instruction ( 0x7e000301 ):

int main()
{
    // Initialize the decoder with the MI300/CDNA3 XML ISA specification file.
    amdisa::IsaDecoder decoder;
    const char* kPathToSpec = "path/to/xml/spec/amdgpu_isa_mi300.xml";
    std::string error_msg;
    bool is_initialized = decoder.Initialize(kPathToSpec, error_msg);
    if (is_initialized)
    {
        // Decode instruction 0x7e000301.
        amdisa::InstructionInfoBundle inst_bundle;
        bool is_decoded = decoder.DecodeInstruction(0x7e000301, inst_bundle, error_msg);
        if (is_decoded)
        {
            for (const amdisa::InstructionInfo& inst : inst_bundle.bundle)
            {
                std::cout << "Instruction Name: " << inst.instruction_name << std::endl;
                std::cout << "Instruction Description: " << inst.instruction_description << std::endl;

                // More information is available in the InstructionInfo structure,
                // such as operands and their type (input/output/SGPR/VGPR/etc.), flags and more.
            }
        }
        else
        {
            std::cerr << error_msg << std::endl;
        }
    }
    else
    {
        std::cerr << error_msg << std::endl;
    }

    return 0;
}

After decoding, the program outputs the instruction name and the human-readable instruction description from the decoded InstructionInfo structure.

  Instruction Name: V_MOV_B32
  Instruction Description: Move 32-bit data from a vector input into a vector register.

The populated InstructionInfo structure contains detailed information about the decoded instruction like its encoding, operands and their types (input/output/SGPR/VGPR etc.), and flags. For a complete description of the available information, please refer to the API documentation on GitHub.

In addition, as mentioned above, the API is not limited to decoding single instructions – it can be used to decode whole kernels and shaders in binary and disassembly formats. API usage examples and additional details are available on the isa_spec_manager repository on GitHub alongside the API source code – check it out!

You can also find out more over on our AMD machine-readable ISA specification page here on GPUOpen!