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
 138 .. op:: OP_SET_EQ
 139         Compare equal.
 140
 141 .. op:: OP_SET_NE
 142         Compare not-equal.
 143
 144 .. op:: OP_SET_LE
 145         Compare less-than-or-equal (signed).
 146
 147 .. op:: OP_SET_GE
 148         Compare greater-than-or-equal (signed).
 149
 150 .. op:: OP_SET_LT
 151         Compare less-than (signed).
 152
 153 .. op:: OP_SET_GT
 154         Compare greater-than (signed).
 155
 156 .. op:: OP_SET_B
 157         Compare less-than (unsigned).
 158
 159 .. op:: OP_SET_A
 160         Compare greater-than (unsigned).
 161
 162 .. op:: OP_SET_BE
 163         Compare less-than-or-equal (unsigned).
 164
 165 .. op:: OP_SET_AE
 166         Compare greater-than-or-equal (unsigned).
 167
 168 Floating-point compares
 169 -----------------------
 170 They all have the same signature as the integer compares.
 171
 172 The usual 6 operations exist in two versions: 'ordered' and
 173 'unordered'. These operations first check if any operand is a
 174 NaN and if it is the case the ordered compares return false
 175 and then unordered return true, otherwise the result of the
 176 comparison, now guaranteed to be done on non-NaNs, is returned.
 177
 178 .. op:: OP_FCMP_OEQ
 179         Floating-point compare ordered equal
 180
 181 .. op:: OP_FCMP_ONE
 182         Floating-point compare ordered not-equal
 183
 184 .. op:: OP_FCMP_OLE
 185         Floating-point compare ordered less-than-or-equal
 186
 187 .. op:: OP_FCMP_OGE
 188         Floating-point compare ordered greater-or-equal
 189
 190 .. op:: OP_FCMP_OLT
 191         Floating-point compare ordered less-than
 192
 193 .. op:: OP_FCMP_OGT
 194         Floating-point compare ordered greater-than
 195
 196
 197 .. op:: OP_FCMP_UEQ
 198         Floating-point compare unordered equal
 199
 200 .. op:: OP_FCMP_UNE
 201         Floating-point compare unordered not-equal
 202
 203 .. op:: OP_FCMP_ULE
 204         Floating-point compare unordered less-than-or-equal
 205
 206 .. op:: OP_FCMP_UGE
 207         Floating-point compare unordered greater-or-equal
 208
 209 .. op:: OP_FCMP_ULT
 210         Floating-point compare unordered less-than
 211
 212 .. op:: OP_FCMP_UGT
 213         Floating-point compare unordered greater-than
 214
 215
 216 .. op:: OP_FCMP_ORD
 217         Floating-point compare ordered: return true if both operands are ordered
 218         (none of the operands are a NaN) and false otherwise.
 219
 220 .. op:: OP_FCMP_UNO
 221         Floating-point compare unordered: return false if no operands is ordered
 222         and true otherwise.
 223
 224 Unary ops
 225 ---------
 226 .. op:: OP_NOT
 227         Logical not.
 228
 229         * .src: operand (type must be compatible with .target)
 230         * .target: result of the operation
 231         * .type: type of .target, must be an integral type
 232
 233 .. op:: OP_NEG
 234         Integer negation.
 235
 236         * .src: operand (type must be compatible with .target)
 237         * .target: result of the operation (must be an integral type)
 238         * .type: type of .target
 239
 240 .. op:: OP_FNEG
 241         Floating-point negation.
 242
 243         * .src: operand (type must be compatible with .target)
 244         * .target: result of the operation (must be a floating-point type)
 245         * .type: type of .target
 246
 247 .. op:: OP_SYMADDR
 248         Create a pseudo corresponding to the address of a symbol.
 249
 250         * .src: input symbol (must be a PSEUDO_SYM)
 251         * .target: symbol's address
 252
 253 .. op:: OP_COPY
 254         Copy (only needed after out-of-SSA).
 255
 256         * .src: operand (type must be compatible with .target)
 257         * .target: result of the operation
 258         * .type: type of .target
 259
 260 Type conversions
 261 ----------------
 262 They all have the following signature:
 263         * .src: source value
 264         * .orig_type: type of .src
 265         * .target: result value
 266         * .type: type of .target
 267
 268 Currently, a cast to a void pointer is treated like a cast to
 269 an unsigned integer of the same size.
 270
 271 .. op:: OP_TRUNC
 272         Cast from integer to an integer of a smaller size.
 273
 274 .. op:: OP_SEXT
 275         Cast from integer to an integer of a bigger size with sign extension.
 276
 277 .. op:: OP_ZEXT
 278         Cast from integer to an integer of a bigger size with zero extension.
 279
 280 .. op:: OP_UTPTR
 281         Cast from pointer-sized unsigned integer to pointer type.
 282
 283 .. op:: OP_PTRTU
 284         Cast from pointer type to pointer-sized unsigned integer.
 285
 286 .. op:: OP_PTRCAST
 287         Cast between pointers.
 288
 289 .. op:: OP_FCVTU
 290         Conversion from float type to unsigned integer.
 291
 292 .. op:: OP_FCVTS
 293         Conversion from float type to signed integer.
 294
 295 .. op:: OP_UCVTF
 296         Conversion from unsigned integer to float type.
 297
 298 .. op:: OP_SCVTF
 299         Conversion from signed integer to float type.
 300
 301 .. op:: OP_FCVTF
 302         Conversion between float types.
 303
 304 Ternary ops
 305 -----------
 306 .. op:: OP_SEL
 307         * .src1: condition, must be of integral type
 308         * .src2, .src3: operands (types must be compatible with .target)
 309         * .target: result of the operation
 310         * .type: type of .target
 311
 312 .. op:: OP_RANGE
 313         Range/bounds checking (only used for an unused sparse extension).
 314
 315         * .src1: value to be checked
 316         * .src2, src3: bound of the value (must be constants?)
 317         * .type: type of .src[123]?
 318
 319 Memory ops
 320 ----------
 321 .. op:: OP_LOAD
 322         Load.
 323
 324         * .src: base address to load from
 325         * .offset: address offset
 326         * .target: loaded value
 327         * .type: type of .target
 328
 329 .. op:: OP_STORE
 330         Store.
 331
 332         * .src: base address to store to
 333         * .offset: address offset
 334         * .target: value to be stored
 335         * .type: type of .target
 336
 337 Others
 338 ------
 339 .. op:: OP_SETFVAL
 340         Create a pseudo corresponding to a floating-point literal.
 341
 342         * .fvalue: the literal's value (long double)
 343         * .target: the corresponding pseudo
 344         * .type: type of the literal & .target
 345
 346 .. op:: OP_SETVAL
 347         Create a pseudo corresponding to a string literal or a label-as-value.
 348         The value is given as an expression EXPR_STRING or EXPR_LABEL.
 349
 350         * .val: (expression) input expression
 351         * .target: the resulting value
 352         * .type: type of .target, the value
 353
 354 .. op:: OP_PHI
 355         Phi-node (for SSA form).
 356
 357         * .phi_list: phi-operands (type must be compatible with .target)
 358         * .target: "result"
 359         * .type: type of .target
 360
 361 .. op:: OP_PHISOURCE
 362         Phi-node source.
 363         Like OP_COPY but exclusively used to give a defining instructions
 364         (and thus also a type) to *all* OP_PHI operands.
 365
 366         * .phi_src: operand (type must be compatible with .target, alias .src)
 367         * .target: the "result" PSEUDO_PHI
 368         * .type: type of .target
 369         * .phi_users: list of phi instructions using the target pseudo
 370
 371 .. op:: OP_CALL
 372         Function call.
 373
 374         * .func: (pseudo_t) the function (can be a symbol or a "register",
 375           alias .src))
 376         * .arguments: (pseudo_list) list of the associated arguments
 377         * .target: function return value (if any)
 378         * .type: type of .target
 379         * .fntypes: (symbol_list) list of the function's types: the first
 380           entry is the full function type, the next ones are the type of
 381           each arguments
 382
 383 .. op:: OP_INLINED_CALL
 384         Only used as an annotation to show that the instructions just above
 385         correspond to a function that have been inlined.
 386
 387         * .func: (pseudo_t) the function (must be a symbol, alias .src))
 388         * .arguments: list of pseudos that where the function's arguments
 389         * .target: function return value (if any)
 390         * .type: type of .target
 391
 392 .. op:: OP_SLICE
 393         Extract a "slice" from an aggregate.
 394
 395         * .base: (pseudo_t) aggregate (alias .src)
 396         * .from, .len: offet & size of the "slice" within the aggregate
 397         * .target: result
 398         * .type: type of .target
 399
 400 .. op:: OP_ASM
 401         Inlined assembly code.
 402
 403         * .string: asm template
 404         * .asm_rules: asm constraints, rules
 405
 406 Sparse tagging (line numbers, context, whatever)
 407 ------------------------------------------------
 408 .. op:: OP_CONTEXT
 409         Currently only used for lock/unlock tracking.
 410
 411         * .context_expr: unused
 412         * .increment: (1 for locking, -1 for unlocking)
 413         * .check: (ignore the instruction if 0)
 414
 415 Misc ops
 416 --------
 417 .. op:: OP_ENTRY
 418         Function entry point (no associated semantic).
 419
 420 .. op:: OP_BADOP
 421         Invalid operation (should never be generated).
 422
 423 .. op:: OP_NOP
 424         No-op (should never be generated).
 425
 426 .. op:: OP_DEATHNOTE
 427         Annotation telling the pseudo will be death after the next
 428         instruction (other than some other annotation, that is).
 429
 430 .. # vim: tabstop=4