C v4.4 Interactive Debugger Glossary

Software development in C uses the Mosaic IDE Integrated Development Environment. The IDE provides a full-featured text editor, ANSI C compiler, and customized terminal for rapid code downloads and interactive debugging sessions with the 68HC11 processor on the controller board. This glossary summarizes functions and keywords that can be interactively typed at the terminal and interpreted by the QED-Forth debugger and operating system.

Note that Forth tokens are delimited by spaces, and the tokens themselves may contain any printable non-space character, including parentheses, commas, periods, and exclamation points, etc. Also note that Forth is case-insensitive, so that any keyword can be typed in all capitals, all small letters, or any combination.

To improve the readability of this glossary, all of the QED-Forth interactive debugger library functions are CAPITALIZED to distinguish them from the type parameters that specify the input and output parameters. This is especially important for glossary entries such as INT, where the name of the QED-Forth function is spelled the same as the type designator int that we use to describe the input and output parameters.

Many of the entries in this glossary refer to entries in the C V4.4 Function Glossary. For example, the interactive QED-Forth function PRIORITY.AUTOSTART which sets up a program to automatically start each time the QED Board turns on is fully described in the Main Glossary entry for PriorityAutostart().

We use some non-ANSI notation when specifying the input parameters of these functions. For example, when an input parameter can be one of several types, we use the notation:

function_name ( [type1] or [type2] or [type3] )

Forth compilers are more forgiving than C compilers when it comes to accepting input parameters of differing types.

Glossary entries are alphabetized in ASCII Order:

void (EE!) ( int val, int* addr )

Stores val at the specified addr in EEPROM. Any byte that already contains the specified contents is not re-programmed; this helps lengthen the lifetime of the EEPROM. See StoreEEInt() in the Main Glossary for an example of how to define a "variable" in EEPROM and interactively initialize it.
Pronunciation: "paren-e-e-store"

void (EE2!) ( long val, long* addr )

Stores val at the specified addr in EEPROM. The most significant word is stored at addr, and the least significant word is stored at addr+2. Any byte that already contains the specified contents is not re-programmed; this helps lengthen the lifetime of the EEPROM. See StoreEELong() in the Main Glossary for an example of how to define a "variable" in EEPROM and interactively initialize it.
Pronunciation: "paren-e-e-two-store"

void (EEC!) ( char val, char* addr )

Stores val at the specified addr in EEPROM. Any byte that already contains the specified contents is not re-programmed; this helps lengthen the lifetime of the EEPROM. See StoreEEChar() in the Main Glossary for an example of how to define a "variable" in EEPROM and interactively initialize it.
Pronunciation: "paren-e-e-c-store"

void (EEF!) ( float val, float* addr )

Stores val at the specified addr in EEPROM. The most significant word is stored at addr, and the least significant word is stored at addr+2. Any byte that already contains the specified contents is not re-programmed; this helps lengthen the lifetime of the EEPROM. See StoreEEFloat() in the Main Glossary for an example of how to define a "variable" in EEPROM and interactively initialize it.
Pronunciation: "paren-e-e-f-store"

void . ( int )

Prints the input parameter as a signed integer. Number conversion is performed in the current number base set by the most recent execution of DECIMAL or HEX.
Pronunciation: "dot"

void =CHAR (LHS: [addr] or [xaddr] ; RHS: [char] or [int] or [float] or [addr] or [xaddr] )

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

Example of use: Assume that the following C code has been compiled and downloaded as part of a program:

static char  data;
FORTH_ARRAY buffer8;
DIM(char, 3, 4, &buffer8);

Now all of the following interactive commands may be typed from the terminal:

Interactive Command      Result
data =CHAR 0x44      Assigns hex 44 to the variable data
buffer8[ 1, 2] =CHAR 9      Assigns 9 to array element at row=1,col=2
data =CHAR buffer8[ 1,2]   Assigns contents of array element to data
buffer8[ 2,3] =CHAR data   Assigns contents of data to array element

In summary, the syntax is similar to a C assignment statement. Note that =CHAR must be typed as one word and must be preceded and followed by spaces.

void =FLOAT (LHS: [addr] or [xaddr] ; RHS: [float] or [addr] or [xaddr] )

=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 (RHS) to the memory location specified by the left-hand-side (LHS).

Example of use: Assume that the following C code has been compiled and downloaded as part of a program:

static float radius;
FORTH_ARRAY fbuffer;
DIM(float, 3, 4, &fbuffer);

Now all of the following interactive commands may be typed from the terminal:

Interactive Command      Result
radius =FLOAT 1.2E3      Assigns 1,200. to the variable radius
fbuffer[ 1, 2] =FLOAT 2.3   Assigns 2.3 to array element at row=1,col=2
radius =FLOAT fbuffer[ 1,2]   Assigns contents of array element to radius
fbuffer[ 2,3] =FLOAT radius   Assigns contents of radius to array element

In summary, the syntax is similar to a C assignment statement. Note that =FLOAT must be typed as one word and must be preceded and followed by spaces.

void =INT (LHS: [addr] or [xaddr] ; RHS: [char] or [int] or [float] or [addr] or [xaddr] )

=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 (RHS) to the memory location specified by the left-hand-side (LHS).

Example of use: Assume that the following C code has been compiled and downloaded as part of a program:

static int radius;
FORTH_ARRAY buffer16;
DIM(int, 3, 4, &buffer16);

Now all of the following interactive commands may be typed from the terminal:

Interactive Command      Result
radius =INT  5         Assigns 5 to the variable radius
buffer16[ 1, 2] =INT 0x44   Assigns hex 44 to array element at row=1,col=2
radius =INT buffer16[ 1,2]   Assigns contents of array element to radius
buffer16[ 2,3] =INT radius   Assigns contents of radius to array element

In summary, the syntax is similar to a C assignment statement. Note that =INT must be typed as one word and must be preceded and followed by spaces.

void =LONG (LHS: [addr] or [xaddr] ; RHS: [char] or [int] or [addr] or [xaddr] )

=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 (RHS) to the memory location specified by the left-hand-side (LHS).

Example of use: Assume that the following C code has been compiled and downloaded as part of a program:

static long data = 56789;
FORTH_ARRAY buffer32;
DIM(long, 3, 4, &buffer32);

Now all of the following interactive commands may be typed from the terminal:

Interactive Command      Result
data =LONG  54321      Assigns 54321 to the variable data
buffer32[ 1, 2] =LONG 0x44   Assigns hex 44 to array element at r=1,c=2
data =LONG buffer32[ 1,2]   Assigns contents of array element to data
buffer32[ 2,3] =LONG data   Assigns contents of data to array element

In summary, the syntax is similar to a C assignment statement. Note that =LONG must be typed as one word and must be preceded and followed by spaces.

void ABORT ( void )

Aborts the current operation; to use, simply type at the terminal:

ABORT

If the CUSTOM_ABORT flag is true (non-zero), executes the abort routine whose xcfa (32-bit extended code field address) is stored in the user variable UABORT, and then returns to the routine that called ABORT. If CUSTOM_ABORT is false (zero), executes the default routine SysAbort() which clears the data and return stacks, and sets the page to the default page (0). If an autostart vector has been installed [see Autostart() and PriorityAutostart()], SysAbort() executes the specified routine; otherwise it executes QUIT which sets the execution mode and enters the QED-Forth monitor. If the stack pointers do not point to common RAM, a COLD restart is initiated. See the entry in the Main Glossary entry for Abort().

void ALL.TO.FLASH ( void )

This function can be called after downloading a forth source program. If the standard map is already set, the function simply executes SAVE. If the download map is set, the function copies pages 4,5,and 6 to flash, sets the STANDARD.MAP, and calls SAVE. This function should not be compiled into a program; it is designed to be invoked interactively or from a download file.

void AUTOSTART ( xaddr )

Expects on the data stack a 32-bit code field xaddress (xcfa) of a function. Compiles a 6-byte sequence into the EEPROM in the 68HC11. On subsequent restarts and ABORTs, the routine having the specified xcfa will be executed. This allows a finished application to be automatically entered upon power up and resets.

CAUTION: To put your application into production, it is recommended that you use the PRIORITY.AUTOSTART function which stores the 6-byte autostart sequence in flash memory.

Usage: We recommend that Autostart() and PriorityAutostart() be executed interactively from the QED-Forth monitor. The easiest way to do this is to use Forth syntax instead of C syntax. After your application program is completed and debugged, simply type from your terminal the command:

CFA.FOR   MAIN   AUTOSTART

This writes a pattern into EEPROM that causes MAIN to be executed upon all subsequent resets and restarts.

Implementation detail: At location hex AE00 in EEPROM, AUTOSTART writes the pattern 1357 followed by the four byte xcfa. To undo the effects of this command and return to the default startup action, type the QED-Forth command

  NO.AUTOSTART

from your terminal. To recover from the installation of a buggy autostart routine, use the special cleanup mode as described in the "Programming the QED Board in C" chapter in the "Getting Started" Manual. See PRIORITY.AUTOSTART, and see the entry in the Main Glossary entry for Autostart().

void BAUD1.AT.STARTUP ( int baud )

Configures the QED Board so that the baud rate of the primary serial port (serial1) supported by the 68HC11's hardware UART will equal the specified standard baud rate upon all subsequent resets and restarts. Standard baud rates are 150, 300, 600, 1200, 2400, 4800, 9600, and 19200 baud.

Example of use: To set the baud rate of the serial1 port to 19,200 baud, type from your terminal:

DECIMAL  19200  BAUD1.AT.STARTUP

Be sure to modify your terminal's baud rate setting to match the new baud rate. The new rate will take effect upon all subsequent resets and restarts.

Implementation detail: This routine calls InstallRegisterInits() which writes into EEPROM the required contents of INIT (=B8H), the contents of BAUD that corresponds to the specified baud rate, and the contents of OPTION, TMSK2, and BPROT that are present when this routine is executed. These values are installed in their respective registers upon each subsequent reset and restart. To undo the effects of this command, type from your terminal the command

DEFAULT.REGISTER.INITS

or invoke the special cleanup mode as described in the "Programming the QED Board in C" chapter in the "Getting Started" Manual. See the entry in the Main Glossary entry for Baud1AtStartup().

void BAUD2 ( int baud )

Sets the baud rate of the secondary serial port (serial2) supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output). Smooth file transfers can be achieved at up to 4800 baud. The baud rate of serial2 is initialized to 1200 baud by the COLD restart routine. See UseSerial2().

Example of use: To set the baud rate of the serial2 port to 4800 baud, type from your terminal:

DECIMAL  4800  BAUD2

Be sure to modify your terminal's baud rate setting to match the new baud rate, and make sure that DIP switch#4 on the QED Board is in the ON position when using the serial2 port. See the entry in the Main Glossary entry for Baud2().

int CALC.CHECKSUM ( xaddr xbase, int numbytes )

Calculates a 16-bit checksum for the buffer specified by xaddr and +n, where xaddr is the starting address, and +n is the number of bytes (0 ≤ +n < 32,768). The buffer must not cross a page boundary, and n must be an even number of bytes. The checksum is calculated by initializing a 16-bit accumulator to zero, then adding in turn each 2-byte number in the buffer to the accumulator; the checksum is the final value of the accumulator. Using this routine provides a method of checking whether the contents of an area of memory have changed since a prior checksum was calculated. This routine is optimized for speed, and executes at less than 3 microseconds per byte.

void CALL.CFN ( xaddr <input_parameter_list> )

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

Example of use: Assume that a function with the following prototype has been compiled and downloaded as part of the GETSTART.C program:

static uint radius;
_Q float CalcArea( uint radius);

Then the GETSTART.TXT download file created by the Control-C compiler will include the following QED-Forth declarations:

HEX
8E1B  CONSTANT radius
:  CalcArea(   DIN 040182  CALL.CFN  ;

While the exact numbers may vary, in this case DIN 040182 is the 32-bit execution address of the CalcArea() function. If we interactively type at the terminal the following commands to initialize the radius variable to 5 and then call the CalcArea() function :

radius =INT  5
CalcArea( int  radius)

QED-Forth executes the function and prints the following summary of the return value:

Rtn: 17053 5242  =0x429D147A =fp:  78.54   ok

We know that CalcArea() returns a floating point (fp) result, so we identify the return value as 78.54 (and indeed this is the area of a circle that has a radius equal to 5). Consult the "Getting Started" book for a full discussion of interactive function calling.
Pronunciation: "call-c-function"

xaddr CFA.FOR ( <function_name> )

Removes <function_name> from the input stream and leaves its extended code field address (cfa) on the data stack. An error occurs if no <function_name> is given or if <function_name> cannot be found in the QED-Forth dictionary. Typically used in conjunction with AUTOSTART or PRIORITY.AUTOSTART. For example:

CFA.FOR  MAIN  PRIORITY.AUTOSTART

configures the QED Board so that the MAIN function is executed upon each subsequent reset or restart.
Pronunciation: "c-f-a-for"

char CHAR ( [char] or [int] or [float] or [addr] or [xaddr] )

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.

Example of use: Assume that the following C code has been compiled and downloaded as part of a program:

static char  ascii_code = 55;
FORTH_ARRAY buffer8;
DIM(char, 3, 4, &buffer8);
_Q void SaveByte( char val, int row, int col, FORTH_ARRAY* array_ptr)
   {   ARRAYSTORE(val, row, col, array_ptr};
   }
SaveByte(55, 1, 2, &buffer8);

Now all of the following interactive commands typed from the terminal will result in the number "55" being printed by QED-Forth:

CHAR  55  U.
CHAR  55.45  U.
CHAR ascii_code  U.
CHAR  buffer8[ 1, 2]  U.

Moreover, to initialize the element of buffer8 at row=0, col=1 to 34, we could interactively type at the terminal:

SaveByte( CHAR 34, INT  0, INT 1, buffer16)

This demonstrates the use of the CHAR keyword in specifying the input parameter types of interactive function calls; the syntax is similar to a C function prototype.

char CHAR* ( [addr] or [xaddr] )

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.

Example of use: Assume that the following C code has been compiled and downloaded as part of a program:

static char data = 5;
char* data_ptr = &data;
FORTH_ARRAY buffer16;
DIM(char*, 3, 4, &buffer16);
_Q void SavePtr(char* val, int row, int col, FORTH_ARRAY* array_ptr)
   {   ARRAYSTORE(val, row, col, array_ptr};
   }
SavePtr(&radius, 1, 2, &buffer16);

Now all of the following interactive commands typed from the terminal will result in the number "5" being printed by QED-Forth:

CHAR  data  U.
CHAR*  data_ptr  U.
CHAR*  buffer16[ 1, 2]  U.

void CLEAR.BOOT.VECTOR ( void )

Removes a boot vector from page 0x0C. Note that the “page C write protect” jumper must be removed for this function to be effective. This function is called during a "factory cleanup", but it is not called by NO.AUTOSTART. See SET.BOOT.VECTOR. This function is typically invoked interactively from the QED-Forth prompt.

void COLD ( void )

Disables interrupts and restarts the QED-Forth system and initializes all of the user variables to their default values. To use, simply type at your terminal the command:

   COLD

Initializes the following machine registers:

PORTG, DDRG, TMSK2, SPCR, BAUD, SCCR1, SCCR2, BPROT,
OPT2, OPTION, HPRIO, INIT, CSCTL.

Initializes the vectors of the vital interrupts if InitVitalIRQsOnCold() has been executed. Calls Abort() which clears the stacks and calls either the QED-Forth interpreter or an autostart routine that has been installed using Autostart() or PriorityAutostart(). If ColdOnReset() has been executed, every reset or power-up will invoke a Cold() as opposed to a Warm() initialization sequence. See the entry in the Main Glossary entry for Cold().

void COLD.ON.RESET ( void )

Initializes a flag in EEPROM that causes subsequent resets to execute a cold restart (as opposed to the standard warm-or-cold restart). This option is useful for turnkeyed systems that have an autostart word installed; any error or reset causes a full Cold() restart which initializes all user variables, after which the autostart routine completes the system initialization and enters the application routine. To use, simply type at your terminal:

COLD.ON.RESET

See STANDARD.RESET, and see the entry in the Main Glossary entry for ColdOnReset().

Implementation detail: Initializes location hex AE1C in EEPROM to contain the pattern 13.

void D. ( long )

Prints the input parameter as a signed long. Number conversion is performed in the current number base set by the most recent execution of DECIMAL or HEX.
Pronunciation: "d-dot"

void DECIMAL ( void )

Sets the number conversion base to decimal. See HEX. The number conversions occur when inputting numbers typed at the terminal, and when QED-Forth prints numbers to the terminal.

void DEFAULT.REGISTER.INITS ( void )

Undoes the effect of the INSTALL.REGISTER.INITS command; to use, simply type at the terminal:

DEFAULT.REGISTER.INITS

Implementation detail: sets the contents of location 0xAE06 in EEPROM to 0xFF to ensure that default initializations will be used after subsequent resets. The default register initializations are:

Register   Register   Default
Name      Address   Value
OPTION   0x8039      0x33
TMSK2      0x8024      0x02
BPROT      0x8035      0x10
BAUD      0x802B      0x31

See the entry in the Main Glossary entry for DefaultRegisterInits().

xaddr DO[] ( addr <input_parameter_list> )

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

Example of use: Assume that the following declaration has been compiled and downloaded as part of a C program:

FORTH_ARRAY circle_parameters;

Then the .TXT download file created by the Control-C compiler will include a QED-Forth definition of the form:

:  circle_parameters   8E03  DO[]  ;

While the exact numbers may vary, in this case 8E03 is the 16-bit pfa of the circle_parameters array. Now debugger expressions such as:

float  circle_parameters[ 0,0]  PrintFP
circle_parameters[1,0]  =FLOAT  3.1416

can be interpreted and executed by the interactive debugger.
Pronunciation: "do-brackets"

void DOWNLOAD.MAP ( void )

Sets a flag in EEPROM and changes the state of a latch in the onboard PALs to put the download memory map into effect. After execution of this routine, and upon each subsequent reset or restart, hex pages 4, 5, 6, and 0x10-17 are addressed in RAM, and pages 1, 2, 3, and 0x18-1F are addressed in flash memory. This allows code (and Forth names) to be compiled into RAM on pages 4, 5 and 6 (and, if a 512K RAM is present, into pages 0x10-17) and then transferred to flash using the PAGE.TO.FLASH function. To establish the standard memory map, see the glossary entry for STANDARD.MAP. Note that the standard map is active after a "factory cleanup" operation.

void DUMP ( xaddr start, uint numbytes)

Displays the contents of numbytes bytes starting at the specified start xaddr. The contents are dumped as hexadecimal bytes regardless of the current number base, and the ascii equivalent contents are also displayed. For example, to display 0x40 bytes starting at address 0x1000 on page 1, execute:

HEX 1000 1   40   DUMP

and to display the last 0x10 bytes on page 1 and the first 0x20 bytes on page 2, execute

7FF0 1 30 DUMP

DUMP calls the function PAUSE.ON.KEY, so the dump responds to XON/XOFF handshaking and can be aborted by typing a carriage return; see PauseOnKey() in the Main Glossary.

void DUMP.INTEL ( char* start, uint start_page, uint reported_start, uint numbytes )

The parameters start and start_page specify the location of the first byte to be dumped, reported_start specifies the starting address reported in the dump, and numbytes is the number of bytes to be dumped. Dumps the contents of numbytes bytes starting at start on start_page using the standard ascii Intel hex format which is useful for transferring data between devices. The line format is:

:{#bytes}{reported.addr}{00}{byte}{byte} ...{byte}{checksum}

All numbers are in hexadecimal base. Each line starts with a : character, followed by a 2-digit number of bytes (20, indicating that the contents of 0x20 bytes are displayed per line), followed by a 4-digit starting address for the line, followed by 00, followed by the contents of the memory locations (2 hex digits per byte), and concluding with a checksum followed by a carriage return/linefeed. The checksum is calculated by summing each of the bytes on the line into an 8-bit accumulator and negating (two's complementing) the result. The hex dump ends with the line

:00000001FF

For example, to dump 0x40 bytes starting at QED Board address 0x1000\1 so that the bytes reside at the beginning of a target memory device, execute:

HEX  1000  01  0000   40  DUMP.INTEL

which specifies 0x1000\1 as the starting address, 0000 as the reported base address in the memory device, and 0x40 as the number of bytes to be dumped. To dump the last 0x20 bytes on page 1 and the first 0x40 bytes on page 2 so that they reside at locations 0x7FE0 through 0x803F in the target memory device, execute

7FE0  1  7FE0   60    DUMP.INTEL

The complementary word RECEIVE.HEX loads QED memory starting at any location based on a received Intel or Motorola hex file. DUMP.INTEL calls the word PAUSE.ON.KEY, so the dump responds to XON/XOFF handshaking and can be aborted by typing a carriage return. See DUMP.S1, DUMP.S2, RECEIVE.HEX and PAUSE.ON.KEY.

void DUMP.S1 ( char* start, uint start_page, uint reported_start, uint numbytes )

The parameters start and start_page specify the location of the first byte to be dumped, the 16-bit reported_start specifies the starting address reported in the dump, and numbytes is the number of bytes to be dumped. Dumps using the standard ascii Motorola S1 hex format which is useful transferring data between devices. Motorola S1 records report 16 bit addresses. (To report full 24 bit addresses, see DUMP.S2.) Outputs an S0 header record which is

S00900004845414445524D

then as many S1 data records as required, followed by an S9 termination record which is

S9030000FC

The Motorola S1 hex line format is:

S1{#bytes}{16bit.reported.addr}{byte}...{byte}{chksum}

All numbers are in hexadecimal base. Each line starts with a the record type (S1 in this case), followed by a 2-digit number of bytes (23, which equals 0x20 bytes per line plus 3 bytes for the reported address and checksum), followed by a 4-digit starting address for the line, followed by the contents of the memory locations (2 hex digits per byte), and concluding with a checksum. The checksum is calculated by summing each of the bytes on the line (excluding the record type) into an 8-bit accumulator and (one's) complementing the result.

For example, to dump 0x40 bytes starting at QED Board address 0x1000\1 so that the bytes reside at the beginning of a target memory device, execute:

HEX  1000  01   0000   40   DUMP.S1

which specifies 0x1000\1 as the starting address, 0000 as the reported base address in the memory device, and 0x40 as the number of bytes to be dumped. To dump the last 0x20 bytes on page 1 and the first 0x40 bytes on page 2 so that they reside at locations 0x7FE0 through 0x803F in the target memory device, execute:

7FE0  1   7FE0    60     DUMP.S1

The complementary word RECEIVE.HEX loads QED memory starting at any location based on a received Motorola or Intel hex file. DUMP.S1 calls the word PAUSE.ON.KEY, so the dump responds to XON/XOFF handshaking and can be aborted by typing a carriage return. See DUMP.S2, DUMP.INTEL, RECEIVE.HEX and PAUSE.ON.KEY.

void DUMP.S2 ( char* start, uint start_page, long reported_start, uint numbytes )

The parameters start and start_page specify the location of the first byte to be dumped, the 32-bit reported_start specifies the starting address reported in the dump, and numbytes is the number of bytes to be dumped. Dumps using the standard ascii Motorola S2 hex format which is useful for transferring data between devices. Motorola S2 records report 24 bit addresses. (To report 16 bit addresses, see DUMP.S1.) Dumps an S0 header record which is

S00900004845414445524D

then as many S2 data records as required, followed by an S9 termination record which is

S9030000FC

The Motorola S2 hex line format is:

S2{#bytes}{24bit.reported.addr}{byte}...{byte}{chksum}

All numbers are in hexadecimal base. Each line starts with a the record type (S2 in this case), followed by a 2-digit number of bytes (24, which equals 0x20 byte per line plus 4 bytes for the reported address and checksum), followed by a 6-digit starting address for the line, followed by the contents of the memory locations (2 hex digits per byte), and concluding with a checksum. The checksum is calculated by summing each of the bytes on the line (excluding the record type) into an 8-bit accumulator and (one's) complementing the result. DUMP.S2 calls the word PAUSE.ON.KEY, so the dump responds to XON/XOFF handshaking and can be aborted by typing a carriage return. See DUMP.S1, DUMP.INTEL, RECEIVE.HEX and PAUSE.ON.KEY.

Example of use: Assume that you have created an application program in pages 4, 5, and 6, and used PRIORITY.AUTOSTART to configure a flash-based autostart vector so that the application runs automatically upon each power-up and restart. To dump a complete application program that resides on pages 4, 5 and 6, so that the bytes reside at the beginning of a flash memory device, execute:

HEX
0000 04   DIN  000000    8000  DUMP.S2
0000 05   DIN  008000    8000  DUMP.S2
0000 06   DIN  010000    8000  DUMP.S2

Now you can edit the resulting file, concatenate the 3 dumps into 1 large S-record by removing all but the first and last S0 (header) and S9 (termination) records, and re-save the file. To transfer the application to a new QED Board, simply execute

DOWNLOAD.MAP
0 4 RECEIVE.HEX   <send the captured file>
4 PAGE.TO.FLASH
5 PAGE.TO.FLASH
6 PAGE.TO.FLASH
STANDARD.MAP

This is a time-effective method of mass producing QED-based products running a “turnkeyed” autostart program.

float FLOAT ( [char] or [int] or [float] or [addr] or [xaddr] )

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.

Example of use: Assume that the following C code has been compiled and downloaded as part of a program:

static float radius = 5.25;
FORTH_ARRAY fbuffer;
DIM(float, 3, 4, &fbuffer);
_Q void FSave( float val, int row, int col, FORTH_ARRAY* array_ptr)
   {   FARRAYSTORE(val, row, col, array_ptr};
   }
FSave(5.25, 1, 2, &fbuffer);

Now all of the following interactive commands typed from the terminal will result in the number "5.25" being printed by QED-Forth:

FLOAT  5.25  PrintFP
FLOAT  radius  PrintFP
FLOAT  fbuffer[ 1, 2]  PrintFP

Moreover, to initialize the element of fbuffer at row=0, col=1 to 12.34, we could interactively type:

FSave( FLOAT 12.34, INT  0, INT 1, fbuffer)

This demonstrates the use of the FLOAT keyword in specifying the input parameter types of interactive function calls; the syntax is similar to a C function prototype.

float FLOAT* ( [addr] or [xaddr] )

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), INT* extracts the 16-bit pointer stored at the specified memory location, and in turn extracts the 32-bit float pointed to by the pointer.

Example of use: Assume that the following C code has been compiled and downloaded as part of a program:

static float radius = 5.6;
float* radius_ptr = &radius;
FORTH_ARRAY buffer16;
DIM(float*, 3, 4, &buffer16);
_Q void SavePtr( float* val, int row, int col, FORTH_ARRAY* array_ptr)
   {   ARRAYSTORE(val, row, col, array_ptr};
   }
SavePtr(&radius, 1, 2, &buffer16);

Now all of the following interactive commands typed from the terminal will result in the number "5.6" being printed by QED-Forth:

FLOAT  radius  PrintFP
FLOAT*  radius_ptr  PrintFP
FLOAT*  buffer16[ 1, 2]  PrintFP

float FP_CtoQ (float ansi_fp_num)

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. See the entry in the Main Glossary entry for FP_CtoQ().

float FP_QtoC (float qed_fp_number)

Converts the QED-Forth formatted input floating point format into an ANSI/IEEE-standard formatted floating point number. See the entry in the Main Glossary entry for FP_QtoC().

void ENABLE.DOWNLOAD ( void )

If the download map is set, this function does nothing. If the standard map is set, this command prepares for a code download by copying pages 4, 5, and 6 to RAM, then setting the download map. When combined with ALL.TO.FLASH, this function ensures that an application program up to 96 Kbytes long compiled on pages 4, 5, and 6 is properly transferred to flash after a download. Usage: When paired with the ALL.TO.FLASH command, this function simplifies the loading of a Forth program. Place the ENABLE.DOWNLOAD command at the top of the first file to be loaded, and place ALL.TO.FLASH at the end of the last file to be loaded. This ensures proper compilation of code into RAM pages 4, 5 and 6 in the download map, followed by transfer to flash and setting of the standard map. It is also possible to put ENABLE.DOWNLOAD at the top of each source code file, and ALL.TO.FLASH at the bottom of each source file. This technique ensures proper compilation of any given source code file during the development process. Of course, this command may also be typed at the QED-Forth prompt before code is downloaded.

void HEX ( void )

Sets the number conversion base to hexadecimal. See DECIMAL. The number conversions occur when inputting numbers typed at the terminal, and when QED-Forth prints numbers to the terminal.

void INIT.VITAL.IRQS.ON.COLD ( void )

Undoes the effect of the NO.VITAL.IRQ.INIT command, and causes subsequent cold restarts to perform the default action of checking the interrupt vectors for the COP, clock monitor, illegal opcode and OC2 interrupts and initializing them if they do not contain the standard interrupt service vectors. To use, simply type at your terminal:

INIT.VITAL.IRQS.ON.COLD

Implementation detail: sets location 0xAE1B in EEPROM to 0xFF.

See the entry in the Main Glossary entry for InitVitalIRQsOnCold().
Pronunciation: "init-vital-i-r-qs-on-cold

void INSTALL.REGISTER.INITS ( char option, char tmsk2, char bprot, char baud )

Compiles a 7-byte sequence into the EEPROM that specifies the contents to be loaded into the "protected registers" plus the BAUD register after subsequent resets. The protected registers are those that must be initialized within 64 machine cycles after a reset; after that their contents cannot be changed. They are INIT, OPTION, TMSK2, and BPROT. The BAUD register controls the BAUD rate of the primary serial communications interface (serial1), and is included so that a user-specified baud rate can be set upon every restart. The INIT register controls the location of the on-chip RAM and the registers. This value is set to 0xB8 (on-chip RAM at 0xB000, and registers at 0x8000); other values are not compatible with QED-Forth. The contents of the other 4 registers may be specified by the user. Once INSTALL.REGISTER.INITS is executed, subsequent resets will cause B8H to be stored in INIT, byte1 in OPTION, byte2 in TMSK2, byte3 in BPROT, and byte4 in BAUD. To undo the effects of this word and return to the default contents of the protected registers use the DEFAULT.REGISTER.INITS command; see its glossary entry for a list of the default values for each of the registers.

Example of use: To set OPTION = 0x33, TMSK2 = 0x02, BPROT = 0x10, and BAUD = 0x31, type from the terminal:

HEX  33 02 10 31  INSTALL.REGISTER.INITS

Implementation detail: INSTALL.REGISTER.INITS writes the hex pattern 13 at location hex AE06 in the EEPROM. The five bytes following the pattern contain the specified contents of INIT (=B8H), OPTION, TMSK2, BPROT, and BAUD, respectively.

See the entry in the Main Glossary entry for InstallRegisterInits().

int INT ( [char] or [int] or [float] or [addr] or [xaddr] )

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.

Example of use: Assume that the following C code has been compiled and downloaded as part of a program:

static int radius = 5;
FORTH_ARRAY buffer16;
DIM(int, 3, 4, &buffer16);
_Q void SaveElement( int val, int row, int col, FORTH_ARRAY* array_ptr)
   {   ARRAYSTORE(val, row, col, array_ptr};
   }
SaveElement(5, 1, 2, &buffer16);

Now all of the following interactive commands typed from the terminal will result in the number "5" being printed by QED-Forth:

INT  5  U.
INT  5.45  U.
INT  radius  U.
INT  buffer16[ 1, 2]  U.

Moreover, to initialize the element of buffer16 at row=0, col=1 to 1234, we could interactively type at the terminal:

SaveElement( INT 1234, INT  0, INT 1, buffer16)

This demonstrates the use of the INT keyword in specifying the input parameter types of interactive function calls; the syntax is similar to a C function prototype.

int INT* ( [addr] or [xaddr] )

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.

Example of use: Assume that the following C code has been compiled and downloaded as part of a program:

static int radius = 5;
int* radius_ptr = &radius;
FORTH_ARRAY buffer16;
DIM(int*, 3, 4, &buffer16);
_Q void SavePtr( int* val, int row, int col, FORTH_ARRAY* array_ptr)
   {   ARRAYSTORE(val, row, col, array_ptr};
   }
SavePtr(&radius, 1, 2, &buffer16);

Now all of the following interactive commands typed from the terminal will result in the number "5" being printed by QED-Forth:

INT  radius  U.
INT*  radius_ptr  U.
INT*  buffer16[ 1, 2]  U.

long LONG ( [char] or [int] or [float] or [addr] or [xaddr] )

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.

Example of use: Assume that the following C code has been compiled and downloaded as part of a program:

static long data = 56789;
FORTH_ARRAY buffer32;
DIM(long, 3, 4, &buffer32);
_Q void SaveLong( long val, int row, int col, FORTH_ARRAY* array_ptr)
   {   ARRAYSTORE(val, row, col, array_ptr};
   }
SaveLong(56789, 1, 2, &buffer32);

Now all of the following interactive commands typed from the terminal will result in the number "56789" being printed by QED-Forth:

LONG  56789  D.
LONG  data  D.
LONG  buffer32[ 1, 2]  D.

To initialize the element of buffer32 at row=0, col=1 to 12345, we can interactively type:

SaveElement( LONG 12345, INT  0, INT 1, buffer32)

This demonstrates the use of the LONG keyword in specifying the input parameter types of interactive function calls; the syntax is similar to a C function prototype.

long LONG* ( [addr] or [xaddr] )

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.

Example of use: Assume that the following C code has been compiled and downloaded as part of a program:

static long data = 12345;
long* data_ptr = &data;
FORTH_ARRAY buffer16;
DIM(long*, 3, 4, &buffer16);
_Q void SavePtr( long* val, int row, int col, FORTH_ARRAY* array_ptr)
   {   ARRAYSTORE(val, row, col, array_ptr};
   }
SavePtr(&data, 1, 2, &buffer16);

Now all of the following interactive commands typed from the terminal will result in the number "12345" being printed by QED-Forth:

LONG  data D.
LONG*  data_ptr  D.
LONG*  buffer16[ 1, 2]  D.

void MAIN ( void )

Executes the main() function which is located at address 0x0000 on page 0x04. Each compiled program must contain one and only one definition of the main() function.

void NO.AUTOSTART (void)

Undoes the effect of the AUTOSTART and PRIORITY.AUTOSTART commands and attempts to ensure that the standard QED-Forth interpreter will be entered after subsequent resets. This command is typically executed interactively using QED-Forth syntax by typing from the terminal:

NO.AUTOSTART

Implementation detail: Erases the 0x1357 pattern at location 0xAE00 [put there by Autostart()] in EEPROM, and erases the 0x1357 pattern at location 0x047FFA [put there by PriorityAutostart()] in page 4 of paged memory. Note that the priority_autostart vector at 0x047FFA cannot be erased if the memory is write-protected when NO.AUTOSTART is executed. NO.AUTOSTART is invoked by the special cleanup mode.

void NO.VITAL.IRQ.INIT ( void )

Writes a pattern into EEPROM so that subsequent cold restarts will not initialize the COP, clock monitor, illegal opcode, and OC2 interrupt vectors. This option is provided for programmers interested in installing their own interrupt service routines in any of these four vectors. Can be undone by INIT.VITAL.IRQS.ON.COLD. To use, simply type from the terminal:

NO.VITAL.IRQ.INIT

Implementation detail: Initializes location hex AE1B in EEPROM to contain the pattern 13. See the entry in the Main Glossary entry for NoVitalIRQInit().
Pronunciation: "no-vital-i-r-q-init"

void PAGE.TO.FLASH ( int source_page )

Transfers the 32 Kbyte contents of the specified RAM source_page to the parallel page in flash. If the current memory map is the "download map", then valid source pages are 4, 5, or 6, (and, if a 512K RAM is installed, pages 0x10-17). Page 4 RAM is transferred to page 1 flash, page 5 RAM is transferred to page 2 flash, page 6 RAM is transferred to page 3 flash, and pages in the range 0x10-17 are transferred to parallel flash pages in the range 0x18-1F. If the current memory map is the "standard map", then valid source pages are 1, 2, or 3 (and, if a 512K RAM is installed, pages 0x18-1F). Page 1 RAM is transferred to page 4 flash, page 2 RAM is transferred to page 5 flash, page 3 RAM is transferred to page 6 flash, and pages in the range 0x18-1F are transferred to parallel flash pages in the range 0x10-17. An "invalid input parameter" error is issued if an invalid source_page is specified. A "can't program flash" error is issued if the flash cannot be programmed. This function uses the RAM at addresses 0x3000-3FFF on page 0F and the 68HC11's on-chip RAM at hex B200 to B3CF to manage the write to the flash (the real-time clock and C/Forth interrupt stack reserve the bytes at B3D0 to B3FF). The remaining on-chip RAM at B000 to B1FF remains available to the user.

void PAGE.TO.RAM ( int source_page )

Transfers the 32 Kbyte contents of the specified flash source page to the parallel page in RAM. If the current memory map is the "download map", then valid source pages are 1, 2, or 3 (and, if a 512K RAM is installed, pages 0x18-1F). Page 1 flash is transferred to page 4 RAM, page 2 flash is transferred to page 5 RAM, page 3 flash is transferred to page 6 RAM, and pages in the range 0x18-1F are transferred to parallel RAM pages in the range 0x10-17. If the current memory map is the "standard map", then valid source pages are 4, 5, or 6 (and, if a 512K RAM is installed, pages 0x10-17). Page 4 flash is transferred to page 1 RAM, page 5 flash is transferred to page 2 RAM, page 6 flash is transferred to page 3 RAM, and pages in the range 0x10-17 are transferred to parallel RAM pages in the range 0x18-1F. An "invalid input parameter" error is issued if an invalid source page is specified.

void PrintFP ( float )

Prints the input ANSI-C floating point parameter using the format specified by the most recent execution of FIXED, SCIENTIFIC, or FLOATING. See the entry in the Main Glossary entry for PrintFP().

void PRIORITY.AUTOSTART ( xaddr )

Expects on the data stack a 32-bit code field xaddress (xcfa) of a function. Compiles a 6-byte sequence at locations 0x7FFA-7FFF on page 4 so that upon subsequent restarts and ABORTs, the routine having the specified xcfa will be automatically executed. This allows a finished application to be automatically entered upon power up and resets. In contrast to the EEPROM-based AUTOSTART function, the PRIORITY.AUTOSTART vector is located in paged memory which is in flash memory in turnkeyed "production" boards. Thus PRIORITY.AUTOSTART facilitates the autostarting of flash-based systems. ABORT (which is called by the error handler and upon every reset or restart) checks the priority autostart vector first and executes the specified routine (if any). If no priority autostart routine is posted or if the specified routine terminates, ABORT then checks the EEPROM-based autostart vector (see AUTOSTART) and executes the specified routine (if any). If no autostart routine is posted or if the specified routine terminates, ABORT then invokes QUIT which is the QED-Forth interpreter.

Usage: We recommend that Autostart() and PriorityAutostart() be executed interactively from the QED-Forth monitor. The easiest way to do this is to use Forth syntax instead of C syntax. After your application program is completed and debugged, simply type from your terminal the command:

CFA.FOR   MAIN   PRIORITY.AUTOSTART

This writes a pattern into EEPROM that causes MAIN to be executed upon all subsequent resets and restarts.

Implementation detail: At location 7FFAH on page 4, PRIORITY.AUTOSTART writes the pattern 1357 followed by the four byte xcfa; make sure that page 4 is not write protected when executing PRIORITY.AUTOSTART. To undo the effects of this command and return to the default startup action, make sure that page 4 is un-write-protected RAM and call NO.AUTOSTART (which clears both the priority autostart and the EEPROM-based autostart vectors). To recover from the installation of a buggy priority autostart routine if page 4 is RAM, make sure that page 4 is not write-protected and invoke use the special cleanup mode (consult the QED-Forth manual). See AUTOSTART, and see the Main Glossary entry for PriorityAutostart().

void RECEIVE.HEX ( xaddr <text> -- )

Accepts a download in standard Intel hex or Motorola S1 or S2 or S3 hex formats and initializes the memory locations starting at the specified xaddr accordingly. The first address specified in the <text> hex dump is stored in memory at xaddr, and all subsequent bytes are stored in QED memory preserving the relative spacing of data specified in the <text> hex dump. If the xaddress equals -1 (=0xFFFFFFFF), the download is stored in the addresses as specified in the hex dump itself. The QED paged memory is treated as a contiguous memory space; recall that the location following 7FFF on a given page is location 0000 on the following page. Accepts empty lines. If a format or checksum error is detected, emits an 'X' character to signal the error, but does not abort. Aborts with a "Missing delimiter" message if the first character on a line is not a : or S character. Terminates when an end-of-file record is received; the final line of an Intel hex dump is

:00000001FF

and the standard final line of a Motorola hex dump is

S9030000FC

although any S7, S8, or S9 termination record will terminate reception. Motorola S0 header records are accepted and ignored. Each input text line is temporarily stored at PAD. Be sure that the PAD buffer is large enough to accommodate a full line (decimal 80 bytes or more is safe). See the glossary entries for DUMP.INTEL, DUMP.S1, and DUMP.S2 for descriptions of Intel and Motorola hex formats.

Implementation detail: RECEIVE.HEX calculates an offset as the specified xaddr minus the first address specified in the <text> file. This offset is then added to every byte's file address (specified in the <text> file) to calculate the QED destination address. If the specified xaddr = -1 (0xFFFFFFFF), the offset is set to zero. This scheme allows the data in a <text> hex dump file with arbitrarily reported addresses to be loaded starting at any desired location in the QED memory space.
Pronunciation: "receive-hex"

void RESTORE ( void )

Restores the memory map user variables stored by the last execution of SAVE to their respective user variables. To use, simply type at your terminal:

RESTORE

See SAVE.

void SAVE ( void )

Saves the current memory map so that it may be restored later. Saves the QED-Forth dictionary pointer DP, names pointer NP, variable pointer VP, last xnfa in the FORTH vocabulary, and CURRENT.HEAP in a reserved area in EEPROM (0xAE0C to 0xAE1A). RESTORE fetches these quantities and places them in the appropriate user variables to restore the saved state. Useful for dictionary management and for recovery from crashes. To use, simply type from the terminal:

SAVE

after sending a .TXT download file created by the WinEdit "Make" or "Rebuild" utilities. Consult the Debugging chapter in the "Getting Started" book for more information.

void SERIAL1.AT.STARTUP ( void )

Initializes a flag in EEPROM which installs the primary serial port (serial1) as the default serial port used by the QED-Forth interpreter after each reset or restart. The serial1 port is supported by the 68HC11's on-chip hardware UART. To use, simply type at the terminal:

SERIAL1.AT.STARTUP

Implementation detail: Sets the contents of address 0xAE1D in EEPROM to 0xFF. Upon each reset or restart, the QED-Forth startup routine checks this byte, and contents of 0xFF cause the USE.SERIAL1 routine to be executed. See the entry in the Main Glossary entry for Serial1AtStartup().
Pronunciation: "serial-one-at-startup"

void SERIAL2.AT.STARTUP ( uint baud_rate )

Initializes a flag in EEPROM which installs the secondary serial port (serial2) at the specified baud_rate as the default serial port used by the QED-Forth interpreter after each reset or restart. The serial2 port is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output). The specified baud rate u must a power of 2 times 75 baud up to a maximum of 9600 baud. Thus the allowed baud rates for this routine are 75, 150, 300, 600, 1200, 2400, 4800, and 9600 baud. The effect of this routine is canceled by executing SERIAL1.AT.STARTUP. Note that the serial2 port can support many more baud rates, but the options have been limited to facilitate setting a reasonable startup baud rate based on a simple implementation as described below. Note also that the maximum baud rate that can be sustained by the serial2 port is less than 9600 baud; see the glossary entry for BAUD. For example, to specify that the serial2 port is to be used at startup with a baud rate of 2400 baud, type from the terminal:

DECIMAL  2400  SERIAL2.AT.STARTUP

Be sure to modify your terminal's baud rate setting to match the new baud rate, and make sure that DIP switch#4 on the QED Board is in the ON position when using the serial2 port. See the entry in the Main Glossary entry for Serial2AtStartup().

void SET.BOOT.VECTOR ( xaddr xcfa -- )

Compiles a 6-byte sequence at locations 0x7FFA-0x7FFF on page 0x0C so that upon subsequent restarts and ABORTs, the function having the xcfa (execution address) will be executed BEFORE any other autostart routines are executed. The execution order at startup is: boot_vector, then priority_autostart, then autostart. Note that the “page C write protect” jumper must be removed for this function to be effective. The boot vector is most useful for extending the kernel in a "bullet-proof" way that cannot be overwritten unless the page C write protect jumper is removed. For example, suppose that you want to allow fail-safe field firmware upgrades using Compact Flash (CF) cards via Mosaic's CF Wildcard. This can be accomplished by removing the page C hardware write protect jumper, loading the CF Wildcard kernel extension on page 0x0C, and compiling a startup function on page C that checks for the presence of an "AUTOEXEC.QED" file that will be automatically executed (loaded) if present. Using SetBootVector, the startup function can be declared as a boot vector, and then the page C write protect jumper can be installed. The boot vector will be able check for the presence of a firmware upgrade file, and the hardware write protection of page C prevents the erasure of the boot vector or its code. To remove the boot vector, take off the page C write protect jumper and call ClearBootVector (CLEAR.BOOT.VECTOR in Forth), or perform a “factory cleanup”. We recommend that this function be invoked interactively from the QED-Forth prompt. Assume that a function called Page_C_Startup has been defined. Forth programmers can just execute:

CFA.FOR  Page_C_Startup SET.BOOT.VECTOR

C programmers can use the *.map file generated by the C compiler to look up the compilation address and page of the Page_C_Startup function, or the function can be defined using the _Q prefix as:

_Q void Page_C_Startup( void ) { function body goes here }

Then from the QED-Forth prompt, type

CFA.FOR  Page_C_Startup SET.BOOT.VECTOR

Make sure that the page containing the debug headers is included in your final runtime system.

void SP! ( ... )

Clears all items off the QED-Forth data stack and resets the data stack pointer to its default location.
Pronunciation: "s-p-store"

void STANDARD.MAP ( void )

Sets a flag in EEPROM and changes the state of a hardware latch to put the standard memory map into effect. After execution of this routine, and upon each subsequent reset or restart, hex pages 4, 5, 6, and 0x10-17 are addressed in flash memory, and pages 1, 2, 3, and 0x18-1F are addressed in RAM. After code is downloaded to RAM and transferred to flash using the PAGE.TO.FLASH function, establishing the standard map allows code resident on pages 4, 5 and 6 (and pages 0x10-17) to be executed. To establish the download memory map, see the glossary entry for DOWNLOAD.MAP. Note that the standard map is active after a "factory cleanup" operation.

void STANDARD.RESET ( void )

Undoes the effect of the COLD.ON.RESET command so that subsequent resets will result in the standard warm-or-cold startup sequence. To use, simply type at the terminal:

STANDARD.RESET

Implementation detail: sets the flag at location 0xAE1C in EEPROM to 0xFF.

See the entry in the Main Glossary entry for StandardReset().

int TO.FLASH ( xaddr source, xaddr destination, uint numbytes )

Transfers the unsigned integer number of bytes, u (0 ≤ num ≤ 65,535), starting at the specified source extended address, xaddr1, to the specified destination extended address, xaddr2, in flash. The source may be anywhere in memory; it may even be in the flash which is being programmed. The destination must be in flash.

TO.FLASH returns a flag equal to -1 if the programming was successful, or 0 if the programming failed. The most common reason for failure is a destination that is not in a programmable page in flash memory. Less likely, but possible, if any locations in the flash are programmed more than 10,000 times, the cell may wear out causing a failure flag to be returned.

Assuming that the standard 512 Kbyte flash is present on the board, writable flash pages include pages hex 4, 5, 6, 7, 0xC, 0xD, and 0x10-17 in the standard map, and pages 1, 2, 3, 0xC, 0xD, and 0x18-1F in the download memory map. Page 7 is always in flash and writable; it provides an excellent location for data or graphics storage. Page 0x0D is also writeable flash, and is often used to hold kernel extension code. Page 0x0C can be optionally write protected with a jumper, enabling the installation of bullet-proof kernel extensions that cannot be erased until the jumper is removed.

This function uses the RAM at addresses 0x3000-3FFF on page 0F and the 68HC11's on-chip RAM at hex B200 to B3CF to manage the write to the flash (the real-time clock and C/Forth interrupt stack reserve the bytes at B3D0 to B3FF). The remaining on-chip RAM at B000 to B1FF remains available to the user.

Caution: TO.FLASH is usually used at compile time to load code and data into Flash, but you may use it at runtime with the understanding that the prolonged disabling of interrupts by TO.FLASH can adversely affect real-time servicing of interrupts including those associated with the secondary serial line.

Upgrade notice: Kernel v4.41 upgrades TO.FLASH to accommodate newly available Flash devices. The various chips now require the following buffer sizes/location:

While it would be possible to use any of these chips, the kernel V4.41 product starting in 2014 ships with a 39SF040 flash chip, which is programmed using the 4 kbyte buffer at 0x3000-3FFF on page 0F.

See also PAGE.TO.FLASH and ALL.TO.FLASH.

void U. ( int )

Prints the input parameter as an unsigned integer. Number conversion is performed in the current number base set by the most recent execution of DECIMAL or HEX.
Pronunciation: "u-dot"

void USE.SERIAL1 ( void )

Installs the primary serial port (serial1) as the serial link called by Emit(), AskKey(), and Key(). The serial1 port is associated with the 68HC11's on-chip hardware UART. Stores the xcfa of Key1() in UKEY, the xcfa of AskKey1() in UASK_KEY, and the xcfa of Emit1() in UEMIT. Thus the vectored routines Key(), AskKey(), and Emit() will automatically execute the serial1 routines Key1(), AskKey1(), and Emit1() respectively. Initializes the resource variable SERIAL1.RESOURCE to zero, and initializes the resource variable associated with the prior serial channel in use (typically either SERIAL1.RESOURCE or SERIAL2.RESOURCE) to zero. Does not disable the serial2 port. To use, simply type at the terminal:

USE.SERIAL1

See the entry in the Main Glossary entry for UseSerial1().

void USE.SERIAL2 ( void )

Installs the secondary serial port (serial2) as the serial link called by Emit(), AskKey(), and Key(), calls INIT.SERIAL2 to initialize the serial2 port, and globally enables interrupts to allow the serial2 port to operate. The serial2 port is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output). Stores the xcfa of Key2() in UKEY, the xcfa of AskKey2() in UASK_KEY, and the xcfa of Emit2() in UEMIT. Thus the vectored routines Key(), AskKey(), and Emit() will automatically execute the serial2 routines Key2(), AskKey2(), and Emit2() respectively. Initializes the resource variable SERIAL2.RESOURCE to zero, and initializes the resource variable associated with the prior serial channel in use (typically either SERIAL1.RESOURCE or SERIAL2.RESOURCE) to zero. Does not disable the serial1 port. To use, simply type at the terminal:

USE.SERIAL2

See BAUD2, and see the entry in the Main Glossary entry for UseSerial2().

void WARM ( void )

Restarts the QED-Forth system and clears the data and return stacks and executes ABORT. Unlike COLD, WARM does not initialize all of the user variables to their default values. To use, simply type at the terminal:

WARM

See the entry in the Main Glossary entry for Warm().

int WHICH.MAP ( void )

Returns a 0 if the current memory map is the "standard map", and returns a 1 if the current map is the "download map". If the standard map is active, pages 4, 5, and 6 and 0x10-0x17 are addressed as flash, and pages 1, 2, and 3 (and pages 0x18-0x1F, if present) are addressed in as RAM. If the download map is active, pages 4, 5, and 6 (and 0x10-0x17, if present) are addressed as RAM, and pages 1, 2, and 3 and pages 0x18-0x1F are addressed as flash memory. This routine allows a user or program to verify which map is currently being used. After a "factory cleanup" operation, the standard map is active. See STANDARD.MAP and DOWNLOAD.MAP.

void WORDS ( void )

Prints all words in the CURRENT QED-Forth vocabulary; this can be a useful way of reminding yourself of which recently defined QED-Forth function names can be interactively typed. WORDS incorporates PAUSE.ON.KEY, so the printout can be terminated by typing a carriage return or . (dot); it can be suspended and resumed by typing other characters, and it responds to XON/XOFF handshaking (see PAUSE.ON.KEY). Each word is printed left justified in a field of 16 or 32 characters, 3 names per line. Characters that are not saved in the headers are represented by the appropriate number of _ characters. To use, simply type at the terminal:

WORDS

and then type an additional carriage return to stop the printout when you have seen enough.