[llvm] [AMDGPU] Clarify description of _HI relocation types (PR #73663)

[Jay Foad via llvm-commits]

https://github.com/jayfoad created https://github.com/llvm/llvm-project/pull/73663

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.


>From 3a1edb9568e42953f4396bea737e2db5c7a37ce7 Mon Sep 17 00:00:00 2001
From: Jay Foad <jay.foad at amd.com>
Date: Tue, 28 Nov 2023 15:41:35 +0000
Subject: [PATCH] [AMDGPU] Clarify description of _HI relocation types

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.
---
 llvm/docs/AMDGPUUsage.rst | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

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