Stack Symbols & Naming Conventions

Using the data stack for Forth language software development

Stack conventions and notation
Stack symbols
Stack representations of data structures
Naming conventions
Attributes

Stack conventions and notation

Understanding stack notation is very important when programming in Forth. Each Forth glossary entry contains a "stack comment" (also called a "stack picture") that describes the inputs and outputs of the function.

When editing your source code using the Mosaic Integrated Development Environment (IDE) we strongly recommend that you include a stack comment for each Forth function that you write. Much like a function prototype in C, the stack picture documents the input and output parameters of the function. This chapter describes the standard stack notation used throughout this glossary and all of the QED-Forth Software and Hardware documentation.

Each stack picture is enclosed in parentheses, so it is automatically treated as a comment by the QED-Forth compiler. A stack picture indicates the input(s) and output(s) of a routine. Inputs are listed to the left of the -- symbol, and outputs are listed to the right. Stack items are separated by the \ character which can be read as "under".

For example, the stack picture of the addition routine + is:

( n1\n2 -- n3 )

This indicates that the function expects two integer inputs (n1 under n2), and returns the integer result n3 as an output. If we want to convey a bit more information within the stack picture, we can add an explanatory phrase within the parentheses. The standard way to do this is to insert a vertical bar symbol before the explanatory phrase. For example, a more instructive stack picture for the + routine would be:

( n1\n2 -- n3 | n3 = n1 + n2 )
or
( n1\n2 -- n3 | adds two signed integers )

which tells us that the output n3 is the sum of the two inputs.

Even words that expect no inputs and return no outputs should be documented with a stack picture; in this case the stack picture would be as follows:

( -- )

Alternate stack inputs or outcomes are indicated by placing the alternatives within brackets as in

( -- [n1\true] or [false] )

The word associated with this stack picture either places a signed integer under a true flag on the stack, or places a false flag on the stack. Note that unlike languages like C, Forth can return several or even a variable number of parameters from a function call.

The smallest item that can be stored on the stack is called a "cell". Each stack cell consists of two bytes. The most significant byte is stored on the top of the stack (in the lower memory location), and the data stack grows downward toward low memory. For stack items whose data size is less than two bytes, for example a character, page or byte, the datum is stored in the least significant byte of the stack cell.

If a function removes a name or text from the input stream, it is indicated by <name> or <text>, etc. on the input side of the stack picture. For example, the stack picture of ANEW is

( <name> -- )

which means that ANEW removes the next blank-delimited name from the input stream.

The remainder of this section describes the standard stack symbols, data structure names, and naming conventions used in the QED-Forth Glossary and documentation.

Stack symbols

The following table describes the standard symbols used to represent items placed on the data stack.

Stack Symbol	Size on Stack	Size in Memory	Valid Data Size	Meaning
`addr`	1 cell	2 bytes	2 bytes	16-bit address. Range: 0 to 65,535 (0-0xFFFF).
`page`	1 cell	2 bytes	1 byte	Page. Range: 0 to 63 (0-0x3F).
`xaddr`	2 cells	4 bytes	3 bytes	32-bit extended address comprising an address and page: addr\page. In paged memory, the address immediately after 0xBFFF on a specified page is 0x8000 on the following page.
`$addr`	1 cell	2 bytes	2 bytes	16-bit address of the count byte of an ASCII string. The count byte precedes the string in memory.
`x$addr`	2 cells	4 bytes	3 bytes	Extended string address, same as: $addr\page.
`addr.offset`	1 cell	2 bytes	2 bytes	16-bit signed address offset. The xcfa of a function is stored as address- and page-offsets relative to the segment base xaddress.
`page.offset`	1 cell	2 bytes	1 byte	8-bit signed page offset. The xcfa of a function is stored as address- and page-offsets relative to the segment base xaddress.
`xtask.id`	2 cells	4 bytes	3 bytes	Extended task identifier address, also called STATUS addr or base addr of user area.
`xresource`	2 cells	4 bytes	3 bytes	Extended address of a resource variable.
`xmailbox`	2 cells	4 bytes	3 bytes	Extended address of a mailbox variable.
`cfa`	1 cell	2 bytes	2 bytes	16-bit code field address.
`nfa`	1 cell	2 bytes	2 bytes	16-bit name field address.
`pfa`	1 cell	2 bytes	2 bytes	16-bit parameter field address.
`xcfa`	2 cells	4 bytes	3 bytes	Code field xaddr.
`xnfa`	2 cells	4 bytes	3 bytes	Name field xaddr.
`xpfa`	2 cells	4 bytes	3 bytes	Parameter field xaddr.
`xhandle`	2 cells	4 bytes	3 bytes	32-bit address of a memory location that contains a 32-bit xaddr. Typically used to hold the base xaddr of a heap item.
`flag`	1 cell	2 bytes	2 bytes	Boolean flag, 0 indicates false. Non-zero indicates true.
`true`	1 cell	2 bytes	2 bytes	Boolean flag, = -1 = 0xFFFF.
`false`	1 cell	2 bytes	2 bytes	Boolean flag, = 0
`-1`	1 cell	2 bytes	2 bytes	-1
`0`	1 cell	2 bytes	2 bytes	0
`1`	1 cell	2 bytes	2 bytes	1
`char`	1 cell	1 byte	1 byte	ASCII character.
`byte`	1 cell	1 byte	1 byte	Unspecified single byte datum.
`cnt`	1 cell	1 byte	1 byte	Unsigned byte-sized integer, the count of an ASCII string. Range: 0 to 255.
`n`	1 cell	2 bytes	2 bytes	Signed 16-bit (single) integer. Range: -32,768 to 32,767.
`+n`	1 cell	2 bytes	2 bytes	Signed positive 16-bit (single) integer. Range: 0 to 32,767.
`u`	1 cell	2 bytes	2 bytes	Unsigned 16-bit (single) integer range: 0 to 65,535.
`w`	1 cell	2 bytes	2 bytes	Unspecified signed or unsigned 16-bit integer, either n or u.
`d`	2 cells	4 bytes	4 bytes	Signed 32-bit integer. Range: -2,147,483,648 to +2,147,483,647
`+d`	2 cells	4 bytes	4 bytes	Signed positive 32-bit (double) integer. Range: 0 to +2,147,483,647.
`ud`	2 cells	4 bytes	4 bytes	Unsigned 32-bit (double) integer. Range: 0 to 4,294,967,295.
`wd`	2 cells	4 bytes	4 bytes	Unspecified signed or unsigned double integer, either d or ud.
`r`	2 cells	4 bytes	4 bytes	Floating point (real) number, sign and exponent are in most significant cell (low memory) mantissa is in least significant cell (high memory).
`mode`	1 cell	2 bytes	2 bytes	Synonym for n, specifies the address mode and/or a target register for an assembly mnemonic.
`condition`	1 cell	2 bytes	2 bytes	Synonym for n, specifies the condition for assembly branches and control structures.
`arg`	1 cell	2 bytes	2 bytes	Synonym for w, an argument passed to an assembly mnemonic. The interpretation of arg depends on the specified mode.
`reg.arg`	1 cell	2 bytes	2 bytes	Synonym for n, specifies a target register argument for an assembly mnemonic.
`array.xpfa`	2 cells	4 bytes	3 bytes	The xpfa of an array. Used to refer to an array as a whole.
`matrix.xpfa`	2 cells	4 bytes	3 bytes	The xpfa of a matrix. Used to refer to a matrix as a whole.
`#rows`	1 cell	2 bytes	2 bytes	Specifies the number of rows in a matrix. Range: 0 to 65,535.
`row#`	1 cell	2 bytes	2 bytes	Used as row index for matrices, range: 0 to 65,535.
`#cols`	1 cell	2 bytes	2 bytes	Specifies the number of columns in a matrix. Range: 0 to 65,535.
`col#`	1 cell	2 bytes	2 bytes	Used as column index for matrices. Range: 0 to 65,535.
`xvaddr`	2 cells	4 bytes	3 bytes	32-bit extended address specifying the starting xaddr of a vector (a vector is a collection of floating point numbers evenly spaced in memory). For the vector operations to function properly, xvaddr must be 4-byte aligned (i.e., it must be an even multiple of 4 bytes). The heap manager and array and matrix dimensioning words perform this alignment automatically.
`sep`	1 cell	2 bytes	2 byte	Specifies the separation used by vector words expressed in multiples of 4 bytes. Range: 0 to 16,383. sep=1 means a vector of contiguous floating point numbers, sep=2 means elements are separated by 8 bytes, etc.
`d.#el`	2 cells	4 bytes	3 bytes	Synonym for +d. Number of elements in a vector; the allowed number of elements is limited only by available memory.
`offset`	1 cell	2 bytes	1 byte	Unsigned byte-sized integer, the offset from the base address of a Wildcard to the specified target in the 256 byte address range of the Wildcard.
`module_num`	1 cell	2 bytes	1 byte	Unsigned integer that specifies the module number (hardware address) of a Wildcard I/O module. Range: 0 to 15 (numbers 8-15 specify slow accesses).
`channel_id`	1 cell	2 bytes	2 bytes	Unsigned integer that specifies the channel identifier of a hardware signal such as a PWM or timer-controlled I/O line. The channel_id can be a numeric integer, or can be represented by a named constant. The allowed range depends on the hardware device.
`segment`	1 cell	2 bytes	1 byte	Unsigned integer that specifies the segment index of a library or application segment. Range: 0 to 31.
`segment.`
`xhandle`	2 cells	4 bytes	3 bytes	32-bit address of a memory location that contains a segment index. Typically used by the operating system to compile a relocation-tolerant library-to-library function call.
`\...\`	variable	variable	variable	Unspecified number of bytes.
`<name>`	none	none	none	Indicates that a single word is taken from the input stream.
`<text>`	none	none	none	Indicates that text is taken from the input stream or placed into the output stream.

Stack representations of data structures

The following table describes the stack pictures used to represent data structures such as arrays, and matrices. A matrix is defined as a 2-dimensional array containing 4-byte floating point numbers.

Data Structure	Stack Picture	Representation
array	`array.xpfa`	An array is represented by its extended parameter field address, which is obtained by using the word `'` (tick). For example, `' MY.ARRAY` returns the `xpfa`.
matrix	`matrix.xpfa`	A matrix is represented by its extended parameter field address, which is obtained by using the word `'` (tick). For example, `' MY.MATRIX` returns the `xpfa`.
row/col	[row#\-1] or [-1\col#]	A number of words operate on a specified row or column in a matrix. A matrix row is specified by a row number under a -1 under a matrix.xpfa: row#\-1\matrix.xpfa -- A matrix column is specified by a -1 under a column number under a matrix.xpfa: -1\col#\matrix.xpfa $$–$$
vector	xvaddr\sep\d.#el	A vector is a collection of floating point numbers evenly spaced in memory. All matrices and their constituent rows and columns can be represented as vectors, and fast vector operators form the basis of all matrix math operations. A vector is represented by an extended base address xvaddr, a vector element separation value sep, and the 32-bit number of elements in the vector d.#el. xvaddr must be 4-byte aligned; that is, it must be an even multiple of 4 bytes; the heap manager and array and matrix dimensioning words perform this alignment automatically (see `XALIGN`). sep is expressed as a multiple of 4 bytes (e.g., sep=1 means a vector of contiguous floating point numbers, sep=2 means elements are separated by 8 bytes, and so on). The number of elements in the vector is limited only by available memory. A vector may cross one or more page boundaries.

Naming conventions

Hexadecimal (base sixteen) numbers are denoted by the prefix 0x or 0X. The letters and symbols listed below are commonly used in the names of words to help convey their meaning.

Symbol	Meaning
`(`	Words delimited by parentheses are either page-less variations of words, as in `(!)` versus `!` , or subsidiary words, as in (CREATE) versus CREATE .
`,`	Words ending with `,` (comma) are assembler control words. The comma suggests that execution of the word causes code to be compiled into the dictionary. For example, `BEGIN,` ... `UNTIL,` are assembler loop control words analogous to `BEGIN` ... `UNTIL` in high level Forth.
`->`	These are the final two characters of each structure defining word. They suggest the defining nature of the word.
`:`	A word ending with a colon indicates a defining word.
`2`	A word beginning with `2` indicates that it operates on double width 32-bit values.
`D`	The D prefix indicates that a word operates on double numbers (32-bit values). This prefix is also used to distinguish words related to the definitions area of the dictionary (for example, `DP`, `DPAGE`).
`EE`	The `EE` prefix distinguishes words related to the EEPROM area.
`F`	The `F` prefix indicates that a word operates on floating point numbers.
`IO`	`IO` indicates that the word relates to accesses of the Wildcard I/O (input/output) modules.
`M`	An `M` indicates that a word operates on matrices or on mixed double/single number types (for example, `UM/` ).
`N`	The `N` prefix distinguishes words related to the names area of the dictionary (for example, `NP`, `NPAGE`).
`ROW/COL`	Words that operate on a specified row or column in a matrix include `ROW/COL` in their name.
`S`	The S prefix indicates that a word performs an operation involving a scalar (for example, `S*MATRIX`).
`R`	Redefinition words such as R: RCODE .
`U`	The `U` prefix indicates that a word operates on unsigned numbers.
`V`	The `V` prefix distinguishes words related to the variable area (for example, `VP`, `VPAGE`).
`X`	The X prefix indicates that a word operates on extended addresses, or that an extended C-callable header is associated with the definition (as in X: `XCODE` and `XCREATE`).
`\|`	Words delimited by the `\|` (vertical bar) character are uninterruptable operators (for example, `\|>2@\|`). These provide robust behavior even when multiple concurrent tasks or routines are accessing a shared memory location or 32 bit variable.

Attributes

Some glossary entries include an "Attributes" field. The following table presents the meaning of the single-character codes used in the Attributes field of the Main Glossary.

Symbol	Meaning
`C`	Compilation only. The word may be used only during compilation of a colon definition.
`D`	Defining. The word is a defining word.
`I`	Immediate. An immediate word is executed (rather than compiled) even if the interpreter is in compilation mode.
`M`	Multi-programming impact. The word may execute PAUSE and cause a task switch. See the Chapter in this Glossary titled "Words That Disable Interrupts" for a list of routines that call PAUSE.
`S`	Scratchpad impact. The word modifies one or more scratchpad user variables related to floating point math, floating point string/number conversion, or integer string/number conversion. If the word is to be used inside an interrupt service routine that shares the same user area as another program, then the affected scratchpad variables should be saved at the start of the interrupt service routine and restored before the service routine terminates. The words `FP.PUSH`, `FP.POP`, `FP&STRING.PUSH`, and `FP&STRING.POP` are helpful utilities for saving and restoring the affected scratchpad variables; consult their glossary entries for examples of use.
`U`	User. The word is a user value.

This page is about: How to Use Forth Language Data Stack, Forth Software Development, Forth Stack Naming Conventions – How to use the data stack for Forth language software development. Each Forth glossary entry contains a stack comment (or stack picture) that describes the inputs and outputs of the function.