From 92a85ebe86f970a8505f12694380143115f4908b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= Date: Fri, 22 Apr 2016 12:56:46 +0200 Subject: [PATCH] compiler.*: more compiler docs --- basis/compiler/cfg/cfg-docs.factor | 7 ++--- .../allocation/allocation-docs.factor | 14 ++++++---- .../allocation/state/state-docs.factor | 2 +- .../cfg/linear-scan/linear-scan-docs.factor | 2 +- .../live-intervals/live-intervals-docs.factor | 15 ++++++++--- .../cfg/liveness/liveness-docs.factor | 27 ++++++++++++++++--- .../ssa/destruction/destruction-docs.factor | 2 ++ 7 files changed, 53 insertions(+), 16 deletions(-) diff --git a/basis/compiler/cfg/cfg-docs.factor b/basis/compiler/cfg/cfg-docs.factor index 33db978d4e..ae45d1c12c 100644 --- a/basis/compiler/cfg/cfg-docs.factor +++ b/basis/compiler/cfg/cfg-docs.factor @@ -1,6 +1,7 @@ USING: compiler.cfg.instructions compiler.cfg.rpo -compiler.cfg.stack-frame compiler.tree help.markup help.syntax kernel -math namespaces sequences vectors words ; +compiler.cfg.stack-frame compiler.tree cpu.x86.assembler.operands +help.markup help.syntax kernel math namespaces sequences vectors words +; IN: compiler.cfg HELP: basic-block @@ -33,7 +34,7 @@ HELP: cfg { { $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." } } - { { $slot "frame-pointer?" } { "Whether the cfg needs a frame pointer. Only cfgs generated for " { $link #alien-callback } " nodes does need it." } } + { { $slot "frame-pointer?" } { "Whether the cfg needs a frame pointer. Only cfgs generated for " { $link #alien-callback } " nodes does need it. If the slot is " { $link t } ", then the frame pointer register (" { $link RBP } " on x86.64 archs) will not be clobbered by register allocation. See " { $vocab-link "compiler.cfg.linear-scan" } " for details." } } } } { $see-also post-order } ; diff --git a/basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor b/basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor index 8c4f31c468..8146c9a5a0 100644 --- a/basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor +++ b/basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor @@ -1,7 +1,7 @@ -USING: assocs compiler.cfg compiler.cfg.instructions -compiler.cfg.linear-scan.allocation compiler.cfg.linear-scan.allocation.state -compiler.cfg.linear-scan.live-intervals cpu.architecture hashtables help.markup -help.syntax kernel sequences ; +USING: assocs compiler.cfg.instructions +compiler.cfg.linear-scan.allocation.state +compiler.cfg.linear-scan.live-intervals cpu.architecture hashtables +help.markup help.syntax kernel sequences ; IN: compiler.cfg.linear-scan.allocation HELP: (allocate-registers) @@ -25,7 +25,11 @@ HELP: assign-register { $description "Assigns a processor register to the live interval." } ; HELP: free-positions -{ $values { "registers" assoc } { "reg-class" { $or int-regs float-regs } } { "avail-registers" assoc } } +{ $values + { "registers" assoc } + { "reg-class" { $or int-regs float-regs } } + { "avail-registers" assoc } +} { $description "Creates an alist mapping registers to their desirability for allocation. 'avail-registers' is an alist and not a " { $link hashtable } " because the register allocation order is significant." } { $see-also register-status } ; diff --git a/basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor b/basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor index 00728c7521..b3c23bc51b 100644 --- a/basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor +++ b/basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor @@ -58,7 +58,7 @@ HELP: next-spill-slot { $description "Creates a new " { $link spill-slot } " of the given size and also allocates space in the " { $link cfg } " in the cfg for it." } ; HELP: progress -{ $var-description "Start index of current live interval. We ensure that all live intervals added to the unhandled set have a start index strictly greater than this one. This ensures that we can catch infinite loop situations. We also ensure that all live intervals added to the handled set have an end index strictly smaller than this one. This helps catch bugs." } +{ $var-description "Start index of current live interval. We ensure that all live intervals added to the unhandled set have a start index greater than or equal to this one. This ensures that we can catch infinite loop situations. We also ensure that all live intervals added to the handled set have an end index strictly smaller than this one. This helps catch bugs." } { $see-also check-handled check-unhandled } ; HELP: register-available? diff --git a/basis/compiler/cfg/linear-scan/linear-scan-docs.factor b/basis/compiler/cfg/linear-scan/linear-scan-docs.factor index fb1710f9b6..765a1de875 100644 --- a/basis/compiler/cfg/linear-scan/linear-scan-docs.factor +++ b/basis/compiler/cfg/linear-scan/linear-scan-docs.factor @@ -11,7 +11,7 @@ HELP: allocate-and-assign-registers HELP: linear-scan { $values { "cfg" cfg } } -{ $description "Entry point for the linear scan register alloation pass." } ; +{ $description "Entry point for the linear scan register allocation pass." } ; ARTICLE: "compiler.cfg.linear-scan" "Linear-scan register allocation" "Linear scan to assign physical registers. SSA liveness must have been computed already. It also spills registers that are live during gc calls." diff --git a/basis/compiler/cfg/linear-scan/live-intervals/live-intervals-docs.factor b/basis/compiler/cfg/linear-scan/live-intervals/live-intervals-docs.factor index 1c7058bf45..fe486c7cf1 100644 --- a/basis/compiler/cfg/linear-scan/live-intervals/live-intervals-docs.factor +++ b/basis/compiler/cfg/linear-scan/live-intervals/live-intervals-docs.factor @@ -32,9 +32,6 @@ HELP: compute-live-intervals { $description "Computes the live intervals and sync points of a cfg." } { $notes "The instructions must be numbered." } ; -HELP: hairy-clobber-insn -{ $class-description "Instructions that clobber registers. They receive inputs and produce outputs in spill slots." } ; - HELP: find-use { $values { "insn#" integer } @@ -50,6 +47,13 @@ HELP: finish-live-interval HELP: from { $var-description "An integer representing a sequence number one lower than all numbers in the currently processed block." } ; +HELP: hairy-clobber-insn +{ $class-description "Instructions that clobber registers. They receive inputs and produce outputs in spill slots." } ; + +HELP: insn>sync-point +{ $values { "insn" insn } { "sync-point/f" { $maybe sync-point } } } +{ $description "If the instruction clobbers arbitrary registers, then a sync point for it is emitted. Most instructions don't so then " { $link f } " is returned instead." } ; + HELP: intervals-intersect? { $values { "interval1" live-interval-state } @@ -127,6 +131,11 @@ $nl record-def record-use record-temp +} +"Sync point handling:" +{ $subsections + cfg>sync-points + insn>sync-point } ; diff --git a/basis/compiler/cfg/liveness/liveness-docs.factor b/basis/compiler/cfg/liveness/liveness-docs.factor index ce1c70fb0d..1e8df96e62 100644 --- a/basis/compiler/cfg/liveness/liveness-docs.factor +++ b/basis/compiler/cfg/liveness/liveness-docs.factor @@ -1,5 +1,6 @@ -USING: assocs compiler.cfg compiler.cfg.def-use compiler.cfg.instructions -compiler.cfg.representations hash-sets help.markup help.syntax kernel +USING: assocs compiler.cfg compiler.cfg.def-use +compiler.cfg.instructions compiler.cfg.representations +cpu.architecture hash-sets help.markup help.syntax kernel math sequences ; IN: compiler.cfg.liveness @@ -12,7 +13,7 @@ HELP: compute-live-sets { $description "Main entry point for vocab. Pass must only be run after representation selection. In this pass " { $slot "gc-roots" } " are set." } ; HELP: edge-live-ins -{ $var-description "Assoc mapping basic blocks to sequences of sets of vregs; each sequence is in correspondence with a predecessor." } ; +{ $var-description { $link assoc } " mapping basic blocks to sequences of sets of vregs; each sequence is in correspondence with a predecessor." } ; HELP: fill-gc-map { $values { "live-set" assoc } { "gc-map" gc-map } } @@ -50,6 +51,21 @@ HELP: lookup-base-pointer { $description "Tries to figure out what the base pointer for a vreg is. Can't use cache here because of infinite recursion inside the quotation passed to cache" } { $see-also base-pointers } ; +HELP: visit-gc-root +{ $values + { "vreg" integer } + { "derived-roots" assoc } + { "gc-roots" sequence } +} +{ $description "Handles a vreg that is live at a gc point. The vreg is handled in three ways depending on its representation:" + { $list + { "If it is " { $link tagged-rep } ", then the vreg contains a pointer to an object and it is added to the 'gc-roots' sequence." } + { "If it is " { $link int-rep } " and the vreg has a base pointer, then it is added to the 'derived-roots' assoc along with that base pointer." } + "Otherwise the vreg does not contain an object reference and nothing is done with it." + } +} +{ $see-also lookup-base-pointer } ; + ARTICLE: "compiler.cfg.liveness" "Liveness analysis" "Similar to http://en.wikipedia.org/wiki/Liveness_analysis, with three additions:" $nl @@ -63,6 +79,11 @@ $nl { $subsections live-in live-in? live-ins live-out live-out? live-outs +} +"Filling GC maps:" +{ $subsections + lookup-base-pointer + visit-gc-root } ; ABOUT: "compiler.cfg.liveness" diff --git a/basis/compiler/cfg/ssa/destruction/destruction-docs.factor b/basis/compiler/cfg/ssa/destruction/destruction-docs.factor index ac23165370..b19f894a99 100644 --- a/basis/compiler/cfg/ssa/destruction/destruction-docs.factor +++ b/basis/compiler/cfg/ssa/destruction/destruction-docs.factor @@ -12,6 +12,8 @@ HELP: destruct-ssa { $description "Main entry point for the SSA destruction compiler pass." } ; ARTICLE: "compiler.cfg.ssa.destruction" "SSA Destruction" +"SSA destruction compiler pass. It is preceeded by " { $vocab-link "compiler.cfg.save-contexts" } " and followed by " { $vocab-link "compiler.cfg.linear-scan" } "." +$nl "Because of the design of the register allocator, this pass has three peculiar properties." { $list { "Instead of renaming vreg usages in the CFG, a map from vregs to canonical representatives is computed. This allows the register allocator to use the original SSA names to get reaching definitions. See " { $link leader-map } "." }