[llvm] [RISCV][docs] GP Relaxation and Small Data Limit (PR #108592)

[Sam Elliott via llvm-commits]

https://github.com/lenary created https://github.com/llvm/llvm-project/pull/108592

As discussed in this week's RISC-V sync-up, we said we would add documentation about these options, and how they work.

---

I belive this is an accurate explanation, even though it is done in
reverse order (describing the linker related behaviour before the
compiler related behaviour).

Some discussion from before points to gp-relaxation + PIE being possible (if not implemented) - https://github.com/riscv-non-isa/riscv-elf-psabi-doc/issues/165#issuecomment-747158702 - so I have just documented the executable vs shared library difference, not anything about position-independence. I can certainly add to the description about position independence if needed.

Given this documentation was so target-specific, I thought it should go in one place on the RISC-V page rather than spread around LLD's and Clang's docs. I haven't yet done backreferences from Clang's and LLD's docs to this longer explanation, which I think would be useful.

Clarifications/Corrections welcome, I probably have missed something important.

>From e4e8b163f920d1b962a910b5690e3afacee00ccd Mon Sep 17 00:00:00 2001
From: Sam Elliott <quic_aelliott at quicinc.com>
Date: Fri, 13 Sep 2024 08:49:35 -0700
Subject: [PATCH] [RISCV][docs] GP Relaxation and Small Data Limit

As discussed in this week's RISC-V sync-up, we said we would add
documentation about these options, and how they work.
---
 llvm/docs/RISCVUsage.rst | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/llvm/docs/RISCVUsage.rst b/llvm/docs/RISCVUsage.rst
index a15af9adfa945a..7ee1f2e10982a5 100644
--- a/llvm/docs/RISCVUsage.rst
+++ b/llvm/docs/RISCVUsage.rst
@@ -431,3 +431,26 @@ line.  This currently applies to the following extensions:
 * ``Zvksg``
 * ``Zvksh``
 * ``Zvkt``
+
+Global Pointer (GP) Relaxation and the Small Data Limit
+=======================================================
+
+Some of the RISC-V psABIs reserve ``gp`` (``x3``) for use as a "Global Pointer", to make generating data addresses more efficient.
+
+To use this functionality, you need to:
+* not be using the ``gp`` register for any other uses -- some platforms use it for other things;
+* compile your objects with Clang's ``-mrelax`` option, to enable relaxation annotations on relocatable objects; and
+* be compiling for an executable (not a shared library); and
+* use LLD's ``--relax-gp`` option.
+
+LLD will relax (rewrite) any code sequences that materialize an address within 2048 bytes of this ``__global_pointer$`` (which will be defined if it does not already exist) to instead generate the address using ``gp`` and the correct (signed) 12-bit immediate. This usually saves at least one instruction compared to materialising a full 32-bit address value.
+
+There can only be one ``__global_pointer$`` in a process (as ``gp`` is not changed when calling into a function in a shared library), so this optimisation is only done for executables, and not for shared libraries. Startup code is expected to put the value of ``__global_pointer$`` (from the executable) into ``gp`` before any user code is run.
+
+Arguably, the most efficient use for this addressing mode is for smaller global variables, as larger global variables are likely to need many more loads or stores when they are being accessed anyway.
+
+Therefore the compiler can do so, by placing smaller global variables into sections with with names starting ``.sdata`` or ``.sbss`` (matching sections with names starting ``.data`` and ``.bss`` respectively). LLD knows these sections should be laid out closer to the ``__global_pointer$`` symbol and adjacent to the ``.data`` section.
+
+Clang's ``-msmall-data-limit=`` option controls what the threshold size is (in bytes) for a global variable to be considered small. ``-msmall-data-limit=0`` disables the use of sections starting ``.sdata`` and ``.sbss``. The ``-msmall-data-limit=`` option will not move global variables that have an explicit data section, and will keep globals separate if using ``-fdata-sections``.
+
+Data suggests that these options can produce significant improvements across a range of benchmarks.