X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=adoc%2Fp_stream.adoc;h=16f6d9c159520b6e6db5e2573b1b1bc6a7a7de99;hb=60057839785134cd60545fa503c31ab50d4056d2;hp=37ffb5ae7aa07c8df2b4aa9b03c34c24a39ffc9d;hpb=b7da3f7bbd1cb10241163abdb950472e539e796d;p=rrq%2Frrqforth.git

diff --git a/adoc/p_stream.adoc b/adoc/p_stream.adoc
index 37ffb5a..16f6d9c 100644
--- a/adoc/p_stream.adoc
+++ b/adoc/p_stream.adoc
@@ -1,9 +1,46 @@
+// stdio.asm:	WORD p_stream,'STREAM',fasm
+
 anchor:p_stream[]
 
-Word: STREAM
-------------
+=== Word: STREAM
+....
+Data stack: ( fd size -- addr ) or ( block -1 -- addr )
+....
+
+"STREAM" is a function word that sets up a buffer for an input file
+descriptor or for a memory block (of size+data).
+
+==== File descriptor backed STREAM
+
+
+A file descriptor backed STREAM gains a buffer of the given size
+prefixed by a 32 byte STREAM header of the following layout:
+
+====
+.file descriptor stream
+[caption='Layout {counter:layout}: ']
+----
+  8 bytes = size of buffer (excluding the 32 byte header)
+  8 bytes source file descriptor
+  8 bytes current fill
+  8 current read position
+----
+====
+
+==== Memory block backed STREAM
+
+A memory block stream is only the header (though allocated via
+<<p_malloc,MALLOC>> which reserves a full kernel page) with the
+following layout:
 
+====
+.memory block stream
+[caption='Layout {counter:layout}: ']
 ----
-stdio.asm:	WORD p_stream,'STREAM',fasm
+  8 bytes = block address
+  8 -1 (indicates memory block)
+  8 size of block (taken from the block's first 8 bytes)
+  8 current read position
 ----
+====