From 0c2559ef6e533ae43b28fe80585397c6914410aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= Date: Sat, 9 May 2015 03:21:24 +0200 Subject: [PATCH] compiler.*: a bunch more compiler docs --- .../alias-analysis/alias-analysis-docs.factor | 65 +++++++++++++++++++ .../cfg/alias-analysis/alias-analysis.factor | 54 --------------- basis/compiler/cfg/cfg-docs.factor | 1 + .../cfg/gc-checks/gc-checks-docs.factor | 4 ++ basis/compiler/cfg/gc-checks/gc-checks.factor | 3 - .../call-effect/call-effect-docs.factor | 5 +- .../call-effect/call-effect.factor | 3 - .../propagation/inlining/inlining-docs.factor | 20 ++++++ .../tree/propagation/inlining/inlining.factor | 11 +--- basis/cpu/x86/x86-docs.factor | 25 +++++-- .../known-words/known-words-docs.factor | 6 +- 11 files changed, 119 insertions(+), 78 deletions(-) create mode 100644 basis/compiler/cfg/alias-analysis/alias-analysis-docs.factor create mode 100644 basis/compiler/tree/propagation/inlining/inlining-docs.factor diff --git a/basis/compiler/cfg/alias-analysis/alias-analysis-docs.factor b/basis/compiler/cfg/alias-analysis/alias-analysis-docs.factor new file mode 100644 index 0000000000..8d09150190 --- /dev/null +++ b/basis/compiler/cfg/alias-analysis/alias-analysis-docs.factor @@ -0,0 +1,65 @@ +USING: compiler.cfg.instructions help.markup help.syntax ; +IN: compiler.cfg.alias-analysis + +HELP: useless-compare? +{ $values + { "insn" "a " { $link ##compare } " instruction" } + { "?" "a boolean" } +} +{ $description "Checks if the comparison instruction is required." } ; + +ARTICLE: "compiler.cfg.alias-analysis" +"Alias analysis for stack operations, array elements and tuple slots" +"We try to eliminate redundant slot operations using some simple heuristics." +$nl +"All heap-allocated objects which are loaded from the stack, or other object slots are pessimistically assumed to belong to the same alias class." +$nl +"Freshly-allocated objects get their own alias class." +$nl +"Simple pseudo-C example showing load elimination:" +{ $code + "int *x, *y, z: inputs" + "int a, b, c, d, e: locals" +} +"Before alias analysis:" +{ $code + "a = x[2]" + "b = x[2]" + "c = x[3]" + "y[2] = z" + "d = x[2]" + "e = y[2]" + "f = x[3]" +} +"After alias analysis:" +{ $code + "a = x[2]" + "b = a /* ELIMINATED */" + "c = x[3]" + "y[2] = z" + "d = x[2] /* if x=y, d=z, if x!=y, d=b; NOT ELIMINATED */" + "e = z /* ELIMINATED */" + "f = c /* ELIMINATED */" +} +"Simple pseudo-C example showing store elimination:" +$nl +"Before alias analysis:" +{ $code + "x[0] = a" + "b = x[n]" + "x[0] = c" + "x[1] = d" + "e = x[0]" + "x[1] = c" +} +"After alias analysis:" +{ $code + "x[0] = a /* dead if n = 0, live otherwise; NOT ELIMINATED */" + "b = x[n]" + "x[0] = c" + "/* x[1] = d */ /* ELIMINATED */" + "e = c" + "x[1] = c" +} ; + +ABOUT: "compiler.cfg.alias-analysis" diff --git a/basis/compiler/cfg/alias-analysis/alias-analysis.factor b/basis/compiler/cfg/alias-analysis/alias-analysis.factor index b4ddff9fca..b12014e60e 100644 --- a/basis/compiler/cfg/alias-analysis/alias-analysis.factor +++ b/basis/compiler/cfg/alias-analysis/alias-analysis.factor @@ -8,60 +8,6 @@ namespaces sequences sets ; FROM: namespaces => set ; IN: compiler.cfg.alias-analysis -! We try to eliminate redundant slot operations using some -! simple heuristics. -! -! All heap-allocated objects which are loaded from the stack, or -! other object slots are pessimistically assumed to belong to -! the same alias class. -! -! Freshly-allocated objects get their own alias class. -! -! Simple pseudo-C example showing load elimination: -! -! int *x, *y, z: inputs -! int a, b, c, d, e: locals -! -! Before alias analysis: -! -! a = x[2] -! b = x[2] -! c = x[3] -! y[2] = z -! d = x[2] -! e = y[2] -! f = x[3] -! -! After alias analysis: -! -! a = x[2] -! b = a /* ELIMINATED */ -! c = x[3] -! y[2] = z -! d = x[2] /* if x=y, d=z, if x!=y, d=b; NOT ELIMINATED */ -! e = z /* ELIMINATED */ -! f = c /* ELIMINATED */ -! -! Simple pseudo-C example showing store elimination: -! -! Before alias analysis: -! -! x[0] = a -! b = x[n] -! x[0] = c -! x[1] = d -! e = x[0] -! x[1] = c -! -! After alias analysis: -! -! x[0] = a /* dead if n = 0, live otherwise; NOT ELIMINATED */ -! b = x[n] -! x[0] = c -! /* x[1] = d */ /* ELIMINATED */ -! e = c -! x[1] = c - ! Local copy propagation SYMBOL: copies diff --git a/basis/compiler/cfg/cfg-docs.factor b/basis/compiler/cfg/cfg-docs.factor index 10fa5b9440..7b87310dc9 100644 --- a/basis/compiler/cfg/cfg-docs.factor +++ b/basis/compiler/cfg/cfg-docs.factor @@ -10,6 +10,7 @@ HELP: basic-block { { $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." } } + { { $slot "kill-block?" } { "The first and the last block in a cfg and all blocks containing " { $link ##call } " instructions are kill blocks." } } } } ; diff --git a/basis/compiler/cfg/gc-checks/gc-checks-docs.factor b/basis/compiler/cfg/gc-checks/gc-checks-docs.factor index a6c9cc86b4..71f353c86f 100644 --- a/basis/compiler/cfg/gc-checks/gc-checks-docs.factor +++ b/basis/compiler/cfg/gc-checks/gc-checks-docs.factor @@ -4,6 +4,10 @@ IN: compiler.cfg.gc-checks [ first2 allocation-size cc<= int-rep next-vreg-rep int-rep next-vreg-rep diff --git a/basis/compiler/tree/propagation/call-effect/call-effect-docs.factor b/basis/compiler/tree/propagation/call-effect/call-effect-docs.factor index 1f88ecbfb8..7493f23687 100644 --- a/basis/compiler/tree/propagation/call-effect/call-effect-docs.factor +++ b/basis/compiler/tree/propagation/call-effect/call-effect-docs.factor @@ -2,6 +2,10 @@ USING: combinators.private compiler.units effects help.markup help.syntax quotations ; IN: compiler.tree.propagation.call-effect +HELP: already-inlined-quot? +{ $values { "quot" quotation } { "?" "a boolean" } } +{ $description "Some bookkeeping to make sure that crap like [ dup curry call( quot -- ) ] dup curry call( quot -- ) ] doesn't hang the compiler." } ; + HELP: cached-effect-valid? { $values { "quot" quotation } { "?" "a boolean" } } { $description { $link t } " if the cached effect is valid." } ; @@ -26,7 +30,6 @@ HELP: update-inline-cache { $values { "word/quot" "word or quotation" } { "ic" inline-cache } } { $description "Sets the inline caches " { $slot "value" } " to the given word/quot and updates its " { $slot "counter" } " to the value of the " { $link effect-counter } "." } ; - ARTICLE: "compiler.tree.propagation.call-effect" "Expansions of call( and execute( words" "call( and execute( have complex expansions." $nl diff --git a/basis/compiler/tree/propagation/call-effect/call-effect.factor b/basis/compiler/tree/propagation/call-effect/call-effect.factor index 04083e76ff..16e75bee8d 100644 --- a/basis/compiler/tree/propagation/call-effect/call-effect.factor +++ b/basis/compiler/tree/propagation/call-effect/call-effect.factor @@ -111,9 +111,6 @@ M: quotation cached-effect : execute-effect>quot ( effect -- quot ) inline-cache new '[ drop _ _ execute-effect-ic ] ; -! Some bookkeeping to make sure that crap like -! [ dup curry call( quot -- ) ] dup curry call( quot -- ) ] -! doesn't hang the compiler. GENERIC: already-inlined-quot? ( quot -- ? ) M: curry already-inlined-quot? quot>> already-inlined-quot? ; diff --git a/basis/compiler/tree/propagation/inlining/inlining-docs.factor b/basis/compiler/tree/propagation/inlining/inlining-docs.factor new file mode 100644 index 0000000000..5d453b5ef2 --- /dev/null +++ b/basis/compiler/tree/propagation/inlining/inlining-docs.factor @@ -0,0 +1,20 @@ +USING: compiler.tree help.markup help.syntax kernel quotations words ; +IN: compiler.tree.propagation.inlining + +HELP: custom-inlining? +{ $values { "word" word } { "quot/f" "a quotation or " { $link f } } } +{ $description "Returns the custom inlining " { $link quotation } " for a word if it has one." } ; + +HELP: (do-inlining) +{ $values { "#call" #call } { "word" word } { "?" boolean } } +{ $description + "Performs inlining of a word." + $nl + "If the generic was defined in an outer compilation unit, then it doesn't have a definition yet; the definition is built at the end of the compilation unit. We do not attempt inlining at this stage since the stack discipline is not finalized yet, so dispatch# might return an out of bounds value. This case comes up if a parsing word calls the compiler at parse time (doing so is discouraged, but it should still work.)" +} ; + +ARTICLE: "compiler.tree.propagation.inlining" "Method inlining and dispatch elimination" +"Splicing nodes:" +{ $subsections splicing-call open-code-#call splicing-body } ; + +ABOUT: "compiler.tree.propagation.inlining" diff --git a/basis/compiler/tree/propagation/inlining/inlining.factor b/basis/compiler/tree/propagation/inlining/inlining.factor index f9fc8e8d46..495021c695 100644 --- a/basis/compiler/tree/propagation/inlining/inlining.factor +++ b/basis/compiler/tree/propagation/inlining/inlining.factor @@ -8,7 +8,6 @@ generic.math generic.single generic.standard kernel locals math math.partial-dispatch namespaces quotations sequences words ; IN: compiler.tree.propagation.inlining -! Splicing nodes : splicing-call ( #call word -- nodes ) [ [ in-d>> ] [ out-d>> ] bi ] dip <#call> 1array ; @@ -95,7 +94,7 @@ SYMBOL: history : never-inline-word? ( word -- ? ) { [ deferred? ] [ "default" word-prop ] [ \ call eq? ] } 1|| ; -: custom-inlining? ( word -- ? ) +: custom-inlining? ( word -- quot/f ) "custom-inlining" word-prop ; : inline-custom ( #call word -- ? ) @@ -104,14 +103,6 @@ SYMBOL: history object swap eliminate-dispatch ; : (do-inlining) ( #call word -- ? ) - #! If the generic was defined in an outer compilation unit, - #! then it doesn't have a definition yet; the definition - #! is built at the end of the compilation unit. We do not - #! attempt inlining at this stage since the stack discipline - #! is not finalized yet, so dispatch# might return an out - #! of bounds value. This case comes up if a parsing word - #! calls the compiler at parse time (doing so is - #! discouraged, but it should still work.) { { [ dup never-inline-word? ] [ 2drop f ] } { [ dup always-inline-word? ] [ inline-word ] } diff --git a/basis/cpu/x86/x86-docs.factor b/basis/cpu/x86/x86-docs.factor index 6f89aa8f3e..b2e5f5ef16 100644 --- a/basis/cpu/x86/x86-docs.factor +++ b/basis/cpu/x86/x86-docs.factor @@ -1,17 +1,30 @@ -USING: cpu.x86.assembler.operands.private help.markup help.syntax layouts -math ; +USING: cpu.x86.assembler cpu.x86.assembler.operands.private help.markup +help.syntax layouts math ; IN: cpu.x86 +HELP: %boolean +{ $values + { "dst" "register" } + { "cc" "comparision symbol" } + { "temp" "temporary register" } +} +{ $description "Helper word for emitting conditional move instructions." } +{ $see-also CMOVL CMOVLE CMOVG CMOVGE CMOVE CMOVNE } ; + +HELP: JLE +{ $values "dst" "destination offset (relative to the instruction pointer register)" } +{ $description "Emits a 'jle' instruction." } ; + +HELP: reserved-stack-space +{ $values { "n" integer } } +{ $description "Size in bytes of the register parameter area. It only exists on the windows x86.64 architecture, where it is 32 bytes and allocated by the caller. On all other platforms it is 0." } ; + HELP: stack-reg { $values { "reg" "a register symbol" } } { $description "Symbol of the machine register that holds the (cpu) stack address." } ; -HELP: reserved-stack-space -{ $values { "n" integer } } -{ $description "Size in bytes of the register parameter area. It only exists on the windows x86.64 architecture, where it is 32 bytes and allocated by the caller. On all other platforms it is 0." } ; - HELP: ds-reg { $values { "reg" "a register symbol" } } { $description diff --git a/basis/stack-checker/known-words/known-words-docs.factor b/basis/stack-checker/known-words/known-words-docs.factor index 4b25149d34..be58bb7df3 100644 --- a/basis/stack-checker/known-words/known-words-docs.factor +++ b/basis/stack-checker/known-words/known-words-docs.factor @@ -1,4 +1,5 @@ -USING: help.markup help.syntax kernel kernel.private sequences words ; +USING: combinators help.markup help.syntax kernel kernel.private sequences +words ; IN: stack-checker.known-words HELP: check-declaration @@ -12,6 +13,9 @@ HELP: define-primitive HELP: infer-call { $description "Performs inferencing for the " { $link call } " word." } ; +HELP: infer-call-effect +{ $description "Performs inferencing for the " { $link call-effect } " word." } ; + HELP: infer-local-reader { $values { "word" word } } { $description "This is a hack for combinators " { $vocab-link "combinators.short-circuit.smart" } "." } ;