Docs: more compiler-related documentation

basis/compiler/cfg/cfg-docs.factor

@@ -1,5 +1,6 @@
-USING: compiler.cfg compiler.cfg.instructions compiler.cfg.rpo help.markup
-help.syntax namespaces sequences vectors words ;
+USING: compiler.cfg compiler.cfg.instructions compiler.cfg.rpo
+compiler.cfg.stack-frame help.markup help.syntax namespaces sequences vectors
+words ;
 IN: compiler.cfg
 
 HELP: basic-block
@@ -22,6 +23,7 @@ HELP: cfg
     { { $slot "entry" } { "Initial " { $link basic-block } " of the graph." } }
     { { $slot "word" } { "The " { $link word } " the cfg is produced from." } }
     { { $slot "post-order" } { "The blocks of the cfg in a post order traversal " { $link sequence } "." } }
+    { { $slot "stack-frame" } { { $link stack-frame } " of the cfg." } }
   }
 }
 { $see-also post-order } ;

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

@@ -1,5 +1,5 @@
-USING: compiler.cfg help.markup help.syntax kernel layouts slots.private
-classes ;
+USING: classes compiler.cfg help.markup help.syntax kernel layouts
+slots.private ;
 IN: compiler.cfg.instructions
 
 HELP: new-insn
@@ -33,7 +33,8 @@ HELP: ##inc-d
 
 HELP: ##prologue
 { $class-description
-  "An instruction for generating the prologue for a cfg." } ;
+  "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." }
+{ $see-also ##epilogue } ;
 
 HELP: ##alien-invoke
 { $class-description
@@ -47,6 +48,11 @@ HELP: ##alien-invoke
   }
 } ;
 
+HELP: ##call
+{ $class-description
+  "An instruction for calling a Factor word."
+} ;
+
 HELP: ##set-slot
 { $class-description
   "An instruction for the non-primitive, non-immediate variant of " { $link set-slot } ". It has the following slots:"
@@ -66,8 +72,19 @@ HELP: ##replace-imm
 HELP: ##replace
 { $class-description
   "Copies a value from a machine register to a stack location." }
-{ $see-also ##peek ##replace-imm } ;
+  { $see-also ##peek ##replace-imm } ;
 
+HELP: ##write-barrier
+{ $class-description
+  "An instruction for inserting a write barrier. This instruction is almost always inserted after a " { $link ##set-slot } " instruction. It has the following slots:"
+  { $table
+    { { $slot "src" } { "Object which the writer barrier refers." } }
+    { { $slot "slot" } { "Slot index of the object." } }
+    { { $slot "tag" } { "Type tag for obj." } }
+    { { $slot "temp1" } { "First temporary register to clobber." } }
+    { { $slot "temp2" } { "Second temporary register to clobber." } }
+  }
+} ;
 
 HELP: ##jump
 { $class-description
@@ -111,3 +128,6 @@ HELP: ##copy
 
 HELP: ##compare-integer
 { $class-description "This instruction is emitted for integer comparisons." } ;
+
+HELP: gc-map-insn
+{ $class-description "Union class of all instructions that contain subroutine calls to functions which allocate memory." } ;

basis/compiler/cfg/intrinsics/slots/slots-docs.factor

@@ -1,5 +1,6 @@
-USING: classes classes.builtin compiler.tree compiler.tree.propagation.info
-help.markup help.syntax math layouts sequences slots.private words ;
+USING: classes classes.builtin compiler.cfg.instructions compiler.tree
+compiler.tree.propagation.info help.markup help.syntax math layouts sequences
+slots.private words ;
 IN: compiler.cfg.intrinsics.slots
 
 HELP: class-tag
@@ -32,7 +33,8 @@ HELP: value-tag
 HELP: emit-write-barrier?
 { $values { "infos" "a " { $link sequence } " of " { $link value-info-state } " tuples." } { "?" "true or false" } }
 { $description
-  "Whether a given call to " { $link set-slot } " requires a write barrier to be emitted or not. Write barriers are always needed except when the element to set in the slot is known by the compiler to be " { $link immediate } "." } ;
+  "Whether a given call to " { $link set-slot } " requires a write barrier to be emitted or not. Write barriers are always needed except when the element to set in the slot is known by the compiler to be " { $link immediate } "." }
+{ $see-also ##write-barrier } ;
 
 HELP: emit-set-slot
 { $values { "node" node } }

basis/compiler/cfg/save-contexts/save-contexts-docs.factor

@@ -3,8 +3,14 @@ IN: compiler.cfg.save-contexts
 
 HELP: insert-save-contexts
 { $values { "cfg" cfg } { "cfg'" cfg } }
-{ $description "Inserts " { $link ##save-context } " instructions in each " { $link basic-block } " in the cfg that needs them. Save contexts are needed after instructions that modify the context, or instructions that read parameter registers." } ;
+{ $description "Inserts " { $link ##save-context } " instructions in each " { $link basic-block } " in the cfg that needs them. Save contexts are needed after instructions that modify the context, or instructions that read parameter registers." }
+{ $see-also needs-save-context? } ;
 
 HELP: bb-needs-save-context?
 { $values { "bb" basic-block } { "?" "a boolean" } }
-{ $description "Whether to insert a " { $link ##save-context } " instruction in the block or not." } ;
+{ $description "Whether to insert a " { $link ##save-context } " instruction in the block or not." }
+{ $see-also needs-save-context? } ;
+
+HELP: needs-save-context?
+{ $description "Whether the given instruction needs to be preceeded by a " { $link ##save-context } " instruction or not. Only instructions that can allocate memory mandates save contexts." }
+{ $see-also gc-map-insn } ;

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

@@ -12,3 +12,11 @@ HELP: adjust-d
 HELP: rs-store
 { $values { "vregs" "a " { $link sequence } " of vregs." } }
 { $description "Stores one or more virtual register values on the retain stack. This modifies the " { $link current-height } " dynamic variable." } ;
+
+HELP: 2inputs
+{ $values { "vreg1" "a vreg" } { "vreg2" "a vreg" } }
+{ $description "Lifts the two topmost values from the datastack and stores them in virtual registers. The datastacks height is adjusted afterwards." } ;
+
+HELP: 3inputs
+{ $values { "vreg1" "a vreg" } { "vreg2" "a vreg" } { "vreg2" "a vreg" } }
+{ $description "Lifts the three topmost values from the datastack and stores them in virtual registers. The datastacks height is adjusted afterwards." } ;

basis/compiler/codegen/relocation/relocation-docs.factor

@@ -3,7 +3,8 @@ help.markup help.syntax make strings ;
 IN: compiler.codegen.relocation
 
 HELP: relocation-table
-{ $description "A " { $link byte-vector } " holding the relocations for the current compilation. Each sequence of four bytes in the vector represents one relocation." } ;
+{ $description "A " { $link byte-vector } " holding the relocations for the current compilation. Each sequence of four bytes in the vector represents one relocation." }
+{ $see-also init-relocation } ;
 
 HELP: add-relocation
 { $values
@@ -16,6 +17,9 @@ HELP: add-literal
 { $values { "obj" "a symbol" } }
 { $description "Adds a symbol to the " { $link literal-table } "." } ;
 
+HELP: init-relocation
+{ $description "Initializes the dynamic variables related to code relocation." } ;
+
 HELP: rel-safepoint
 { $values { "class" "a relocation class" } }
 { $description "Adds a safe point to the " { $link relocation-table } " for the current code offset. This word is used by the " { $link %safepoint } " generator." } ;

basis/compiler/compiler-docs.factor

@@ -63,6 +63,10 @@ HELP: backend
 { $description "The second last step of the compilation process. A word and its SSA tree is taken as input and a " { $link cfg } " is built from which assembly code is generated." }
 { $see-also generate } ;
 
+HELP: compiled
+{ $description { "An " { $link assoc } " used by the optimizing compiler for intermediate storage of generated code. The keys are the labels to the CFG:s and the values the generated code as given by the " { $link generate } " word." } } ;
+
+
 HELP: compile-word
 { $values { "word" word } }
 { $description "Compile a single word." }

basis/cpu/architecture/architecture-docs.factor

@@ -30,6 +30,18 @@ USING: cpu.architecture make ;
 0000000002270cce: 4883c807        or rax, 0x7
 0000000002270cd2: 48830130        add qword [rcx], 0x30
 ;
+
+STRING: ex-%context
+USING: cpu.architecture make ;
+[ EAX %context ] B{ } make disassemble
+00000000010f5ed0: 418b4500  mov eax, [r13]
+;
+
+STRING: ex-%safepoint
+USING: cpu.architecture make ;
+init-relocation [ %safepoint ] B{ } make disassemble
+00000000010b05a0: 890500000000  mov [rip], eax
+;
 >>
 
 HELP: signed-rep
@@ -75,7 +87,17 @@ HELP: %box-alien
 
 HELP: %context
 { $values { "dst" "a register symbol" } }
-{ $description "Emits machine code for putting a pointer to the context field of the " { $link vm } " in a register." } ;
+{ $description "Emits machine code for putting a pointer to the context field of the " { $link vm } " in a register." }
+{ $examples { $unchecked-example $[ ex-%context ] } } ;
+
+HELP: %safepoint
+{ $description "Emits a safe point to the current code sequence being generated." }
+{ $examples { $unchecked-example $[ ex-%safepoint ] } } ;
+
+HELP: %save-context
+{ $values { "temp1" "a register symbol" } { "temp2" "a register symbol" } }
+{ $description "Emits machine code for saving pointers to the callstack, datastack and retainstack in the current context field struct." } ;
+
 
 HELP: %allot
 { $values

basis/cpu/x86/x86-docs.factor

@@ -26,6 +26,10 @@ HELP: (%inc)
   }
 } ;
 
+HELP: decr-stack-reg
+{ $values { "n" number } }
+{ $description "Emits an instruction for decrementing the stack register the given number of bytes." } ;
+
 HELP: load-zone-offset
 { $values { "nursery-ptr" "a register symbol" } }
 { $description