Add Explanation of Mips Backend Relocation Principles

[joelkevinjones]

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.

[sdardis]

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

Nit: adresses -> addresses.

41–42

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

3. 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

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

61–62

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

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

89

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.

[joelkevinjones]

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

[joelkevinjones]

Updated per comments.

[sdardis]

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.)

[joelkevinjones]

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

[joelkevinjones]

Ping

[sdardis]

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"

Relocation.txt

+Mips Relocation Principles
+
+In LLVM, there are several elements of the llvm::ISD::NodeType enum that deal
+with adresses and/or relocations. These are defined in
+include/llvm/Target/TargetSelectionDAG.td, namely:
+    GlobalAddress, GlobalTLSAddress, JumpTable, ConstantPool, ExternalSymbol,
+    BlockAddress
+The Mips backend uses several principles to handle these.
+
+1. Code for lowering addresses references to machine dependent code is
+factored into common code for generating different address forms and is
+called by the relocation specific lowering function, using templated
+functions. For example:
+
+  SDValue MipsTargetLowering:: // lib/Target/Mips/MipsISelLowering.cpp
+  lowerJumpTable(SDValue Op, SelectionDAG &DAG) const
+
+calls
+
+  template <class NodeTy> // lib/Target/Mips/MipsISelLowering.h
+  SDValue getAddrLocal(NodeTy *N, const SDLoc &DL, EVT Ty,
+                       SelectionDAG &DAG, bool IsN32OrN64) const
+
+which calls the overloaded function:
+
+  // lib/Target/Mips/MipsISelLowering.h
+  SDValue getTargetNode(JumpTableSDNode *N, EVT Ty, SelectionDAG &DAG,
+                        unsigned Flag) const;
+
+2. Instruction selection is deferred by using
+MipsISD::{Highest, Higher, Hi, Lo}. For example, in getAddrLocal, the
+pseudo-code generated is:
+
+  (add (load (wrapper $gp, %got(sym)), %lo(sym))
+
+where "%lo" represents an instance of an SDNode with opcode "MipsISD::Lo",
+"wrapper" indicates one with opcode "MipsISD::Wrapper", and "%got" the global
+table pointer "getGlobalReg(...)". The "add" is "ISD::ADD", not a target
+dependent one.
+
+3. Table-gen "multiclass" is used to define patterns varying over load, add,
+zero, and type:
+
+  // lib/Target/Mips/MipsInstrInfo.td
+  multiclass MipsHiLoRelocs<Instruction Lui, Instruction Addiu,
+                            Register ZeroReg, RegisterOperand GPROpnd> {
+    def : MipsPat<(MipsHi tglobaladdr:$in), (Lui tglobaladdr:$in)>;
+    ...
+    def : MipsPat<(MipsLo tglobaladdr:$in), (Addiu ZeroReg, tglobaladdr:$in)>;
+    ...
+    def : MipsPat<(add GPROpnd:$hi, (MipsLo tglobaladdr:$lo)),
+                (Addiu GPROpnd:$hi, tglobaladdr:$lo)>;
+    ...
+  }
+  defm : MipsHiLoRelocs<LUi, ADDiu, ZERO, GPR32Opnd>;
+
+  // lib/Target/Mips/Mips64InstrInfo.td
+  defm : MipsHiLoRelocs<LUi64, DADDiu, ZERO_64, GPR64Opnd>, SYM_32;
+
+Here the instantiation of MipsHiLoRelocs in MipsInstrInfo.td is used by
+Mips32. The instantiation in Mips64InstrInfo.td is used by Mips64 in ILP32
+mode, as guarded by the predicate "SYM_32". A similar "multiclass" for Mips64
+in LP64 mode is also defined:
+
+  // lib/Target/Mips/Mips64InstrInfo.td
+  multiclass MipsHighestHigherHiLoRelocs<Instruction Lui, Instruction Daddiu> {
+  ...
+    def : MipsPat<(MipsHighest (i64 tglobaladdr:$in)),
+                  (Lui tglobaladdr:$in)>;
+  ...
+    def : MipsPat<(MipsHigher (i64 tglobaladdr:$in)),
+                  (Daddiu ZERO_64, tglobaladdr:$in)>;
+  ...
+    def : MipsPat<(add GPR64:$hi, (MipsHigher (i64 tglobaladdr:$lo))),
+                  (Daddiu GPR64:$hi, tglobaladdr:$lo)>;
+  ...
+    def : MipsPat<(add GPR64:$hi, (MipsHi (i64 tglobaladdr:$lo))),
+                  (Daddiu GPR64:$hi, tglobaladdr:$lo)>;
+  ...
+    def : MipsPat<(add GPR64:$hi, (MipsLo (i64 tglobaladdr:$lo))),
+                  (Daddiu GPR64:$hi, tglobaladdr:$lo)>;
+  }
+
+although it is only instantiated once:
+
+  // lib/Target/Mips/Mips64InstrInfo.td
+  defm : MipsHighestHigherHiLoRelocs<LUi64, DADDiu>, SYM_64;
+
+4. Instruction encoding is separated from types. For example:
+
+  // lib/Target/Mips/MipsInstrInfo.td
+  let AdditionalPredicates = [NotInMicroMips] in {
+  ...
+  def LW  : StdMMR6Rel, Load<"lw", GPR32Opnd, load, II_LW, addrDefault>, MMRel,
+            LW_FM<0x23>;
+  }
+
+  // lib/Target/Mips/Mips64InstrInfo.td
+  def LW64  : Load<"lw", GPR64Opnd, sextloadi32, II_LW>, LW_FM<0x23>;
+
+defines two names "LW" and "LW64" with two different types, but with the
+same encoding—"LW_RM<0x23>".