+// 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
----
+====