Documentation/IR.rst

   1 .. default-domain:: ir
   2
   3 Intermediate Representation
   4 ===========================
   5
   6 Instructions
   7 ~~~~~~~~~~~~
   8
   9 This document briefly describes which field of struct instruction is
  10 used by which operation.
  11
  12 Some of those fields are used by almost all instructions,
  13 some others are specific to only one or a few instructions.
  14 The common ones are:
  15
  16 * .src1, .src2, .src3: (pseudo_t) operands of binops or ternary ops.
  17 * .src: (pseudo_t) operand of unary ops (alias for .src1).
  18 * .target: (pseudo_t) result of unary, binary & ternary ops, is
  19   sometimes used otherwise by some others instructions.
  20 * .cond: (pseudo_t) input operands for condition (alias .src/.src1)
  21 * .type: (symbol*) usually the type of .result, sometimes of the operands
  22
  23 Terminators
  24 -----------
  25 .. op:: OP_RET
  26         Return from subroutine.
  27
  28         * .src : returned value (NULL if void)
  29         * .type: type of .src
  30
  31 .. op:: OP_BR
  32         Unconditional branch
  33
  34         * .bb_true: destination basic block
  35
  36 .. op:: OP_CBR
  37         Conditional branch
  38
  39         * .cond: condition
  40         * .type: type of .cond, must be an integral type
  41         * .bb_true, .bb_false: destination basic blocks
  42
  43 .. op:: OP_SWITCH
  44         Switch / multi-branch
  45
  46         * .cond: condition
  47         * .type: type of .cond, must be an integral type
  48         * .multijmp_list: pairs of case-value - destination basic block
  49
  50 .. op:: OP_UNREACH
  51         Mark code as unreachable
  52
  53 .. op:: OP_COMPUTEDGOTO
  54         Computed goto / branch to register
  55
  56         * .src: address to branch to (void*)
  57         * .multijmp_list: list of possible destination basic blocks
  58
  59 Arithmetic binops
  60 -----------------
  61 They all follow the same signature:
  62         * .src1, .src2: operands (types must be compatible with .target)
  63         * .target: result of the operation (must be an integral type)
  64         * .type: type of .target
  65
  66 .. op:: OP_ADD
  67         Integer addition.
  68
  69 .. op:: OP_SUB
  70         Integer subtraction.
  71
  72 .. op:: OP_MUL
  73         Integer multiplication.
  74
  75 .. op:: OP_DIVU
  76         Integer unsigned division.
  77
  78 .. op:: OP_DIVS
  79         Integer signed division.
  80
  81 .. op:: OP_MODU
  82         Integer unsigned remainder.
  83
  84 .. op:: OP_MODS
  85         Integer signed remainder.
  86
  87 .. op:: OP_SHL
  88         Shift left (integer only)
  89
  90 .. op:: OP_LSR
  91         Logical Shift right (integer only)
  92
  93 .. op:: OP_ASR
  94         Arithmetic Shift right (integer only)
  95
  96 Floating-point binops
  97 ---------------------
  98 They all follow the same signature:
  99         * .src1, .src2: operands (types must be compatible with .target)
 100         * .target: result of the operation (must be a floating-point type)
 101         * .type: type of .target
 102
 103 .. op:: OP_FADD
 104         Floating-point addition.
 105
 106 .. op:: OP_FSUB
 107         Floating-point subtraction.
 108
 109 .. op:: OP_FMUL
 110         Floating-point multiplication.
 111
 112 .. op:: OP_FDIV
 113         Floating-point division.
 114
 115 Logical ops
 116 -----------
 117 They all follow the same signature:
 118         * .src1, .src2: operands (types must be compatible with .target)
 119         * .target: result of the operation
 120         * .type: type of .target, must be an integral type
 121
 122 .. op:: OP_AND
 123         Logical AND
 124
 125 .. op:: OP_OR
 126         Logical OR
 127
 128 .. op:: OP_XOR
 129         Logical XOR
 130
 131 Integer compares
 132 ----------------
 133 They all have the following signature:
 134         * .src1, .src2: operands (types must be compatible)
 135         * .target: result of the operation (0/1 valued integer)
 136         * .type: type of .target, must be an integral type
 137         * .itype: type of the input operands
 138
 139 .. op:: OP_SET_EQ
 140         Compare equal.
 141
 142 .. op:: OP_SET_NE
 143         Compare not-equal.
 144
 145 .. op:: OP_SET_LE
 146         Compare less-than-or-equal (signed).
 147
 148 .. op:: OP_SET_GE
 149         Compare greater-than-or-equal (signed).
 150
 151 .. op:: OP_SET_LT
 152         Compare less-than (signed).
 153
 154 .. op:: OP_SET_GT
 155         Compare greater-than (signed).
 156
 157 .. op:: OP_SET_B
 158         Compare less-than (unsigned).
 159
 160 .. op:: OP_SET_A
 161         Compare greater-than (unsigned).
 162
 163 .. op:: OP_SET_BE
 164         Compare less-than-or-equal (unsigned).
 165
 166 .. op:: OP_SET_AE
 167         Compare greater-than-or-equal (unsigned).
 168
 169 Floating-point compares
 170 -----------------------
 171 They all have the same signature as the integer compares.
 172
 173 The usual 6 operations exist in two versions: 'ordered' and
 174 'unordered'. These operations first check if any operand is a
 175 NaN and if it is the case the ordered compares return false
 176 and then unordered return true, otherwise the result of the
 177 comparison, now guaranteed to be done on non-NaNs, is returned.
 178
 179 .. op:: OP_FCMP_OEQ
 180         Floating-point compare ordered equal
 181
 182 .. op:: OP_FCMP_ONE
 183         Floating-point compare ordered not-equal
 184
 185 .. op:: OP_FCMP_OLE
 186         Floating-point compare ordered less-than-or-equal
 187
 188 .. op:: OP_FCMP_OGE
 189         Floating-point compare ordered greater-or-equal
 190
 191 .. op:: OP_FCMP_OLT
 192         Floating-point compare ordered less-than
 193
 194 .. op:: OP_FCMP_OGT
 195         Floating-point compare ordered greater-than
 196
 197
 198 .. op:: OP_FCMP_UEQ
 199         Floating-point compare unordered equal
 200
 201 .. op:: OP_FCMP_UNE
 202         Floating-point compare unordered not-equal
 203
 204 .. op:: OP_FCMP_ULE
 205         Floating-point compare unordered less-than-or-equal
 206
 207 .. op:: OP_FCMP_UGE
 208         Floating-point compare unordered greater-or-equal
 209
 210 .. op:: OP_FCMP_ULT
 211         Floating-point compare unordered less-than
 212
 213 .. op:: OP_FCMP_UGT
 214         Floating-point compare unordered greater-than
 215
 216
 217 .. op:: OP_FCMP_ORD
 218         Floating-point compare ordered: return true if both operands are ordered
 219         (none of the operands are a NaN) and false otherwise.
 220
 221 .. op:: OP_FCMP_UNO
 222         Floating-point compare unordered: return false if no operands is ordered
 223         and true otherwise.
 224
 225 Unary ops
 226 ---------
 227 .. op:: OP_NOT
 228         Logical not.
 229
 230         * .src: operand (type must be compatible with .target)
 231         * .target: result of the operation
 232         * .type: type of .target, must be an integral type
 233
 234 .. op:: OP_NEG
 235         Integer negation.
 236
 237         * .src: operand (type must be compatible with .target)
 238         * .target: result of the operation (must be an integral type)
 239         * .type: type of .target
 240
 241 .. op:: OP_FNEG
 242         Floating-point negation.
 243
 244         * .src: operand (type must be compatible with .target)
 245         * .target: result of the operation (must be a floating-point type)
 246         * .type: type of .target
 247
 248 .. op:: OP_SYMADDR
 249         Create a pseudo corresponding to the address of a symbol.
 250
 251         * .src: input symbol (must be a PSEUDO_SYM)
 252         * .target: symbol's address
 253
 254 .. op:: OP_COPY
 255         Copy (only needed after out-of-SSA).
 256
 257         * .src: operand (type must be compatible with .target)
 258         * .target: result of the operation
 259         * .type: type of .target
 260
 261 Type conversions
 262 ----------------
 263 They all have the following signature:
 264         * .src: source value
 265         * .orig_type: type of .src
 266         * .target: result value
 267         * .type: type of .target
 268
 269 Currently, a cast to a void pointer is treated like a cast to
 270 an unsigned integer of the same size.
 271
 272 .. op:: OP_TRUNC
 273         Cast from integer to an integer of a smaller size.
 274
 275 .. op:: OP_SEXT
 276         Cast from integer to an integer of a bigger size with sign extension.
 277
 278 .. op:: OP_ZEXT
 279         Cast from integer to an integer of a bigger size with zero extension.
 280
 281 .. op:: OP_UTPTR
 282         Cast from pointer-sized unsigned integer to pointer type.
 283
 284 .. op:: OP_PTRTU
 285         Cast from pointer type to pointer-sized unsigned integer.
 286
 287 .. op:: OP_PTRCAST
 288         Cast between pointers.
 289
 290 .. op:: OP_FCVTU
 291         Conversion from float type to unsigned integer.
 292
 293 .. op:: OP_FCVTS
 294         Conversion from float type to signed integer.
 295
 296 .. op:: OP_UCVTF
 297         Conversion from unsigned integer to float type.
 298
 299 .. op:: OP_SCVTF
 300         Conversion from signed integer to float type.
 301
 302 .. op:: OP_FCVTF
 303         Conversion between float types.
 304
 305 Ternary ops
 306 -----------
 307 .. op:: OP_SEL
 308         * .src1: condition, must be of integral type
 309         * .src2, .src3: operands (types must be compatible with .target)
 310         * .target: result of the operation
 311         * .type: type of .target
 312
 313 .. op:: OP_FMADD
 314     Fused multiply-add.
 315
 316         * .src1, .src2, .src3: operands (types must be compatible with .target)
 317         * .target: result of the operation (must be a floating-point type)
 318         * .type: type of .target
 319
 320 .. op:: OP_RANGE
 321         Range/bounds checking (only used for an unused sparse extension).
 322
 323         * .src1: value to be checked
 324         * .src2, src3: bound of the value (must be constants?)
 325         * .type: type of .src[123]?
 326
 327 Memory ops
 328 ----------
 329 .. op:: OP_LOAD
 330         Load.
 331
 332         * .src: base address to load from
 333         * .offset: address offset
 334         * .target: loaded value
 335         * .type: type of .target
 336
 337 .. op:: OP_STORE
 338         Store.
 339
 340         * .src: base address to store to
 341         * .offset: address offset
 342         * .target: value to be stored
 343         * .type: type of .target
 344
 345 Others
 346 ------
 347 .. op:: OP_SETFVAL
 348         Create a pseudo corresponding to a floating-point literal.
 349
 350         * .fvalue: the literal's value (long double)
 351         * .target: the corresponding pseudo
 352         * .type: type of the literal & .target
 353
 354 .. op:: OP_SETVAL
 355         Create a pseudo corresponding to a string literal.
 356         The value is given as an expression EXPR_STRING.
 357
 358         * .val: (expression) input expression
 359         * .target: the resulting value
 360         * .type: type of .target, the value
 361
 362 .. op:: OP_LABEL
 363         Create a pseudo corresponding to a label-as-value.
 364
 365         * .bb_true: the BB corresponding to the label
 366         * .target: the resulting value
 367         * .type: type of .target (void \*)
 368
 369 .. op:: OP_PHI
 370         Phi-node (for SSA form).
 371
 372         * .phi_list: phi-operands (type must be compatible with .target)
 373         * .target: "result"
 374         * .type: type of .target
 375
 376 .. op:: OP_PHISOURCE
 377         Phi-node source.
 378         Like OP_COPY but exclusively used to give a defining instructions
 379         (and thus also a type) to *all* OP_PHI operands.
 380
 381         * .phi_src: operand (type must be compatible with .target, alias .src)
 382         * .target: the "result" PSEUDO_PHI
 383         * .type: type of .target
 384         * .phi_node: the unique phi instruction using the target pseudo
 385
 386 .. op:: OP_CALL
 387         Function call.
 388
 389         * .func: (pseudo_t) the function (can be a symbol or a "register",
 390           alias .src))
 391         * .arguments: (pseudo_list) list of the associated arguments
 392         * .target: function return value (if any)
 393         * .type: type of .target
 394         * .fntypes: (symbol_list) list of the function's types: the first
 395           entry is the full function type, the next ones are the type of
 396           each arguments
 397
 398 .. op:: OP_INLINED_CALL
 399         Only used as an annotation to show that the instructions just above
 400         correspond to a function that have been inlined.
 401
 402         * .func: (pseudo_t) the function (must be a symbol, alias .src))
 403         * .arguments: list of pseudos that where the function's arguments
 404         * .target: function return value (if any)
 405         * .type: type of .target
 406
 407 .. op:: OP_SLICE
 408         Extract a "slice" from an aggregate.
 409
 410         * .base: (pseudo_t) aggregate (alias .src)
 411         * .from: offset of the "slice" within the aggregate
 412         * .target: result
 413         * .type: type of .target
 414
 415 .. op:: OP_ASM
 416         Inlined assembly code.
 417
 418         * .string: asm template
 419         * .asm_rules: asm constraints, rules
 420
 421 Sparse tagging (line numbers, context, whatever)
 422 ------------------------------------------------
 423 .. op:: OP_CONTEXT
 424         Currently only used for lock/unlock tracking.
 425
 426         * .context_expr: unused
 427         * .increment: (1 for locking, -1 for unlocking)
 428         * .check: (ignore the instruction if 0)
 429
 430 Misc ops
 431 --------
 432 .. op:: OP_ENTRY
 433         Function entry point (no associated semantic).
 434
 435 .. op:: OP_BADOP
 436         Invalid operation (should never be generated).
 437
 438 .. op:: OP_NOP
 439         No-op (should never be generated).
 440
 441 .. op:: OP_DEATHNOTE
 442         Annotation telling the pseudo will be death after the next
 443         instruction (other than some other annotation, that is).
 444
 445 .. # vim: tabstop=4