Forth v4.4 Functions for C Debugging

If you are programming the QED Board or the QVGA Controller using the Control C compiler and its IDE (Integrated Development Environment), you will find the interactive debugging functions listed here useful.

The Forth language functions described here 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. If you program exclusively in the QED-Forth language won't need these functions, but if your application program is written in C, these functions are very useful.

For help in understanding the notation used in the following function definitions, consult the description of stack symbols, abbreviations and naming conventions.

The following glossary entries are alphabetized in ASCII Order: =ABCDEFGHIJKLMNOPQRSTUVWXYZ

=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> -- )

A low-level function inserted by the "Make" utility in the .TXT download file created by the Control C compiler. When properly inserted in a QED-Forth function, enables interactive calls to C functions that were declared using the _Q keyword. 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 "pascal" type function (i.e., a function declared using the _Q or _pascal keyword) that has been compiled by the Control C compiler. 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 )

A low-level function inserted by the "Make" utility in the .TXT download file by the Control C compiler. 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-C 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-C-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-C 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-C 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.

FP_CtoQ ( r1 -- r2 | r1 is in ANSI C format; r2 is in QED format )

Converts the ANSI/IEEE-standard formatted input floating point number into the QED-Forth floating point format. Converts denormalized input numbers to zero; that is, if the biased exponent = 0, the returned QED-formatted floating point number = zero. NAN (not a number) inputs are converted to +/- infinity depending on their sign bit. The least significant bit (lsb) of the mantissa is not rounded, resulting in up to 1 lsb error during the conversion.

FP_QtoC ( r1 -- r2 | r1 is in QED format; r2 is in ANSI C format )

Converts the QED-Forth formatted input floating point format into an ANSI/IEEE-standard formatted floating point number.

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 0x0000 on page 0x04. Each compiled C program must contain one and only one definition of the main() function.

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

Prints the input ANSI-C floating point parameter using the format specified by the most recent execution of FIXED, SCIENTIFIC, or FLOATING.