steve
/
factor
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

compiler.cfg.*: compiler doc updates

char-rename
Björn Lindqvist 2016-09-01 02:16:30 +02:00
parent f7542e95a9
commit 26d53f9019
7 changed files with 52 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
basis/compiler/cfg/builder/blocks/blocks-docs.factor
View File

@ -76,7 +76,7 @@ HELP: end-branch
HELP: set-basic-block
{ $values { "basic-block" basic-block } }
{ $description "Sets the given blocks as the current one by storing it in the basic-block dynamic variable. If it has any " { $slot "instructions" } " the current " { $link building } " is set to those." } ;
{ $description "Sets the given blocks as the current one. If it has any " { $slot "instructions" } " the current " { $link building } " is set to those." } ;
HELP: with-branch
{ $values

20
basis/compiler/cfg/builder/builder-docs.factor
View File

@ -37,11 +37,7 @@ T{ basic-block
STRING: ex-make-input-map
USING: compiler.cfg.builder prettyprint ;
T{ #shuffle { in-d { 37 81 92 } } } make-input-map .
H{
{ 81 T{ ds-loc { n 1 } } }
{ 37 T{ ds-loc { n 2 } } }
{ 92 T{ ds-loc } }
}
{ { 37 D: 2 } { 81 D: 1 } { 92 D: 0 } }
;
>>
@ -109,7 +105,18 @@ HELP: end-word
HELP: height-changes
{ $values { "#shuffle" #shuffle } { "height-changes" sequence } }
{ $description "Returns a two-tuple which represents how much the " { $link #shuffle } " node increases or decreases the data and retainstacks." } ;
{ $description "Returns a two-tuple which represents how much the " { $link #shuffle } " node increases or decreases the data and retainstacks." }
{ $examples
{ $example
"USING: compiler.cfg.builder compiler.tree prettyprint ;"
"T{ #shuffle { in-d { 37 81 92 } } { out-d { 20 } } } height-changes ."
"{ -2 0 }"
}
} ;
HELP: out-vregs/stack
{ $values { "#shuffle" #shuffle } { "seq" sequence } }
{ $description "Returns a sequence of what vregs are on which stack locations after the shuffle instruction." } ;
HELP: trivial-branch?
{ $values
@ -172,6 +179,7 @@ $nl
{
$subsections
height-changes
out-vregs/stack
} ;
ABOUT: "compiler.cfg.builder"

19
basis/compiler/cfg/instructions/instructions-docs.factor
View File

@ -10,6 +10,10 @@ HELP: ##alien-invoke
{ $class-description
"An instruction for calling a function in a dynamically linked library. It has the following slots:"
{ $table
{
{ $slot "dead-outputs" }
{ "A sequence of return values from the function that the compiler.cfg.dce pass has figured out are not used." }
}
{
{ $slot "reg-inputs" }
{ "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." }
@ -22,14 +26,18 @@ HELP: ##alien-invoke
{ $slot "reg-outputs" }
{ "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." }
}
{
{ $slot "gc-map" }
{ "If the invoked C function calls Factor code which triggers a GC, then a " { $link gc-map } " is necessary to find the roots." }
}
{ { $slot "symbols" } { "Name of the function to call." } }
{ { $slot "dll" } { "A dll handle or " { $link f } "." } }
{
{ $slot "gc-map" }
{
"If the invoked C function calls Factor code which triggers a GC, then a "
{ $link gc-map }
" is necessary to find the roots."
}
}
}
"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 } " the first six arguments are passed in registers and then stack parameters are used for the remainder."
"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."
}
{ $see-also #alien-invoke %alien-invoke } ;
@ -286,6 +294,7 @@ HELP: ##store-memory-imm
{ $slot "offset" }
{ "Offset in bytes from the address to where the data should be written." }
}
{ { $slot "rep" } { "Value representation in the vector register." } }
{ { $slot "src" } { "Vreg that contains the item to set." } }
}
}

6
basis/compiler/cfg/intrinsics/misc/misc-docs.factor
View File

@ -1,4 +1,4 @@
USING: compiler.cfg compiler.tree help.markup help.syntax
USING: compiler.cfg compiler.tree help.markup help.syntax kernel
kernel.private ;
IN: compiler.cfg.intrinsics.misc
@ -9,3 +9,7 @@ HELP: emit-context-object
{ "block'" basic-block }
}
{ $description "Emits intrinsic code for a call to the " { $link context-object } " primitive." } ;
HELP: emit-eq
{ $values { "node" node } }
{ $description "Intrinsic emitter for the " { $link eq? } " word." } ;

1
basis/compiler/cfg/stack-frame/stack-frame-docs.factor
View File

@ -13,6 +13,7 @@ HELP: stack-frame
"The stack frame is also aligned to a 16 byte boundary. It has the following slots:"
{ $table
{ { $slot "total-size" } { "Total size of the stack frame." } }
{ { $slot "params" } { "Reserved parameter space." } }
{ { $slot "allot-area-base" } { "Base offset of the allocation area." } }
{ { $slot "allot-area-size" } { "Number of bytes requires for the allocation area." } }
{ { $slot "allot-area-align" } { "This slot is always at least " { $link cell } " bytes." } }

15
basis/compiler/cfg/stacks/stacks-docs.factor
View File

@ -8,8 +8,8 @@ HELP: ds-push
{ $description "Used when translating the " { $link #push } " SSA node to CFG form. The node pushes a literal value onto the data stack." } ;
HELP: begin-stack-analysis
{ $description "Initializes a set of variables related to stack analysis of Factor words." }
{ $see-also height-state } ;
{ $description "Initializes a set of variables related to global stack analysis of Factor words." }
{ $see-also begin-local-analysis height-state } ;
HELP: end-stack-analysis
{ $values { "cfg" cfg } }
@ -36,3 +36,14 @@ HELP: 2inputs
HELP: 3inputs
{ $values { "vreg1" "a vreg" } { "vreg2" "a vreg" } { "vreg3" "a vreg" } }
{ $description "Lifts the three topmost values from the datastack and stores them in virtual registers. The datastacks height is adjusted afterwards." } ;
ARTICLE: "compiler.cfg.stacks" "Generating instructions for accessing the data and retain stacks" "This vocab contains utility words for manipulating the analysis data and retain stacks."
$nl
"When nodes in the dataflow IR pushes or pops items from the stacks, instructions for performing those actions aren't immediately emitted. Instead the analysis stacks are manipulated and when the stack analysis phase is complete, optimal stack shuffling code is emitted. This way, exactly the same instructions are emitted for equivalent qutations such as [ dup drop ] and [ ]."
$nl
"Popping from the datastack:"
{ $subsections 2inputs 3inputs ds-drop }
"Pushing to the datastack:"
{ $subsections ds-push store-vregs } ;
ABOUT: "compiler.cfg.stacks"

8
basis/compiler/tree/tree-docs.factor
View File

@ -1,6 +1,6 @@
USING: alien assocs help.markup help.syntax kernel kernel.private quotations
sequences stack-checker.alien stack-checker.inlining stack-checker.values
stack-checker.visitor words ;
USING: alien assocs help.markup help.syntax kernel kernel.private
quotations sequences stack-checker.alien stack-checker.inlining
stack-checker.values stack-checker.visitor words ;
IN: compiler.tree
HELP: node
@ -14,7 +14,7 @@ HELP: #alien-invoke
{ $see-also alien-invoke } ;
HELP: #alien-callback
{ $class-description "SSA tree node that constructs an alien callback." } ;
{ $class-description "SSA tree node that constructs an alien callback. It is not a subclass of " { $link #alien-node } ". " } ;
HELP: #call
{ $class-description "SSA tree node that calls a word. It has the following slots:"