OpenBoot 2.x Command Reference Manual

The Stack Diagram

To aid understanding, conventional coding style requires that a stack diagram of the form ( -- ) appears on the first line of every definition of a Forth word. The stack diagram specifies what happens to the stack with the execution of the word.

Entries to the left of -- show stack items that are consumed (i.e. removed) from the stack and used by the operation of that word. Entries to the right of -- show stack items that are left on the stack after the word finishes execution. For example, the stack diagram for the word + is: ( nu1 nu2 -- sum ), and the stack diagram for the word. is: ( nu -- ). Therefore, + removes two numbers (nu1 and nu2), then leaves their sum (sum) on the stack. The word . removes the number on the top of the stack (nu) and displays it.

Words that have no effect on the contents of the stack (such as showstack or decimal), have a ( -- ) stack diagram.

Occasionally, a word will require another word or other text immediately following it. For example, the word see, used in the form see thisword ( -- ).

Stack items are generally written using descriptive names to help clarify correct usage. See Table 4-1 for stack item abbreviations used in this manual.

Table 4-1 Stack Item Notation


Notation	Description
`\|`	Alternate stack results shown with space, e.g. ( input -- addr len false \| result true ).
`\|`	Alternate stack items shown without space, e.g. ( input -- addr len\|0 result ).
`???`	Unknown stack item(s).
	Unknown stack item(s). If used on both sides of a stack comment, means the same stack items are present on both sides.
`< > <space>`	Space delimiter. Leading spaces are ignored.
`a-addr`	Variable-aligned address.
`addr`	Memory address (generally a virtual address).
`addr len`	Address and length for memory region
`byte bxxx`	8-bit value (low order byte in a 32-bit word).
`char`	7-bit value (low order byte), high bit unspecified.
`cnt len size`	Count or length.
`dxxx`	Double (extended-precision) numbers. 2 stack items, hi quadlet on top of stack.
`<eol>`	End-of-line delimiter.
`false`	0 (false flag).
`ihandle`	Pointer for an instance of a package.
`n n1 n2 n3`	Normal signed values (32-bit).
`nu nu1`	Signed or unsigned values (32-bit).
`<nothing>`	Zero stack items.
`phandle`	Pointer for a package.
`phys`	Physical address (actual hardware address).
`phys.lo` `phys.hi`	Lower / upper cell of physical address
`pstr`	Packed string.
`quad qxxx`	Quadlet (32-bit value).
`qaddr`	Quadlet (32-bit) aligned address
`{text}`	Optional text. Causes default behavior if omitted.
`"text<delim>"`	Input buffer text, parsed when command is executed. Text delimiter is enclosed in <>.
`[text<delim>]`	Text immediately following on the same line as the command, parsed immediately. Text delimiter is enclosed in <>.
`true`	-1 (true flag).
`uxxx`	Unsigned value, positive values (32-bit).
`virt`	Virtual address (address used by software).
`waddr`	Doublet (16-bit) aligned address
`word wxxx`	Doublet (16-bit value, low order two bytes in a 32-bit word).
`x x1`	Arbitrary stack item.
`x.lo x.hi`	Low/high significant bits of a data item
`xt`	Execution token.
`xxx?`	Flag. Name indicates usage (e.g. `done?` `ok?` `error?`).
`xyz-str xyz-len`	Address and length for unpacked string.
`xyz-sys`	Control-flow stack items, implementation-dependent.
`( C: -- )`	Compilation stack diagram
`( -- ) ( E: -- )`	Execution stack diagram
`( R: -- )`	Return stack diagram