RISC-V medlow and medany: Diagnose the Address Range Behind a Relocation Failure

A linker reports that a RISC-V relocation cannot reach its symbol after firmware moves to a new memory region. The useful first question is not whether the address fits in a 64-bit register. It is whether the selected instruction sequence can construct that address under its code model.

This analysis pins the ELF psABI code-model definitions at commit 3095deae52ae3feecc54b5e185d14eb177e05d04, together with RV64I 2.1 in library v20260120. The address worksheet is hypothetical. No linker failure was reproduced for this article.

Recognize an absolute medlow reference

The medlow model uses an upper-immediate construction with LUI, followed by a signed lower immediate in an instruction such as ADDI or a load/store. On RV64, LUI sign-extends its 32-bit result. That behavior determines which absolute addresses the pair can reach.

The pinned psABI gives two inclusive RV64 regions:

0x0000000000000000 through 0x000000007ffff7ff
0xffffffff7ffff800 through 0xffffffffffffffff

The edges are deliberately not rounded to the usual positive and negative 2 GiB boundaries. The lower immediate is signed, so its positive endpoint is 0x7ff and its negative endpoint is -0x800. Combining those endpoints with the signed upper construction produces the stated limits.

A target at 0x000000007ffff7ff is at the positive edge. The next address, 0x000000007ffff800, is already beyond this ordinary absolute pair’s range. Moving the instruction itself does not repair that absolute target constraint. The code model is about how addresses are formed, not simply whether code and data are close together.

Evaluate medany from the instruction’s own PC

The medany model uses AUIPC followed by a signed lower-immediate operation. AUIPC adds its sign-extended upper offset to the address of the AUIPC instruction itself. The exact inclusive target interval is:

PC - 0x80000800 through PC + 0x7ffff7ff

Use that instruction address, not the start of the function, the following instruction or the image load base. A symbol can be reachable from one reference and out of range from another. A large image needs each relevant reference checked rather than one image-wide distance estimate.

Consider an illustrative pair at PC=0x0000000080001000. A data symbol at 0x0000000080002000 has displacement 0x1000, comfortably inside the medany range, although its absolute address is outside the positive medlow region. Changing the model can address that particular relationship, provided the actual producer objects use the intended sequences.

Include the undefined weak-symbol case

Now consider an optional weak symbol that is undefined and therefore resolves to zero. From the same hypothetical AUIPC address, its displacement is -0x80001000. That is below the allowed lower endpoint -0x80000800. Nearby real data being reachable does not establish that the optional reference to zero is also reachable.

The pinned psABI recommends indirect access through the Global Offset Table for possibly undefined weak symbols. It deprecates direct references and says a future specification will require the GOT approach. At this pinned commit, however, the text explicitly says that it is not yet a requirement. Preserve that distinction when assessing an older toolchain rather than declaring every direct reference immediately nonconforming.

A null check after an unrepresentable address construction is too late to solve the relocation. Inspect the sequence used to obtain the optional symbol’s address before reasoning about the branch that follows it.

Do not confuse medany with shared-library PIC

Although the relative sequence is position independent in a limited sense, the psABI says medany is unsuitable for ELF shared libraries because their symbol-interposition requirements differ. Its medium position-independent model uses the GOT for non-local symbol addresses.

Thus a successful nearby-symbol calculation is not a general license to build a shared library under the same model. Identify the output type and symbol-binding semantics separately from the numeric reach calculation. Likewise, global-pointer relaxation has its own assumptions; this worksheet does not replace startup initialization of gp.

Preserve evidence for the particular reference

For a proposed diagnosis, retain the original relocation diagnostic, the producing object, the referenced symbol and the relevant instruction pair. Record the final symbol address and the AUIPC address where applicable, then evaluate the exact inclusive interval. Check the linked instructions as well as the original object if relaxation changed the sequence.

Correct the producer’s code model or the supported memory layout only after identifying that failing relationship. A blanket final-link flag does not prove that every prebuilt object was generated under the intended model. The result should be a reference-specific explanation: absolute reach, PC-relative reach, or symbol-binding requirements, with no claim that an untested model change fixes every relocation.