TheRock/rocm-systems/experimental/python/perfxpert/docs/contributing/gpu_arch.md

Contributing: new GPU architecture

What you're adding

Support for a new GPU architecture (e.g., a new CDNA variant, RDNA revision, or vendor GPU). Requires entries in two knowledge YAMLs and corresponding test updates.

File locations

• GPU specs: perfxpert/knowledge/gpu_specs.yaml
• VGPR occupancy tables: perfxpert/knowledge/vgpr_occupancy_tables.yaml
• Tests: tests/test_knowledge/test_gpu_specs.py

Template

Entry in gpu_specs.yaml

gfx950:
  name: "MI350X"
  codename: "CDNA4"
  peak_fp64_tflops: 72.1
  peak_fp32_tflops: 144.2
  peak_fp16_tflops: 2300.0
  peak_bf16_tflops: 2300.0
  peak_fp8_tflops: 4600.0
  peak_int8_tops: 4600.0
  memory_bandwidth_tbs: 8.0
  cu_count: 256
  lds_kb: 160
  lds_per_cu_kb: 160
  wave_size: 64
  max_vgprs_per_thread: 256
  vgprs_per_simd: 512
  simds_per_cu: 4
  max_waves_per_simd: 8
  ridge_point: 18.0

Entry in vgpr_occupancy_tables.yaml

gfx950:
  - {max_vgprs: 64,  waves_per_eu: 8}
  - {max_vgprs: 80,  waves_per_eu: 6}
  - {max_vgprs: 96,  waves_per_eu: 5}
  - {max_vgprs: 128, waves_per_eu: 4}
  - {max_vgprs: 160, waves_per_eu: 3}
  - {max_vgprs: 256, waves_per_eu: 2}

Schema constraints (CI-enforced)

• gpu_specs.yaml validated against JSON schema
• vgpr_occupancy_tables.yaml validated
• VGPR table entries ordered by VGPR count (ascending)
• All peak specs (TFLOPS, bandwidth) must cite an AMD data sheet

Key specs to get right

• MI300X FP64: 81.7 TFLOPS (NOT 163.4 — that's FP32)
• MI300X occupancy: 32 max waves/CU and 4 SIMDs/CU, so 8 waves/SIMD
• CDNA4 LDS: 160 KB/CU (not 64)
• MI350X public peaks: 72.1 FP64 TFLOPS, 144.2 FP32 TFLOPS, 8.0 TB/s HBM

Tests you must add

Update tests/test_knowledge/test_gpu_specs.py:

• test_new_gfx_id_loads() — YAML loads
• test_new_gfx_id_has_required_fields() — all mandatory fields
• test_new_gfx_id_tflops_reasonable() — sanity check on compute
• test_new_gfx_occupancy_table_ordered() — vgpr table sorted

Review requirements

• 1 core reviewer
• Data sheet citation must be verifiable (AMD public data sheet or internal memo)
• CI green (schema + tests)

Common pitfalls

• Don't confuse FP32 and FP64 TFLOPS (MI300X is 163.4 FP32, 81.7 FP64)
• Don't use MI355X higher-bin peaks for the gfx950 MI350X default unless you explicitly split the SKU key first
• VGPR table must be complete (cover typical code patterns: 64, 96, 128, 192, 256 at minimum)
• LDS must match official spec (check against latest AMD app notes)

Related docs

• GPU schema (spec §6.2 Task 2)
• AMD GPU data sheets: https://www.amd.com/en/products/specifications/processors
• CDNA architecture docs: https://rocmdocs.amd.com