various improvements

[rrq/rrqforth.git] / adoc / p_stream.adoc

diff --git a/adoc/p_stream.adoc b/adoc/p_stream.adoc
index 37ffb5ae7aa07c8df2b4aa9b03c34c24a39ffc9d..16f6d9c159520b6e6db5e2573b1b1bc6a7a7de99 100644 (file)
--- 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
 ----
+====