Forth v6 Functions for C Debugging

These are Forth v6 words that are used for C debugging.

This glossary summarizes Forth library functions and keywords that assist those who are doing software development on Mosaic's PDQ Board or PDQ Board Lite in the C language using the GNU C (GCC) compiler via the Codeblocks-based IDE+. These keywords can be interactively typed at the terminal and interpreted by the QED-Forth debugger and operating system to assist in the calling and debugging of C functions. In general, those who program exclusively in the QED-Forth language will not use these functions.

=CHAR ( [addr] or [xaddr] <name> -- )

=CHAR is a QED-Forth function that acts as an interactive assignment operator. It is used in the form:

<destination>  =CHAR  <char_specifier>

where <destination> is a 16-bit address left on the data stack by a variable name, or a 32-bit xaddress left on the data stack by a FORTH_ARRAY element. <char_specifier> is either a valid number or a variable name or FORTH_ARRAY element that contains a byte. =CHAR assigns the byte specified by the right-hand-side (RHS) to the memory location specified by the left-hand-side (LHS). The syntax is similar to a C assignment statement.

=FLOAT ( [addr] or [xaddr] <name> -- )

=FLOAT is a QED-Forth function that acts as an interactive assignment operator. It is used in the form:

<destination>  =FLOAT  <float_specifier>

where <destination> is a 16-bit address left on the data stack by a variable name, or a 32-bit xaddress left on the data stack by a FORTH_ARRAY element. <float_specifier> is either a valid floating point number or a variable name or FORTH_ARRAY element that contains a floating point number. =FLOAT assigns the float specified by the right-hand-side to the memory location specified by the left-hand-side. The syntax is similar to a C assignment statement.

=INT ( [addr] or [xaddr] <name> -- )

=INT is a QED-Forth function that acts as an interactive assignment operator. It is used in the form:

<destination>  =INT  <integer_specifier>

where <destination> is a 16-bit address left on the data stack by a variable name, or a 32-bit xaddress left on the data stack by a FORTH_ARRAY element. <integer_specifier> is either a valid number or a variable name or FORTH_ARRAY element that contains an integer. =INT assigns the integer specified by the right-hand-side to the memory location specified by the left-hand-side. The syntax is similar to a C assignment statement.

=LONG ( [addr] or [xaddr] <name> -- )

=LONG is a QED-Forth function that acts as an interactive assignment operator. It is used in the form:

<destination>  =LONG  <long_specifier>

where <destination> is a 16-bit address left on the data stack by a variable name, or a 32-bit xaddress left on the data stack by a FORTH_ARRAY element. <long_specifier> is either a valid number or a variable name or FORTH_ARRAY element that contains an long. =LONG assigns the long specified by the right-hand-side to the memory location specified by the left-hand-side. The syntax is similar to a C assignment statement.

C$>COUNTED$ ( xaddr1 -- x$addr2 )

Converts the specified null-terminated string at xaddr1 into a Forth-style counted string at x$addr2 with the count in the first byte and the non-null-terminated string in the remaining bytes. x$addr2 is the 32-bit address of PAD which is where the converted counted string is located. Note that the size of the PAD buffer puts a limit on the string size; the input string length should be less than 86 bytes.

See also STRINGMOVE() and PAD.
Pronunciation: "c-string-to-counted-string"

CALL.CFN ( xaddr <input_parameter_list> -- )

When properly inserted in a QED-Forth function, enables interactive calls to C functions. CALL.CFN expects on the data stack a 32-bit xaddress representing the execution address of the function to be called. CALL.CFN removes from the input stream a list of comma-delimited parameters terminated by the ) character. It then sets up the proper stack frame for a C function. CALL.CFN calls the designated function, then prints the return values (passed in the D and Y registers):

in the current number base as two 16-bit integers;
as a 32-bit hexadecimal number; and,
as a floating point number.

It is up to the programmer to decide which (if any) of these return value summaries is relevant based on the declared type of the called function's return value.
Pronunciation: "call-c-function"

CHAR ( <name> -- char )

CHAR is a QED-Forth function that examines the next token; if it is a valid number such as 5 or 3.2, CHAR simply converts it to the nearest 8-bit byte. There is an unchecked error if the input is not in the range 0-255 (unsigned char) or -128 to _127 (signed char). If the next token is a named 16-bit address (such as a variable name) or a 32-bit xaddress (such as a FORTH_ARRAY element xaddress), CHAR extracts the 8-bit contents stored at the specified memory location. CHAR is also used to specify the type of an input parameter when interactively calling a function.

CHAR* ( <name> -- char )

CHAR* is a QED-Forth function that examines the next token; if it is a named 16-bit address (such as a variable name) or a 32-bit xaddress (such as a FORTH_ARRAY element xaddress), CHAR* extracts the 16-bit pointer stored at the specified memory location, and in turn extracts the 8-bit byte pointed to by the pointer.

DO[] ( addr <input_parameter_list> -- xaddr )

When properly inserted in a QED-Forth function, enables interactive examination and modification of FORTH_ARRAY elements. Expects on the data stack a 16-bit address representing the pfa (parameter field address) of a FORTH_ARRAY. DO[] removes from the input stream a row specifier, a comma, a column specifier, and a terminating ]. It leaves on the stack the 32-bit xaddress of the specified element in the specified FORTH_ARRAY.
Pronunciation: "do-brackets"

FLOAT ( <name> -- r | r is an ANSI floating point number )

FLOAT is a QED-Forth function that examines the next token; if it is a valid integer or QED-formatted floating point number such as 5 or 3.2, FLOAT simply converts it to an ANSI-formatted floating point number. If the next token is a named 16-bit address (such as a variable name) or a 32-bit xaddress (such as a FORTH_ARRAY element xaddress), FLOAT extracts the 32-bit (float) contents stored at the specified memory location. FLOAT is also used to specify the type of an input parameter when interactively calling a function.

FLOAT* ( <name> -- r | r is an ANSI floating point number )

FLOAT* is a QED-Forth function that examines the next token; if it is a named 16-bit address (such as a variable name) or a 32-bit xaddress (such as a FORTH_ARRAY element xaddress), FLOAT* extracts the 16-bit pointer stored at the specified memory location, and in turn extracts the 32-bit float pointed to by the pointer.

FPtoString ( r -- addr | r is an ANSI floating point number )

Converts the specified ansi input floating point number to a null-terminated ascii string, and returns the 16-bit address of the string. If the conversion fails, returns 0. The specified number is converted into one of three formats: FIXED, SCIENTIFIC, or FLOATING. FLOATING format is the default after a COLD restart.

INT ( <name> -- n )

INT is a QED-Forth function that examines the next token; if it is a valid integer or floating point number such as 5 or 3.2, INT simply converts it to the nearest integer. If the next token is a named 16-bit address (such as a variable name) or a 32-bit xaddress (such as a FORTH_ARRAY element xaddress), INT extracts the 16-bit contents stored at the specified memory location. INT is also used to specify the type of an input parameter when interactively calling a function.

INT* ( <name> -- n )

INT* is a QED-Forth function that examines the next token; if it is a named 16-bit address (such as a variable name) or a 32-bit xaddress (such as a FORTH_ARRAY element xaddress), INT* extracts the 16-bit pointer stored at the specified memory location, and in turn extracts the 16-bit integer pointed to by the pointer.

LONG ( <name> -- d )

LONG is a QED-Forth function that examines the next token; if it is a valid number such as 5 or 1234567 or 453.2, LONG simply converts it to the nearest 32-bit long number. If the next token is a named 16-bit address (such as a variable name) or a 32-bit xaddress (such as a FORTH_ARRAY element xaddress), LONG extracts the 32-bit (long) contents stored at the specified memory location. LONG is also used to specify the type of an input parameter when interactively calling a function.

LONG* ( <name> -- d )

LONG* is a QED-Forth function that examines the next token; if it is a named 16-bit address (such as a variable name) or a 32-bit xaddress (such as a FORTH_ARRAY element xaddress), LONG* extracts the 16-bit pointer stored at the specified memory location, and in turn extracts the 32-bit long pointed to by the pointer.

MAIN ( -- )

Executes the main() function which is located at address 0x8000 on page 0x00. Each compiled C program must contain one and only one definition of the main() function. You can type MAIN at your terminal to interactively invoke your C program. You can also use MAIN as the autostart routine for your instrument; see the glossary entries for AUTOSTART: and PRIORITY.AUTOSTART:

MAIN2 ( -- )

Executes the function which is located at address 0x8000 on page 0x20 in the 9S12 (HCS12) processor’s on-chip flash memory. This utility function is rarely used; it is provided to simplify access to applications or libraries that are moved to the processor’s on-chip flash.

PrintFP ( r -- | r is an ANSI floating point number )

Prints the input floating point parameter using the format specified by the most recent execution of FIXED, SCIENTIFIC, or FLOATING. PrintFP is a synonym for the Forth function F.