[AMDGPU] Clarify description of _HI relocation types

[jayfoad]

Clarify how the addend is used in _HI relocation types like
R_AMDGPU_ABS32_HI based on the current behaviour of the Mesa and AMDPAL
ELF loaders.

This affects Mesa and AMDPAL because they use REL relocation records, so
the addend for these types is the 32-bit literal value from the
instruction being relocated. AMDHSA is not affected because it uses RELA
relocation records which have a 64-bit addend.

[llvmbot]

@llvm/pr-subscribers-backend-amdgpu

Author: Jay Foad (jayfoad)

Changes

Clarify how the addend is used in _HI relocation types like
R_AMDGPU_ABS32_HI based on the current behaviour of the Mesa and AMDPAL
ELF loaders.

This affects Mesa and AMDPAL because they use REL relocation records, so
the addend for these types is the 32-bit literal value from the
instruction being relocated. AMDHSA is not affected because it uses RELA
relocation records which have a 64-bit addend.

---

Full diff: https://github.com/llvm/llvm-project/pull/73663.diff

1 Files Affected:

• (modified) llvm/docs/AMDGPUUsage.rst (+6-1)

diff --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst
index c910c1238294400..63566c4a35ccc10 100644
--- a/llvm/docs/AMDGPUUsage.rst
+++ b/llvm/docs/AMDGPUUsage.rst
@@ -2050,7 +2050,12 @@ relocatable fields are:
 Following notations are used for specifying relocation calculations:
 
 **A**
-  Represents the addend used to compute the value of the relocatable field.
+  Represents the addend used to compute the value of the relocatable field. If
+  the addend field is smaller than 64 bits then it is zero-extended to 64 bits
+  for use in the calculations below. (In practice this only affects ``_HI``
+  relocation types on Mesa/AMDPAL, where the addend comes from the 32-bit field
+  but the result of the calculation depends on the high part of the full 64-bit
+  address.)
 
 **G**
   Represents the offset into the global offset table at which the relocation

[jayfoad]

Here's the relevant part of the Mesa and AMDPAL ELF loaders:

Mesa: https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/src/amd/common/ac_rtld.c?ref_type=heads#L638
AMDPAL: https://github.com/GPUOpen-Drivers/pal/blob/6bdc69412b3c3936bcc6e23edf9e338d66b69d5f/src/core/hw/gfxip/pipeline.cpp#L1080