Relocations documentation about riscv-elf-psabi-doc HOT 5 OPEN

It might be helpful to look at other psABIs, that had actual tech writers involved. For instance, you can find the MIPS one here
http://refspecs.linux-foundation.org/elf/mipsabi.pdf
and page 4-16 is where the relocation info starts. This one actually explains what the symbols mean, and they likely mean the same thing for RISC-V. There are a bunch of other ones in this elf dir also.

Yes, the R_RISCV_SUB32 doc is wrong. The symbol should be subtracted. Also, this is what bfd calls an inplace reloc, it reads the old value from the target and then subtracts the symbol and addend from it. R_RISCV_ADD32 is also an inplace reloc.

The idea here is that we can do symbol subtraction by having a pair of relocs, R_RISCV_ADD32 and R_RISCV_SUB32. R_RISCV_ADD32 reads the old value, adds its symbol value and stores it back.
R_RISCV_SUB32 reads the old value, subtracts its symbol value and stores it back. The starting value at the target should be 0, and the two relocs can occur and be processed in either order, and we still get the right result at the end.

Inplace relocs like this aren't very common for other targets, so it might be hard to find a good example we can copy from to improve the documentation.

from riscv-elf-psabi-doc.

@jim-wilson Thanks once again for a thoughtful reply (you spoil us!). I think some minimal extra documentation such as stating what the one letter variables stand for and a quick note about the inplace relocs would significantly improve the clarity for not much effort. But perhaps someone with more experience should help review the rest of the relocations to check their correctness, point out any subtle semantics, corner cases, etc. --- the kind of stuff that always seems to pop up when things are specified precisely.

from riscv-elf-psabi-doc.

stating what the one letter variables stand for and a quick note about the inplace relocs would significantly improve the clarity for not much effort.

Actually the names are already documented in the doc but not in a very "semantic" way. Something that made it clear that, say, the addend would be an offset, the symbol would be the address of the symbol, etc. would have made it 100% clear that the problem was a bug in the R_RISCV_SUB* documentation entries. The way things currently are there wasn't enough redundancy for a reliable error correction code ;-).

from riscv-elf-psabi-doc.

FYI pull request #83 updated the ADDx and SUBx reloc docs to mention that they use the old value in the calculation. This stuff could still use some improvement from a tech writer though.

from riscv-elf-psabi-doc.

The description of R_RISCV_ADD* and R_RISCV_SUB* should probably say that they are intended for local labels.

# snippet extracted from llvm/test/MC/RISCV/fixups-expr.s
.globl G1
.globl G2

.data
.dword G2-G1

~/projects/binutils-gdb/riscv/gas/as-new a.s -o a.o
~/projects/binutils-gdb/riscv/ld/ld-new a.o -shared # succeeded

G1 and G2 are preemptably in -shared mode, but it appears binutils ld.bfd doesn't give an error/warning.

from riscv-elf-psabi-doc.