basis/compiler/cfg/instructions/instructions-docs.factor

   1 USING: alien arrays assocs byte-arrays classes combinators
   2 compiler.cfg compiler.cfg.builder compiler.cfg.intrinsics.fixnum
   3 compiler.cfg.linear-scan.assignment compiler.cfg.liveness
   4 compiler.cfg.ssa.destruction compiler.cfg.value-numbering
   5 compiler.codegen.gc-maps compiler.tree cpu.architecture help.markup
   6 help.syntax kernel layouts math sequences slots.private system vm ;
   7 IN: compiler.cfg.instructions
   8
   9 HELP: ##alien-invoke
  10 { $class-description
  11   "An instruction for calling a function in a dynamically linked library. It has the following slots:"
  12   { $slots
  13     {
  14         "dead-outputs"
  15         { "A sequence of return values from the function that the compiler.cfg.dce pass has figured out are not used." }
  16     }
  17     {
  18         "reg-inputs"
  19         { "Registers to use for the arguments to the function call. Each sequence item is a 3-tuple consisting of a " { $link spill-slot } ", register representation and a register. When the function is called, the parameter is copied from the spill slot to the given register." }
  20     }
  21     {
  22         "stack-inputs"
  23         { "Stack slots used for the arguments to the function call." }
  24     }
  25     {
  26         "reg-outputs"
  27         { "If the called function returns a value, then this slot is a one-element sequence containing a 3-tuple describing which register is used for the return value." }
  28     }
  29     { "symbols" { "Name of the function to call." } }
  30     { "dll" { "A dll handle or " { $link f } "." } }
  31     {
  32         "gc-map"
  33         {
  34             "If the invoked C function calls Factor code which triggers a GC, then a "
  35             { $link gc-map }
  36             " is necessary to find the roots."
  37         }
  38     }
  39   }
  40   "Which function arguments that goes in " { $slot "reg-inputs" } " and which goes in " { $slot "stack-inputs" } " depend on the calling convention. In " { $link cdecl } " on " { $link x86.32 } ", all arguments goes in " { $slot "stack-inputs" } ", in " { $link x86.64 } " on " { $link unix } ", the first six arguments are passed in registers and then stack parameters are used for the remainder."
  41 }
  42 { $see-also #alien-invoke %alien-invoke } ;
  43
  44 HELP: ##alien-indirect
  45 { $class-description
  46   "An instruction representing an indirect alien call. The first item on the datastack is a pointer to the function to call and the parameters follows. It has the following slots:"
  47   { $slots
  48     { "src" { "Spill slot containing the function pointer." } }
  49     { "reg-outputs" { "Sequence of output values passed in registers." } }
  50   }
  51 }
  52 { $see-also alien-indirect %alien-indirect } ;
  53
  54 HELP: ##allot
  55 { $class-description
  56   "An instruction for allocating memory in the nursery. Usually the instruction is preceded by " { $link ##check-nursery-branch } " which checks that there is enough room in the nursery to allocate. It has the following slots:"
  57   { $slots
  58     { "dst" { "Register to put the pointer to the memory in." } }
  59     { "size" { "Number of bytes to allocate." } }
  60     { "class-of" { "Class of object to allocate, e.g " { $link tuple } " or " { $link array } "." } }
  61     { "temp" { "Temporary register to clobber." } }
  62   }
  63 } ;
  64
  65 HELP: ##bit-count
  66 { $class-description "Specialized instruction for counting the number of lit bits in an integer." }
  67 { $see-also %bit-count } ;
  68
  69 HELP: ##box
  70 { $class-description
  71   "This instruction boxes a value into a tagged pointer."
  72 } { $see-also %box } ;
  73
  74 HELP: ##box-alien
  75 { $class-description
  76   "An instruction for boxing an alien value."
  77 } ;
  78
  79 HELP: ##call
  80 { $class-description
  81   "An instruction for calling a Factor word."
  82   { $slots
  83     { "word" { "The word called." } }
  84   }
  85 } ;
  86
  87 HELP: ##check-nursery-branch
  88 { $class-description
  89   "Instruction that inserts a conditional branch to a " { $link basic-block } " that garbage collects the nursery. The " { $vocab-link "compiler.cfg.gc-checks" } " vocab goes through each block in the " { $link cfg } " and checks if it allocates memory. If it does, then this instruction is inserted in the cfg before that block and checks if there is enough available space in the nursery. If it isn't, then a basic block containing code for garbage collecting the nursery is executed."
  90   $nl
  91   "It has the following slots:"
  92   { $slots
  93     { "size" { "Number of bytes the next block in the cfg will allocate." } }
  94     { "cc" { "A comparison symbol." } }
  95     { "temp1" { "First register that will be clobbered." } }
  96     { "temp2" { "Second register that will be clobbered." } }
  97   }
  98 }
  99 { $see-also %check-nursery-branch } ;
 100
 101 HELP: ##compare-float-ordered-branch
 102 { $class-description
 103   "It has the following slots:"
 104   { $slots
 105     { "cc" { "Comparison symbol." } }
 106   }
 107 } ;
 108
 109 HELP: ##compare-imm
 110 { $class-description "Instruction used to implement trivial ifs and not ifs." }
 111 { $see-also emit-trivial-if emit-trivial-not-if } ;
 112
 113 HELP: ##compare-imm-branch
 114 { $class-description "The instruction used to implement branching for the " { $link if } " word." } ;
 115
 116 HELP: ##compare-integer
 117 { $class-description "This instruction is emitted for " { $link fixnum } " comparisons." }
 118 { $see-also emit-fixnum-comparison } ;
 119
 120 HELP: ##copy
 121 { $class-description "Instruction that copies a value from one register to another of the same type. For example, you can copy between two gprs or two simd registers but not across. It has the following slots:"
 122   { $slots
 123     { "rep" { "Value representation. Both the source and destination register must have the same representation." } }
 124   }
 125 } ;
 126
 127 HELP: ##dispatch
 128 { $class-description "Special instruction for implementing " { $link case } " blocks." } ;
 129
 130 HELP: ##fixnum-add
 131 { $class-description "Instruction for adding two fixnums together." }
 132 { $see-also emit-fixnum+ } ;
 133
 134 HELP: ##inc
 135 { $class-description
 136   "An instruction that increases or decreases a stacks height by n. For example, " { $link 2drop } " decreases the datastacks height by two and pushing an item increases it by one."
 137 } ;
 138
 139 HELP: ##jump
 140 { $class-description
 141   "An uncondiation jump instruction. It has the following slots:"
 142   { $slots
 143     { "word" { "Word whose address the instruction is jumping to." } }
 144   }
 145   "Note that the optimizer is sometimes able to optimize away a " { $link ##call } " and " { $link ##return } " pair into one ##jump instruction."
 146 } ;
 147
 148 HELP: ##load-double
 149 { $class-description "Loads a " { $link float } " into a SIMD register." }
 150 { $see-also %load-double } ;
 151
 152 HELP: ##load-memory-imm
 153 { $class-description "Instruction for loading data from memory into a register. Either a General Purpose or an SSE register." }
 154 { $see-also %load-memory-imm } ;
 155
 156 HELP: ##load-reference
 157 { $class-description
 158   "An instruction for loading a pointer to an object into a register. It has the following slots:"
 159   { $slots
 160     { "dst" { "Register to load the pointer into." } }
 161     { "obj" { "A Factor object." } }
 162   }
 163 } ;
 164
 165 HELP: ##load-tagged
 166 { $class-description "Loads a tagged value into a register." } ;
 167
 168 HELP: ##load-vector
 169 { $class-description
 170   "Loads a " { $link byte-array } " into an SSE register."
 171 }
 172 { $see-also %load-vector } ;
 173
 174 HELP: ##local-allot
 175 { $class-description
 176   "An instruction for allocating memory in the words own stack frame. It's mostly used for receiving data from alien calls. It has the following slots:"
 177   { $slots
 178     { "dst" { "Register into which a pointer to the stack allocated memory is put." } }
 179     { "size" { "Number of bytes to allocate." } }
 180     { "offset" { } }
 181   }
 182 }
 183 { $see-also ##allot } ;
 184
 185 HELP: ##mul-vector
 186 { $class-description
 187   "SIMD instruction." } ;
 188
 189 HELP: ##no-tco
 190 { $class-description "A dummy instruction that simply inhibits TCO." } ;
 191
 192 HELP: ##parallel-copy
 193 { $class-description "An instruction for performing multiple copies. It allows for optimizations or (or prunings) if more than one source or destination vreg is the same. They are transformed into " { $link ##copy } " instructions in " { $link destruct-ssa } ". It has the following slots:"
 194   { $slots
 195     { "values" { "An assoc mapping source vregs to destinations." } }
 196   }
 197 } ;
 198
 199 HELP: ##peek
 200 { $class-description
 201   "Copies a value from a stack location to a machine register."
 202 }
 203 { $see-also ##replace } ;
 204
 205 HELP: ##phi
 206 { $class-description
 207   "A special kind of instruction used to mark control flow. It is inserted by the " { $vocab-link "compiler.cfg.ssa.construction" } " vocab. It has the following slots:"
 208   { $slots
 209     { "inputs" { "An assoc containing as keys the blocks/block numbers where the vreg was defined and as values the vreg. Why care about the blocks?" } }
 210     { "dst" { "A merged vreg for the value." } }
 211   }
 212 } ;
 213
 214 HELP: ##prologue
 215 { $class-description
 216   "An instruction for generating the prologue for a cfg. All it does is decrementing the stack register a number of cells to give the generated code some stack space to work with." }
 217   { $see-also ##epilogue } ;
 218
 219 HELP: ##reload
 220 { $class-description "Instruction that copies a value from a " { $link spill-slot } " to a register." } ;
 221
 222 HELP: ##replace
 223 { $class-description "Copies a value from a machine register to a stack location." }
 224 { $see-also ##peek ##replace-imm } ;
 225
 226 HELP: ##replace-imm
 227 { $class-description "An instruction that replaces an item on the data or register stack with an " { $link immediate } " value. The " { $link value-numbering } " compiler optimization pass can sometimes rewrite " { $link ##replace } " instructions to ##replace-imm's." }
 228 { $see-also ##replace } ;
 229
 230
 231 HELP: ##return
 232 { $class-description "Instruction that returns from a procedure call." } ;
 233
 234 HELP: ##safepoint
 235 { $class-description "Instruction that inserts a safe point in the generated code." } ;
 236
 237 HELP: ##save-context
 238 { $class-description "The ##save-context instructions saves the state of the data, retain and callstacks in the threads " { $link context } " struct." }
 239 { $see-also %save-context } ;
 240
 241 HELP: ##set-slot
 242 { $class-description
 243   "An instruction for the non-primitive, non-immediate variant of " { $link set-slot } ". It has the following slots:"
 244   { $slots
 245     { "src" { "Object to put in the slot." } }
 246     { "obj" { "Object to set the slot on." } }
 247     { "slot" { "Slot index." } }
 248     { "tag" { "Type tag for obj." } }
 249   }
 250 } ;
 251
 252 HELP: ##set-slot-imm
 253 { $class-description
 254   "An instruction for what? It has the following slots:"
 255   { $slots
 256     { "src" { "Register containing the value to put in the slot." } }
 257     { "obj" { "Register containing the object to set the slot on.." } }
 258     { "slot" { "Slot index." } }
 259     { "tag" { "Type tag for obj." } }
 260   }
 261 }
 262 { $see-also ##set-slot %set-slot-imm } ;
 263
 264 { ##set-slot-imm ##set-slot } related-words
 265
 266 HELP: ##single>double-float
 267 { $class-description "Converts a single precision value (32-bit usually) stored in a SIMD register to a double precision one (64-bit usually)." } ;
 268
 269 HELP: ##shuffle-vector-imm
 270 { $class-description "Shuffles the vector in a SSE register according to the given shuffle pattern. It is used to extract a given element of the vector."
 271   { $slots
 272     { "dst" { "Destination register to shuffle the vector to." } }
 273     { "src" { "Source register." } }
 274     { "shuffle" { "Shuffling pattern." } }
 275   }
 276 }
 277 { $see-also %shuffle-vector-imm } ;
 278
 279 HELP: ##slot-imm
 280 { $class-description
 281   "Instruction for reading a slot with a given index from an object."
 282   { $slots
 283     { "dst" { "Register to read the slot value into." } }
 284     { "obj" { "Register containing the object with the slot." } }
 285     { "slot" { "Slot index." } }
 286     { "tag" { "Type tag for obj." } }
 287   }
 288 } { $see-also %slot-imm } ;
 289
 290 HELP: ##spill
 291 { $class-description "Instruction that copies a value from a register to a " { $link spill-slot } "."
 292   { $slots
 293     { "rep" { "Register representation which is necessary when spilling SIMD registers." } }
 294   }
 295 } { $see-also ##reload } ;
 296
 297 HELP: ##store-memory-imm
 298 { $class-description "Instruction that copies an 8 byte value from a XMM register to a memory location addressed by a normal register. This instruction is often turned into a cheaper " { $link ##store-memory } " instruction in the " { $link value-numbering } " pass."
 299   { $slots
 300     { "base" { "Vreg that contains the base address." } }
 301     {
 302         "offset"
 303         { "Offset in bytes from the address to where the data should be written." }
 304     }
 305     { "rep" { "Value representation in the vector register." } }
 306     { "src" { "Vreg that contains the item to set." } }
 307   }
 308 }
 309 { $see-also %store-memory-imm } ;
 310
 311 HELP: ##test-branch
 312 { $class-description "Instruction inserted by the " { $vocab-link "compiler.cfg.value-numbering" } " compiler pass." }
 313 { $see-also ##compare-integer-imm-branch } ;
 314
 315 HELP: ##unbox-any-c-ptr
 316 { $class-description "Instruction that unboxes a pointer in a register so that it can be fed to a C FFI function. For example, if 'src' points to a " { $link byte-array } ", then in 'dst' will be put a pointer to the first byte of that byte array."
 317   { $slots
 318     { "dst" { "Destination register." } }
 319     { "src" { "Source register." } }
 320   }
 321 }
 322 { $see-also %unbox-any-c-ptr } ;
 323
 324 HELP: ##unbox-long-long
 325 { $class-description "Instruction that unboxes a 64-bit integer to two 32-bit registers. Only used on 32 bit architectures." } ;
 326
 327 HELP: ##vector>scalar
 328 { $class-description
 329   "This instruction is very similar to " { $link ##copy } "."
 330   { $slots
 331     { "dst" { "destination vreg" } }
 332     { "src" { "source vreg" } }
 333     { "rep" { "representation for the source vreg" } }
 334   }
 335 }
 336 { $notes "The two vregs must not necessarily share the same representation." }
 337 { $see-also %vector>scalar } ;
 338
 339 HELP: ##vm-field
 340 { $class-description "Instruction for loading a pointer to a vm field."
 341   { $slots
 342     { "dst" { "Register to load the field into." } }
 343     { "offset" { "Offset of the field relative to the vm address." } }
 344   }
 345 }
 346 { $see-also %vm-field } ;
 347
 348 HELP: ##write-barrier
 349 { $class-description
 350   "An instruction for inserting a write barrier. This instruction is almost always inserted after a " { $link ##set-slot } " instruction. If the container object is in an older generation than the item inserted, this instruction guarantees that the item will not be garbage collected. It has the following slots:"
 351   { $slots
 352     { "src" { "Object to which the writer barrier refers." } }
 353     { "slot" { "Slot index of the object." } }
 354     { "scale" { "No idea." } }
 355     { "tag" { "Type tag for obj." } }
 356     { "temp1" { "First temporary register to clobber." } }
 357     { "temp2" { "Second temporary register to clobber." } }
 358   }
 359 } ;
 360
 361 HELP: alien-call-insn
 362 { $class-description "Union class of all alien call instructions." } ;
 363
 364 HELP: allocation-insn
 365 { $class-description "Union class of all instructions that allocate memory." } ;
 366
 367 HELP: def-is-use-insn
 368 { $class-description "Union class of instructions that have complex expansions and require that the output registers are not equal to any of the input registers." } ;
 369
 370 HELP: new-insn
 371 { $values { "class" class } { "insn" insn } }
 372 { $description
 373   "Boa wrapper for the " { $link insn } " class with " { $slot "insn#" } " set to " { $link f } "."
 374 } ;
 375
 376 HELP: insn
 377 { $class-description
 378   "Base class for all virtual cpu instructions, used by the CFG IR."
 379 } ;
 380
 381 HELP: vreg-insn
 382 { $class-description
 383   "Base class for instructions that uses vregs."
 384 } ;
 385
 386 HELP: flushable-insn
 387 { $class-description
 388   "Instructions which do not have side effects; used for dead code elimination." } ;
 389
 390 HELP: foldable-insn
 391 { $class-description
 392   "Instructions which are referentially transparent; used for value numbering." } ;
 393
 394 HELP: gc-map-insn
 395 { $class-description "Union class of all instructions that contain subroutine calls to functions which allocate memory. Each of the instances has a " { $snippet "gc-map" } " slot." } ;
 396
 397 HELP: gc-map
 398 { $class-description "A tuple that holds info necessary for a gc cycle to figure out where the gc root pointers are. It has the following slots:"
 399   { $slots
 400     {
 401         "gc-roots"
 402         { { $link sequence } " of vregs or spill-slots" }
 403     }
 404     {
 405         "derived-roots"
 406         { "An " { $link assoc } " of pairs of vregs or spill slots." } }
 407   }
 408   "The 'gc-roots' and 'derived-roots' slots are initially vreg integers referencing objects that are live during the gc call and needs to be spilled so that they can be traced. In the " { $link emit-gc-map-insn } " word in " { $vocab-link "compiler.cfg.linear-scan.assignment" } " they are converted to spill slots which the collector is able to trace."
 409 }
 410 { $see-also emit-gc-info-bitmap fill-gc-map } ;
 411
 412 ARTICLE: "compiler.cfg.instructions" "Basic block instructions"
 413 "The " { $vocab-link "compiler.cfg.instructions" } " vocab contains all instruction classes used for generating CFG:s (Call Flow Graphs)."
 414 $nl
 415 "All instructions are tuples prefixed with '##' and inheriting from the base class " { $link insn } ". Most instructions are coupled with a generic word in " { $vocab-link "cpu.architecture" } " which emits machine code for it. For example, " { $link %copy } " emits code for " { $link ##copy } " instructions."
 416 $nl
 417 "Instruction classes for moving values around:"
 418 { $subsections
 419   ##copy
 420   ##parallel-copy
 421   ##peek
 422   ##reload
 423   ##replace
 424   ##replace-imm
 425   ##spill
 426 }
 427 "Control flow:"
 428 { $subsections
 429   ##branch
 430   ##call
 431   ##jump
 432   ##no-tco
 433   ##phi
 434   ##return
 435 }
 436 "Alien calls and FFI:"
 437 { $subsections
 438   ##alien-assembly
 439   ##alien-indirect
 440   ##alien-invoke
 441   ##box
 442   ##box-alien
 443   ##box-displaced-alien
 444   ##box-long-long
 445   ##callback-inputs
 446   ##callback-outputs
 447   ##unbox
 448   ##unbox-alien
 449   ##unbox-any-c-ptr
 450   ##unbox-long-long
 451   alien-call-insn
 452 }
 453 "Allocation and garbage collection:"
 454 { $subsections
 455   ##allot
 456   ##call-gc
 457   ##check-nursery-branch
 458   ##local-allot
 459   ##save-context
 460   allocation-insn
 461   gc-map
 462   gc-map-insn
 463   <gc-map>
 464 }
 465 "Comparison instructions:"
 466 { $subsections
 467   ##compare
 468   ##compare-imm
 469   ##compare-imm-branch
 470   ##compare-integer
 471   ##compare-integer-branch
 472   ##compare-integer-imm-branch
 473   ##test
 474   ##test-branch
 475   ##test-imm
 476   ##test-imm-branch
 477 }
 478 "Constant loading:"
 479 { $subsections
 480   ##load-integer
 481   ##load-reference
 482   ##load-tagged
 483 }
 484 "Floating point SIMD instructions:"
 485 { $subsections
 486   ##add-float
 487   ##div-float
 488   ##mul-float
 489   ##sub-float
 490 }
 491  "Integer arithmetic and bit operations:"
 492 { $subsections
 493   ##add
 494   ##add-imm
 495   ##and
 496   ##and-imm
 497   ##fixnum-add
 498   ##fixnum-sub
 499   ##mul
 500   ##mul-imm
 501   ##neg
 502   ##not
 503   ##or
 504   ##or-imm
 505   ##sar
 506   ##sar-imm
 507   ##shl
 508   ##shl-imm
 509   ##shr
 510   ##shr-imm
 511   ##sub
 512   ##sub-imm
 513   ##xor
 514   ##xor-imm
 515 }
 516 "Slot access:"
 517 { $subsections
 518   ##slot
 519   ##slot-imm
 520   ##set-slot
 521   ##set-slot-imm
 522   ##write-barrier
 523 }
 524 "SIMD instructions"
 525 { $subsections
 526   ##add-vector
 527   ##add-sub-vector
 528   ##bit-count
 529   ##compare-float-ordered-branch
 530   ##div-vector
 531   ##horizontal-add-vector
 532   ##horizontal-sub-vector
 533   ##load-double
 534   ##load-vector
 535   ##mul-vector
 536   ##shuffle-vector-imm
 537   ##single>double-float
 538   ##store-memory-imm
 539   ##sub-vector
 540   ##vector>scalar
 541 }
 542 "Stack height manipulation:"
 543 { $subsections
 544   ##inc
 545 } ;
 546
 547 ABOUT: "compiler.cfg.instructions"