From 92165e4ee7eaa4269b2753283aa0bcff1c6d21bc Mon Sep 17 00:00:00 2001 From: =?utf8?q?Bj=C3=B6rn=20Lindqvist?= Date: Mon, 16 Mar 2015 09:06:00 +0000 Subject: [PATCH] Docs: bunch of smaller documentation fixes for various vocabs --- .../cpu/architecture/architecture-docs.factor | 108 +++++++++++------- basis/cpu/x86/x86-docs.factor | 21 +++- basis/tools/walker/walker-docs.factor | 5 +- core/bootstrap/primitives-docs.factor | 7 ++ core/classes/classes-docs.factor | 12 +- core/continuations/continuations-docs.factor | 7 +- core/definitions/definitions-docs.factor | 6 +- core/generic/parser/parser-docs.factor | 10 ++ 8 files changed, 129 insertions(+), 47 deletions(-) create mode 100644 core/bootstrap/primitives-docs.factor create mode 100644 core/generic/parser/parser-docs.factor diff --git a/basis/cpu/architecture/architecture-docs.factor b/basis/cpu/architecture/architecture-docs.factor index bcb70beea3..eff0de7d7f 100644 --- a/basis/cpu/architecture/architecture-docs.factor +++ b/basis/cpu/architecture/architecture-docs.factor @@ -5,6 +5,16 @@ QUALIFIED: vm IN: cpu.architecture << +STRING: ex-%allot +USING: cpu.architecture make ; +[ RAX 40 tuple RCX %allot ] B{ } make disassemble +0000000002270cc0: 498d4d10 lea rcx, [r13+0x10] +0000000002270cc4: 488b01 mov rax, [rcx] +0000000002270cc7: 48c7001c000000 mov qword [rax], 0x1c +0000000002270cce: 4883c807 or rax, 0x7 +0000000002270cd2: 48830130 add qword [rcx], 0x30 +; + STRING: ex-%box-alien USING: compiler.codegen compiler.codegen.relocation cpu.architecture make ; init-fixup init-relocation [ RAX RBX RCX %box-alien ] B{ } make disassemble @@ -22,22 +32,18 @@ init-fixup init-relocation [ RAX RBX RCX %box-alien ] B{ } make disassemble 000000e9fcc720dd: 4889581a mov [rax+0x1a], rbx ; -STRING: ex-%allot -USING: cpu.architecture make ; -[ RAX 40 tuple RCX %allot ] B{ } make disassemble -0000000002270cc0: 498d4d10 lea rcx, [r13+0x10] -0000000002270cc4: 488b01 mov rax, [rcx] -0000000002270cc7: 48c7001c000000 mov qword [rax], 0x1c -0000000002270cce: 4883c807 or rax, 0x7 -0000000002270cd2: 48830130 add qword [rcx], 0x30 -; - STRING: ex-%context USING: cpu.architecture make ; [ EAX %context ] B{ } make disassemble 00000000010f5ed0: 418b4500 mov eax, [r13] ; +STRING: ex-%copy +USING: cpu.architecture make ; +RAX RBX int-rep [ %copy ] B{ } make disassemble +000000000108a970: 4889d8 mov rax, rbx +; + STRING: ex-%safepoint USING: cpu.architecture make ; init-relocation [ %safepoint ] B{ } make disassemble @@ -54,10 +60,16 @@ USING: cpu.architecture make ; 0000000000e63ac0: 4c897818 mov [rax+0x18], r15 ; -STRING: ex-%copy -USING: cpu.architecture make ; -RAX RBX int-rep [ %copy ] B{ } make disassemble -000000000108a970: 4889d8 mov rax, rbx +STRING: ex-%write-barrier +USING: cpu.architecture make tools.disassembler ; +init-relocation [ RAX RBX 3 -14 RCX RDX %write-barrier ] B{ } make disassemble +000000000143f960: 488d4cd80e lea rcx, [rax+rbx*8+0xe] +000000000143f965: 48c1e908 shr rcx, 0x8 +000000000143f969: 48ba0000000000000000 mov rdx, 0x0 +000000000143f973: 48c60411c0 mov byte [rcx+rdx], 0xc0 +000000000143f978: 48c1e90a shr rcx, 0xa +000000000143f97c: 48ba0000000000000000 mov rdx, 0x0 +000000000143f986: 48c60411c0 mov byte [rcx+rdx], 0xc0 ; >> @@ -92,13 +104,18 @@ HELP: param-regs { $values { "abi" "a calling convention symbol" } { "regs" assoc } } { $description "Retrieves the order in which machine registers are used for parameters for the given calling convention." } ; -HELP: %load-immediate -{ $values { "reg" "a register symbol" } { "val" "a value" } } -{ $description "Emits code for loading an immediate value into a register. On " { $link x86 } ", if val is 0, then an " { $link XOR } " instruction is emitted instead of " { $link MOV } "." } ; - -HELP: %call -{ $values { "word" word } } -{ $description "Emits code for calling a Factor word." } ; +HELP: %allot +{ $values + { "dst" "destination register symbol" } + { "size" "number of bytes to allocate" } + { "class" "one of the built-in classes listed in " { $link type-numbers } } + { "temp" "temporary register symbol" } +} +{ $description "Emits machine code for allocating memory." } +{ $examples + "In this example 40 bytes is allocated and a tagged pointer to the memory is put in " { $link RAX } ":" + { $unchecked-example $[ ex-%allot ] } +} ; HELP: %box { $values @@ -116,6 +133,10 @@ HELP: %box-alien { $examples { $unchecked-example $[ ex-%box-alien ] } } { $see-also ##box-alien %allot } ; +HELP: %call +{ $values { "word" word } } +{ $description "Emits code for calling a Factor word." } ; + HELP: %context { $values { "dst" "a register symbol" } } { $description "Emits machine code for putting a pointer to the context field of the " { $link vm } " in a register." } @@ -126,6 +147,20 @@ 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: %load-immediate +{ $values { "reg" "a register symbol" } { "val" "a value" } } +{ $description "Emits code for loading an immediate value into a register. On " { $link x86 } ", if val is 0, then an " { $link XOR } " instruction is emitted instead of " { $link MOV } " because the former is shorter." } +{ $see-also ##load-tagged } ; + +HELP: %local-allot +{ $values + { "dst" "destination register symbol" } + { "size" "number of bytes to allocate" } + { "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." } ; + HELP: %safepoint { $description "Emits a safe point to the current code sequence being generated." } { $examples { $unchecked-example $[ ex-%safepoint ] } } ; @@ -135,28 +170,17 @@ HELP: %save-context { $description "Emits machine code for saving pointers to the callstack, datastack and retainstack in the current context field struct." } { $examples { $unchecked-example $[ ex-%save-context ] } } ; - -HELP: %allot +HELP: %write-barrier { $values - { "dst" "destination register symbol" } - { "size" "number of bytes to allocate" } - { "class" "one of the built-in classes listed in " { $link type-numbers } } - { "temp" "temporary register symbol" } + { "src" "a register symbol" } + { "slot" "a register symbol" } + { "scale" integer } + { "tag" integer } + { "temp1" "a register symbol" } + { "temp2" "a register symbol" } } -{ $description "Emits machine code for allocating memory." } -{ $examples - "In this example 40 bytes is allocated and a tagged pointer to the memory is put in " { $link RAX } ":" - { $unchecked-example $[ ex-%allot ] } -} ; - -HELP: %local-allot -{ $values - { "dst" "destination register symbol" } - { "size" "number of bytes to allocate" } - { "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 "Generates code for the " { $link ##write-barrier } " instruction." } +{ $examples { $unchecked-example $[ ex-%write-barrier ] } } ; HELP: test-instruction? { $values { "?" "a boolean" } } @@ -210,6 +234,8 @@ $nl } "Control flow code emitters:" { $subsections %call %jump %jump-label %return } +"Slot access:" +{ $subsections %write-barrier } "Representation metadata:" { $subsections narrow-vector-rep diff --git a/basis/cpu/x86/x86-docs.factor b/basis/cpu/x86/x86-docs.factor index 9e904eac7a..6f89aa8f3e 100644 --- a/basis/cpu/x86/x86-docs.factor +++ b/basis/cpu/x86/x86-docs.factor @@ -1,4 +1,5 @@ -USING: help.markup help.syntax math ; +USING: cpu.x86.assembler.operands.private help.markup help.syntax layouts +math ; IN: cpu.x86 HELP: stack-reg @@ -30,6 +31,24 @@ HELP: (%inc) } } ; +HELP: (%slot) +{ $values + { "obj" "a register symbol" } + { "slot" "a register symbol" } + { "scale" "number of bits required to address all bytes in a " { $link cell } "." } + { "tag" integer } + { "op" indirect } +} +{ $description "Creates an indirect operand for addressing a slot in a container." } +{ $examples + { $unchecked-example + "USING: cpu.x86 ;" + "[ RAX RBX 3 -14 (%slot) EDI MOV ] B{ } make disassemble" + "0000000001dd0990: 897cd80e mov [rax+rbx*8+0xe], edi" + } +} ; + + HELP: decr-stack-reg { $values { "n" number } } { $description "Emits an instruction for decrementing the stack register the given number of bytes." } ; diff --git a/basis/tools/walker/walker-docs.factor b/basis/tools/walker/walker-docs.factor index 94c1a7790d..d47a858bf3 100644 --- a/basis/tools/walker/walker-docs.factor +++ b/basis/tools/walker/walker-docs.factor @@ -15,7 +15,7 @@ HELP: breakpoint-if { $description "Annotates a word definition to enter the single stepper if the quotation yields true. The quotation has access to the datastack as it exists just before " { $snippet "word" } " is called." } { $examples "Break if the input to sq is 3:" - { $unchecked-example + { $unchecked-example "USE: tools.walker \\ sq [ dup 3 = ] breakpoint-if" "" } @@ -27,6 +27,9 @@ HELP: B HELP: B: { $description "A breakpoint for parsing words. When this word is executed, it copies the definition of the following parsing word, prepends a " { $link break } " to it so that it is the first word to be executed when the definition is called, and calls this new definition.\n\nWhen the walker tool opens, execution will still be inside " { $link POSTPONE: B: } ". To step out of B: and into the parsing word, do just that: jump out with O, then into with I." } ; +HELP: step-into +{ $var-description "Signal set to the walker thread to step into the word." } ; + ARTICLE: "breakpoints" "Setting breakpoints" "In addition to invoking the walker explicitly through the UI, it is possible to set breakpoints on words using words in the " { $vocab-link "tools.walker" } " vocabulary." $nl diff --git a/core/bootstrap/primitives-docs.factor b/core/bootstrap/primitives-docs.factor new file mode 100644 index 0000000000..06d464dfbf --- /dev/null +++ b/core/bootstrap/primitives-docs.factor @@ -0,0 +1,7 @@ +USING: bootstrap.image.private effects help.markup help.syntax strings ; +IN: bootstrap.primitives + +HELP: make-sub-primitive +{ $values { "word" string } { "vocab" string } { "effect" effect } } +{ $description "Defines a sub primitive word." } +{ $see-also define-sub-primitive } ; diff --git a/core/classes/classes-docs.factor b/core/classes/classes-docs.factor index 29ac0dee43..54ba4883b6 100644 --- a/core/classes/classes-docs.factor +++ b/core/classes/classes-docs.factor @@ -84,6 +84,17 @@ HELP: classes HELP: update-map { $var-description "Assoc mapping each class to a set of classes defined in terms of this class. The " { $link define-class } " word uses this information to update generic words when classes are redefined." } ; +HELP: predicate-def +{ $values { "obj" "a type object" } { "quot" quotation } } +{ $description "Outputs a quotation that can be used to check if objects are an instance of the given type." } +{ $examples + { $example + "USING: classes math prettyprint ;" + "fixnum predicate-def ." + "[ fixnum? ]" + } +} ; + HELP: predicate-word { $values { "word" word } { "predicate" "a predicate word" } } { $description "Suffixes the word's name with \"?\" and creates a word with that name in the same vocabulary as the word itself." } ; @@ -165,4 +176,3 @@ HELP: forget-class HELP: forget-methods { $values { "class" class } } { $description "Forgets all methods defined on a class. In contrast to " { $link reset-class } ", this not only forgets accessors but also any methods at all on the class." } ; - diff --git a/core/continuations/continuations-docs.factor b/core/continuations/continuations-docs.factor index d5bd657ae9..c86093507e 100644 --- a/core/continuations/continuations-docs.factor +++ b/core/continuations/continuations-docs.factor @@ -116,13 +116,16 @@ HELP: catchstack { $values { "catchstack" "a vector of continuations" } } { $description "Outputs a copy of the current catchstack." } ; +HELP: current-continuation +{ $values { "continuation" continuation } } +{ $description "Creates a continuation object from the current execution context." } ; + HELP: set-catchstack { $values { "catchstack" "a vector of continuations" } } { $description "Replaces the catchstack with a copy of the given vector." } ; HELP: continuation -{ $values { "continuation" continuation } } -{ $description "Reifies the current continuation from the point immediately after which the caller returns." } ; +{ $class-description "Reifies the current continuation from the point immediately after which the caller returns." } ; HELP: >continuation< { $values { "continuation" continuation } { "data" vector } { "call" vector } { "retain" vector } { "name" vector } { "catch" vector } } diff --git a/core/definitions/definitions-docs.factor b/core/definitions/definitions-docs.factor index d92c250faf..3da59b0e1c 100644 --- a/core/definitions/definitions-docs.factor +++ b/core/definitions/definitions-docs.factor @@ -1,4 +1,4 @@ -USING: help.markup help.syntax words math source-files +USING: generic hash-sets help.markup help.syntax words math source-files parser quotations compiler.units ; IN: definitions @@ -91,3 +91,7 @@ HELP: forget-all { $values { "definitions" "a sequence of definition specifiers" } } { $description "Forgets every definition in a sequence." } { $notes "This word must be called from inside " { $link with-compilation-unit } "." } ; + +HELP: outdated-generics +{ $var-description "A " { $link hash-set } " where newly defined generic words are kept until they are being remade." } +{ $see-also remake-generic remake-generics } ; diff --git a/core/generic/parser/parser-docs.factor b/core/generic/parser/parser-docs.factor new file mode 100644 index 0000000000..ef56739f45 --- /dev/null +++ b/core/generic/parser/parser-docs.factor @@ -0,0 +1,10 @@ +USING: effects generic.single help.markup help.syntax math words ; +IN: generic.parser + +HELP: generic-effect +{ $values { "word" word } { "effect" effect } } +{ $description "Gets the effect for a method." } ; + +ARTICLE: "generic.parser" "Utilities for generic word and method defining parsing words" "This vocab creates method words." ; + +ABOUT: "generic.parser" -- 2.34.1