Interactive Debugger Glossary

This glossary summarizes functions and keywords that can be interactively typed at the terminal and interpreted by the QED-Forth RTOS (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 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 Main Glossary. For example, the interactive QED-Forth function IS.AUTOSTART which sets up a program to automatically start each time the controller turns on is fully described in the Main Glossary entry for IsAutostart().

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.

Software development in C uses the Codeblocks-based Mosaic IDE Plus Integrated Development Environment. The IDE Plus provides a full-featured text editor, GNU C (GCC) compiler, and customized terminal for rapid code downloads and interactive debugging sessions with the 9S12 (HCS12) processor on the controller board.

Listed functions are alphabetized in the following ASCII order:

( . = A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

(EE!)

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

Stores val at the specified addr in EEPROM.

See StoreEEInt() in the Main Glossary.
Pronunciation: "paren-e-e-store"

(EE2!)

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.

See StoreEELong() in the Main Glossary.
Pronunciation: "paren-e-e-two-store"

(EEC!)

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

Stores val at the specified addr in EEPROM.

See StoreEEChar() in the Main Glossary.
Pronunciation: "paren-e-e-c-store"

(EEF!)

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.

See StoreEEFloat() in the Main Glossary.
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"

.MAP

.MAP ( -- )

Prints a two line summary of the forth memory map and segment information. Reports the DP (current dictionary pointer to the code area), NP (names area pointer), VP (variable area pointer), EEP (EEProm area pointer), heap start and end xaddresses, and the name, segment index, code base xaddress, names area base xaddress, and segment type of the currently compiling segment. For example:

DP: 0x18000 NP: 0x109000 VP: 0x2000 EEP: 0x400 HEAP: 0x188000 to 0x1CBFFF
Segment: ''MYLIB'' ID: 0xF  Code base: 0x108000  Name base: 0x128000

This routine is invoked automatically by WARM and COLD, and provides a useful overview of the current memory map.

Type: LIB
Pronunciation: dot-map
Attributes: M, S

=CHAR

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.

=FLOAT

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.

=INT

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.

=LONG

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.

ABORT

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 Main Glossary entry for Abort()

AUTOSTART:

void AUTOSTART: ( <function_name> )

Removes <function_name> from the input stream and compiles a 6-byte sequence at 0xBFFA on page 0x37 in the HCS12 on-chip flash so that upon subsequent restarts and ABORTs, <name> will be automatically executed. This allows a finished application to be automatically entered upon power up and resets. The autostart routine is invoked by ABORT which is called by the error handler and upon every reset or restart. The autostart is executed after the processing of any valid boot vectors that have been posted by Mosaic’s kernel extensions, and after the PRIORITY.AUTOSTART vector is checked. If no priority autostart or autostart routine is posted or if the specified autostart routine terminates, ABORT then invokes QUIT which is the QED-Forth interpreter. To setup MAIN as an autostart routine, type at the QED-Forth terminal prompt:

AUTOSTART:  MAIN

To undo the effects of this command and return to the default startup action, call NO.AUTOSTART. To recover from the installation of a buggy autostart routine, invoke the special cleanup mode by following the directions in the hardware manual. NOTE: For production systems, consider using the PRIORITY.AUTOSTART: or IS.PRIORITY.AUTOSTART routines which place the startup vector near the top of page 0x0F in external RAM and shadow flash, making it easier to include the vector as part of the downloaded code. See the examples in the glossary entries for DUMP.S2 and DUMP.MANY.S2. Implementation detail: At location 0xBFFA on page 0x37, AUTOSTART: writes the pattern 0x1357 followed by the 4-byte xcfa of <name>.

See IS.AUTOSTART, PRIORITY.AUTOSTART: and IS.PRIORITY.AUTOSTART.

BAUD

void BAUD ( int baud_over_100, int port_id )

Configures the serial port specified by port_id (= 1 or 2 to indicate Serial1 or Serial2) to have a baud rate equal to 100 times the baud_over_100 parameter, both now and after all future resets and restarts. Serial1 (called SCI0 in the HCS12 processor documentation) and Serial2 (called SCI1 SCI0 in the HCS12 processor documentation) are implemented by on-chip hardware UARTs on the HCS12. These UARTs can implement standard baud rates of 300, 2400, 4800, 9600, 19200, 38400, 57600, and 115200 baud. The default rate at startup and after a factory clean is 115200 baud. Baud rates up to 19200 baud have bit rate errors under 0.16%, and baud rates 38400, 57600, and 115200 have a bit-rate timing error of under 1.4%, which leads to excellent performance.

Implementation detail: This routine calculates the baud divisor parameter and writes it to the SCIBDH and SCIBDL register pair for the specified port to immediately cange the baud rate, and writes the same value to a reserved cell in EEPROM so that the specified baud rate is set for the specified serial port upon subsequent restarts. To undo the effects of this command, execute BAUD with a new value or invoke the special cleanup mode. CAUTION: frequent run-time changes to the baud rate under program control are not recommended, as this can wear out the EEPROM cell that configures the baud rate at startup. If your application requires this, it is better to directly write to the hardware registers to modify the baud rate.

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

DECIMAL  4800  2 BAUD

Be sure to modify your terminal's baud rate setting to match the new baud rate, and make sure that the serial communication jumpers are configured for your chosen serial protocol.

See the entry in the Main Glossary for Baud()

CALC.CHECKSUM

int CALC.CHECKSUM ( xaddr base_addr, int numbytes )

Calculates a 16-bit checksum for the buffer specified by base_addr and numbytes, where numbytes is even and 0 ≤ numbytes < 65,534. The buffer may cross one or more page boundaries. 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 0.7 microseconds per byte. The number of bytes must be even; otherwise, an additional byte is included in the checksum. The result is undefined if numbytes = 0 or 1.

CALL.CFN

void CALL.CFN ( xaddr <input_parameter_list> )

A low-level utility that, 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 function 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"

CFA.FOR

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 IS.AUTOSTART or IS.PRIORITY.AUTOSTART. For example:

CFA.FOR  MAIN  IS.AUTOSTART

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

CHAR

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

CHECKSTART.DISABLE

void CHECKSTART.DISABLE ( void )

Undoes the effect of CHECKSTART.ENABLE. Implementation detail: Erases 8 bytes starting at 0xBFF0 on page 0x37 in on-chip flash.

CHECKSTART.ENABLE

void CHECKSTART.ENABLE ( xaddr xcfa, int numbytes )

Configures a checksum calculation that protects the boot vectors. When this function is executed, CALC.CHECKSUM is invoked to calculate a 16-bit checksum starting at xcfa over a range of numbytes bytes, where numbytes must be even. The checksum region may cross one or more page boundaries. The calculated checksum is stored along with xcfa and numbytes in a structure in flash memory that is checked by ABORT at “runtime” upon every power-up and restart. The checksum is recalculated at runtime and compared with the stored checksum. If the checksums match, any boot vectors that were set up using SET.BOOT.VECTOR are executed. If the checksums do not match, no boot vectors are executed. This function is typically not used by the end customer; rather, it is typically invoked as part of a “kernel extension” package that sets up boot vectors and invokes this routine to provide checksum protection at runtime. This prevents the operating system from trying to execute boot vectors that have been erased or otherwise altered. Implementation detail: Starting at address 0xBFF0 on page 0x37 in on-chip flash, stores the 2-byte pre-calculated checksum, the 2-byte number of bytes u, followed by the 4-byte xcfa with the most significant byte set to 0x13.

CLEAR.BOOT.VECTORS

void CLEAR.BOOT.VECTORS ( void )

Disables all boot vectors so that none will be executed at reset or restart. This function is called during a “factory cleanup”, but it is not called by NO.AUTOSTART. This function is typically invoked interactively from the QED-Forth prompt. Implementation detail: Writes 0 to the most significant byte in each location in the vector table to disable all 16 boot vectors at 0xBFB0 to 0xBFFF in page 0x37 on-chip flash memory.

COLD

void COLD ( void )

Disables interrupts and restarts the QED-Forth system and initializes all of the user variables to their default values. Initializes the following machine registers:

SYNR, REFDV, RTICTL, SPI0CR1, PPSS, PERS, PTS, DDRS, PLLCTL, CLKSEL, INITRM, INITRG, INITEE, MISC, PEAR, MODE, EBICTL, PPAGE, RDRIV, TSCR1, TSCR2, PACTL, RDRS, WOMS, DDRJ, PERJ, PPSJ, MODRR, SCI0BDH, SCI0BDL, SCI0CR1, SCI1BDH, SCI1BDL, SCI1CR1.

Initializes the vectors of the vital interrupts if INIT.VITAL.IRQS.ON.COLD has been executed (see its glossary entry). Initializes the user pointer UP and writes initial values to each system user variable in the default forth task. Sets the memory map as follows:

DP: 0x1D8000 NP: 0x1D9000 VP: 0x2000 EEP: 0x400

HEAP: 0x188000 to 0x1CBFFF

Initializes the timeslice increment to 1.024 msec, and initializes the system resource variables. Calls FP.DEFAULTS, BUILD.HASH.TABLE, and copies from xflash to ram by invoking LOAD.PAGES to copy the memory pages designated by the LOAD.PAGES.AT.STARTUP command(s). Unless an autostart is present, this routine prints the coldstart message, flash-to-ram pages loaded report, and executes .MAP to summarize the memory map. Calls ABORT which clears the stacks and calls either the QED-Forth interpreter or an autostart routine that has been installed using PRIORITY.AUTOSTART:, IS.PRIORITY.AUTOSTART, AUTOSTART:, or IS.AUTOSTART. If COLD.ON.RESET has been executed, every reset or power-up will invoke a COLD (as opposed to a WARM) initialization sequence. Consult the documentation for more information about cold restarts.

COLD.ON.RESET

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 Main Glossary entry for ColdOnReset()

D.

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"

DECIMAL

void DECIMAL ( void )

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

DEFAULT.MAP

DEFAULT.MAP ( -- )

Establishes a default memory map that is convenient for programming. Sets DP = 0x8000 on page 0x00, sets NP = 0x8000 on page 0x10, sets VP = 0x2000 in common RAM, and sets the 80 Kbyte default heap at 0x8000 on page 0x18 through 0xBFFF on page 0x1C. The only difference between the DEFAULT.MAP and to the memory map established after a COLD restart is that this routine sets DP at 0x8000 on page 0x00 and NP at 0x8000 on page 0x10, compared to DP and NP on page 0x1D after COLD. This routine leaves the user area, stacks, TIB, POCKET and PAD as they were. It is recommended that the programmer execute ANEW <name> (or equivalently, declare a new segment using LIBRARY or APPLICATION) immediately after using this command; this will properly reset the memory pointers when reloading the compiled words during program development.

DISABLE.BOOT.VECTORS

DISABLE.BOOT.VECTORS ( -- )

Prevents any boot vectors installed by SET.BOOT.VECTOR from being executed. The effect of this command can be reversed by ENABLE.BOOT.VECTORS.

DO[]

xaddr DO[] ( addr <input_parameter_list> )

A low-level utility that, 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"

DUMP

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.

DUMP.AUTOSTARTS

void DUMP.AUTOSTARTS ( void )

Dumps to the active serial port the contents of addresses 0xBFFA through BFFF on pages 0x0F and 0x37 with in-place reported xaddresses in Motorola S2 hex format. The resulting dump includes the autostart code vectors compiled by PRIORITY.AUTOSTART (on page 0x0F) and AUTOSTART (on page 0x37); see their glossary entries. Using this routine facilitates transferring the autostart vectors to production units; to load a dumped set of autostart vectors into a board, simply execute:

-1 -1 RECEIVE.HEX

and use the QED Terminal program to send the result created by DUMP.AUTOSTARTS to the production board.

DUMP.INTEL

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 (a maximum of 0x20 bytes 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 PDQ controller address 0x9000\1 so that the bytes reside at the beginning of a target memory device, execute:

HEX  9000  01  0000   40  DUMP.INTEL

which specifies 0x9000\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 0xBFE0 through 0xC03F in the target memory device, execute

BFE0  1  BFE0   60    DUMP.INTEL

The complementary word RECEIVE.HEX loads the controller’s 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 also DUMP.S1, DUMP.S2, RECEIVE.HEX and PAUSE.ON.KEY

DUMP.MANY.S2

void DUMP.MANY.S2 ( char* start, uint start_page, long reported_start, long 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 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. A maximum of 0x20 data bytes are dumped per line. Each line starts with the record type (S2 in this case), followed by a 2-digit number of bytes (typically 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 also DUMP.S2, RECEIVE.HEX and PAUSE.ON.KEY

Example of use: Assume that you have created an application program using the memory map established by DEFAULT.MAP. Let’s say that this is a program with code in pages 0 through 0x0F, names in pages 0x10 through 0x13, heap on pages 0x18-0x1D, and that you used PRIORITY.AUTOSTART: to configure a startup vector so that the application runs automatically upon each power-up and restart. Referring to the glossary entry for PRIORITY.AUTOSTART: we see that it installs the vector at locations 0xBFFA-0xBFFF on page 0x0F. We assume that no additional libraries or boot vectors need to be written into other memory areas such as on-chip flash. To dump this program including the 6 byte priority autostart vector at the top of page 0x0F, configure the terminal to save the incoming text to a file (via the “save file” menu item), and execute:

DIN 0x008000    DIN  0x008000   DIN  0x50000  DUMP.S2   \ pages 00-0x13

Note that the reported xaddresses equal the actual dumped xaddresses; this allows us to use the simple –1 –1 RECEIVE.HEX command to reload the image in place. Now open and edit the resulting file, removing any extraneous text, then re-save the file. To transfer the application to each new production controller board such that it reloads to the same addresses contained in the dump, follow these steps. First execute at the terminal

-1 -1 RECEIVE.HEX   <send the captured file>

This loads the image into RAM. Next, save the image in the shadow flash using the command:

0x00  0x14  STORE.PAGES .

which writes from pages 00 through 0x13 to the back-up flash; this page range contains the code area, priority autostart vector, and names area. The . (dot) command prints the success flag; it should equal –1 (FFFF in hex base). Finally, we instruct the controller to load RAM from the back-up flash upon each COLD restart, and we write-protect RAM pages 0 through 0x0F (write protect region 1) and pages 0x10 through 0x13 (write protect region 2) to prevent corruption using these commands:

00 0x14  1  LOAD.PAGES.AT.STARTUP   \ load/restore pages 0x00 to 0x13
1 WRITE.PROTECT            \ protect pages 0x00-0x0F
2 WRITE.PROTECT            \ protect pages 0x10-0x13

This is an effective method of mass producing controller-based products running a “turnkeyed” autostart program. See the glossary entry for DUMP.S2 for an example illustrating how to handle a smaller program, and consult the documentation for further discussion of these issues.

DUMP.S1

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 for 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. A maximum of 0x20 data bytes are dumped per line. Each line starts with the record type (S1 in this case), followed by a 2-digit number of bytes (typically 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. 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 also DUMP.S2, DUMP.INTEL, RECEIVE.HEX and PAUSE.ON.KEY

DUMP.S2

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

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}

See DUMP.S1, DUMP.INTEL, RECEIVE.HEX and PAUSE.ON.KEY

Example of use: Assume that you have created an application program using the memory map established by DEFAULT.MAP. Let’s say that this is a simple program with code in pages 0 and 1, names in pages 0x10 and 0x11, heap on pages 0x18-0x1D, and that you used PRIORITY.AUTOSTART: to configure a startup vector so that the application runs automatically upon each power-up and restart. Referring to the glossary entry for PRIORITY.AUTOSTART: we see that it installs the vector at locations 0xBFFA-0xBFFF on page 0x0F. We assume that no additional libraries or boot vectors need to be written into other memory areas such as on-chip flash. To dump this program including the 6 byte priority autostart vector at the top of page 0x0F, configure the terminal to save the incoming text to a file (via the “save file” menu item), and execute:

DIN 0x008000    DIN  0x008000    0x8000  DUMP.S2   \ pages 1 and 2
DIN 0x108000    DIN  0x108000    0x8000  DUMP.S2   \ pages 0x10 and 0x11
DIN 0x0FBFFA   DIN  0x0FBFFA   0x06     DUMP.S2   \ startup vector, page 0xF

Note that the reported xaddresses equal the actual dumped xaddresses; this allows us to use the simple –1 –1 RECEIVE.HEX command to reload the image in place. Now open and edit the resulting file, removing any extraneous text and concatenating the 3 dumps into 1 S-record by removing all but the first and last S0 (header) and S9 (termination) records, then re-save the file. To transfer the application to each new production controller board such that it reloads to the same addresses contained in the dump, follow these steps. First execute at the terminal

-1 -1 RECEIVE.HEX   <send the captured file>

This loads the image into RAM. Next, save the image in the shadow flash using the command:

0x00  0x12  STORE.PAGES .

which writes from pages 00 through 0x11 to the back-up flash; this page range contains the code area, priority autostart vector, and names area. The . (dot) command prints the success flag; it should equal –1 (FFFF in hex base). Finally, we instruct the controller to load RAM from the back-up flash upon each COLD restart, and we write-protect RAM pages 0 through 0x0F (write protect region 1) and pages 0x10 through 0x13 (write protect region 2) to prevent corruption using these commands:

00 0x12  1  LOAD.PAGES.AT.STARTUP   \ load/restore pages 0x00 to 0x11
1 WRITE.PROTECT            \ protect pages 0x00-0x0F
2 WRITE.PROTECT            \ protect pages 0x10-0x13

This is an effective method of mass producing controller-based products running a “turnkeyed” autostart program. See the glossary entry for DUMP.MANY.S2 for an example illustrating how to handle a longer program, and consult the documentation for further discussion of these issues.

ENABLE.BOOT.VECTORS

void ENABLE.BOOT.VECTORS ( void )

Undoes the effect of DISABLE.BOOT.VECTORS, allowing any boot vectors installed by SET.BOOT.VECTOR to be executed upon subsequent restarts.

Implementation detail: Clears a configuration bit in reserved system EEPROM to enable the execution of all installed boot vectors.

FLOAT

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

HEX

void HEX ( void )

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

HEX.

void HEX. ( uint num, char field_width )

Prints num as unsigned hexadecimal number with zero or more leading spaces and a leading 0x right justified in field of minimum field_width characters.
Pronunciation: “hex-dot”

HEXD.

HEXD. ( ulong num, char field_width )

Prints num as unsigned hexadecimal number with zero or more leading spaces and a leading 0x right justified in field of minimum field_width characters.
Pronunciation: “hex-d-dot”

INIT.VITAL.IRQS.ON.COLD

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 RTI 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

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

INT

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

IS.AUTOSTART

void IS.AUTOSTART ( xaddr xcfa )

Compiles a 6-byte sequence at 0xBFFA on page 0x37 in the HCS12 on-chip flash so that upon subsequent restarts and ABORTs, the function having the specified execution address will be automatically executed. This allows a finished application to be automatically entered upon power up and resets. This function is typically executed from the terminal using QED-Forth syntax by typing:

CFA.FOR  MAIN  IS.AUTOSTART

or,

AUTOSTART:  MAIN

after a C program has been downloaded as described in the documentation. The autostart routine is invoked by ABORT which is called by the error handler and upon every reset or restart. The autostart is executed after the processing of any valid boot vectors that have been posted by Mosaic’s kernel extensions, and after the PRIORITY.AUTOSTART vector is checked. If no priority autostart or autostart routine is posted or if the specified autostart routine terminates, ABORT then invokes QUIT which is the QED-Forth interpreter. To undo the effects of this command and return to the default startup action, call NoAutostart (or interactively type NO.AUTOSTART). To recover from the installation of a buggy autostart routine, invoke the cleanup mode by following the directions in the hardware manual. NOTE: for production systems, consider using the PRIORITY.AUTOSTART: or IS.PRIORITY.AUTOSTART routines which place the startup vector on page 0x0F in external RAM and shadow flash, making it easier to include the vector as part of the downloaded code. See the examples in the glossary entries for DUMP.S2 and DUMP.MANY.S2 in the interactive debugger glossary section of this document. Implementation detail: At location 0xBFFA on page 0x37, AUTOSTART: writes the pattern 0x1357 followed by the specified 4-byte xcfa.

See also AUTOSTART:, PRIORITY.AUTOSTART: and IS.PRIORITY.AUTOSTART

IS.PRIORITY.AUTOSTART

void IS.PRIORITY.AUTOSTART ( xaddr xcfa )

Compiles a 6-byte sequence at 0xBFFA on page 0x0F in the external RAM and corresponding shadow flash memory so that upon subsequent restarts and ABORTs, the function having the specified execution address will be automatically executed. This allows a finished application to be automatically entered upon power up and resets. This function is typically executed from the terminal using QED-Forth syntax by typing:

CFA.FOR  MAIN  IS.AUTOSTART

or,

AUTOSTART:  MAIN

after a C program has been downloaded as described in the documentation. The priority autostart routine is invoked by ABORT which is called by the error handler and upon every reset or restart. The priority autostart is executed after the processing of any valid boot vectors that have been posted by Mosaic’s kernel extensions, and before the AUTOSTART: vector is checked. If no priority autostart or autostart routine is posted or if the specified autostart routine terminates, ABORT then invokes QUIT which is the QED-Forth interpreter. To undo the effects of this command and return to the default startup action, call NoAutostart (or interactively type NO.AUTOSTART). To recover from the installation of a buggy autostart routine, invoke the cleanup mode by following the directions in the hardware manual. This priority autostart is ideal for production systems, as the vector is co-located with the downloaded code. See the examples in the glossary entries for DUMP.S2 and DUMP.MANY.S2 in the interactive debugger section of this document.

Implementation detail: Writes the pattern 0x1357 followed by the specified 4-byte xcfa at the specified vector location. On the PDQ Board, the startup vector is at address 0xBFFA on page 0x0F in external RAM and shadow flash, while on the PDQ Board Lite, the vector located at address 0xBFFA on page 0x36 in the processor's on-chip flash.

See also PRIORITY.AUTOSTART: and AUTOSTART:

LOAD.PAGE

void LOAD.PAGE ( int src_flash_page, int dest_ram_page )

Loads the 16 Kbyte contents of external flash memory from src_flash_page into RAM memory at dest_ram_page. No error checking is performed. This routine can be used to read external flash pages 0x1E and 0x1F which have no parallel RAM pages. To allow an effective load to RAM, the destination RAM pages must not be write protected. CAUTION: This routine disables interrupts for over half a millisecond during the read of each 1 Kbyte block from the external flash, corresponding to nearly 10 msec total disabled time. Be sure to schedule the use of this routine so that it does not interfere with any interrupt-based runtime procedures.

See also WRITE.ENABLE and LOAD.PAGES

LOAD.PAGES

void LOAD.PAGES (int starting_page, int num_pages)

For the specified num_pages beginning at starting_page, loads from each (virtual) page in external flash to the parallel page in external RAM. All referenced pages must be in the range 00-0x1D; pages outside this range are ignored. Pages 0x1E and 0x1F of RAM are not implemented in the memory map, and pages starting at 0x20 correspond to the on-chip flash on HCS12 processors with 512K of flash. To simplify the load to RAM, the destination RAM pages are automatically write enabled before the load, and then the prior write protection status is restored after the load.

See also WRITE.ENABLE and LOAD.PAGES.AT.STARTUP

Example of use: To program all of the ram pages accessible by this routine, execute:

0  0x1E  LOAD.PAGES

Memory map summary:

XFlash Pages      RAM Pages         DEFAULT.MAP
@addr=0-3FFF   @addr=8000-BFFF   Typical Use; and write-protect (WP) area ID

   00-0F          00-0F       Typically code (DP);    WP region 1
   10-13          10-13       Typically names (NP);   WP region 2
   14-1D          14-1D       Always RAM,             not write-protectable
   1E-1F          --          RAM pages 1E, 1F are not implemented.

CAUTION: This routine disables interrupts for over half a millisecond during the read of each 1 Kbyte block from the external flash, corresponding to nearly 10 msec total disabled time per page. Be sure to schedule the use of this routine so that it does not interfere with any interrupt-based runtime procedures.

LOAD.PAGES.AT.STARTUP

void LOAD.PAGES.AT.STARTUP (int starting_page, int num_pages, int area_id)

Stores a sequence into reserved system EEPROM that causes the specified num_pages starting at starting_page to be loaded from external flash to the parallel pages in RAM upon subsequent COLD restarts. The area_id can be 1, 2 or 3. Any valid set of RAM pages can be assigned to any of the 3 valid area_id’s. This scheme allows flexibility in determining which pages are restored from the shadow flash to RAM upon each COLD powerup or restart. At the time of the restart, COLD write-enables the affected RAM pages, invokes the LoadPages function to perform the memory load operation, and then establishes any write-protection that was configured using the WRITE.PROTECT function. To undo the effect of this command for a given area.id, specify a valid starting page with num_pages equal to 0 for the specified area.id. A factory cleanup clears all three area_id’s so that no pages are loaded. All referenced pages must be in the range 00-0x1D; pages outside this range are ignored. Pages 0x1E and 0x1F of RAM are not implemented in the memory map, and pages starting at 0x20 correspond to the on-chip flash on HCS12 processors with 512K of flash.

LONG

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

MAIN

void MAIN ( void )

On the PDQ Board, executes the main() function which is located at address 0x8000 on page 0x00. (Note: on the PDQ Board Lite, the execution address is 0x8000 on page 0x20 in the processor's flash memory). 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: IS.AUTOSTART PRIORITY.AUTOSTART and IS.PRIORITY.AUTOSTART:

MAIN2

MAIN2 ( void )

Executes the function which is located at address 0x8000 on page 0x20 in the 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.

NO.AUTOSTART

void NO.AUTOSTART (void)

Undoes the effect of the PRIORITY.AUTOSTART:, IS.PRIORITY.AUTOSTART, AUTOSTART:, and IS.AUTOSTART commands and attempts to ensure that the standard QED-Forth interpreter will be entered after subsequent resets. Does not affect startup configurations set by CHECKSTART.ENABLE or SET.BOOT.VECTOR. NO.AUTOSTART is invoked by the special cleanup mode. This command is typically typed at the interactive Forth monitor as:

NO.AUTOSTART

Implementation detail for PDQ Board: Erases the 0x1357 pattern at location 0x0FBFFA in RAM and shadow flash put there by priority autostart, and erases the 0x1357 pattern at location 0x37BFFA in on-chip flash put there by autostart. Note that the RAM-based priority autostart vector cannot be erased if the memory is write-protected (see WRITE.PROTECT and WRITE.ENABLE).

Implementation detail for PDQ Board Lite: Erases the 0x1357 pattern at location 0x36BFFA in the processor's on-chip flash put there by priority autostart, and erases the 0x1357 pattern at location 0x37BFFA in on-chip flash put there by autostart.

NO.STATUS.AT.STARTUP

void NO.STATUS.AT.STARTUP ( void )

Initializes a flag in EEPROM that suppresses the status report that is typically printed at each COLD and WARM restart. Suppresses the REPORT.PAGES.LOADED printout at subsequent COLD restarts, and suppresses the .MAP printout at subsequent WARM and COLD restarts. Note that these printouts are automatically suppressed if a (priority) autostart is installed. To undo the effect of this routine, call STATUS.AT.STARTUP or do a factory clean. To temporarily suppress the status printouts during a COLD restart, use QUIET.COLD; see its glossary entry.

NO.VITAL.IRQ.INIT

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 trap, and RTI 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

See the Main Glossary entry for NoVitalIRQInit()
Pronunciation: "no-vital-i-r-q-init"

PrintFP

void PrintFP ( float )

Prints the input ANSI floating point parameter using the format specified by the most recent execution of FIXED, SCIENTIFIC, or FLOATING. See the Main Glossary entry for PrintFP() This is a synonym for the F. function.

PRIORITY.AUTOSTART:

PRIORITY.AUTOSTART: ( <name> -- )

Removes <name> from the input stream and compiles a 6-byte sequence at 0xBFFA on page 0x0F in the external RAM and corresponding shadow flash memory so that upon subsequent restarts and ABORTs, the function having the specified xcfa will be automatically executed. This allows a finished application to be automatically entered upon power up and resets. The priority autostart routine is invoked by ABORT which is called by the error handler and upon every reset or restart. The priority autostart is executed after the processing of any valid boot vectors that have been posted by Mosaic’s kernel extensions, and before the AUTOSTART: vector is checked. To configure the controller to execute MAIN upon each power-up or restart, simply type at the terminal:

PRIORITY.AUTOSTART:  MAIN

If no priority autostart or autostart routine is posted or if the specified autostart routine terminates, ABORT then invokes QUIT which is the QED-Forth interpreter. To undo the effects of this command and return to the default startup action, call NO.AUTOSTART. To recover from the installation of a buggy autostart routine, invoke the special cleanup mode by following the directions in the hardware manual. This priority autostart is ideal for production systems, because it places the startup vector on page 0x0F in external RAM and shadow flash, making it easier to include the vector as part of the downloaded code. See the examples in the glossary entries for DUMP.S2 and DUMP.MANY.S2.

Implementation detail for PDQ Board: At location 0xBFFA on page 0x0F, writes the pattern 0x1357 followed by the specified 4-byte xcfa.

Implementation detail for PDQ Board Lite: At location 0xBFFA on page 0x36, writes the pattern 0x1357 followed by the specified 4-byte xcfa.

See IS.PRIORITY.AUTOSTART and AUTOSTART:

QUIET.COLD

void QUIET.COLD ( void )

Performs a COLD restart while suppressing the status report that is typically printed at each COLD restart. Suppresses the REPORT.PAGES.LOADED and .MAP printouts. This is often useful during a download to avoid confusing the terminal with extra carriage return/linefeed sequences, as the linefeed character is used for “handshaking” during the terminal download. Unlike NO.STATUS.AT.STARTUP, this routine does not affect the behavior of subsequent restarts.

RECEIVE.HEX

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

Accepts a download in standard Intel hex or Motorola S1 or S2 or S3 hex formats and initializes the RAM and/or onchip flash 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 paged memory is treated as a contiguous memory space; recall that the location following 0xBFFF on a given page is location 0x8000 on the following page. There is an unchecked error if the specified xaddr input parameter is in paged memory and the address embedded in the hex dump is in unpaged (“common”) memory, or vis versa. 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. Intel records must have a record type of 00.

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 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 board’s memory space.

If the target memory is in onchip flash and a flash programming error occurs, this routine emits the ascii BELL character as a warning.

REPORT.PAGES.LOADED

REPORT.PAGES.LOADED ( -- )

Prints a single-line report of the pages loaded from external shadow flash to the parallel RAM pages upon a COLD restart, and summarizes the write-protect status of write protect region 1 (pages 0-0x0F) and write protect region 2 (pages 0x10-13). The user can designate any valid pages in the range 00-0x1D for each of three areas using LOAD.PAGES.AT.STARTUP (see its glossary entry), and these designated page ranges are reported by this function. For example, if the user has executed the commands:

0x00  5  1 LOAD.PAGES.AT.STARTUP
0x10  3  3 LOAD.PAGES.AT.STARTUP
1  WRITE.PROTECT   2 WRITE.ENABLE

then the next COLD restart or invocation of REPORT.PAGES.LOADED would print:

XFlash->RAM pages loaded: Area 1: 0x00-0x04  2: None  3: 0x10-0x12
WP1: ON  WP2: OFF

(The printout appears on a single line).

Attributes: M, S

RESTORE

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

RESTORE.ALL

void RESTORE.ALL ( void )

This handy utility function is typically typed at the terminal to restore the memory state that was saved using the SAVE.ALL function. RESTORE.ALL is equivalent to:

0x00  0x18  LOAD.PAGES
RESTORE

The LOAD.PAGES operation write-enables pages 0x00 through 0x13, reads the saved contents of the external flash (put there by SAVE.ALL) into RAM pages 0x00 through 0x17, and restores the write-protect status to the state it was in before RESTORE.ALL was executed. The RESTORE operation then loads all of the memory map pointers so that they have the values they had when the last SAVE or SAVE.ALL was executed. Because the application code and names typically reside in pages 0x00 through 0x17, this SAVE.ALL and RESTORE.ALL pair provides a handy tool for managing the development process. After downloading a program from the terminal into the RAM on the board, SAVE.ALL can be executed to back up the RAM contents to the shadow flash. If the memory is corrupted by a software bug during development, the RAM and memory pointers can be restored by simply typing RESTORE.ALL at the terminal. If the board’s power is cycled after SAVE.ALL has been executed, the RAM will be automatically restored from the shadow flash upon power-up; in this case simply executing RESTORE will complete the restoration process.

See also RESTORE, SAVE.ALL, LOAD.PAGES, and LOAD.PAGES.AT.STARTUP

CAUTION: This routine disables interrupts for over half a millisecond during the read of each 1 Kbyte block from the external flash, corresponding to nearly 10 msec total disabled time per memory page. Be sure to schedule the use of this routine so that it does not interfere with any interrupt-based runtime procedures.

SAVE

void SAVE ( void )

Saves the current memory map so that it may be restored later. Saves the DP, NP, VP, EEP, last xnfa in the FORTH vocabulary, CURRENT.HEAP, THIS.SEGMENT, and LAST.SEGMENT in a reserved area in EEPROM. 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. Consult the Manual for examples of use. Useful for dictionary management and for recovery from crashes. To use, simply type from the terminal:

SAVE

after sending a download file.

SAVE.ALL

int SAVE.ALL ( void )

This handy utility function is typically typed at the terminal to save the current RAM contents and memory state so that it can be restored by simply typing RESTORE.ALL at the terminal. It returns a flag equal to –1 if the save operation is successful. SAVE.ALL is equivalent to:

0 18 STORE.PAGES   ( -- success? )   \ store pages 0-1x17->Xflash, takes 11 sec
0 18 1 LOAD.PAGES.AT.STARTUP   \ restore on subsequent COLD startups
SAVE               \ save memory pointers

The STORE.PAGES operation takes about eleven seconds to back up pages 0x00 through 0x17 to shadow flash. The LOAD.PAGES.AT.STARTUP operation ensures that the saved contents will be automatically copied to pages 0x00-0x17 RAM upon subsequent power-ups and COLD restarts, and the SAVE operation writes the current memory pointers (DP, NP, VP, pointer to LATEST, segment control variables, etc.) to the EEPROM so they can be restored by RESTORE or RESTORE.ALL. Because the application code and names typically reside in pages 0x00 through 0x17, this SAVE.ALL and RESTORE.ALL pair provides a convenient tool for managing the development process. After loading a program from the terminal into the RAM on the board, SAVE.ALL can be executed to back up the RAM contents to the shadow flash. If the board is turned off, or if the memory is corrupted by a software bug during development, the RAM and memory pointers can be restored by simply typing RESTORE.ALL at the terminal. If the board’s power is cycled after SAVE.ALL has been executed, the RAM will be automatically restored from the shadow flash upon power-up; in this case simply executing RESTORE will complete the restoration process.

See also SAVE, RESTORE, STORE.PAGES, LOAD.PAGES.AT.STARTUP, and RESTORE.ALL

CAUTION: This routine takes approximately 11 seconds to execute and disables interrupts for significant time periods while writing to the onboard shadow flash. It is meant for use during program development. If for some reason you choose to use this function in a program, be sure to schedule it so that it does not interfere with any interrupt-based runtime procedures.

SERIAL1.AT.STARTUP

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 processor’s on-chip hardware UART SCI0. To use, simply type at the terminal:

SERIAL1.AT.STARTUP

SERIAL2.AT.STARTUP

void SERIAL2.AT.STARTUP ( void )

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

SERIAL2.AT.STARTUP

SET.BOOT.VECTOR

void SET.BOOT.VECTOR ( xaddr xcfa, int vector_index -- )

Configures the function specified by xcfa as a boot vector with index n (0 ≤ n ≤ 15). To support pre-coded “kernel extensions” that are packaged by Mosaic Industries, a set of “boot vectors” is implemented. These vectors allow the posting of up to sixteen functions that are executed before the autostart program is run. Typically, the boot vector programs are initializers associated with kernel extensions. They are automatically installed when the kernel extension is loaded onto the board. They can be removed by executing CLEAR.BOOT.VECTORS or invoking the “factory cleanup” procedure described in the EtherSmart manual. An optional layer of checksum protection is provided for the boot vectors to ensure that corrupted or missing boot vectors are not executed; see CHECKSTART.ENABLE

SP!

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"

STANDARD.RESET

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

See the Main Glossary entry for StandardReset()

STATUS.AT.STARTUP

void STATUS.AT.STARTUP ( void )

Initializes a flag in EEPROM that enables the status report that is typically printed at each COLD and WARM restart. The status print is enabled by default after a factory cleanup. Enables the REPORT.PAGES.LOADED printout at subsequent COLD restarts, and enables the .MAP printout at subsequent WARM and COLD restarts. Note that these printouts are automatically suppressed if a (priority) autostart is installed. To use, simply type at the terminal:

STATUS.AT.STARTUP

To undo the effect of this routine, call NO.STATUS.AT.STARTUP or do a factory clean. To temporarily suppress the status printouts during a COLD restart, use QUIET.COLD.

STORE.PAGES

int STORE.PAGES ( int starting_page, int num_pages)

For the specified num_pages beginning at starting_page, stores from each (virtual) page in external RAM to the parallel page in external flash, returning a true flag if the flash was programmed successfully. All referenced pages must be in the range 00-0x1D; pages outside this range are ignored and cause a false flag to be returned. Pages 0x1E and 0x1F of RAM are not implemented in the memory map, and pages starting at 0x20 correspond to the on-chip flash on HCS12 processors with 512K of flash.

Example of use: To back up all of the ram pages accessible by this routine and store them in the nonvolative shadow flash, execute:

0  0x1E STORE.PAGES

Memory map summary:

XFlash Pages      RAM Pages         DEFAULT.MAP
@addr=0-3FFF   @addr=8000-BFFF   Typical Use; and write-protect (WP) area ID

   00-0F          00-0F       Typically code (DP);    WP region 1
   10-13          10-13       Typically names (NP);   WP region 2
   14-1D          14-1D       Always RAM,             not write-protectable
   1E-1F          --          RAM pages 1E, 1F are not implemented.

CAUTION: This routine disables interrupts for a significant period during the write of each 1 Kbyte block to the external flash. Be sure to schedule the use of this routine so that it does not interfere with any interrupt-based runtime procedures. See LOAD.PAGES and LOAD.PAGES.AT.STARTUP

TO.EEPROM

TO.EEPROM ( xaddr1\addr2\u -- flag | xaddr1=src, addr2=dest, u = byte count )

Transfers the specified number of bytes u (0 ≤ u ≤ 65,535) starting at the specified source extended address xaddr1, to the specified destination 16-bit address addr2 in on-chip eeprom, and returns a success flag. This routine programs only on-chip eeprom. The source xaddr1 may be anywhere in memory; it may even be in the eeprom which is being programmed. This routine returns a flag equal to -1 if the programming was successful, or 0 if the programming failed. (If any locations in the EEPROM are programmed more than 10,000 times, the cell may wear out causing a failure flag to be returned). Caution: This routine disables interrupts for 30 msec per 4-byte eeprom segment. The prolonged disabling of interrupts by TO.EEPROM can adversely affect real-time servicing of interrupts. This routine is not re-entrant, as it uses a fixed content buffer. The buffer is shared by on-chip and off-chip flash programming. If multitasking access to this routine is required, define a resource variable and use GET and RELEASE to manage access to these flash programming routines.

TO.FLASH

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

Transfers numBytes bytes (0 ≤ numBytes ≤ 65,535) starting at the specified source extended address, to the specified destination extended address in on-chip flash, and returns a success flag.

This routine programs only on-chip flash pages (0x30-3F for 256K processors, or 0x20-3F for 512K processors), but note that pages 0x38-3F are write protected and reserved for the operating system. To program external flash, see ToXFlash().

The source may be anywhere in memory; it may even be in the flash which is being programmed. This routine returns a flag equal to -1 if the programming was successful, or 0 if the programming failed. Reasons for failure include trying to program a page that is not a writeable on-chip flash page. (If any locations in the flash are programmed more than 1,000 times, the cell may wear out causing a failure flag to be returned).

Caution: This routine disables interrupts for 35 msec per segment (there are 512 bytes/segment for the 256K HCS12, or 1024 bytes/segment for the 512K HCS12). The prolonged disabling of interrupts by this routine can adversely affect real-time servicing of interrupts. This routine is not re-entrant, as it uses a fixed content buffer. The buffer is shared by onchip and off-chip flash programming. If multitasking is required, define a resource variable and use GET and RELEASE to manage access to the flash programming routines.

TO.FLASH.MANY

TO.FLASH.MANY ( xaddr1\xaddr2\ud -- flag | xaddr1=src, xaddr2=dest, ud = byte count )

Transfers the specified number of bytes ud starting at the specified source extended address xaddr1, to the specified destination extended address xaddr2 in on-chip flash, and returns a success/failure flag.

This routine returns a flag equal to -1 if the programming was successful, or 0 if the programming failed. Reasons for failure include trying to program a page that is not a writeable on-chip flash page. (If any locations in the flash are programmed more than 1,000 times, the cell may wear out causing a failure flag to be returned).

Caution: This routine disables interrupts for 35 msec per segment (there are 512 bytes/segment for the 256K HCS12, or 1024 bytes/segment for the 512K HCS12). The prolonged disabling of interrupts by TO.FLASH can adversely affect real-time servicing of interrupts. This routine is not re-entrant, as it uses a fixed content buffer. The buffer is shared by on-chip and off-chip flash programming. If multitasking access to this routine is required, define a resource variable and use GET and RELEASE to manage access to the flash programming routines.

TO.MEMORY

void TO.MEMORY (xaddr source, xaddr destination, uint numBytes)

This routine is an onchip-flash-smart version of CMOVE. It transfers numBytes bytes (0 ≤ numBytes ≤ 65,535) starting at the specified source extended address, to the specified destination extended address. The destination can be in on-chip RAM, external RAM, or on-chip flash. Unlike TO.FLASH, this routine does not report a programming error (such as trying to program a write-protected region of on-chip flash). Restrictions on use: The destination region must be either entirely in onchip flash or entirely in ram. If both the source and destination are in on-chip flash and the source and destination regions overlap, memory propagation will occur if destination > source.

TO.XFLASH

int TO.XFLASH (xaddr source, xaddr destination, uint numBytes)

Transfers the numBytes bytes (0 ≤ numBytes ≤ 65,535) starting at the specified source extended address, to the specified destination extended address in eXternal flash, and returns a success flag. This routine programs only the external flash at shadow pages 0x00-0x1F. To program the processor’s on-chip flash, see ToFlash(). The source is typically in the external RAM mapped as 16 Kbyte pages at addresses 0x8000-BFFF on pages 0x00-0x1D (RAM pages 0x1E and 0x1F are not accessible). The external flash is mapped as a virtual paged device with 16 Kbyte pages at 0x0000-0x3FFF at pages 0x00-0x1F; thus the destination xaddress must be in this range. This routine returns a flag equal to -1 if the programming was successful, or 0 if the programming failed. Reasons for failure include trying to program a region that includes an invalid xaddress. (If any locations in the flash are programmed more than 1,000 times, the cell may wear out causing a failure flag to be returned). Caution: This routine disables interrupts for 12 msec per sector. The default sector size is 256 bytes; the sector size is read from the external flash chip’s ID byte and stored in EEPROM at each factory cleanup. The prolonged disabling of interrupts by this routine can adversely affect real-time servicing of interrupts. This routine is not re-entrant, as it uses a fixed content buffer. The buffer is shared by on-chip and off-chip flash programming. If multitasking is required, define a resource variable and use GET and RELEASE to manage access to the flash programming routines.

U.

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"

UNSAVE.ALL

void UNSAVE.ALL ( void )

This function provides a “partial undo” operation after SAVE.ALL has been executed. UNSAVE.ALL undoes the SAVE.PAGES.AT.STARTUP action that was performed by SAVE.ALL so that no pages will be restored on subsequent power-ups or COLD restarts. Note that the memory pointer SAVE operation that was performed by SAVE.ALL is unchanged and still valid until SAVE or SAVE.ALL is executed again.

Implementation detail: UNSAVE.ALL is equivalent to:

0 0 1 LOAD.PAGES.AT.STARTUP

In other words, for area_id 1, it specifies that no pages are to be loaded from shadow flash to RAM upon subsequent COLD restarts.

USE.SERIAL1

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 processor’s on-chip hardware UART SCI0. 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 Main Glossary entry for UseSerial1()

USE.SERIAL2

void USE.SERIAL2 ( void )

Installs the secondary serial port (serial2) as the serial link called by Emit(), AskKey(), and Key(). The serial1 port is associated with the processor’s on-chip hardware UART SCI0. 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 the Main Glossary entry for UseSerial2()

WARM

void WARM ( void )

Restarts the QED-Forth system, initializes key hardware registers (as listed in the COLD glossary entry), 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 Main Glossary entry for Warm()

WE.ALL

void WE.ALL ( void )

This handy function write enables the RAM pages 0x00 through 0x13, undoing the effect of a prior execution of WP.ALL. WE.ALL is equivalent to:

1 WRITE.ENABLE   \ write enables pages 0x00-0x0F
2 WRITE.ENABLE   \ write enables pages 0x10-0x13

Write protected RAM cannot be corrupted, even by a program crash that tries to overwrite memory. During program development, the programmer can type

WP.ALL
SAVE.ALL

to protect the program and back it up to shadow flash so that it is automatically reloaded on subsequent power-ups, COLD restarts, or by executing RESTORE.ALL. After invoking WP.ALL, and before attempting to download a new version of your program, execute WE.ALL to write-enable the RAM so the board will accept the download into RAM.

WORDS

void WORDS ( void )

Prints all words in the CURRENT 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

WP.ALL

void WP.ALL ( void )

This handy function write protects RAM pages 0x00 through 0x13. It is equivalent to:

1 WRITE.PROTECT   \ write protects pages 0x00-0x0F
2 WRITE.PROTECT   \ write protects pages 0x10-0x13

Write protected RAM cannot be corrupted, even by a program crash that tries to overwrite memory. During program development, the programmer can type

WP.ALL
SAVE.ALL

to protect the program and back it up to shadow flash so that it is automatically reloaded on subsequent power-ups, COLD restarts, or by executing RESTORE.ALL.

NOTE: After invoking WP.ALL, and before attempting to download a new version of your program, execute WE.ALL to write-enable the RAM so the board will accept the download into RAM.

WRITE.ENABLE

void WRITE.ENABLE (int region_id)

Undoes the effect of WRITE.PROTECT for the specified region_id, where region_id = 1 or 2. If region_id = 1, this routine allows writes to external RAM pages 0x00-0x0F, and if region_id = 2 this routine write enables external RAM pages 0x10-0x13. For example, to write enable RAM pages 00 through 0x0F, simply type at the terminal:

1 WRITE.ENABLE

Implementation detail: sets a bit in reserved system EEPROM; this information is written to the on-board logic upon each restart to configure the writeability of the specified memory pages.

WRITE.PROTECT

void WRITE.PROTECT (int region_id)

Undoes the effect of WriteEnable for the specified region_id, where region_id = 1 or 2. If region_id = 1, this routine disallows writes to external RAM pages 0x00-0x0F, and if region_id = 2 this routine disallows writes to external RAM pages 0x10-0x13. For example, to write protect RAM pages 00 through 0x0F, simply type at the terminal:

1 WRITE.PROTECT

Implementation detail: clears a bit in reserved system EEPROM; this information is written to the on-board logic upon each restart to configure the write protection of the specified memory pages.

This page is about: C Language Library Functions for Microcontroller Interactive Debugger, Interactively Debug and Test C Programs – This glossary summarizes embedded RTOS functions and keywords that are interactively typed at a terminal and interpreted by the an embedded RTOS and debugger to test debug C application programs running on the PDQ Board, a low cost single board computer using the 9S12 HCS12 microcontroller.