Document how are relocation values encoded for various instructions

[marxin]

Please consider adding a section describing that a computed relocation value needs to be properly encoded (as an immediate) for various instructions. It's difficult to find a proper instruction flavor that is related to a particular relocation.

It can be added after the following part of the docs:

[msb:lsb] is a bit-mask operation representing the selection of bits in a value. The bits selected range from lsb up to msb inclusive. For example, ‘bits [3:0]’ represents the bits under the mask 0x0000000F. When range checking is applied to a value, it is applied before the masking operation is performed.

[smithp35]

Would you be able to be more specific about what you found difficult?

I'm not sure that there is much that can be usefully written in that section. The ABI describes software conventions for how a relocation is calculated, whether there is overflow or not etc. The Arm ARM describes how instructions are encoded, the ABI has to be read in conjunction with the Arm ARM. We could write something like see the Arm ARM for details of instruction encodings, but that isn't adding much useful information as the Arm ARM is already a reference.

More could be written alongside each relocation, but that risks duplicating information that's already in the Arm ARM, and the tables are large enough as they are. Are there any specific examples where you couldn't find the information in the Arm ARM about how to encode the addend?

In the 32-bit ABI with REL format relocations there were some special cases, such as representing the PC-bias in Thumb branch instructions (https://github.com/ARM-software/abi-aa/blob/main/aaelf32/aaelf32.rst#5611addends-and-pc-bias-compensation) where some encoding tricks had to be used. With RELA format the addend is independent of the encoding so we've not needed these.

[marxin]

First, thank you for the thoughtfull reply, appreciate that.

The Arm ARM describes how instructions are encoded, the ABI has to be read in conjunction with the Arm ARM. We could write something like see the Arm ARM for details of instruction encodings, but that isn't adding much useful information as the Arm ARM is already a reference.

Yes, fully understand it's out of the scope for the ABI specification. Consider adding a single sentence which will expain that a relocation place points to a beginning of an instruction and that each instruction encodes the calculated value of the relocation differently.