AMDGPU ABI and Register Implementation Research Archive

This repository preserves the structured research artifacts produced while studying the AMDGPU ABI, calling conventions, register architecture, and LLVM's end-to-end implementation. It is intended for fact verification and future technical writing. The archive records the research scope, source baselines, register inventory, topic coverage, evidence matrices, and static validation results.

The central objective is to ensure that every significant technical claim can answer four questions:

1. Which GPU, execution environment, wave size, and Code Object version does the claim apply to?
2. Does the claim come from a public specification, a release implementation, static compiler output, or an explanatory derivation?
3. Do the release LLVM implementation and upstream LLVM implement the same behavior?
4. How far has the claim been validated in an environment without AMDGPU hardware?

This repository does not contain article manuscripts, published Markdown or HTML, image assets, LLVM/ROCm source snapshots, generated object files, research probes, or build programs. Source evidence is identified through pinned commits, repository lock files, source paths, symbols, and line numbers.

Research Profile

The primary research profile is fixed as follows:

Dimension	Fixed value
Product	AMD Instinct MI350X
ISA / target	CDNA 4 / gfx950
Wave size	wave64
Execution environment	AMDHSA
Language entry points	HIP C++ kernels and device functions
Toolchain	ROCm 7.2.4
Code Object	V6
Release LLVM commit	f58b06dce1f9c15707c5f808fd002e18c2accf7e
LLVM main audit commit	12ce00a865b09cb72a3ea9a84f9308236a4f6038
Validation method	Specifications, source code, compiler output, and static object-file inspection

The research follows two connected tracks:

• AMDGPU ABI: kernel entry, ordinary device-function calls, arguments and return values, caller/callee-save rules, stack and frame organization, ELF, metadata, kernel descriptors, runtime loading, and the memory model.
• AMDGPU registers: SGPRs, VGPRs, AGPRs, special state, kernel-argument preload, register numbering domains, RegisterBank and RegisterClass, register allocation, spills, occupancy, and resource-field generation.

Repository Layout

.
├── README.md
├── research/
│   ├── README.md
│   ├── coverage.md
│   ├── fact-matrix.md
│   ├── register-inventory.md
│   ├── register-fact-matrix.md
│   ├── validation.md
│   └── register-validation.md
├── scope/
│   ├── profile.md
│   └── register-profile.md
└── sources/
    ├── README.md
    ├── source-policy.md
    ├── references.yml
    ├── source-lock-rocm-7.2.4.tsv
    ├── source-lock-rocm-7.14.0-audit.tsv
    └── source-lock-llvm-main.tsv

scope/: Research Boundaries

• profile.md defines the product, ISA, execution environment, toolchain, evidence levels, and out-of-scope subjects for the ABI study.
• register-profile.md defines the five register-numbering domains, the gfx950-visible register set, LLVM's cross-target register universe, ABI contexts, counting terminology, and confidence labels.

These files constrain every unconditional statement in the archive. Evidence must be reviewed again when the target, version, or runtime environment falls outside the fixed profile.

sources/: Provenance and Version Locks

• source-policy.md defines the evidence priority among specifications, release source, toolchain behavior, LLVM main, and historical material.
• references.yml stores the structured bibliography and the purpose of each source.
• source-lock-rocm-7.2.4.tsv pins the repositories, revisions, and resolved commits referenced by the ROCm 7.2.4 manifest.
• source-lock-rocm-7.14.0-audit.tsv records a recency audit of a later top-level ROCm release tag.
• source-lock-llvm-main.tsv pins the LLVM main revision used to audit implementation evolution.

The source trees themselves are excluded. Lock files establish reproducible source identities, while the evidence matrices record precise paths, symbols, and line locations.

research/: Research Process and Evidence

• coverage.md is an ABI topic-coverage checklist for calling conventions, object format, runtime behavior, debugging interfaces, and related subjects.
• fact-matrix.md connects ABI claims to their applicability boundaries and implementation evidence.
• register-inventory.md inventories the gfx950 register sets, numbering domains, roles, preservation obligations, and resource accounting rules.
• register-fact-matrix.md contains 91 locked register facts, with ROCm 7.2.4 and LLVM main evidence locations, confidence levels, and generation scopes.
• validation.md records static checks of Code Object V6, ELF, metadata, descriptors, ordinary calls, and kernarg preload.
• register-validation.md records end-to-end static validation from HIP and LLVM IR through instruction selection, register allocation, spilling, MC emission, and Code Object generation.

Generated assembly, object files, disassembly, and tool output under research/generated/ are reproducible artifacts and are not tracked.

Evidence Model

The archive organizes evidence into the following levels:

1. Specification contracts: AMD ISA, HSA, ELF, DWARF, and public Code Object documentation.
2. Release implementation: producer and consumer implementations in ROCm 7.2.4.
3. Stable toolchain behavior: IR, MIR, assembly, ELF, metadata, and descriptors generated by the pinned LLVM toolchain.
4. Upstream evolution audit: a pinned LLVM main revision used to identify implementation drift and future documentation work.
5. Explanatory derivation: conclusions derived from multiple high-confidence facts, with their applicability stated explicitly.

The register fact matrix uses the following confidence labels:

Label	Meaning
H	Confirmed by both implementation baselines, or jointly established by producer and consumer implementations
H-D	A deterministic derivation from multiple high-confidence facts
M	Version-sensitive, dependent on work-in-progress documentation, or affected by explainable implementation drift
L	The contract remains incomplete and is retained only as a research boundary

Confidence and applicability are recorded independently. A high-confidence fact does not automatically apply to every AMDGPU generation.

Recommended Reading Order

1. Read scope/profile.md and scope/register-profile.md to establish the applicability boundaries.
2. Read sources/source-policy.md and the source-lock files to verify source identity.
3. Use research/coverage.md and research/register-inventory.md to build a complete topic map.
4. Locate specific evidence in research/fact-matrix.md and research/register-fact-matrix.md.
5. Use research/validation.md and research/register-validation.md to compare static toolchain behavior with the source-level rules.

Validation Boundary

The fixed end-to-end register validation result is:

Status	Count
PASS	25
FAIL	0
SKIP	1

The only skipped check is hardware execution. The research environment has no /dev/kfd, so it did not create an HSA queue, submit an AQL dispatch packet, or execute a kernel. Compile-time ABI behavior, MIR, machine code, relocations, kernel descriptors, and metadata were validated statically. Runtime dispatch state, preemption, traps, debugger behavior, and observed occupancy remain outside the static validation boundary.

Maintenance Rules

• When the release baseline changes, update scope/, the source locks, the evidence matrices, and the validation records together.
• Every register quantity must state whether it denotes a declared count, an addressable count, a per-function allocatable count, an explicit high-water mark, or a dispatch resource count.
• Every register number must identify its domain: ISA name, LLVM identity, instruction encoding, DWARF number, or resource accounting.
• LLVM upstream changes belong to the evolution audit and must not silently redefine the pinned release behavior.
• Conclusions produced without hardware execution must preserve an explicit static-validation boundary.