[llvm] [RFC][AMDGPU][Doc] Add documentation about ABI occupancy (PR #224103)

[Siu Chi Chan via llvm-commits]

================
@@ -3035,6 +3038,46 @@ unit's worst case (i.e, maxima) ``num_vgpr``, ``num_agpr``, and
 symbolic expressions. These three symbols are ``amdgcn.max_num_vgpr``,
 ``amdgcn.max_num_agpr``, and ``amdgcn.max_num_sgpr``.
 
+.. _amdgpu-abi-occupancy:
+
+ABI Occupancy (Object Linking)
+------------------------------
+
+When object linking is enabled, the AMDGPU backend no longer assumes
+whole-program visibility. Individual translation units must agree on an ABI that
+callers and callees can rely on without seeing each other's register usage. The
+compiler enforces this with an *ABI occupancy*: a floor on waves per EU, which
+is a cap on the register budget for separately compiled functions. The default
+ABI occupancy is the number of waves per EU required to support a
+1024-workitem workgroup:
+
+``ceil(ceil(1024 / wavefront-size) / workgroup-SIMDs)``, where
+``workgroup-SIMDs`` is the number of SIMDs that a workgroup's waves run on.
+
+For example, on ``gfx900`` (wave64, 4 workgroup SIMDs) the default ABI occupancy
+is ``ceil(ceil(1024 / 64) / 4) = 4``, which caps VGPRs at
+``getMaxNumVGPRs(4) = 64``. On a gfx12 target such as ``gfx1200`` (wave32,
+4 workgroup SIMDs), the default ABI occupancy is ``ceil(ceil(1024 / 32) / 4) =
+8``, which caps VGPRs at ``getMaxNumVGPRs(8) = 192``.
+
+The ``amdgpu_abi_waves_per_eu`` module flag overrides the default ABI occupancy
+floor for a module. A value lower than the default lowers that floor and raises
+the register cap (a looser ABI contract). A value higher than the default
+raises the floor and lowers the register cap (a stricter ABI contract).
+
+``amdgpu-flat-work-group-size`` is ABI-significant. If a function carries this
+attribute, the occupancy implied by its maximum flat workgroup size replaces
+the default ABI occupancy for that function, so it can either raise or lower
----------------
scchan wrote:

Inflating or not is going to be in the backend.  For object linking, I'm thinking about whether the contract mandates or not?

https://github.com/llvm/llvm-project/pull/224103