duskos

commit d4881a048d2117880111b0e5f11a23f3601c7eb9
parent 0d2ac308a8325cd3ec62f81a590bb48d761acc94
Author: Virgil Dupras <hsoft@hardcoded.net>
Date:   Tue,  2 Aug 2022 16:09:39 -0400

doc: Document "parens" words

Diffstat:
M
fs/doc/arch.txt
 | 
34
++++++++++++++++++++++++++++++++++

1 file changed, 34 insertions(+), 0 deletions(-)
diff --git a/fs/doc/arch.txt b/fs/doc/arch.txt
@@ -141,3 +141,37 @@ a subsystem.
 
 For example, sys/scratch is centered around a buffer which can vary in size
 depending on what the sysop wants.
+
+# Parens words ()
+
+At the core of each kernel is a set of words that all have their name wrapped
+inside parentheses, such as (br), (val), etc. These words are designed to not
+be called directly, but compiled inside a definite structure. These structures
+are documented here:
+
+(cell): Compiled by "create", a call to this word pushes the current PC to PS
+and then returns.
+
+(val): Compiled by "value", it works like a (cell), but instead of pushing the
+address to PS, it reads the 4b value there and pushes that instead. It also
+obeys "to" semantics.
+
+(alias): Compiled by "alias", it works like a (val), but it jumps to the address
+read. Also obeys "to" semantics.
+
+(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.
+
+(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,
+which is the length of the string, and pushes it to PS.
+
+(br): Compiled by "again" and "else", it's an unconditional branch. It works
+like (alias), but ignores "to" semantics.
+
+(?br): Compiled by "if" and "until", a conditional branch. It pops from PS and
+if the popped value is zero, branches exactly like (br). Otherwise, it continues
+to PC+4.
+
+(next): Compiled by "next". Decreases RS TOS by one. If zero is reached, pop it
+from RS and continue to PC+4. If not, branch like (br).