From 769ca5550f944307efb6a3f872c6e6a9de418d2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= Date: Fri, 18 Jul 2014 10:47:08 +0200 Subject: [PATCH] compiler.cfg.*: docs for compiler words --- .../cfg/builder/alien/alien-docs.factor | 19 +++++++- .../builder/alien/boxing/boxing-docs.factor | 17 +++++++ .../cfg/builder/blocks/blocks-docs.factor | 45 ++++++++++++++++--- .../compiler/cfg/builder/builder-docs.factor | 5 ++- basis/compiler/cfg/cfg-docs.factor | 5 ++- .../cfg/instructions/instructions-docs.factor | 10 ++++- .../cfg/stacks/local/local-docs.factor | 9 +++- 7 files changed, 96 insertions(+), 14 deletions(-) diff --git a/basis/compiler/cfg/builder/alien/alien-docs.factor b/basis/compiler/cfg/builder/alien/alien-docs.factor index 0dee4a3d81..0899fd4918 100644 --- a/basis/compiler/cfg/builder/alien/alien-docs.factor +++ b/basis/compiler/cfg/builder/alien/alien-docs.factor @@ -1,6 +1,21 @@ -USING: help.markup help.syntax make stack-checker.alien ; +USING: help.markup help.syntax literals make multiline stack-checker.alien ; IN: compiler.cfg.builder.alien +<< +STRING: ex-caller-return +USING: compiler.cfg.builder.alien make prettyprint ; +[ + T{ ##alien-invoke { reg-outputs { { 1 int-rep RAX } } } } , + T{ alien-invoke-params { return pointer: void } } caller-return +] { } make . +{ + T{ ##alien-invoke { reg-outputs { { 1 int-rep RAX } } } } + T{ ##box-alien { dst 116 } { src 1 } { temp 115 } } +} +; +>> + HELP: caller-return { $values { "params" alien-node-params } } -{ $description "If the last alien call returns a value, then this word will emit an instruction to the current sequence being constructed by " { $link make } " which boxes it." } ; +{ $description "If the last alien call returns a value, then this word will emit an instruction to the current sequence being constructed by " { $link make } " that boxes it." } +{ $examples { $unchecked-example $[ ex-caller-return ] } } ; diff --git a/basis/compiler/cfg/builder/alien/boxing/boxing-docs.factor b/basis/compiler/cfg/builder/alien/boxing/boxing-docs.factor index 8305754e66..742ed07f6e 100644 --- a/basis/compiler/cfg/builder/alien/boxing/boxing-docs.factor +++ b/basis/compiler/cfg/builder/alien/boxing/boxing-docs.factor @@ -19,6 +19,23 @@ HELP: box } { $see-also ##box-alien } ; +HELP: box-return +{ $values + { "vregs" "vregs that contains the return value of the alien call" } + { "reps" "representations of the vregs" } + { "c-type" abstract-c-type } + { "dst" "vreg in which the boxed value, or a reference to it, will be placed" } +} +{ $description "Emits instructions for boxing the return value from an alien function call." } +{ $examples + { $unchecked-example + "USING: compiler.cfg.builder.alien.boxing kernel make prettyprint ;" + "[ { 10 } { tagged-rep } int base-type box-return drop ] { } make ." + "{ T{ ##convert-integer { dst 118 } { src 10 } { c-type int } } }" + } +} +{ $see-also ##box-alien } ; + HELP: stack-size { $values { "c-type" c-type } diff --git a/basis/compiler/cfg/builder/blocks/blocks-docs.factor b/basis/compiler/cfg/builder/blocks/blocks-docs.factor index c7e8ff7ee6..b8cb49a224 100644 --- a/basis/compiler/cfg/builder/blocks/blocks-docs.factor +++ b/basis/compiler/cfg/builder/blocks/blocks-docs.factor @@ -1,15 +1,37 @@ -USING: compiler.cfg compiler.tree help.markup help.syntax math ; +USING: compiler.cfg compiler.tree help.markup help.syntax literals math +multiline quotations ; IN: compiler.cfg.builder.blocks -HELP: initial-basic-block -{ $description "Creates an initial empty " { $link basic-block } " and stores it in the basic-block dynamic variable." } ; +<< +STRING: ex-emit-trivial-block +USING: compiler.cfg.builder.blocks prettyprint ; +initial-basic-block [ [ gensym ##call, ] emit-trivial-block ] { } make drop +basic-block get . +T{ basic-block + { id 2040412 } + { successors + V{ + T{ basic-block + { id 2040413 } + { instructions + V{ + T{ ##call { word ( gensym ) } } + T{ ##branch } + } + } + { successors + V{ T{ basic-block { id 2040414 } } } + } + } + } + } +} +; +>> HELP: begin-basic-block { $description "Terminates the current block and initializes a new " { $link basic-block } " to begin outputting instructions to. The new block is included in the old blocks " { $slot "successors" } "." } ; -HELP: make-kill-block -{ $description "Marks the current " { $link basic-block } " being processed as a kill block." } ; - HELP: call-height { $values { "#call" #call } { "n" number } } { $description "Calculates how many items a " { $link #call } " will add or remove from the data stack." } @@ -20,3 +42,14 @@ HELP: call-height "-2" } } ; + +HELP: emit-trivial-block +{ $values { "quot" quotation } } +{ $description "Combinator that emits a trivial block, constructed by calling the supplied quotation." } +{ $examples { $unchecked-example $[ ex-emit-trivial-block ] } } ; + +HELP: initial-basic-block +{ $description "Creates an initial empty " { $link basic-block } " and stores it in the basic-block dynamic variable." } ; + +HELP: make-kill-block +{ $description "Marks the current " { $link basic-block } " being processed as a kill block." } ; diff --git a/basis/compiler/cfg/builder/builder-docs.factor b/basis/compiler/cfg/builder/builder-docs.factor index 7700636c8e..9f0671388b 100644 --- a/basis/compiler/cfg/builder/builder-docs.factor +++ b/basis/compiler/cfg/builder/builder-docs.factor @@ -5,7 +5,8 @@ IN: compiler.cfg.builder << STRING: ex-emit-call -USING: compiler.cfg.builder kernel make prettyprint ; +USING: compiler.cfg.builder compiler.cfg.builder.blocks compiler.cfg.stacks +kernel make prettyprint ; begin-stack-analysis initial-basic-block \ dummy 3 [ emit-call ] { } make drop current-height basic-block [ get . ] bi@ . T{ current-height { d 3 } } @@ -59,7 +60,7 @@ HELP: emit-call HELP: emit-node { $values { "node" node } } -{ $description "Emits some kind of code for the node." } ; +{ $description "Emits CFG instructions for the given SSA node." } ; HELP: trivial-branch? { $values diff --git a/basis/compiler/cfg/cfg-docs.factor b/basis/compiler/cfg/cfg-docs.factor index 3b35e183a4..46712a6dcd 100644 --- a/basis/compiler/cfg/cfg-docs.factor +++ b/basis/compiler/cfg/cfg-docs.factor @@ -5,9 +5,10 @@ IN: compiler.cfg HELP: basic-block { $class-description - "Factors representation of a basic block in the cfg. A basic block is a sequence of instructions that always are executed sequentially and doesn't contain any branching. It has the following slots:" + "Factors representation of a basic block in the Call Flow Graph (CFG). A basic block is a sequence of instructions that always are executed sequentially and doesn't contain any branching. It has the following slots:" { $table { { $slot "successors" } { "A " { $link vector } " of basic blocks that may be executed directly after this block. Most blocks only have one successor but a block that checks where an if-condition should branch to would have two for example." } } + { { $slot "predecessors" } { "The opposite of successors -- a " { $link vector } " of basic blocks from which the execution may have arrived into this block." } } { { $slot "instructions" } { "A " { $link vector } " of " { $link insn } " tuples which form the instructions of the basic block." } } } } ; @@ -20,7 +21,7 @@ HELP: cfg { $class-description "Call flow graph. It has the following slots:" { $table - { { $slot "entry" } { "Initial " { $link basic-block } " of the graph." } } + { { $slot "entry" } { "Root " { $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." } } diff --git a/basis/compiler/cfg/instructions/instructions-docs.factor b/basis/compiler/cfg/instructions/instructions-docs.factor index 981fff4626..e9f88e8617 100644 --- a/basis/compiler/cfg/instructions/instructions-docs.factor +++ b/basis/compiler/cfg/instructions/instructions-docs.factor @@ -42,7 +42,10 @@ HELP: ##alien-invoke { $table { { $slot "reg-inputs" } { "Registers to use for the arguments to the function call." } } { { $slot "stack-inputs" } { "Stack slots used for the arguments to the function call. Only used if all register arguments are already filled." } } - { { $slot "reg-outputs" } { "Register that wil contain the return value of the function call if any." } } + { + { $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 "symbols" } { "Name of the function to call." } } { { $slot "dll" } { "A dll handle." } } } @@ -74,6 +77,11 @@ HELP: ##replace "Copies a value from a machine register to a stack location." } { $see-also ##peek ##replace-imm } ; +HELP: ##box-alien +{ $class-description + "An instruction for boxing an alien value." +} ; + 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:" diff --git a/basis/compiler/cfg/stacks/local/local-docs.factor b/basis/compiler/cfg/stacks/local/local-docs.factor index 8fff7d90c0..dd4028178a 100644 --- a/basis/compiler/cfg/stacks/local/local-docs.factor +++ b/basis/compiler/cfg/stacks/local/local-docs.factor @@ -2,7 +2,14 @@ USING: compiler.cfg compiler.cfg.registers help.markup help.syntax ; IN: compiler.cfg.stacks.local HELP: current-height -{ $class-description "A tuple used to keep track of the heights of the data and retain stacks in a " { $link basic-block } "." } ; +{ $class-description "A tuple used to keep track of the heights of the data and retain stacks in a " { $link basic-block } " The idea is that if the stack change instructions are tracked, then multiple changes can be folded into one. It has the following slots:" + { $table + { { $slot "d" } { "Current datastack height." } } + { { $slot "r" } { "Current retainstack height." } } + { { $slot "emit-d" } { "Queued up datastack height change." } } + { { $slot "emit-r" } { "Queued up retainstack height change." } } + } +} ; HELP: translate-local-loc { $values { "loc" loc } { "loc'" loc } }