Docs: various more compiler-related docs

basis/bootstrap/image/image-docs.factor

@@ -1,4 +1,5 @@
-USING: help.markup help.syntax io io.files io.pathnames strings ;
+USING: bootstrap.image.private help.markup help.syntax io io.files
+io.pathnames quotations strings words ;
 IN: bootstrap.image
 
 ARTICLE: "bootstrap.image" "Bootstrapping new images"
@@ -13,8 +14,18 @@ $nl
 
 ABOUT: "bootstrap.image"
 
+HELP: architecture
+{ $var-description "Bootstrap architecture name" } ;
+
+HELP: bootstrap-startup-quot
+{ $var-description "This image's startup quotation or " { $link f } ". "} ;
+
+HELP: define-sub-primitive
+{ $values { "quot" quotation } { "word" word } }
+{ $description "Defines a sub primitive by running the quotation which is supposed to output assembler code. The word is then used to call the assembly." } ;
+
 HELP: make-image
 { $values { "arch" string } }
 { $description "Creates a bootstrap image from sources, where " { $snippet "architecture" } " is one of the following:"
-{ $code "x86.32" "unix-x86.64" "windows-x86.64" "linux-ppc" }
+{ $code "\"x86.32\"" "\"unix-x86.64\"" "\"windows-x86.64\"" "\"linux-ppc\"" }
 "The new image file is written to the " { $link resource-path } " and is named " { $snippet "boot." { $emphasis "architecture" } ".image" } "." } ;

basis/bootstrap/image/image.factor

@@ -149,7 +149,6 @@ SYMBOL: bootstrapping-image
 ! Image output format
 SYMBOL: big-endian
 
-! Bootstrap architecture name
 SYMBOL: architecture
 
 RESET

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

@@ -1,6 +1,15 @@
-USING: compiler.codegen.relocation help.markup help.syntax strings ;
+USING: byte-arrays compiler.codegen.relocation help.markup help.syntax
+strings ;
 IN: compiler.codegen.labels
 
+HELP: binary-literal-table
+{ $var-description "A relocation table used during code generation to keep track of binary relocations. Binary literals are stored at the end of the generated assembly code on the code heap." } ;
+
+HELP: rel-binary-literal
+{ $values { "literal" byte-array } { "class" "relocation class" } }
+{ $description "Adds a binary literal to the relocation table." }
+{ $see-also binary-literal-table } ;
+
 HELP: define-label
 { $values { "name" string } }
 { $description "Defines a new label with the given name. The " { $slot "offset" } " slot is filled in later." } ;

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

@@ -20,6 +20,10 @@ HELP: add-literal
 HELP: init-relocation
 { $description "Initializes the dynamic variables related to code relocation." } ;
 
+HELP: rel-decks-offset
+{ $values { "class" "a relocation class" } }
+{ $description "Adds a decks offset relocation. It is used for marking cards when emitting write barriers." } ;
+
 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." } ;
@@ -42,6 +46,9 @@ HELP: compiled-offset
 } ;
 
 ARTICLE: "compiler.codegen.relocation" "Relocatable VM objects"
-"The " { $vocab-link "compiler.codegen.relocation" } " deals with assigning memory addresses to VM objects, such as the card table. Those objects have different addresses during each execution which is why they are \"relocatable\". The vocab is shared by the optimizing and non-optimizing compiler." ;
+"The " { $vocab-link "compiler.codegen.relocation" } " deals with assigning memory addresses to VM objects, such as the card table. Those objects have different addresses during each execution which is why they are \"relocatable\". The vocab is shared by the optimizing and non-optimizing compiler."
+$nl
+"Adding relocations:"
+{ $subsections add-relocation rel-decks-offset rel-safepoint } ;
 
 ABOUT: "compiler.codegen.relocation"

basis/compiler/tree/tree-docs.factor

@@ -1,5 +1,6 @@
-USING: assocs help.markup help.syntax kernel quotations sequences
-stack-checker.alien stack-checker.values stack-checker.visitor words ;
+USING: assocs help.markup help.syntax kernel kernel.private quotations
+sequences stack-checker.alien stack-checker.values
+stack-checker.visitor words ;
 IN: compiler.tree
 
 HELP: node
@@ -20,10 +21,15 @@ HELP: #call
     { { $slot "word" } { "The " { $link word } " to call." } }
     { { $slot "in-d" } { "Sequence of input variables to the call. The items are ordered from top to bottom of the stack." } }
     { { $slot "out-d" } { "Output values of the call." } }
-    { { $slot "info" } { "An assoc that contains various annotations for the words input and output values. It is set during the propagation pass of the optimizer." } }
+    { { $slot "method" } { "If the called word is generic and inlined here, then 'method' contains the inlined " { $link quotation } "." } }
+    { { $slot "body" } { "If the called word is generic and inlined, then 'body' is a sequence of SSA nodes built from the inlined method." } }
+    { { $slot "info" } { "If the called word is generic and inlined, then the info slot contains an assoc of value infos for the body of the inlined generic. It is set during the propagation pass of the optimizer." } }
   }
 } ;
 
+HELP: #declare
+{ $class-description "SSA tree node emitted when " { $link declare } " declarations are encountered." } ;
+
 HELP: #introduce
 { $class-description "SSA tree node that puts an input value from the \"outside\" on the stack. It is used to \"introduce\" data stack parameter whenever they are needed. It has the following slots:"
   { $table
@@ -58,3 +64,13 @@ HELP: #if
 HELP: node,
 { $values { "node" node } }
 { $description "Emits a node to the " { $link stack-visitor } " variable." } ;
+
+ARTICLE: "compiler.tree" "High-level optimizer operating on lexical tree SSA IR"
+"Node types:"
+{ $subsections
+  #call
+  #declare
+  #shuffle
+} ;
+
+ABOUT: "compiler.tree"

basis/compiler/tree/tree.factor

@@ -4,8 +4,6 @@ USING: accessors arrays assocs kernel namespaces sequences
 stack-checker.visitor vectors ;
 IN: compiler.tree
 
-! High-level tree SSA form.
-
 TUPLE: node < identity-tuple ;
 
 TUPLE: #introduce < node out-d ;

basis/cpu/architecture/architecture-docs.factor

@@ -151,6 +151,10 @@ HELP: %copy
 { $description "Emits code copying a value from a register, arbitrary memory location or " { $link spill-slot } " to a destination." }
 { $examples { $unchecked-example $[ ex-%copy ] } } ;
 
+HELP: %dispatch
+{ $values { "src" "a register symbol" } { "temp" "a register symbol" } }
+{ $description "Code emitter for the " { $link ##dispatch } " instruction." } ;
+
 HELP: %horizontal-add-vector
 { $values
   { "dst" "destination register symbol" }
@@ -197,7 +201,8 @@ HELP: %local-allot
   { "align" "alignment" }
   { "offset" "where to allocate the data, relative to the stack register" }
 }
-{ $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." } ;
+{ $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." }
+{ $see-also ##local-allot } ;
 
 HELP: %replace-imm
 { $values

basis/io/ports/ports-docs.factor

@@ -41,6 +41,10 @@ ABOUT: "io.ports"
 HELP: port
 { $class-description "Instances of this class present a blocking stream interface on top of an underlying non-blocking I/O system, giving the illusion of blocking by yielding the thread which is waiting for input or output." } ;
 
+HELP: shutdown
+{ $values { "handle" "a port handle" } }
+{ $description "Called when a port is being disposed." } ;
+
 HELP: input-port
 { $class-description "The class of ports implementing the input stream protocol." } ;
 

basis/math/partial-dispatch/partial-dispatch-docs.factor

@@ -0,0 +1,16 @@
+USING: help.markup help.syntax math sequences words ;
+IN: math.partial-dispatch
+
+HELP: define-integer-ops
+{ $values { "word" word } { "fix-word" word } { "big-word" word } }
+{ $description "Defines an integral arithmetic operation. 'word' is the generic word, 'fix-word' the word to dispatch on if the last argument is a " { $link fixnum } " and 'big-word' thew ord if it is a " { $link bignum } "." } ;
+
+HELP: derived-ops
+{ $values { "word" word } { "words" sequence } }
+{ $description "Lists all derived words of the given word, including the word itself." } ;
+
+ARTICLE: "math.partial-dispatch"
+"Partially-dispatched math operations, used by the compiler"
+"Partially-dispatched math operations" ;
+
+ABOUT: "math.partial-dispatch"

basis/math/vectors/simd/intrinsics/intrinsics-docs.factor

@@ -0,0 +1,11 @@
+USING: help.markup help.syntax sequences ;
+IN: math.vectors.simd.intrinsics
+
+HELP: (simd-select)
+{ $description "Word which implements " { $link nth } " for SIMD vectors." }
+{ $examples
+  { $unchecked-example
+    "float-4{ 3 4 9 1 } underlying>> 2 float-4-rep (simd-select)"
+    "9.0"
+  }
+} ;

basis/threads/threads-docs.factor

@@ -73,10 +73,34 @@ ABOUT: "threads"
 HELP: thread
 { $class-description "A thread. The slots are as follows:"
     { $list
-        { { $snippet "id" } " - a unique identifier assigned to each thread." }
-        { { $snippet "name" } " - the name passed to " { $link spawn } "." }
-        { { $snippet "quot" } " - the initial quotation passed to " { $link spawn } "." }
-        { { $snippet "status" } " - a " { $link string } " indicating what the thread is waiting for, or " { $link f } ". This slot is intended to be used for debugging purposes." }
+      {
+          { $snippet "id" }
+          " - a unique identifier assigned to each thread."
+      }
+      {
+          { $snippet "exit-handler" }
+          " - a " { $link quotation } " run when the thread is being stopped."
+      }
+      {
+          { $snippet "name" }
+          " - the name passed to " { $link spawn } "."
+      }
+      {
+          { $snippet "quot" }
+          " - the initial quotation passed to " { $link spawn } "."
+      }
+      {
+          { $snippet "runnable" }
+          " - whether the thread is runnable. Initially it is, " { $link f } "."
+      }
+      {
+          { $snippet "status" }
+          " - a " { $link string } " indicating what the thread is waiting for, or " { $link f } ". This slot is intended to be used for debugging purposes."
+      }
+      {
+          { $snippet "context" }
+          " - a " { $link box } " holding an alien pointer to the threads " { $link context } " object."
+      }
     }
 } ;
 

core/compiler/units/units-docs.factor

@@ -1,5 +1,5 @@
 USING: definitions help.markup help.syntax kernel parser
-quotations source-files stack-checker.errors words ;
+quotations sequences source-files stack-checker.errors words ;
 IN: compiler.units
 
 ARTICLE: "compilation-units-internals" "Compilation units internals"
@@ -73,6 +73,10 @@ HELP: recompile
 { $values { "words" "a sequence of words" } { "alist" "an association list mapping words to compiled definitions" } }
 { $contract "Internal word which compiles words. Called at the end of " { $link with-compilation-unit } "." } ;
 
+HELP: to-recompile
+{ $values { "words" sequence } }
+{ $description "Sequence of words that will be recompiled by the compilation unit." } ;
+
 HELP: no-compilation-unit
 { $values { "word" word } }
 { $description "Throws a " { $link no-compilation-unit } " error." }

core/kernel/kernel-docs.factor

@@ -63,6 +63,9 @@ HELP: build
 { $values { "n" integer } }
 { $description "The current build number. Factor increments this number whenever a new boot image is created." } ;
 
+HELP: leaf-signal-handler
+{ $description "A word called by the VM when a VM error occurs." } ;
+
 HELP: hashcode*
 { $values { "depth" integer } { "obj" object } { "code" fixnum } }
 { $contract "Outputs the hashcode of an object. The hashcode operation must satisfy the following properties:"