Chapter 15 - A Tour of the User Area

The user area contains parameters that control and configure the operation of QED-Forth. The following table lists the system variables in the order that they appear in the user area, with short-hand comments about their functions. In-depth descriptions of the user variables follow.

To facilitate multitasking, the addresses of the system variables are defined as offsets from a base address designated by the contents of UP (user pointer). Executing UP returns the extended address 8200H\0. A fetch from this address yields a 16-bit address in the common RAM; this is the base address of the user area of the current task. Multiple tasks can be implemented by assigning a separate user area in common RAM to each of the tasks.

The following table lists the user variables, their offsets (in hexadecimal) from the user base address, and a short description. Variable names that are followed by an * (asterisk) can be found in the QED-Forth dictionary, and executing the name leaves the extended address of the user variable on the stack. The number of bytes assigned to each user variable can be inferred from the offsets. For example, we can calculate that DP is a 4-byte user variable by subtracting DP's offset from the offset of the following variable VP.

User variables are created by the defining word USER. At runtime, a user variable fetches the contents of UP, adds an offset to it, and places the address on the data stack under the DEFAULT.PAGE which is 0. You can employ USER to define additional user variables, or to give dictionary names to some of the headerless variables. For example, if you want to be able to access the pointer that is used during integer-to-string conversion, you need to create a definition for the #PTR user variable. The table shows that #PTR has an offset of A2H in the user area, so we can define the user variable as

HEX A2 USER TAB.WIDTH

When #PTR is executed, it will leave its address on the stack, and its contents can be read using the @ (fetch) command.

You may define additional user variables by specifying an offset and executing USER followed by a name of your choice, subject to the constraint that the maximum offset of a user variable is 255. To see how many bytes are already reserved by QED-Forth in the user area, execute #USER.BYTES.

STATUS is the first variable in the user area. Thus executing STATUS puts the base xaddress of the user area on the data stack. This extended base address is used as a task identification xaddress by the multitasking system. STATUS contains a value that indicates whether the task is AWAKE or ASLEEP.

NEXT.TASK contains the 16-bit base address of the next task in the round robin task list. The multitasking executive uses its contents to enter the next task in the loop.

RP.SAVE is the location where the return stack pointer for the task is saved by the multitasking executive. The contents of the registers and the page are saved on the return stack, so knowledge of this stack pointer allows the state of the task to be restored by the multitasking executive.

SERIAL.ACCESS contains a flag that tells the words KEY, EMIT, and ?KEY when they may execute the commands SERIAL GET and SERIAL RELEASE to acquire and give up the current task's control of the serial I/O port. Any of the constants RELEASE.NEVER, RELEASE.ALWAYS, or RELEASE.AFTER.LINE may be stored at this location. The latter is the default; it GETs only at the beginning of a line and RELEASEs only at the end of an interpreted line. This minimizes the time required to GET and RELEASE the serial resource and maximizes the download baud rate.

RELEASE.NEVER ensures that the task that has control of the serial resource (typically the QED-Forth task) maintains control of it. RELEASE.ALWAYS releases control after each character is transmitted and received.

The variables that specify the memory map can be modified by the programmer using standard ! and X! commands.

DP is the definitions pointer, a 32-bit user variable. Initializing it with an X! command sets the xaddress where the code field of the next definition will start. The word HERE leaves the contents of DP on the stack. DPAGE leaves the page of the current dictionary pointer on the stack; its equivalent definition is DP @ (fetch from the high order cell of DP). ALLOT increments the contents of DP by a specified number of bytes, and issues an error message if DP crosses a page boundary during a definition. In general, the definition code of a single word cannot cross a page boundary.

VP is the variable pointer; its contents, which can be initialized with an X! command, specify the next available location in the variable area. VHERE leaves the contents of VP on the stack. The programmer must guarantee that the variable area will always be in modifiable RAM. VALLOT increments the contents of VP by a specified number of bytes, and aborts if a page boundary is crossed. In general, the parameter field of a data structure such as an array or a matrix cannot cross a page boundary.

NP is the name pointer which sets the address where the next header will be compiled. NHERE leaves the contents of NP on the stack. NPAGE leaves the page of NP on the stack; it is equivalent to NP @. An individual header cannot cross a page boundary.

R0 (R-zero) is the 16-bit address of the bottom of the return stack, which must be in common RAM. R0 is used by ABORT to initialize the S register, which is the return stack pointer. The first value on the stack is stored at the two bytes below R0, and the stack grows downward in memory. After R0 is modified, the new value takes effect after the next ABORT or warm restart.

S0 (S-zero) is the 16-bit address of the bottom of the data stack, which must be in common RAM. S0 is used by ABORT to initialize the Y register, which is the data stack pointer. The first value on the stack is stored at the two bytes below S0, and the stack grows downward in memory. After S0 is modified, the new value takes effect after the next ABORT or warm restart.

CURRENT.HEAP holds an extended address that is 1 greater than the last byte in the current heap area. The heap configuration variables START.HEAP, HEAP.PTR, HANDLE.PTR, and FREE.HANDLE are saved in the heap just below CURRENT.HEAP. Below these variables in the heap are the handles. The heap items are allocated at the start of the heap growing upward in memory. A heap is initialized using the IS.HEAP command. A task may access several initialized heaps by simply changing the value of CURRENT.HEAP stored in the user area.

UPOCKET holds the 16-bit address of POCKET, a 33-byte (minimum) buffer used by WORD. The pocket buffer must reside in common RAM. POCKET places the contents of UPOCKET on the stack under the default page.

UPAD contains the extended address of a scratchpad area called PAD. The system uses the 32 bytes below PAD for string conversion of integers and floating point numbers; the bytes above PAD are available for the user's program. PAD places the contents of UPAD on the stack. The PAD buffer can be on any page or in common memory, but it may not cross a page boundary.

UTIB contains the extended address of the start of the terminal input buffer (TIB). If the contents of the user variable BLK equal 0, characters from the current line of the input stream are stored in the TIB while they await interpretation. The FORTH word TIB returns the contents of UTIB. The TIB buffer can be on any page or in common memory, but it may not cross a page boundary.

Vocabularies allow the linked list of names in the dictionary to be structured like a tree with branches, where each branch is a separate vocabulary. The word FIND starts at a specified point in the linked list at the outer edge of a branch (i.e., at the last word defined in a specified vocabulary), and searches the list until either the sought-after word is found or the end of the linked list is encountered. There are two benefits to having this branched structure. First, dictionary searching is faster if fewer words have to be searched. Infrequently accessed words, such as those associated with the in-line assembler, can be placed in a separate vocabulary outside of the main linked list, so the assembler names do not have to be traversed on each search. Second, vocabularies allow the programmer to assign different meanings to identical names. The programmer can control which meaning is found by invoking the appropriate vocabulary.

The defining word VOCABULARY allocates a 32-bit xhandle in the variable area and creates a child word that, when executed, stores the address of the xhandle into the user variable CONTEXT. The xhandle contains the extended name field address (xnfa) of the last header defined in that vocabulary. The user variable CONTEXT tells the dictionary search word FIND which vocabulary to search first. Thus CONTEXT specifies the search vocabulary.

The user variable CURRENT contains a vocabulary xhandle that specifies which vocabulary the next defined word should be appended to. FIND searches the CURRENT vocabulary after searching CONTEXT. As each new word is created, CREATE updates the handle pointed to by CURRENT so that it points to the xnfa of the latest word defined.

Executing CURRENT X@ yields the vocabulary handle of the current vocabulary, and executing an additional X@ yields the address of the count byte in the header of the latest word defined. Thus an equivalent definition of LATEST is

: MY.LATEST     ( -- xnfa.of.latest.word.defined )
    CURRENT X@ X@
;

Executing ID. will then print the name of the LATEST routine defined.

QED-Forth implements three vocabularies: FORTH, ASSEMBLER, and EDITOR. Their 32-bit handles (VFORTH, VASSM, AND VEDITOR, respectively) are in the user area. The FORTH vocabulary holds the great majority of kernel words. The ASSEMBLER vocabulary holds the assembler control and mnemonic words, and the EDITOR vocabulary is empty in the current version of QED-Forth.

QED-Forth allows the programmer to specify the behavior of several error handling, I/O, and debugger routines by storing the xcfa of the routine in the user area. A COLD restart always initializes these handles to hold the xcfa of the default routines.

To post a customized ABORT action, store the extended code field address of the routine into the UABORT user variable and set the user variable CUSTOM.ABORT to true. The default abort action is (ABORT). The customized abort action may end with a call to (ABORT), if desired.

The ERROR handler responds to all errors detected by QED-Forth (data stack underflow, missing delimiter, etc.) If the user variable CUSTOM.ERROR is false, the standard system error routine (ERROR) executes when an error occurs, and most of the errors end with a call to ABORT (which itself can be revectored as described above). To post a customized error handler, store the extended code field address of the handler routine into the UERROR user variable and set the user variable CUSTOM.ERROR to true. Appendix B explains error handling in detail.

The serial I/O words KEY, EMIT, and ?KEY call the routines whose xcfa's are stored at UKEY, UEMIT, and U?KEY, respectively. To modify these routines (for example, to use a UART instead of the standard serial port), use X! commands to store the extended cfa's of your routines into these user variables.

UREAD/WRITE contains the xcfa of the READ/WRITE routine used by the blocks interface words to read and write mass memory. The default routine implements a "RAM disk" that allows an area of RAM to be used as if it were a disk drive. To interface a floppy or hard drive to the QED-Forth system, you would install the xcfa of a hardware-dependent read/write routine in this user variable. Before using the ramdisk and mass memory interfaces, IS.RAMDISK and BLOCK.BUFFERS must be executed.

TRACE.ACTION holds the xcfa of the first action that is executed each time the compiled trace routine executes. The trace routine is compiled before each routine in the dictionary if the TRACE variable is ON during compilation. The default trace action, installed after a COLD restart and by DEFAULT.TRACE.ACTION, is the do-nothing NO.OP routine. Use IS.TRACE.ACTION to install the xcfa of a customized trace action in this user variable.

TAB.WIDTH holds the number of spaces that are placed in the input stream to replace the tab character (ascii 9). The default value is 4. Tabs are convenient for formatting source code; QED-Forth replaces them by spaces so that the tabs will be treated as valid delimiters between words.

The value in WARM.START is checked every time the standard restart routine runs (e.g., after a reset or power up, after executing COLD or WARM, etc.) If the contents of WARM.START equal the pattern 1357H, then the restart routine assumes that the user area is properly initialized, and a warm restart is performed. If the pattern is not present, a cold restart is performed. Because the user area is typically in battery backed RAM, resets including power-on resets usually detect the correct pattern and initiate a warm restart.

WIDTH holds the number of characters that CREATE saves in the header of a newly defined word. A cold restart sets width to its default value of 4. Larger values of WIDTH reduce the incidence of non-unique names, but also increase the memory space required by each header.

CHARS/LINE contains a number specifying the maximum number of characters that can be handled by the interpreter's line input word QUERY. The default is decimal 90 characters. Make sure that the length of the TIB is large enough to handle CHARS/LINE characters; the length of the default TIB is 96 characters.

BASE contains a number indicating the current number base which is used to convert input strings to binary, and to convert binary numbers to numeric output strings. The words DECIMAL and HEX set this quantity, and it may also be altered via a ! command.

DEBUG holds a flag that, if true, enables embedded debugging features in the kernel or in user-defined words. If DEBUG is ON, the system prints the stack contents after every carriage return while in console mode, the trace instruction prints the name and stack result of each traced word, index checking is performed by the array and matrix words, and stack depth checking is performed by the word NEEDED.

UNIQUE.MSG contains a flag that, if true, enables the printing of the error message "<name> isn't unique" when a non-unique definition is encountered by the interpreter. Turning the UNIQUE.MSG flag OFF disables the printing of the message.

The mass memory interface deals with "blocks" of memory with 1024 bytes per block. Both the mass memory device and the files being edited are divided into 1K blocks. Each block in a file is assigned a 16-bit block number starting at 0, and each block in mass memory is assigned a 32-bit block number so that very high capacity hard disks (up to 4 million megabytes!) can be managed.

To use the mass memory interface, at least 2 contiguous block buffers must be allocated in RAM (the block buffers may cross a page boundary). The block buffers hold data that is read from the mass memory device, are modified by editing commands, and are subsequently written to the mass memory to save to the disk any changes that were made.

UFIRST holds FIRST, a 32-bit extended address of the first byte of the block buffers.

ULIMIT holds LIMIT, a 32-bit extended address which is one greater than the last byte in the last block buffer.

USE holds the starting xaddress of the block buffer to be used next, which is the least most recently accessed buffer.

PREV holds the starting xaddress of the most recently accessed block buffer.

BLK is a 16-bit user variable that holds the block number in the current file. If BLK = 0, the TIB is the source of input commands (block#0 in any file cannot be loaded). If BLK is non-zero, the contents of BLK specify the mass memory block that contains the input stream to be interpreted.

OFFSET is a 32-bit quantity equal to the difference between the physical block number on the disk and the block number in a particular file.

SCR is a 16-bit variable that holds the number of the last block listed by the LIST command.

STATE contains a flag that, if 0, indicates that QED-Forth is in execution mode, and, if nonzero, indicates compilation mode. The word [ sets STATE to the execution mode, and the word ] sets it to compilation mode. Higher level words call [ and ] to change the state. For example, the word : calls ] to enter the compilation mode, and ; calls [ to re-establish the execution mode.

The CSP variable holds the "check stack pointer" value which is used by the system to flag an error if there is a net change in the stack depth while a high level or assembly code definition is being compiled. The "Definition incomplete!" error message is printed if an error is detected.

>IN contains a 16-bit offset from the start of the TIB to the position of the next character to be interpreted in the input stream. >IN is reset to 0 by QUERY, and is advanced by WORD.

#TIB contains the number of characters received from the serial port by the last execution of QUERY. QUERY calls EXPECT and, immediately after EXPECT executes, transfers the contents of SPAN into #TIB.

SPAN contains the number of characters received from the serial port by the last execution of EXPECT.

CUSTOM.ERROR contains a flag that, if true, indicates that QED-Forth should execute a user-supplied error routine when any error is encountered. If the user sets CUSTOM.ERROR true, the user should store the extended code field address of the error routine at UERROR in the user area. If CUSTOM.ERROR is false (the default condition), then the default error routine (ERROR) will execute when an error is encountered.

CUSTOM.ABORT contains a flag that, if true, indicates that QED-Forth should execute a user-supplied abort action. If the user sets CUSTOM.ABORT true, the user should store the extended code field address of the abort routine at UABORT in the user area. If CUSTOM.ABORT is false (the default condition), then the default action is (ABORT).

CR.BEFORE.MSG? contains a flag that, if true, enables the printing of a carriage return before any error message. Turning CR.BEFORE.MSG? OFF (the default condition) suppresses the carriage return. This is useful in smoothing the download process. The optimal host terminal program waits for a linefeed character (ascii 10) before transmitting the following line of text; this allows QED-Forth the time it needs to interpret the input stream. If an error occurs and the 68HC11 is allowed to print a carriage return and linefeed, then the host terminal will start to send the next line of text while the 68HC11 is sending the error message, and the text will not be received. Suppressing extra carriage returns during the download avoids this problem.

If the QUIET flag is true, BEEP (called by the error routine) does not send the audible bell character. If QUIET is false (the default condition), then all error messages and warnings send the bell character to the host to alert the programmer.

The XMIT.DISABLE flag is set and reset by EXPECT in response to incoming XOFF (ascii 19) and XON (ascii 17) characters, respectively. It is not used by the QED-Forth system to control output, but is available to implement serial I/O handshaking in user-defined programs. Note that it is still useful to set up the host terminal to send XOFF and XON characters; they will disable and enable output in any word that contains PAUSE.ON.KEY, including the kernel commands DUMP, DUMP.INTEL, DUMP.S1, DUMP.S2, WORDS, and the matrix printing routines. See the glossary entry for PAUSE.ON.KEY.

#PTR (number pointer) is used by the system during pictured integer-to-string conversion. It typically points below PAD, where numeric conversion is performed.

The floating point and numeric conversion scratchpad variables starting at #PTR up to and including $ADDR.PTR are saved by FP&STRING.PUSH and restored by FP&STRING.POP. The floating point scratchpad variables starting at FP.ERROR up to and including DATA.SP.SAVE are saved by FP.PUSH and restored by FP.POP. These routines are intended for use inside interrupt service routines to prevent corruption of the contents of the scratchpad variables. Consult their glossary entries for complete descriptions of their use.

FP.ERROR contains the error status of the most recent floating point operation. If the contents are 0, there was no error, while contents of 1 indicate underflow and -1 indicates overflow. The QED-Forth words UNDERFLOW and OVERFLOW set FP.ERROR to 1 and -1, respectively. Errors detected in the floating point math operations do not cause an ABORT; if the programmer desires, this can be accomplished by polling the FP.ERROR variable and executing an ABORT with an appropriate message if it is non-zero.

FTEMP0 and FTEMP1 are scratchpad variables used by the basic floating point math operations.

RETURN.SP.SAVE and DATA.SP.SAVE are temporary variables that hold the values of the return and data stack pointers, respectively, when a basic floating point math operator is entered. The saved values facilitate rapid "bailing out" of the operation if an error condition is detected.

MANTISSA, EXPONENT, EXPONENT.SIGN, and OK? are temporary scratchpad variables used by the floating point string-to-number and number-to-string conversion routines.

DEFAULT.FORMAT is a single-byte user variable whose contents specify the format for the F. printing word. The contents of DEFAULT.FORMAT are set by the words FIXED SCIENTIFIC and FLOATING . The default format is FLOATING.

$ADDR.PTR holds a temporary pointer to the current character during floating point numeric string conversion.

F+COUNT is a 16 bit variable that holds the number of F+ or F- operations that have been performed since the counter was initialized to 0. F*/COUNT performs the same function for F* and F/ operations. The kernel word BENCHMARK: uses these counters to report the number of floating point operations required to perform a specified function.

RANDOM# is the 16-bit mantissa of the last random number generated by the pseudo-random number generator. It can be initialized to generate a reproducible stream of pseudo-random numbers.

MAX#DIMENSIONS contains a value that is used by ARRAY: to allocate space for a parameter field in the variable area. The default value, set by a cold restart and by executing FP.DEFAULTS, is 4. If a different value is desired, it should be set before any arrays or matrices are defined, and maintained throughout the execution of the program. Erratic operation can result if an array is defined with one value of MAX#DIMENSIONS and operated on (copied, deleted, etc.) when a larger value is in effect.

RIGHT.PLACES (default = 3) and LEFT.PLACES (default = 4) specify the number of decimal digits to the right and left of the decimal point, respectively, when a floating point number is displayed in FIXED format.

MANTISSA.PLACES (default = 3) specifies the number of decimal digits to the right of the decimal point when a floating point number is displayed in SCIENTIFIC format, and also determines the field width in FLOATING format.

TRAILING.ZEROS contains a flag that, if OFF, suppresses the display of trailing zeros. The default state is OFF.

If NO.SPACES is ON, leading and trailing spaces are stripped from a displayed floating point number. The default state is OFF.

If FILL.FIELD is on, FIXED format numbers are padded out with spaces so that their decimal points line up when the numbers are printed in tabular columns. The default state is OFF.

The default states of the preceding 7 user variables are initialized upon a cold startup or by executing FP.DEFAULTS.

At runtime, the values of the local variables are pushed to a stack frame on the return stack. The variables LP, PARAM.SAVE, and LOCALS.RTN.SAVE are used to set up the return stack frame when the code compiled by LOCALS{ executes, and to remove the return stack frame when the definition terminates.

The four user variables DEBUG, SINGLE.STEP, DUMP.REGISTERS, and TRACE configure QED-Forth's debugging system. The DEBUG flag was described above.

If the user variable TRACE is true, the QED-Forth compiler places a trace instruction before every compiled call in the definitions area.

If the DEBUG flag is true, each compiled trace instruction prints the name of the command and the stack picture it produces. This gives a line-by-line display of the operation of the traced word.

The trace instruction also checks the DUMP.REGISTERS flag; if it is true, the contents of the registers (D, IX, IY, SP, PC, and CCR) are printed.

If SINGLE.STEP is true, BREAK is called after every traced instruction to allow the programmer to examine memory locations, change stack items, etc. If SINGLE.STEP is false, the traced program will enter the BREAK mode upon receipt of any keystroke. A single CR alone on a line continues the trace, and ABORT returns to the QED-Forth interpreter.

TRACE.INDENT holds the current number of spaces that each trace instruction should be indented. A trace of a : command increases the indentation by 3, and ; decreases it by 3. The result is a visual display of the nesting of the traced words.

PAGE.CHANGE.COUNTER is initialized to 0 by FIND and incremented every time a page change is required during the search of the dictionary. An COLD restart is performed if more than 255 page changes are required; this indicates that the linked list of names in the dictionary has become corrupted.