Chapter 4 The Stacks

Scope

Fig-Forth v2 uses two stack configurations to pass all parameters, maintain program flow and error correcting status. As with their machine implemented versions, all stacks operate as a last-in, first-out word buffer.

The primary stack is called the Parameter Stack, commonly referred to by the terms TOS or an Nth item value. (TOS=Top Of Stack) This stack is the one most commonly diagrammed for definition functions, and uses the free space between the current dictionary tail and the end of effective memory. The number of items on this stack can be found by executing DEPTH, and it is on this stack where all kernel routines expect that any values, words or addresses will be located at the time of execution. This stack is equivalent to the CPU heap, or the SS:SP registers in machine level coding.

The second stack is called the Return or Control stack, where the kernel routines save instruction pointer addresses and loop control variables. The return stack should be preserved across user defined words or incorrect operation will result. Serious return stack errors may even cause the kernel to cease operation by branching to a point of uninitialized memory and executing random instructions.

For the purposes of programming in Fig-Forth the Return Stack has a maximum depth of 512 items, with a typical system overhead of 80 items. Exceeding the Return Stack depth will destroy, in order, the Text Input Buffer and then the Parameter Stack's data. If a greater depth is required the following process can be used, though such action is not expected.

512 S0 -! SP! 512 TIB -! -- this increases the return stack by 256 items, resets

    the parameter stack and then sets a new TIB area.

Using this process all further functions of the compiler and operating programs will use the new setting, until and unless the COLD word is run. Using COLD will reset the compiler to its default limits, such that if such a change is required by a program it should be the first process performed.

Stack Operations

As is common to most Forth languages, Fig-Forth v2 contains a great deal of stack manipulation words. Several of these functions are standard to all versions of Forth, while many are specific to Fig-Forth v2 itself. The following index gives an over-view;

Table 4-1. Stack Operations

word

stack does

DROP

n --

Removes the top stack word

2DROP

n1 n2 --

Removes the top two stack words

3DROP

n1 n2 n3 --

Removes the top 3 stack words.

4DROP

n1 n2 n3 n4 --

Removes the top 4 stack words.

DUP

n -- n n

Duplicates the top word.

-DUP

n -- n | n n

Duplicates the top word if non-zero

2DUP

n1 n2 -- n1 n2 n1 n2

Duplicates the top two words

NIP

n1 n2 -- n2

Removes the second word

2NIP

n1 n2 n3 -- n3

Removes the 2nd and 3rd word.

3NIP

n1 n2 n3 n4 -- n4

Removes the 2nd, 3rd and 4th word.

4NIP

n1 n2 n3 n4 n5 -- n5

Removes the 2nd, 3rd, 4th and 5th word.

DNIP

n1 n2 n3 n4 -- n3 n4

Removes the 3rd and 4th item. (Or second double word.)

PICK

n -- (n)

Copies the Nth stack word to the top of the stack.

PLEAT

n1 n2 -- n1 n1 n2

Duplicates the second word.

2PLEAT

d1 d2 -- d1 d1 d2

n1 n2 n3 n4 -- n1 n2 n1 n2 n3 n4

Duplicates the second double word.

PUT

n1 n2 --

Replaces the nth stack word as specified by n2 with n1.

R

-- n

Copies the top Return Stack word to the Parameter Stack.

2R

-- n1 n2

Copies the top two Return Stack words to the Parameter Stack.

>R

n1 --

Moves a word from the Parameter Stack and places it on the Return Stack.

R>

-- n1

Moves a word from the Return Stack and places it on the Parameter Stack.

RDROP

--

Drops the top Return Stack word.

ROLL

n4 n3 n2 n1 n -- n3 n2 n1 n4

Pulls the Nth word from the stack and makes it the top. N is top item, example n=4.

-ROLL

n4 n3 n2 n1 n -- n1 n4 n3 n2

Inserts the second word into the Nth position of the stack. N top, example n=4.

ROT

n1 n2 n3 -- n2 n3 n1

Pulls the 3rd word from the stack and makes it the top. (3 ROLL)

-ROT

n1 n2 n3 -- n3 n1 n2

Inserts the top word into the third position. ( 3 -ROLL)

2ROT

d1 d2 d3 -- d2 d3 d1

Pulls the 3rd double word item and places it on top.

-2ROT

d1 d2 d3 -- d3 d1 d2

Inserts the top double word item into the third position.

RPICK

n -- [n]

Copies the Nth Return Stack item to the Parameter Stack. N is TOS.

SWAP

n1 n2 -- n2 n1

Exchanges the top stack word with the second one.

2SWAP

n1 n2 n3 n4 -- n3 n4 n1 n2

Exchanges words 3 and 4 for words 1 and 2. Or two double word values.

TUCK

n1 n2 -- n2 n1 n2

Copies top item to third item.

+UNDER

n1 n2 n3 -- n1+n3 n2

Adds the top word to 3rd word on the stack.

+2UNDER

d1 d2 d3 -- d1+d3 d2

Adds top double word to the 3rd double word.

UNLOOP

--

drop index & limit of loop (or 2 control stack items)

As can be seen from the above table, controlling the stack data order can be a complex process. Even given this lengthy collection of pre-defined words, there will be times when they are not sufficient. One example of this would be a Quad word rotate (bring the third quad number to the top) which can be achieved by the following definition;

          : QROLL 4 0 DO 12 ROLL LOOP ; -- A quad rotate.

Stack Controls

As shown in the Scope section of this chapter, Fig-Forth v2 uses specialized system variables for controlling its internal stacks. Though your program may never require these values, I list them here for your information. The modification or use of these values can be found in the chapter on Advanced Procedures and Functions.

Table 4-2. Stack Controls

word

stack operation

CS@

-- seg

Returns the segment of the Kernel Code.

DEPTH

-- n

Returns the number of items on the Parameter Stack.

DS@

-- seg

Returns the segment of the Dictionary Space.

R0

-- adr

System variable that holds the WARM start value of the Return Stack.

RP!

--

Resets the Return Stack to the value in R0

RP@

-- adr

Returns the value of the Return Stack pointer.

S0

-- adr

System variable that holds the WARM start value of the Parameter Stack.

SP@

-- adr

Returns the value of the Parameter Stack pointer.

SP!

--

Resets the Stack Pointer to the value in S0

Return to Contents.   Next Chapter.   Previous Chapter.