Add Explanation of Mips Backend Relocation Principles
ClosedPublic

Authored by joelkevinjones on Mon, Apr 3, 3:02 PM.

Details

Summary

This revision adds a brief document describing how a combination of C++ and table-gen code is used to deal with relocations and addresses.

Diff Detail

Repository
rL LLVM
joelkevinjones created this revision.Mon, Apr 3, 3:02 PM

Some initial comments inlined, mostly focusing on accuracy. I'll take a second look later at 1 & 2.

One recurring nit is the usage of the word 'type'. In most of the contexts it is used here, it's actually referring to register class. The difference is that 'i32' is a type, but GPR32Opnd is a register class that can hold that type. I'd prefer not to confuse the reader by overloading the meaning of the word type.

Another nit is the usage of ILP32 mode and LP64 mode. For MIPS at least, we generally refer to these as N32 (our ILP32 ABI) and N64 (our LP64 ABI).

Relocation.txt
4 ↗(On Diff #93953)

Nit: adresses -> addresses.

41–42 ↗(On Diff #93953)

Depending on the knowledge level this document is targeted towards, this sentence is a bit poor and inaccurate.

  1. A TableGen multiclass pattern "MipsHiLoRelocs" is used to define a template pattern parameterised over the load, add operations, the zero register and register type:

Is somewhat better IMHO. If necessary, this document should reference the TableGen documentation for the specifics on multiclasses.

60 ↗(On Diff #93953)

I would move this sentence to just below the MIPS32 multiclass instantiation for clarity.

61–62 ↗(On Diff #93953)

Nit: The SYM_32 predicate covers ILP32 mode and a submode of LP64 known as sym32, where symbols are assumed to be 32bits wide. I don't know if you want to cover that level of detail.

84 ↗(On Diff #93953)

Nit: It's actually instantiated twice. Once in Mips64InstrInfo.td and once in MicroMips64r6InstrInfo.td.

89 ↗(On Diff #93953)

This first sentence is inaccurate. The instruction definitions are multiply defined to cover the different register classes. In some cases, such as LW / LW64, this also accounts for the differences in the results of instruction execution. On MIPS32, "lw" loads a 32bit value from memory. On MIPS64, "lw" loads a 32 bit value from memory and sign extends the value to 64bits.

Thanks for all your comments. I'm about to post a new revision modified per your comments.

Updated per comments.

Another batch of comment inlined. Hopefully they should help tie it all together.

One nit: Mips should be spelt MIPS when referring to the architecture. Referring to it as Mips when highlighting a file or in existing code is fine, it's just an inconsistency that crept in over time.

lib/Target/Mips/Relocation.txt
12 ↗(On Diff #94093)

relocation model specific lowering function, ...

(Some of MIPS relocations are shared between relocation models, so I think it's clearer to describe those lowering functions as relocation model specific rather than relocation specific)

31–33 ↗(On Diff #94093)

Generic address nodes are lowered to some combination of target independent and machine specific SDNodes (MipsISD::{Wrapper, GotHi, Highest, Higher, Hi, Lo}) depending on relocation model, ABI and compilation options.

The choice of specific instructions that are to be used is delegated to ISel which in turn relies on TableGen patterns to choose subtarget specific instructions.

42 ↗(On Diff #94093)

patter -> pattern.

Missing " after MipsHiLocRelocs.

43 ↗(On Diff #94093)

I goofed here. This should be "template pattern parameterized over the load upper immediate (lui) instruction and add operations.."

44 ↗(On Diff #94093)

Before the 'Here the..', you should note that this specific pattern is used to compute addresses for the static relocation model. (Readers may get confused as you've given the example of PIC address nodes above).

65 ↗(On Diff #94093)

Duplicated '.'

99 ↗(On Diff #94093)

You should note that these patterns are used during the Instruction selection phase to match MipsISD::{Highest, Higher, Hi, Lo} to a specific machine instruction and operands.

117 ↗(On Diff #94093)

Another example would be LUi/LUi64 (as used in the TableGen patterns above) which loads a 16 bit immediate into bits 31-16 and clears the lower 15 bits. As with lw on MIPS64, the result is sign extended to 64 bits.

(This helps tie 4. into the rest of the doc imho. As it is, I felt point 4 was a bit left of field.)

Improve consistency of capitalization of MIPS, types vs. register classes, etc.

sdardis accepted this revision.Fri, Apr 21, 6:29 AM

LGTM. Two tiny nits inlined.

Thanks for doing the documentation.
Simon

lib/Target/Mips/Relocation.txt
52 ↗(On Diff #94448)

by -> for.

70 ↗(On Diff #94448)

by -> for.

123 ↗(On Diff #94448)

"These" -> "These instructions"

This revision is now accepted and ready to land.Fri, Apr 21, 6:29 AM
This revision was automatically updated to reflect the committed changes.