Home Vocabulary: Test & misc. words


Debugging

CLS ( -- ) Clears the console. Typical usage {{ CLS }}.
BUG ( <name> -- ) Invokes the high level debugger. Opens the source file to the start position and makes sure target is in test mode.
TRACE ( <name> -- ) Invokes the low level debugger. Opens the debugger window and displays the disassembled code.
LOADLABELS ( -- ) Uploads addresses from the target's binding table to enable low level debugging.
FSEND ( <filename> -- ) Sends a bytecode file to the target and evaluates it.
RESET ( -- ) Asserts the target board's reset line for ½ second. Typically by dropping the DTR line.
LOADFLASH ( -- ) On processors that support JTAG or SPI loading, load the ROM image into the processor's program flash.

The watch list is used by the watch window to display target data in real time. The watch window can call a Forth word and display the result, or it can monitor memory. For memory watching, ( address format string" -- ) parameters are needed. Address is the target memory address to watch, format is how it's displayed, and string" is a quote-delimited description. The format number is two bytes: the upper byte is the display format and the lower byte is the byte count. Formats are: 0=byte, 1=16bit-LE, 2=16bit-BE, 3=32bit-LE, 4=32bit-BE, 5=ASCII.

Example: 0xC000 0x102 WATCHDATA" Location C000 = " adds an item to the watch list that fetches 2 bytes from data memory location 0xC000 and displays the data as a 16-bit little-endian number.

CLEARWATCH ( -- ) Clears the watch list.
ADDWATCH ( <name> -- ) Adds a word to the watch list.
WATCHCODE" ( address format string" -- ) Adds a code memory watch record to the watch list.
WATCHDATA" ( address format string" -- ) Adds a data memory watch record.
WATCHREG" ( address format string" -- ) Adds a register watch record.
WATCHEE" ( address format string" -- ) Adds a non-volatile memory watch record.

The debugger can use TCP/IP instead of a serial connection. The program HOST.EXE runs on a remote Windows PC and serves as a gateway. The remote PC talks to the target board through a serial link.

IP? ( -- ) Displays the current IP address of the remote server.
IP= ( <string> -- ) Sets the current IP address of the remote server. Ex: IP= 123.45.67.89
IP: ( -- u ) Fetches the current IP address of the remote server.

Token list rebuilding words

When you build a ROM and TSAVE a token file, that token file can be FLOADed to restore token assignments. This file is the interface between your application and your (or a user's) add-on code. You can supply this file to enable the end user to modify the application. These words modify fields in the words header and may be used by typical source code.

NEW-IMAGE ( -- ) Clears the image and pointers.
NOFILES ( -- ) Clears the file ID list.
ADD-TOKEN ( xt spos sid dt cfa <name> -- )
  Adds a token header to the current vocabulary.
xt = token#.
spos, sid = file position and source file id.
dt = datatype cfa = image address.
ADDFILE ( id# <filename> -- ) Adds a filename to the file ID list. See NOFILES.
DATATYPE ( x -- ) Stores to the datatype field of the last created header.
>FLAGS ( x -- ) Stores x to the flags field of the last created header.
>LITERAL ( x -- ) Stores x to the literal field of the last created header.
C( ( string) -- ) Stores a comment string, up to 32 characters long and delimited by ')', to the comment field of the last created header.

Host miscellaneous

{{ ( ? -- ? ) Interpret the input stream until }}. Uses only HOME in the search order and assumes there is no compilation.
}} ( -- ) Ends a {{ ... }} phrase. Must be on the same line as {{.
(( ( -- ) Skip source until )) is encountered.
// ( -- ) Skips source until end of line. Like the C version.
\ ( -- ) Skips source until end of line.
\S ( -- ) Skips the rest of the file.
(SEE) ( <name> -- ) Decompiles a host Forth word.
_DBG ( <name> -- ) Starts Win32forth's debugger, includes Forth at the top of the search order. To use this, you must set OldStartup to 1 and recompile the Firmware Studio source. This is good for debugging Firmware Studio itself.
_DEBUG ( <name> -- ) Similar to _DBG but doesn't start debugger until <name> is executed.
WARNING ( -- addr ) Flag: True if redefinitions cause a warning message.
NOSLACK ( -- addr ) Flag: True if warnings abort compilation.
OFF ( addr -- ) Stores false (0) to address.
ON ( addr -- ) Stores true (-1) to address.
BYTE-JOIN ( lo hi -- x ) Joins two bytes to form a 16-bit value.
BYTE-SPLIT ( x -- lo hi ) Splits a 16-bit value to form two bytes.
WORD-JOIN ( lo hi -- x ) Joins two 16-bit values to form a 32-bit value.
WORD-SPLIT ( x -- lo hi ) Splits a 32-bit value to form two 16-bit values.
SHELL ( -- ) Opens a DOS window.