commit 89ba11ccf55bacbdb043171f8e526a5cb3c2de2d
parent 18659cc6bd59eb06530cfb3e877e982d1854f68c
Author: Virgil Dupras <hsoft@hardcoded.net>
Date: Sat, 29 Oct 2022 10:52:37 -0400
Clarify documentation slightly
Diffstat:
3 files changed, 24 insertions(+), 22 deletions(-)
diff --git a/fs/doc/arch.txt b/fs/doc/arch.txt
@@ -38,7 +38,8 @@ call it.
When we refer to an "entry", we refer to the data structure. This means that an
entry is a pointer to the "previous entry" field. To get a word from an entry,
-we add 5 bytes.
+we add 5 bytes. "e>w" and "w>e" are helper words to add and remove that offset
+from a given address.
Except for words specifically made for manipulating dictionary entries, we
rarely deal with "entry" pointers. We most often deal with word pointers.
@@ -177,17 +178,9 @@ obeys "to" semantics.
(alias): Compiled by "alias", it works like a (val), but it jumps to the address
read. Also obeys "to" semantics.
-(to): A generalized version of (val) and (alias), but slower and wider. It is
-followed by 12b of data, 2 word pointers and a 4 b data area. The first pointer
-is the "address getter". It is called with (to)+8 as an argument and returns
-an effective address for both the getter and the setter (the toptr). The getter
-returns the value from the effective address when toptr=0. PC then continues at
-(to)+12. For example, (val) would be "compile (to) ' noop , ' @ , $1234 ,"
-
(does): Compiled by "doer", it's a hybrid between (alias) and (cell). It pushes
PC+4 to PS, but also reads the 4b int at PC+0 and jumps to its address.
-Does *not* obey "to" semantics. We need it not to in order to have fancy does
-words that use the "to?" word.
+Does *not* obey "to" semantics.
(s): A string literal, compiled by S". It pushes PC+1 to PS, which is the
address of the first character of the string. Then, it reads the byte at PC+0,
diff --git a/fs/doc/usage.txt b/fs/doc/usage.txt
@@ -97,13 +97,12 @@ equivalent of "addr-of-myvalue @", it executes "addr-of-myvalue !".
As soon as a "to" override is used, the global "to" pointer is reset to 0.
+Refer to doc/dict for a complete list of "to" words.
+
Warning: this variable is global. any usage of "to" will affect the next value
or alias that pops up. To avoid problems, always put your "to" call very, very
close to your value/alias call.
-to+ sets "to" to "+!"
-to' sets "to" to "noop" (returns the address)
-
## Chain
It's a common pattern to want to "chain" behaviors in aliases. For example, one
@@ -158,14 +157,16 @@ Each metadata element has this structure:
## Local variables
-It's a common pattern, to avoid PS juggling, to place an element on RS and
-recall that element with r@. It works well, but unfortunately, this only works
-with a single element. Another drawback is that this element can be "buried" by
-a pattern (a "next" loop for example) that needs to place something on RS.
+It's a common pattern, to avoid PS juggling, to place an element on RS (Return
+Stack) and recall that element with r@. It works well, but unfortunately, this
+only works with a single element. Another drawback is that this element can be
+"buried" by a pattern (a "next" loop for example) that needs to place something
+on RS.
A workaround to this is to declare a "private" value near the word and store
temporary values in there. It works too, but because those values are statically
-allocated, this can't be done in words that require recursion.
+allocated, this can't be done in words that require recursion. Also, it's a bit
+verbose.
Local variables are there to the rescue! There are 4 of them: V1 V2 V3 V4. These
words do a simple thing: they reference an element on RS with "to" semantics.
@@ -263,8 +264,7 @@ and are declared thus:
smethod :bleh
]struct
-This describes an 12 byte wide struct with 3 fields. All fields in structs are
-always contiguous and 4 bytes wide.
+This describes an 12 byte wide struct with 3 fields.
Anything goes inside of a struct. Whatever word you define there will be
included in the struct's namespace. Those words will not be present in the
@@ -348,7 +348,16 @@ There are several kinds of fields:
* sfield': a field that yields its address instead of a value. Useful for
buffers. It must be called with a size argument.
-You can also extend a previous struct with a new struct:
+You can also create gaps in the struct with "sallot":
+
+struct[ Gaps
+ sfield foo
+ 42 sallot
+ sfield bar
+]struct
+
+In this struct, foo's offset is 0 and bar's is 46. You can also extend a
+previous struct with a new struct:
extends Foo struct[ Bar
sfield bazooka
diff --git a/fs/doc/x86.txt b/fs/doc/x86.txt
@@ -1,6 +1,6 @@
# x86 architecture
-The x86 kernel source code is xcomp/i386.fs. Register roles:
+The x86 kernel source code is xcomp/i386/kernel.fs. Register roles:
PSP: EBP
RSP: ESP
