basis/cpu/architecture/architecture-docs.factor

   1 USING: assocs alien classes compiler.cfg.instructions compiler.cfg.registers
   2 compiler.cfg.stack-frame cpu.x86.assembler cpu.x86.assembler.operands
   3 help.markup help.syntax kernel layouts literals math multiline system words ;
   4 QUALIFIED: vm
   5 IN: cpu.architecture
   6
   7 <<
   8 STRING: ex-%allot
   9 USING: cpu.architecture make ;
  10 [ RAX 40 tuple RCX %allot ] B{ } make disassemble
  11 0000000002270cc0: 498d4d10        lea rcx, [r13+0x10]
  12 0000000002270cc4: 488b01          mov rax, [rcx]
  13 0000000002270cc7: 48c7001c000000  mov qword [rax], 0x1c
  14 0000000002270cce: 4883c807        or rax, 0x7
  15 0000000002270cd2: 48830130        add qword [rcx], 0x30
  16 ;
  17
  18 STRING: ex-%box-alien
  19 USING: compiler.codegen compiler.codegen.relocation cpu.architecture make ;
  20 init-fixup init-relocation [ RAX RBX RCX %box-alien ] B{ } make disassemble
  21 000000e9fcc720a0: 48b80100000000000000  mov rax, 0x1
  22 000000e9fcc720aa: 4885db                test rbx, rbx
  23 000000e9fcc720ad: 0f8400000000          jz dword 0xe9fcc720b3
  24 000000e9fcc720b3: 498d4d10              lea rcx, [r13+0x10]
  25 000000e9fcc720b7: 488b01                mov rax, [rcx]
  26 000000e9fcc720ba: 48c70018000000        mov qword [rax], 0x18
  27 000000e9fcc720c1: 4883c806              or rax, 0x6
  28 000000e9fcc720c5: 48830130              add qword [rcx], 0x30
  29 000000e9fcc720c9: 48c7400201000000      mov qword [rax+0x2], 0x1
  30 000000e9fcc720d1: 48c7400a01000000      mov qword [rax+0xa], 0x1
  31 000000e9fcc720d9: 48895812              mov [rax+0x12], rbx
  32 000000e9fcc720dd: 4889581a              mov [rax+0x1a], rbx
  33 ;
  34
  35 STRING: ex-%context
  36 USING: cpu.architecture make ;
  37 [ EAX %context ] B{ } make disassemble
  38 00000000010f5ed0: 418b4500  mov eax, [r13]
  39 ;
  40
  41 STRING: ex-%copy
  42 USING: cpu.architecture make ;
  43 RAX RBX int-rep [ %copy ] B{ } make disassemble
  44 000000000108a970: 4889d8  mov rax, rbx
  45 ;
  46
  47 STRING: ex-%safepoint
  48 USING: cpu.architecture make ;
  49 init-relocation [ %safepoint ] B{ } make disassemble
  50 00000000010b05a0: 890500000000  mov [rip], eax
  51 ;
  52
  53 STRING: ex-%save-context
  54 USING: cpu.architecture make ;
  55 [ RAX RBX %save-context ] B{ } make disassemble
  56 0000000000e63ab0: 498b4500    mov rax, [r13]
  57 0000000000e63ab4: 488d5c24f8  lea rbx, [rsp-0x8]
  58 0000000000e63ab9: 488918      mov [rax], rbx
  59 0000000000e63abc: 4c897010    mov [rax+0x10], r14
  60 0000000000e63ac0: 4c897818    mov [rax+0x18], r15
  61 ;
  62
  63 STRING: ex-%write-barrier
  64 USING: cpu.architecture make tools.disassembler ;
  65 init-relocation [ RAX RBX 3 -14 RCX RDX %write-barrier ] B{ } make disassemble
  66 000000000143f960: 488d4cd80e            lea rcx, [rax+rbx*8+0xe]
  67 000000000143f965: 48c1e908              shr rcx, 0x8
  68 000000000143f969: 48ba0000000000000000  mov rdx, 0x0
  69 000000000143f973: 48c60411c0            mov byte [rcx+rdx], 0xc0
  70 000000000143f978: 48c1e90a              shr rcx, 0xa
  71 000000000143f97c: 48ba0000000000000000  mov rdx, 0x0
  72 000000000143f986: 48c60411c0            mov byte [rcx+rdx], 0xc0
  73 ;
  74 >>
  75
  76 HELP: double-2-rep
  77 { $var-description "Representation for a pair of doubles." } ;
  78
  79 HELP: signed-rep
  80 { $values { "rep" representation } { "rep'" representation } }
  81 { $description "Maps any representation to its signed counterpart, if it has one." } ;
  82
  83 HELP: rep-size
  84 { $values { "rep" representation } { "n" integer } }
  85 { $description "Size in bytes of a representation." } ;
  86
  87 HELP: immediate-arithmetic?
  88 { $values { "n" number } { "?" boolean } }
  89 { $description
  90   "Can this value be an immediate operand for " { $link %add-imm } ", "
  91   { $link %sub-imm } ", or " { $link %mul-imm } "?"
  92 } ;
  93
  94 HELP: machine-registers
  95 { $values { "assoc" assoc } }
  96 { $description "Mapping from register class to machine registers. Only registers not reserved by the Factor VM are included." } ;
  97
  98 HELP: vm-stack-space
  99 { $values { "n" number } }
 100 { $description "Parameter space to reserve in anything making VM calls." } ;
 101
 102 HELP: complex-addressing?
 103 { $values { "?" boolean } }
 104 { $description "Specifies if " { $link %slot } ", " { $link %set-slot } " and " { $link %write-barrier } " accept the 'scale' and 'tag' parameters, and if %load-memory and %store-memory work." } ;
 105
 106 HELP: param-regs
 107 { $values { "abi" "a calling convention symbol" } { "regs" assoc } }
 108 { $description "Retrieves the order in which machine registers are used for parameters for the given calling convention." } ;
 109
 110 HELP: %allot
 111 { $values
 112   { "dst" "destination register symbol" }
 113   { "size" "number of bytes to allocate" }
 114   { "class" "one of the built-in classes listed in " { $link type-numbers } }
 115   { "temp" "temporary register symbol" }
 116 }
 117 { $description "Emits machine code for allocating memory." }
 118 { $examples
 119   "In this example 40 bytes is allocated and a tagged pointer to the memory is put in " { $link RAX } ":"
 120   { $unchecked-example $[ ex-%allot ] }
 121 } ;
 122
 123 HELP: %box
 124 { $values
 125   { "dst" "destination register" }
 126   { "src" "source register" }
 127   { "func" "function?" }
 128   { "rep" "representation class" }
 129   { "gc-map" gc-map }
 130 }
 131 { $description "Call a function to convert a value into a tagged pointer, possibly allocating a bignum, float, or alien instance, which is then pushed on the data stack." } ;
 132
 133 HELP: %box-alien
 134 { $values { "dst" "destination register" } { "src" "source register" } { "temp" "temporary register" } }
 135 { $description "Emits machine code for boxing an alien value. If the alien is not a NULL pointer, then five " { $link cells } " will be allocated in the nursery space to wrap the object. See vm/layouts.hpp for details." }
 136 { $examples { $unchecked-example $[ ex-%box-alien ] } }
 137 { $see-also ##box-alien %allot } ;
 138
 139 HELP: %call
 140 { $values { "word" word } { "height" integer } }
 141 { $description "Emits code for calling a Factor word." } ;
 142
 143 HELP: %context
 144 { $values { "dst" "a register symbol" } }
 145 { $description "Emits machine code for putting a pointer to the context field of the " { $link vm } " in a register." }
 146 { $examples { $unchecked-example $[ ex-%context ] } } ;
 147
 148 HELP: %copy
 149 { $values { "dst" "destination" } { "src" "source" } { "rep" representation } }
 150 { $description "Emits code copying a value from a register, arbitrary memory location or " { $link spill-slot } " to a destination." }
 151 { $examples { $unchecked-example $[ ex-%copy ] } } ;
 152
 153 HELP: %horizontal-add-vector
 154 { $values
 155   { "dst" "destination register symbol" }
 156   { "src1"  "first source register" }
 157   { "src2" "second source register" }
 158   { "rep" "representation" }
 159 }
 160 { $description "Emits machine code for performing a horizontal add, meaning that adjacent elements in the same operand are added together. So if the two vectors are (a0, a1, a2, a3) and (b0, b1, b2, b3) then the result is (a0 + a1, a2 + a3, b0 + b1, b2 + b3)." }
 161 { $examples
 162   { $unchecked-example
 163     "USING: cpu.architecture make tools.disassembler ;"
 164     "[ XMM0 XMM1 XMM2 float-4-rep %horizontal-add-vector ] B{ } make disassemble"
 165     "0000000002660870: 0f28c1    movaps xmm0, xmm1"
 166     "0000000002660873: f20f7cc2  haddps xmm0, xmm2"
 167   }
 168 } ;
 169
 170 HELP: %load-immediate
 171 { $values { "reg" "a register symbol" } { "val" "a value" } }
 172 { $description "Emits code for loading an immediate value into a register. On " { $link x86 } ", if val is 0, then an " { $link XOR } " instruction is emitted instead of " { $link MOV } " because the former is shorter." }
 173 { $see-also ##load-tagged } ;
 174
 175 HELP: %load-memory-imm
 176 { $values
 177   { "dst" "destination register" }
 178   { "base" "base gpr for memory address" }
 179   { "offset" "memory offset" }
 180   { "rep" "representation" }
 181   { "c-type" "no idea" }
 182 }
 183 { $description "Emits code for loading a value from memory into a SIMD register." }
 184 { $examples
 185   { $unchecked-example
 186     "USING: cpu.architecture make tools.disassembler ;"
 187     "[ XMM0 RCX 7 float-4-rep f %load-memory-imm ] B{ } make disassemble"
 188     "0000000002633800: 480f284107  movaps xmm0, [rcx+0x7]"
 189   }
 190 } ;
 191
 192 HELP: %local-allot
 193 { $values
 194   { "dst" "destination register symbol" }
 195   { "size" "number of bytes to allocate" }
 196   { "align" "alignment" }
 197   { "offset" "where to allocate the data, relative to the stack register" }
 198 }
 199 { $description "Emits machine code for stack \"allocating\" a chunk of memory. No memory is really allocated and instead a pointer to it is just put in the destination register." } ;
 200
 201 HELP: %replace-imm
 202 { $values
 203   { "src" integer }
 204   { "loc" loc }
 205 }
 206 { $description "Emits machine code for putting an integer on the stack." }
 207 { $examples
 208   { $unchecked-example
 209     "USING: cpu.architecture make ;"
 210     "[ 777 D 0 %replace-imm ] B{ } make disassemble"
 211     "0000000000aad8c0: 49c70690300000  mov qword [r14], 0x3090"
 212   }
 213 } ;
 214
 215 HELP: %safepoint
 216 { $description "Emits a safe point to the current code sequence being generated." }
 217 { $examples { $unchecked-example $[ ex-%safepoint ] } } ;
 218
 219 HELP: %save-context
 220 { $values { "temp1" "a register symbol" } { "temp2" "a register symbol" } }
 221 { $description "Emits machine code for saving pointers to the callstack, datastack and retainstack in the current context field struct." }
 222 { $examples { $unchecked-example $[ ex-%save-context ] } } ;
 223
 224 HELP: %store-memory-imm
 225 { $values
 226   { "value" "source register" }
 227   { "base" "base register for memory" }
 228   { "offset" "memory offset" }
 229   { "rep" "representation" }
 230   { "c-type" "a c type or " { $link f } }
 231 }
 232 { $description "Emits machine code for " { $link ##store-memory-imm } " instructions." }
 233 { $examples
 234   { $unchecked-example
 235     "USING: cpu.architecture prettyprint ;"
 236     "[ XMM0 RBX 5 double-rep f %store-memory-imm ] B{ } make disassemble"
 237     "0000000002800ae0: f2480f114305  movsd [rbx+0x5], xmm0"
 238   }
 239 } ;
 240
 241 HELP: %vector>scalar
 242 { $values
 243   { "dst" "destination register" }
 244   { "src" "source register" }
 245   { "rep" representation }
 246 }
 247 { $description "Converts the contents of a SIMD register to a scalar. On x86 this instruction is a noop." } ;
 248
 249 HELP: %write-barrier
 250 { $values
 251   { "src" "a register symbol" }
 252   { "slot" "a register symbol" }
 253   { "scale" integer }
 254   { "tag" integer }
 255   { "temp1" "a register symbol" }
 256   { "temp2" "a register symbol" }
 257 }
 258 { $description "Generates code for the " { $link ##write-barrier } " instruction." }
 259 { $examples { $unchecked-example $[ ex-%write-barrier ] } } ;
 260
 261 HELP: test-instruction?
 262 { $values { "?" boolean } }
 263 { $description "Does the current architecture have a test instruction? Used on x86 to rewrite some " { $link CMP } " instructions to less expensive " { $link TEST } "s." } ;
 264
 265 HELP: fused-unboxing?
 266 { $values { "?" boolean } }
 267 { $description "Whether this architecture support " { $link %load-float } ", " { $link %load-double } ", and " { $link %load-vector } "." } ;
 268
 269 HELP: return-regs
 270 { $values { "regs" assoc } }
 271 { $description "What registers that will be used for function return values of which class." } ;
 272
 273 HELP: return-struct-in-registers?
 274 { $values { "c-type" class } { "?" boolean } }
 275 { $description "Whether the size of the struct is so small that it will be returned in registers or not." } ;
 276
 277 HELP: stack-cleanup
 278 { $values
 279   { "stack-size" integer }
 280   { "return" "a c type" }
 281   { "abi" abi }
 282   { "n" integer }
 283 }
 284 { $description "Calculates how many bytes of stack space the caller of the procedure being constructed need to cleanup. For modern abi's the value is almost always 0." }
 285 { $examples
 286   { $unchecked-example
 287     "USING: cpu.architecture prettyprint ;"
 288     "20 void stdcall stack-cleanup ."
 289     "20"
 290   }
 291 } ;
 292
 293 HELP: gc-root-offset
 294 { $values { "spill-slot" spill-slot } { "n" integer } }
 295 { $description "Offset in the " { $link stack-frame } " for the word being constructed where the spill slot is located, in " { $link cell } " units." }
 296 { $see-also vm:gc-info } ;
 297
 298 ARTICLE: "cpu.architecture" "CPU architecture description model"
 299 "The " { $vocab-link "cpu.architecture" } " vocab contains generic words and hooks that serves as an api for the compiler towards the cpu architecture."
 300 $nl
 301 "Architecture support checks:"
 302 { $subsections
 303   complex-addressing?
 304   float-on-stack?
 305   float-right-align-on-stack?
 306   fused-unboxing?
 307   test-instruction?
 308 }
 309 "Control flow code emitters:"
 310 { $subsections %call %jump %jump-label %return }
 311 "Moving values around:"
 312 { $subsections %replace %replace-imm }
 313 "Register categories:"
 314 { $subsections machine-registers param-regs return-regs }
 315 "Representation metadata:"
 316 { $subsections
 317   narrow-vector-rep
 318   rep-component-type
 319   rep-length
 320   rep-size
 321   scalar-rep-of
 322   signed-rep
 323   widen-vector-rep
 324 }
 325 "Slot access:"
 326 { $subsections %write-barrier } ;