C Function Glossary (R-Z)
C language functions available for programming the HCS12
on the PDQ Board using the Mosaic IDE Plus

Programmers of the PDQ Board single-board-computer develop their C language application software using the Codeblocks-based Mosaic IDE Plus Integrated Development Environment. The IDE Plus provides a GNU C (GCC) compiler, a full-featured text editor, and a customized terminal program that enables rapid program downloads and interactive debugging of the HCS12/9S12 MCU. The Mosaic IDE Plus software development environment is ideal for embedded systems and RTOS programming. These C library functions can control all the hardware on the PDQ Board, including all features of the Freescale MC9S12 68HCS12 9S12 HCS12 MCU.

This glossary defines all the customized C functions that speed programming of the PDQ Board.

This glossary is split into three web pages, by alphabetical order (starting with the underscore character): A-H, I-Q, and R-Z (this page).

long Random( void)

Generates and returns a pseudo-random 23bit integer.  The result is also stored in the user variable RANDOM_SEED.

Type: kernel function
Forth name: RANDOM
Header file: numbers.h

RANDOM_SEED

A 32-bit user variable that equals the last 23-bit number generated by Random().  Storing a specific integer (a seed) into RANDOM_SEED leads to the generation of a reproducible series of pseudo-random numbers by repeated calls to Random().  This may be useful for debugging functions that use random numbers.

See also Random()

Type: macro
Related Forth function: RANDOM#
Header file: numbers.h

float RandomGaussian( void)

Generates and returns a floating point random number drawn from a Gaussian distribution with unity standard deviation and zero mean.  Uses the Box-Muller method.

Type: kernel function
Forth name: RANDOM.GAUSSIAN
Header file: numbers.h

ulong ReadElapsedSeconds( void)

Returns the elapsed number of seconds since the timeslice clock was initialized to zero by InitElapsedTime().

See also ReadElapsedSeconds(), FetchTSCount(), TIMESLICE_COUNT, StartTimeslicer(), and ChangeTaskerPeriod()

Type: kernel function
Forth name: READ.ELAPSED.SECONDS
Header file: mtasker.h

Instead of the deprecated ReadElapsedTime function, you should use FetchTSCount(), CountToMsec(), and ReadElapsedSeconds().

void ReadWatch( void)

Reads the battery-operated real-time clock (if present), storing the time, day, and date in the 8-byte watch_results structure located at address 0xB3F8. The stack items, their allowed ranges, and the structure elements that hold the specified contents are as follows:

description              range   result is in structure element:
year                     0 - 99   WATCH_YEAR
month                    1 - 12   WATCH_MONTH
date                     1 - 31   WATCH_DATE
day of week              1 -  7   WATCH_DAY
hour of day              0 - 23   WATCH_HOUR
minute after the hour    0 - 59   WATCH_MINUTE
seconds after the minute 0 - 59   WATCH_SECONDS
hundredths of seconds    0        WATCH_HUNDREDTH_SECONDS

Example of use:

int hour, day, date;   // static variables to hold current time
ReadWatch();           // get current time into watch_results structure
hour = WATCH_HOUR;     // assign from the structure into variables
day  = WATCH_DAY;
date = WATCH_DATE;

Due to a hardware limitation, the hundredths of second parameter always reads as 0; it is included in the structure to maintain backward compatibility with prior code.  Once correctly set, the watch handles the differing numbers of days in each month, and correctly handles leap years.

See also SetWatch()

Type: kernel function
Forth name: READ.WATCH
Header file: watch.h

long RECEIVE( long* mailboxAddr)

If mailboxAddr is empty (ie., if it contains a 32-bit zero), executes Pause() until the mailbox contains a message.  If mailboxAddr contains a message (that is, if it does not contain zero), returns the contents of mailboxAddr and stores a zero into mailboxAddr to indicate that the message has been received and that the mailbox is now empty.  To receive and send floating point messages, use FRECEIVE() and FSEND(). RECEIVE() disables interrupts for 0.55 to 1.5 microseconds to ensure that the state of the mailbox is correctly determined.

See also SEND() and MAILBOX

Type: macro
Related Forth function: RECEIVE
Header file: mtasker.h

long Receive( long* mailboxAddr, uint mailboxPage)

A subsidiary function called by the recommended macro RECEIVE(); see RECEIVE().

Type: kernel function
Forth name: RECEIVE
Header file: mtasker.h

uint ReceiveBinary( xaddr buffer, uint num_bytes )

Accepts a stream of up to num_bytes binary (not ascii!) bytes and initializes the RAM memory locations starting at the specified buffer accordingly.  This function terminates at the earlier of: 1. num_bytes received, or, 2. a 1-second timeout AFTER the first character is detected.  That is, the user can wait a long time before starting to send the binary stream, but once started, a delay of 1 second or more will terminate the load.  This function returns the difference between the input parameter num_bytes and the actual number of binary bytes received.  There can be no extra ascii characters sent by the terminal after the CRLF that terminates the line on which RECEIVE.BINARY resides (assuming that this command is issued interactively).  In other words, this routine immediately starts running KEY in a loop and interprets all incoming bytes as part of the binary data stream.  As usual, this function uses contiguous memory, so the byte after 0xBFFF on a given page is at 0x8000 on the following page.  This function does not GET the serial resource if SERIAL.ACCESS contains RELEASE.AFTER.LINE.

Type: kernel function
Forth name: RECEIVE.BINARY
Header file: memory.h

void ReceiveHex( xaddr buffer)

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 buffer xaddress accordingly.  The first address specified in the <text> hex dump is stored in memory at buffer, and all subsequent bytes are stored in memory preserving the relative spacing of data specified in the <text> hex dump.  If the specified xaddr1 is 0xFFFFFFFF (that is, a 32-bit -1), the memory storage addresses are 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.  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 interactive debugger glossary section 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 buffer xaddress minus the first address specified in the received text stream.  This offset is then added to every byte's file address (specified in the text stream) to calculate the destination address.  This scheme allows the data in a text hex dump file with arbitrary reported addresses to be loaded starting at any desired location in the 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.

Type: kernel function
Forth name: RECEIVE.HEX
Header file: memory.h

void RELEASE( xaddr* resourceAddr)

If the current task owns the resource variable referenced by resourceAddr (that is, if resourceAddr contains the current task's TASKBASE address), releases the resource by storing zero in xresource.  Otherwise, does nothing; this prevents a task from RELEASEing a resource controlled by another task.  Interrupts are not disabled and Pause() is not executed.

See also GET() and RESOURCE

Type: macro
Related Forth function: RELEASE
Header file: mtasker.h

void Release( xaddr* resourceAddr, uint resourcePage)

A subsidiary function called by the recommended macro RELEASE(); see RELEASE().

Type: kernel function
Forth name: RELEASE
Header file: mtasker.h

RELEASE_AFTER_LINE

A constant which is the default value stored into the SERIAL_ACCESS user variable.  If stored into (assigned to) SERIAL_ACCESS, prevents the low level I/O functions Key() Emit() and AskKey() from executing GET() or RELEASE() on the active serial resource variable.  Rather, the task program installed by ACTIVATE() is responsible for executing GET() before each line is received and RELEASE() after each line is received.  This SERIAL_ACCESS method is used by the QED-Forth interpreter to virtually eliminate the overhead required to GET and RELEASE during downloads.

CAUTION: In multitasking systems using both serial ports Serial1 and Serial2, the application code should include the command,

SERIAL_ACCESS = RELEASE_ALWAYS; 

or

SERIAL_ACCESS = RELEASE_NEVER; 

before building the tasks.  This prevents contention that can occur if the default RELEASE_AFTER_LINE option is installed in the SERIAL_ACCESS user variable.

See also SERIAL_ACCESS, RELEASE_NEVER, and RELEASE_ALWAYS

Type: constant
Related Forth function: RELEASE.AFTER.LINE
Header file: mtasker.h

RELEASE_ALWAYS

A constant.  Returns a value that, when stored into the SERIAL_ACCESS user variable, causes the low level I/O functions Key() Emit() and AskKey() to always RELEASE the serial resource variable after each I/O operation.  This is useful if the task that has control over the serial line wants to share access to the serial port.

See also SERIAL_ACCESS, RELEASE_NEVER, and RELEASE_AFTER_LINE

CAUTION: You may find that storing RELEASE_ALWAYS into the QED-Forth task's SERIAL_ACCESS variable decreases the sustainable download baud rate.  To assure the highest sustainable download baud rate, it is recommended that RELEASE_AFTER_LINE be stored in the QED-Forth task's SERIAL_ACCESS variable during program development.

CAUTION: In multitasking systems using both serial ports Serial1 and Serial2, the application code should include the command

SERIAL_ACCESS = RELEASE_ALWAYS; 

or

SERIAL_ACCESS = RELEASE_NEVER; 

before building the tasks.  This prevents contention that can occur if the default RELEASE_AFTER_LINE option is installed in the SERIAL_ACCESS user variable.

Type: constant
Related Forth function: RELEASE.ALWAYS
Header file: mtasker.h

RELEASE_NEVER

A constant.  Returns a value that, when stored into the SERIAL_ACCESS user variable, prevents the low level I/O functions Key() Emit() and AskKey() from executing the command RELEASE(SERIAL).  This is useful if the task that has control over the serial line does not want to share access to the serial port.

See also SERIAL_ACCESS, RELEASE_ALWAYS, and RELEASE_AFTER_LINE

CAUTION: You may find that storing RELEASE_NEVER into the QED-Forth task's SERIAL_ACCESS variable decreases the sustainable download baud rate.  To assure the highest sustainable download baud rate, it is recommended that RELEASE_AFTER_LINE be stored in the QED-Forth task's SERIAL_ACCESS variable during program development.

CAUTION: In multitasking systems using both serial ports Serial1 and Serial2, the application code should include the command,

SERIAL_ACCESS = RELEASE_ALWAYS; 

or

SERIAL_ACCESS = RELEASE_NEVER; 

before building the tasks.  This prevents contention that can occur if the default RELEASE_AFTER_LINE option is installed in the SERIAL_ACCESS user variable.

Type: constant
Related Forth function: RELEASE.NEVER
Header file: mtasker.h

REQUIRED_SEGMENTS_MAX

A constant equal to fourteen that specifies the maximum number of segments (libraries or applications) that can be required by a given segment.  This constant is used in the definition of the SEGMENT_STRUCT that is emplaced at the start of the code area of each segment.  This low-level constant is typically not used by the programmer.

Type: macro
Header file: segments.h

int ResizeHandle( xaddr xhandle, long new_size)

Attempts to resize the heap item associated with xhandle so that it has new_size bytes.  Retains as much data as possible in the heap item.  The heap must have enough space to copy the heap item to be successful.  A true flag is returned if the heap item is successfully resized.  A false flag indicates failure (due to an invalid xhandle or inadequate heap space) and the original heap item is left unchanged.

Type: constant
Related Forth function: RESIZE.HANDLE
Header file: heap.h

RESOURCE

This typedef allocates a 32-bit resource variable in the common RAM.  Use as:

RESOURCE   <name>; 

where <name> is any name of your choosing.  Resource variables are used in multitasked systems to control access to shared resources (for example, an A/D converter, serial port, block of memory, etc.) When the resource associated with <name> is available, <name> contains zero.  When it is controlled by a task (and hence unavailable to other tasks), it contains the TASKBASE address of the controlling task; consult the glossary entries for TASK and TASKBASE.  Before its first use, the resource variable must be initialized to zero.  After initialization to zero, the only operators that should access the resource variable are GET() TRY_TO_GET() and RELEASE().  The following resource variables are pre-defined in the mtasker.h file:

SPI_RESOURCE      SERIAL
SERIAL1_RESOURCE  SERIAL2_RESOURCE

See their glossary entries and consult the Multitasking chapter in the Software Manual for further descriptions and examples of use.

Type: typedef
Related Forth function: RESOURCE.VARIABLE:
Header file: mtasker.h

RIGHT_PLACES

A 16-bit user variable that holds the number of digits to be displayed to the right of the decimal point when a floating point number is printed in FIXED format.

See also FPtoString(), PrintFP() and FIXED()

Type: macro
Related Forth function: RIGHT.PLACES
Header file: numbers.h

ulong Room( void)

Returns the number of bytes available in the HEAP. NOTE: because there is some overhead (up to 12 bytes) associated with adding an item to the heap, you may not be able to dimension a new heap item that requires the exact number of bytes returned by Room().

Type: kernel function
Forth name: ROOM
Header file: heap.h

void RS485Init( void)

Initializes the bits that control the RS485 direction for both serial channels 1 and 2 as outputs, with the default starting states of the RS485 links set to the receive mode.  This routine is automatically called at each COLD or WARM restart or powerup.

Type: kernel function
Forth name: RS485.INIT
Header file: heap.h

void RS485Receive( int id)

Places the RS485 transceiver for serial channel id in the receive mode.  The id parameter = 1 or 2, and designates either the serial1 or serial2 channel, respectively. (Make sure that the onboard RS485 jumper for the specified RS485 channel is properly configured before attempting to use the RS485 interface). Use care not to call this function while a character transmission is in progress, as the transmission will be corrupted; see RS485TransmitDone().

See also RS485Transmit()

Type: kernel function
Forth name: RS485.RECEIVE
Header file: serial.h

void RS485Transmit( int id)

Places the RS485 transceiver for serial channel id in the transmit mode.  The id parameter = 1 or 2, and designates either the serial1 or serial2 channel, respectively. (Make sure that the onboard RS485 jumper for the specified RS485 channel is properly configured before attempting to use the RS485 interface).  Use care not to call this function while data is being received, as the data will be corrupted.

See also RS485Receive()

Type: kernel function
Forth name: RS485.TRANSMIT
Header file: serial.h

int RS485TransmitDone( int id )

Returns a true flag when the serial channel with the specified id has completed its transmission.  The id parameter = 1 or 2, and designates either the serial1 or serial2 channel, respectively.  This function can be used to ensure that RS485Receive is not called while a character transmission is in progress.

Note that if you are using the Queued Serial library, this function does not work due to a low-level conflict in usage of the hardware flag upon which this function relies. See Transmit_Q_Empty() for instructions on determining reliably that an RS485 transmission has completed when using Queued Serial.

RTI_ID

A constant that returns the interrupt identity code for the real time interrupt.  Used as an argument for ATTACH().  Note that this interrupt is used by the multitasker.

Type: constant
Related Forth function: RTI.ID
Header file: interupt.h

SAVE_STRING( name, value )

Declares a constant character array name in flash ROM holding the string literal value, and also declares a global 32-bit pointer for use in later retrieving this string with LOAD_STRING.

See also: FLASH_IPRINTF(), FLASH_PRINT(), FLASH_PRINTF(), FLASH_SNIPRINTF(), FLASH_SNPRINTF(), LOAD_STRING(), LOADED_STRING

Availability: Mosaic IDE+ revision 1231 or greater
Type: macro
Header File: utility.h

SCI0_ID

A constant that returns the interrupt identity code for the asynchronous serial communications interface channel 0 which is the primary serial port (serial1) of the operating system.  Used as an argument for ATTACH().

Type: constant
Related Forth function: SCI0.ID
Header file: interrupt.h

SCI1_ID

A constant that returns the interrupt identity code for the asynchronous serial communications interface channel 1 which is the secondary serial port (serial2) of the operating system.  Used as an argument for ATTACH().

Type: constant
Related Forth function: SCI1.ID
Header file: interrupt.h

void SCIENTIFIC( void )

Sets the default printing format used by PrintFP() and FPtoString() to scientific.  For more details, see the glossary entry for FPtoString().

Type: macro
Related Forth function: SCIENTIFIC
Header file: numbers.h

extern SEG_ARRAY_ENTRY SEG_ARRAY[SEGMENTS_MAX]

An array of type SEG_ARRAY_ENTRY with SEGMENTS_MAX items in EEPROM used to store metadata for loaded firmware, generally driver software for modular add-on hardware.  See SEG_ARRAY_ADDR().  This low-level array is typically not used by the programmer.

Type: system global EEPROM array
Header file: segments.h

SEG_ARRAY_ADDR( )

A macro that, given the segment_ID of a library or application as a parameter, returns the address of that segment’s entry in the operating system’s segment array in EEPROM.  Each segment is assigned an integer ID by the operating system and/or IDE.  Each item in the array consists of a SEG_ARRAY_ENTRY struct; see its glossary entry.  This low-level macro is typically not used by the programmer.

Type: macro
Header file: segments.h

SEG_ARRAY_ENTRY

A struct that specifies the items stored in each entry in the segment array.  The struct is defined as:

typedef struct
{ uchar seg_code_base_page;   // starting page of code area
  uint  seg_code_base_addr;   // base addr of code area
  uchar seg_header_page;      // page of segment name header
  uint  seg_header_base_addr; // addr of segment name header
  uint  seg_varstart_addr;    // base addr of variable area
  uint  seg_eestart_addr;     // base addr of eeprom variable area
} SEG_ARRAY_ENTRY;

This ten-byte struct in eeprom segment array contains data that is used to enable C to invoke functions and variables defined in Forth segments.  This low-level struct is typically not used by the programmer.

Type: struct
Header file: segments.h

SEG_CODE_XBASE( )

A macro that, given the segment_ID of a library or application as a parameter, returns the 32-bit xaddress of that segment’s code area base.  This low-level macro is typically not used by the programmer.

Type: macro
Header file: segments.h

SEG_EEVARSTART( )

A macro that, given the segment_ID of a library or application as a parameter, returns the address of that segment’s “EEPROM variable” area.  This low-level macro is typically not used by the programmer.

Type: macro
Header file: segments.h

SEG_VARSTART( )

A macro that, given the segment_ID of a library or application as a parameter, returns the address of that segment’s variable area in common RAM.  This low-level macro is typically not used by the programmer.

Type: macro
Header file: segments.h

SEG_XNFA( )

A macro that, given the segment_ID of a library or application as a parameter, returns the 32-bit extended name field address (XNFA) of that segment’s header in the names area.  This low-level macro is typically not used by the programmer.

Type: macro
Header file: segments.h

SEGMENT_STRUCT

A 32-byte struct that specifies the items stored at the base of the code area of each library or application segment.  The struct is defined as:

typedef struct
{ uchar segment_index;             // segment_id of this segment, 1 ≤ id ≤ 23
  THREE_BYTES  segment_code_size;  // 24-bit size of code area, always even
  uchar segment_varstart_page;     // page of variable area base
  uint  segment_varstart_addr;     // addr of variable area base
  uint  segment_variable_size;     // 16-bit size of variable area
  uchar segment_eevarstart_page;   // page of eeprom variable area base
  uint  segment_eevarstart_addr;   // addr of eeprom variable area base
  uint  segment_eevariable_size;   // 16-bit size of eeprom variable area
  uint  segment_compilation_start_addr; // 16-bit compilation base address
  uint  segment_code_checksum;     // 16-bit checksum over code area of segment
  char  required_segments[REQUIRED_SEGMENTS_MAX];  // decimal 14 bytes
} SEGMENT_STRUCT;                  // decimal 32 bytes, at base of each segment

This low-level struct is used by the operating system to locate, relocate, and call functions within the compiled segments; it is typically not used by the programmer.

Type: struct
Header file: segments.h

SEGMENTS_MAX

A constant equal to twenty four that specifies the maximum number of segments allowed.  The kernel has segment_ID 0, and ID’s 1 through 23 are available for additional library and application segments.  This low-level macro is typically not used by the programmer.

Type: macro
Header file: segments.h

SELF_CLOCK_ID

A constant that returns the interrupt identity code for the self-clock interrupt.  Used as an argument for ATTACH().

Type: constant
Related Forth function: SELF.CLOCK.ID
Header file: interrupt.h

void SEND( long message, long * mailboxAddr)

Executes Pause() until the mailbox with extended address mailboxAddr is empty (contains zero) and then stores the 32-bit message in mailboxAddr.  The message can be any 32-bit quantity except zero; use FSEND() to send a floating point value as a message.  For example, the message can be an array address returned by ARRAYMEMBER() that points to a block of data.  To ensure that the state of the mailbox is correctly determined, SEND() disables interrupts for 0.75 to 1.55 microseconds.

See also FSEND(), TRY_TO_SEND(), RECEIVE() and MAILBOX

Type: macro
Related Forth function: SEND
Header file: mtasker.h

void Send( long message, long * mailboxAddr, uint mailboxPage)

A subsidiary function called by the recommended macro SEND(); see SEND().

Type: kernel function
Forth name: SEND
Header file: mtasker.h

SERIAL

A constant that returns the address of the resource variable associated with the primary serial I/O port.  A synonym for SERIAL1_RESOURCE (see its glossary entry).

Type: macro constant
Related Forth function: SERIAL
Header file: mtasker.h

void Serial1AtStartup( 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 SCI0 hardware UART.

See also UseSerial1() and Serial2AtStartup()

Type: kernel function
Forth name: SERIAL1.AT.STARTUP
Header file: serial.h

SERIAL1_RESOURCE

A system global resource variable associated with the primary serial I/O port.  This resource variable mediates access to the primary serial port (serial1) associated with the processor’s on-chip hardware UART SCI0. SERIAL1_RESOURCE should be accessed only by the functions GET(), TRY_TO_GET() and RELEASE().  Initialized to zero by UseSerial1() and at each reset or restart.

See also RESOURCE

Type: system global variable
Related Forth function: SERIAL1.RESOURCE
Header file: mtasker.h

void Serial2AtStartup( int baud)

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 SCI1 hardware UART.

See also UseSerial2() and Serial1AtStartup()

Type: kernel function
Forth name: SERIAL2.AT.STARTUP
Header file: serial.h

SERIAL2_RESOURCE

A system global resource variable that mediates access to the secondary serial port (serial2).  The serial2 port is supported by the processor’s SCI1 hardware UART. SERIAL2_RESOURCE should be accessed only by the functions GET(), TRY_TO_GET() and RELEASE().  Initialized to zero by UseSerial2() and at each reset or restart.

See also RESOURCE

Type: system global variable
Related Forth function: SERIAL2.RESOURCE
Header file: mtasker.h

SERIAL_ACCESS

SERIAL_ACCESS is a 16-bit user variable (member of the currently active TASK.USER_AREA structure) that contains a flag that controls when a task GETs and RELEASEs access to the serial resource.  If more than one task needs access to the serial I/O port, this flag can help specify which task (if any) gets priority use.  If SERIAL_ACCESS contains the value RELEASE_ALWAYS, then each I/O operation by Key() Emit() or AskKey() will GET() the active serial resource before each I/O operation and RELEASE() the active serial resource after each character I/O operation is complete.  If SERIAL_ACCESS contains the value RELEASE_NEVER, then I/O operations called by the task always GET() but never RELEASE() the serial resource variable.  If SERIAL_ACCESS contains the value RELEASE_AFTER_LINE, then Key() Emit() and AskKey() never GET() or RELEASE() the serial resource.  Rather, the QED-Forth interpreter GET()s the serial resource before each line is received and RELEASE()s the serial resource after each line is interpreted.  This virtually eliminates the overhead required to GET() and RELEASE() during downloads.  The default value stored in SERIAL_ACCESS after a COLD restart is RELEASE_AFTER_LINE.

CAUTION: In multitasking systems using both serial ports SERIAL1 and SERIAL2, the application code should include the command

SERIAL_ACCESS = RELEASE_ALWAYS; 

or

SERIAL_ACCESS = RELEASE_NEVER; 

before building the tasks.  This prevents contention that can occur if the default RELEASE_AFTER_LINE option is installed in the SERIAL_ACCESS user variable.

See also SERIAL1_RESOURCE, SERIAL2_RESOURCE, GET(), RELEASE(), Key(), Emit() and AskKey()

Type: macro
Related Forth function: SERIAL.ACCESS
Header file: user.h

SET_BITS( MASK, PTR )

For each bit of MASK that is set, sets the corresponding bit of the 8 bit value at the 16-bit address PTR with interrupts disabled to ensure integrity of the read-modify-write operation.  This is a macro which calls SetBits(), but allows a C pointer to common memory to be directly passed as a parameter (most commonly a pointer to an IO port or configuration flag byte). See its glossary entry below.

Availability: Mosaic IDE+ revision 1500 or greater
Type: macro
Header file: memory.h

void SetBits( uchar mask, xaddr address)

For each bit of mask that is set, sets the corresponding bit of the 8 bit value at address.  Disables interrupts for 0.5 microseconds to ensure an uninterrupted read/modify/write operation.

See also ClearBits(), ToggleBits(), and ChangeBits()

Type: kernel function
Forth name: SET.BITS
Header file: memory.h

void SetBootVector( uint fn_addr, uint fn_page, int v_index)

Configures the function specified by fn_addr on fn_page 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 ClearBootVectors(), or invoking the cleanup procedure described in the 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 CheckstartEnable().  Note that this function is typically executed interactively using the Forth operating system; see SET.BOOT.VECTOR in the interactive debugging section of this glossary.

Type: kernel function
Forth name: SET.BOOT.VECTOR
Header file: opsystem.h

void SetWatch( hundredth_seconds, seconds, minute, hour, day, date, month, year)

Sets the battery-operated real-time clock (if present) to the time, day, and date specified by the input parameters.  The input parameters and their allowed ranges are:

             description  range
                    year  0 - 99
                   month  1 - 12
                    date  1 - 31
                     day  1 -  7
                    hour  0 - 23
   minute after the hour  0 - 59
seconds after the minute  0 - 59
       hundredth_seconds  0 - 99

Due to a hardware limitation, the hundredths of second parameter is ignored; it is included in the parameter list to maintain backward compatibility with prior code.  Once correctly set, the watch handles the differing numbers of days in each month, and correctly handles leap years.

See also ReadWatch()

Type: kernel function
Forth name: SET.WATCH
Header file: watch.h

uint SIZEOFMEMBER( FORTH_ARRAY* array_ptr)

A macro that returns the number of bytes per element in the Forth array designated by array_ptr.  An unpredictable result is returned if the array is not dimensioned.

Example of use:

FORTH_ARRAY  Myarray;         // define an array named Myarray
DIM(ulong, 3, 5, &Myarray);   // 3 rows x 5 columns of unsigned longs
static uint  size_of_each_member;
size_of_each_member = SIZEOFMEMBER(&Myarray);

Consult the FORTH_ARRAY glossary entry for a description of how to define an array and its corresponding array_ptr.

See also DIM()

Type: macro
Related Forth function: BYTES/ELEMENT
Header file: array.h

A macro for declaring a minimal task area of 1152 bytes. In general TASK should be used instead, unless your application has a tight budget for common RAM space. Code executed by a SMALL_TASK must not call printf or LOAD_STRING or any functions in the FLASH_PRINT() family, and must limit the depth of function calls. See TASK for more information, and see a detailed definition below.

#define REENT_PADBYTES       ( 512 - sizeof( struct _reent ) )
#define SMALL_BELOWPAD_SIZE      0
#define SMALL_PAD_SIZE           0
#define SMALL_DSTACK_SIZE    ( 256 - sizeof( struct userArea ) )
#define SMALL_RSTACK_SIZE      384
 
struct small_taskArea                      // 1+1/8 k total
{
    struct userArea user_area;             // 186 byte user area struct
    char   belowpad[SMALL_BELOWPAD_SIZE];  // ZERO bytes below pad can be used
    char        pad[SMALL_PAD_SIZE];       // ZERO bytes for pad
    char     dstack[SMALL_DSTACK_SIZE];    // 70 bytes
    char     rstack[SMALL_RSTACK_SIZE];    // 384 bytes
    struct _reent _reent_placeholder;      // 501 bytes
    char reent_padding[REENT_PADBYTES];    // 11 bytes
};
 
#define  SMALL_TASK __attribute__((section (".taskareas"))) struct  small_taskArea

Type: macro
Header file: user.h

char SmartIOFetchChar( int offset, int module_num)

Fetches a byte from the specified offset (0 ≤ offset ≤ 255) in the smart processor-carrying Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  Disables interrupts for 1.5 .microseconds.

Type: kernel function
Forth name: SMART.IO.C@
Header file: ioaccess.h

float SmartIOFetchFloat( int offset, int module_num)

Fetches a 32-bit floating point number from the specified offset (0 ≤ offset ≤ 255) in the smart processor-carrying Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  Disables interrupts for an isolated period of 1.5 microseconds for each byte fetched.

Type: kernel function
Forth name: SMART.IO.F@
Header file: ioaccess.h

int SmartIOFetchInt( int offset, int module_num)

Fetches a 16-bit integer from the specified offset (0 ≤ offset ≤ 255) in the smart processor-carrying Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  Disables interrupts for an isolated period of 1.5 microseconds for each byte fetched.

Type: kernel function
Forth name: SMART.IO.@
Header file: ioaccess.h

long SmartIOFetchLong( int offset, int module_num)

Fetches a 32-bit long number from the specified offset (0 ≤ offset ≤ 255) in the smart processor-carrying Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  Disables interrupts for an isolated period of 1.5 microseconds for each byte fetched.

Type: kernel function
Forth name: SMART.IO.2@
Header file: ioaccess.h

SPI0_ID

A constant that returns the interrupt identity code for the synchronous serial peripheral interface channel 0 which is the SPI channel used on the Wildcard bus and the communications link used by the battery-backed real-time clock.  Used as an argument for ATTACH().

Type: macro
Related Forth function: SPI0.ID
Header file: interrupt.h

SPI1_ID

A constant that returns the interrupt identity code for the synchronous serial peripheral interface channel 1 which is reserved for inter-processor communications on multi-processor systems.  Used as an argument for ATTACH().

Type: macro
Related Forth function: SPI1.ID
Header file: interrupt.h

SPI2_ID

A constant that returns the interrupt identity code for the synchronous serial peripheral interface channel 2 which is reserved for inter-processor communications on multi-processor systems.  Used as an argument for ATTACH().

Type: macro
Related Forth function: SPI2.ID
Header file: interrupt.h

SPI_10KHZ

A constant to be passed to SPIConfig() to specify a 10 KHz clock rate for an SPI channel. See SPIFrequencies.

Availability: Mosaic IDE+ revisions greater than 1300
Type: macro
Header file: serial.h

SPI_89KHZ

A constant to be passed to SPIConfig() to specify an 89 KHz clock rate for an SPI channel. Recommended for systems that specify a maximum clock rate of 100 KHz. See SPIFrequencies.

Availability: Mosaic IDE+ revisions greater than 1300
Type: macro
Header file: serial.h

SPI_10KHZ

A constant to be passed to SPIConfig() to specify a 1 MHz clock rate for an SPI channel. See SPIFrequencies.

Availability: Mosaic IDE+ revisions greater than 1300
Type: macro
Header file: serial.h

SPI_CHAN0

A constant equal to zero to be passed to SPIConfig() and SPIExchange() for clarity in specifying an SPI channel.

Availability: Mosaic IDE+ revisions greater than 1300
Type: macro
Header file: serial.h

SPI_CHAN1

A constant equal to one to be passed to SPIConfig() and SPIExchange() for clarity in specifying an SPI channel.

Availability: Mosaic IDE+ revisions greater than 1300
Type: macro
Header file: serial.h

SPI_CHAN2

A constant equal to two to be passed to SPIConfig() and SPIExchange() for clarity in specifying an SPI channel.

Availability: Mosaic IDE+ revisions greater than 1300
Type: macro
Header file: serial.h

SPI_FALLING_LEADING_EDGE

A constant that returns a clock edge specifier to be passed to the SPIConfig() function to specify the SPI (serial peripheral interface) data-valid clock edge. SPI_FALLING_LEADING_EDGE specifies a clock that idles in the logic high state, with data valid and sampled on the falling leading edge transition of the clock.

Implementation detail: When passed to SPIConfig(), results in CPOL = 1 and CPHA = 0 in the SPI0CR1 register of the SPI0 channel.

Type: macro
Related Forth function: SPI.FALLING.LEADING.EDGE
Header file: serial.h

SPI_FALLING_TRAILING_EDGE

A constant that returns a clock edge specifier to be passed to the SPIConfig() function to specify the SPI (serial peripheral interface) data-valid clock edge. SPI_FALLING_TRAILING_EDGE specifies a clock that idles in the logic low state, with data valid and sampled on the falling trailing edge transition of the clock.  Data is transferred on the rising leading clock edge so that it is stable and ready to be sampled at the falling trailing edge.  This is the default clock edge specifier established after a power-up or restart, and it is the proper configuration for communications with the onboard battery-backed Real-Time clock that is performed by the operating system’s SetWatch() and ReadWatch() functions.

Implementation detail: When passed to SPIConfig(), results in CPOL = 0 and CPHA = 1 in the SPI0CR1 register of the SPI0 channel.

Type: macro
Related Forth function: SPI.FALLING.TRAILING.EDGE
Header file: serial.h

SPI_READBACK

A constant equal to TRUE to be passed to SPIExchange() for clarity in specifying that data is to be received in the specified buffer simultaneously with transmit.

Availability: Mosaic IDE+ revisions greater than 1300
Type: macro
Header file: serial.h

SPI_RESOURCE

A system global RESOURCE variable associated with the serial peripheral interface channel 0 (SPI0) which is used for data transfer to and from the Wildcard bus and the battery-backed real-time clock.  Should be accessed only by the functions GET(), TRY_TO_GET() and RELEASE().  Initialized to zero at each reset or restart. SPI_RESOURCE is automatically acquired by the battery-backed real-time clock device driver routines.

Generally user applications will not acquire SPI_RESOURCE directly, but rather call SPISave() and SPIRestore().

See also: RESOURCE, SPISave(), SPIRestore()

Type: system global variable
Related Forth function: SPI.RESOURCE
Header file: mtasker.h

SPI_RISING_LEADING_EDGE

A constant that returns a clock edge specifier to be passed to the SPIConfig() function to specify the SPI (serial peripheral interface) data-valid clock edge. SPI_RISING_LEADING_EDGE specifies a clock that idles in the logic low state, with data valid and sampled on the rising leading edge transition of the clock.

Implementation detail: When passed to SPIConfig(), results in CPOL = 0 and CPHA = 0 in the SPI0CR1 register of the SPI0 channel.

Type: macro
Related Forth function: SPI.RISING.LEADING.EDGE
Header file: serial.h

SPI_RISING_TRAILING_EDGE

A constant that returns a clock edge specifier to be passed to the SPIConfig() function to specify the SPI (serial peripheral interface) data-valid clock edge. SPI_RISING_TRAILING_EDGE specifies a clock that idles in the logic high state, with data valid and sampled on the rising trailing edge transition of the clock.  Data is transferred on the falling leading clock edge so that it is stable and ready to be sampled at the rising trailing edge.

Implementation detail: When passed to SPIConfig(), results in CPOL = 1 and CPHA = 1 in the SPI0CR1 register of the SPI0 channel.

Type: macro
Related Forth function: SPI.RISING.TRAILING.EDGE
Header file: serial.h

SPI_SENDONLY

A constant equal to FALSE to be passed to SPIExchange() for clarity in specifying that data is only to be transmitted, and that the data appearing on the receive pin is to be ignored.

Availability: Mosaic IDE+ revisions greater than 1300
Type: macro
Header file: serial.h

void SPIConfig( int clock_edge_specifier, int spibr_contents, int spi_channel )

Configures the specified spi_channel (= 0, 1 or 2) based on the specified clock and baud rate input parameters.  The clock_edge_specifier is one of the constants SPI_FALLING_TRAILING_EDGE (the default after a power-up or restart for all 3 SPI channels), SPI_RISING_LEADING_EDGE, SPI_FALLING_LEADING_EDGE, or SPI_RISING_TRAILING_EDGE; consult their glossary entries.  The clock idles in the low state for the first two of these clock_edge_specifiers, and idles in the logic high state for the latter two.  Each named constant describes the clock edge at which the data is sampled and valid; the data is typically transferred on the SPI bus one half cycle before the specified edge.  The spibr_contents input parameter is the baud rate specifier.  All other configuration parameters (master/slave, mode fault enable, SPI interrupt enable, bit order, /SS direction) are unchanged by this routine, and typically retain the state set by InitSPI() for the SPI0 channel, or InitIPSPI() for the SPI1 and SPI2 channels. InitSPI() is called upon each reset and restart, but InitIPSPI() is not, and must be explicitly called by application code before calling SPIConfig(); consult their glossary entries for configuration details.  The SPI0 channel’s default baud register contents equal 0x40 after a power-up or restart, corresponding to a 2 Mhz SPI clock frequency.  The default SPI_FALLING_TRAILING_EDGE with a 2 MHz baud rate is a common configuration, and is proper for the on-chip battery-backed Real-Time Clock which shares the SPI0 channel.  The SPI0 bus is brought out to the Wildcard bus and is available for communication with various peripherals, provided that each peripheral is selected by a unique chip select signal.  The processor’s SPI1 and SPI2 buses come up at a default baud rate of 5 MHz.  To select a configuration for a given SPI peripheral, consult the peripheral’s data sheet to discover the proper data-valid clock edge and baud rate.  Execute the interactive (Forth) SPI.FREQUENCIES function from the terminal to obtain a printout summarizing the available baud rates and corresponding SPIBR baud register contents; consult the SPIFrequencies() glossary entry.

Example of use: Let’s assume that we are interfacing to an SPI peripheral on SPI0 that samples data on the SPI_RISING_TRAILING_EDGE of a clock that idles high, and can run at up to 100 kHz SPI clock frequencies.  Using SPI.FREQUENCIES, we note that the fastest attainable baud rate under 100 kHz is 89 kHz, corresponding to an spibr_contents parameter of 0x64. To interact with this peripheral device, we save the current SPI configuration state using SPISave(), set the new configuration parameters using SPIConfig(), communicate with the peripheral by strobing its unique chip select signal and exchanging data using the SPIExchange() function, and restore the prior SPI configuration using SPIRestore().  To implement this example, execute:

ulong prior_spi_state;      // declare a temporary 32-bit variable to hold state
prior_spi_state = SPISave();   // save prior SPI configuration state, executes Get()
SPIConfig(SPI_RISING_TRAILING_EDGE, 0x64, 0);
// assert the unique chip select for the specific ''SPI0'' peripheral here and
// call SPIExchange() as needed to talk to the peripheral
// de-assert the unique chip select for the specific SPI peripheral here
SPIRestore(prior_spi_state); // restore prior configuration; also does Release()

This approach enables polite reconfiguration of the clock edge and baud rate for various slaves on the SPI0 bus, and also prevents contention on the SPI bus because SPISave() and SPIRestore() correctly GET() and RELEASE() the SPI_RESOURCE.

Implementation detail: Writes to the SPIxCR1 and SPIxBR registers.

Type: kernel function
Forth name: SPI.CONFIG
Header file: serial.h

void SPIEXCHANGE( void* base_addr, uint numbytes, uint readback, uint spi_channel)

Writes to the specified spi_channel (= 0, 1 or 2) the contents of the buffer specified by base_addr, numbytes number of bytes (0 ≤ numbytes < 32,768).  The buffer must be in common memory (all C variables, arrays and strings are common memory).  If the readback flag is nonzero, then a simultaneous readback from the specified remote SPI is performed, and the incoming bytes are written into the buffer (replacing the transmitted bytes).  This routine does not GET or RELEASE the SPI_RESOURCE, nor does it modify the configuration of the specified SPI channel or activate any chip selects.  If required, these additional functions must be performed by the calling program.  This routine executes at approximately 7 microseconds per byte with a 2 MHz SPI clock.

Type: macro
Related Forth function: SPI.EXCHANGE
Header file: serial.h

void SPIExchange( void* base_addr, uint base_page, uint numbytes, uint readback, uint spi_channel)

A subsidiary Forth function called by the recommended macro SPIEXCHANGE(). This function may be used directly if data is to be exchanged on an SPI channel to or from paged memory by specifying the memory page in the parameter base_page. If the readback flag is nonzero, base_page must be RAM, and the buffer specified by base_addr will be overwritten with incoming data on the SPI channel's MISO pin. 

Type: kernel function
Forth name: SPI.EXCHANGE
Header file: serial.h

void SPIFrequencies( void )

This function prints a formatted table of all 64 possible contents of the SPIBR register (serial peripheral interface baud rate) register in both hex and decimal, followed by the corresponding decimal SPI bus frequency.  Units are kHz, and the result is rounded to the nearest kHz.  To use this function, type:

SPI.FREQUENCIES 

(the Forth version of the function name) interactively at the terminal and examine the resulting data table to select the SPIBR register contents that yield the desired SPI bus clock frequency, and pass the selected value to SPIConfig() (see its glossary entry).  If you prefer to work strictly in C, you can invoke the SPIFrequencies() function from a compiled C program to create the printout.  After a power-up or restart, the default SPI0 baud rate register contents equals 0x40, yielding a 2000 kHz (2MHz) baud rate which is the default for the SPI link on the Wildcard bus; the SPI1 and SPI2 buses run at 5MHz after a restart.  When executed, the first few lines of the resulting printout look like this:

Pass the selected SPIBR constant to SPIConfig (or to SPI.CONFIG in Forth).
0xSPIBR  SPIBR  BAUD.KHZ (decimal)
0x0         0    10000
0x1         1    5000
0x2         2    2500
0x3         3    1250

Type: kernel function
Forth name: SPI.FREQUENCIES
Header file: serial.h

void SPIRestore( ulong prior_spi_config )

Stores the specified 4-byte quantity prior_spi_config into the 4 sequential configuration registers of the SPI0 channel, and then releases the SPI_RESOURCE to make the SPI0 (serial peripheral interface 0) bus available to other tasks.  The input parameter is typically the parameter returned by the SPISave() function, and this SPIRestore() function re-saves the register contents to restore the prior SPI clock edge and baud rate specifications. SPI0 is brought out to the Wildcard bus and is available for communication with various peripherals, provided that each peripheral is selected by a unique chip select signal.  See the glossary entries for SPISave() and SPIConfig() for examples of use.

Note: This function cannot be used with SPI channels 1 and 2.

Implementation detail: Stores the 4-byte input parameter prior_spi_config into the four sequential SPI0 configuration registers SPI0CR1, SPI0CR2, SPI0BR, and SPI0SR, then releases the SPI_RESOURCE.

Type: kernel function
Forth name: SPI.RESTORE
Header file: serial.h

ulong SPISave( void )

GETs the SPI_RESOURCE, then fetches and returns as a 32-bit quantity the contents of the four configuration registers of the SPI0 (serial peripheral interface 0) channel.  After calling SPIConfig() to configure the SPI link and SPIExchange() to talk to the specified peripheral, the output parameter should be passed by the application program as the input to SPIRestore() which restores the prior configuration and releases the SPI_RESOURCE to make SPI0 available to other tasks. SPI0 is brought out to the Wildcard bus and is available for communication with various peripherals, provided that each peripheral is selected by a unique chip select signal.

Example of use: Let’s assume that we are interfacing to a peripheral on SPI channel 0 that samples data on the SPI_RISING_TRAILING_EDGE of a clock that idles high, and can run at up to 100 kHz.  Using SPI.FREQUENCIES or SPIFrequencies() (see its glossary entry), we note that the fastest attainable baud rate under 100 kHz is 89 kHz, corresponding to an spibr_contents parameter of 0x64. To interact with this peripheral device, we save the current SPI configuration state using SPISave(), set the new configuration parameters using SPIConfig(), communicate with the peripheral by strobing its unique chip select signal and exchanging data using the SPIExchange() function, and restore the prior SPI configuration using SPIRestore().  To implement this example, execute:

ulong prior_spi_state;         // declare a temporary 32-bit variable to hold state
prior_spi_state = SPISave();   // save prior SPI configuration state, executes Get()
SPIConfig(SPI_RISING_TRAILING_EDGE, 0x64, 0);
// assert the unique chip select for the specific SPI peripheral here and
// call SPIExchange() as needed to talk to the peripheral
// de-assert the unique chip select for the specific SPI peripheral here
SPIRestore(prior_spi_state); // restore prior configuration; also does Release()

This approach enables polite reconfiguration of the clock edge and baud rate for various slaves on the SPI bus, and also prevents contention on the SPI bus because SPISave() and SPIRestore() correctly GET() and RELEASE() the SPI_RESOURCE.

Implementation detail: Gets the SPI.RESOURCE variable, then fetches the four sequential SPI0 configuration registers SPI0CR1, SPI0CR2, SPI0BR, and SPI0SR and returns them as a 32-bit long.

Note: This function cannot be used with SPI channels 1 and 2.

Type: kernel function
Forth name: SPI.SAVE
Header file: serial.h

void StandardReset( void)

Undoes the effect of the ColdOnReset() command so that subsequent resets will result in the standard warm-or-cold startup sequence.  Note that this function can be executed interactively using QED-Forth syntax by typing from the terminal:

STANDARD.RESET

Type: kernel function
Forth name: STANDARD.RESET
Header file: opsystem.h

void StartTimeslicer( void)

Starts the timeslice clock based on the RealTime Interrupt (RTI) and begins timeslice multitasking.  Initializes the RTI interrupt vector (if it wasn't already initialized) so that the multitasking executive/elapsed-time clock routine services the interrupt.  Enables the RTI interrupt mask and globally enables interrupts by clearing the I bit in the condition code register of each built task.

Notes:

1. The default timeslice clock period of 1.024 msec can be changed with the command MsecTimeslicePeriod().

2. StartTimeslicer() does not initialize the value in TIMESLICE_COUNT; execute InitElapsedTime() if you wish to initialize the clock count to zero.

3. After a restart, the system is configured so that timeslice multitasking can begin at any time; if no other tasks have been built, the FORTH_TASK (which is also the task that calls main) is the only task in the task loop.

4. The timeslicer's interrupt service routine disables interrupts for the duration of a task switch which requires 5 microseconds plus 0.5 microseconds for each ASLEEP task encountered in the task list.

See also: FetchTSCount(), TIMESLICE_COUNT, CountToMsec(), and ReadElapsedSeconds().

Type: kernel function
Forth name: START.TIMESLICER
Header file: mtasker.h

STATUS

STATUS is the first element in the currently active task's TASK.USER_AREA structure; its contents specify whether the task is ASLEEP or AWAKE.  The following example shows how to access the status address of another task that has been defined using the TASK directive:

TASK  AnyTask;                            // name and allocate the new task
AnyTask.USER_AREA.user_status = ASLEEP;   // put the task asleep

See the user.h file for a detailed description of all of the user variables, and consult the glossary entries for the constants ASLEEP and AWAKE.

Type: macro
Forth name: STATUS
Header file: user.h

void StatusAtStartup( 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 printouts of the “pages loaded” report at subsequent COLD restarts, and enables the memory map summary 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 NoStatusAtStartup (or interactively type NO.STATUS.AT.STARTUP), or do a factory clean.  To temporarily suppress the status printouts during a COLD restart, see QUIET.COLD in the interactive debugger glossary section.

Type: macro
Forth name: STATUS.AT.STARTUP
Header file: opsystem.h

void StopTimeslicer( void)

Stops the multitasker's timeslice clock by disabling the local RealTime Interrupt (RTI) mask.  Cooperative task switching involving Pause() is not affected.  See StartTimeslicer().  Note that this command also stops the elapsed-time clock; see FetchTSCount(), TIMESLICE_COUNT, CountToMsec(), and ReadElapsedSeconds().

Type: kernel function
Forth name: STOP.TIMESLICER
Header file: mtasker.h

void StoreChar( char value, xaddr address)

Stores the 8-bit value at the specified extended address.  This function is useful for storing data in arrays located in paged memory, where the extended address is returned by ARRAYMEMBER().

Type: kernel function
Forth name: C!
Header file: memory.h

void StoreEEChar( char value, int * addr)

Stores the specified 8-bit value at the specified addr in EEPROM.  Based on the prior contents at the 4-byte aligned EEPROM cell corresponding to the specified addr, this routine determines if the contents will be changed by this operation.  If not, then no programming action is performed, and this helps lengthen the lifetime of the EEPROM.  Requires up to 30 msec per programmed 4-byte-aligned EEPROM cell.  Disables interrupts during the programming of each EEPROM cell.  Caution: The prolonged disabling of interrupts by this function can adversely affect real-time servicing of interrupts.

Creation of an EEPROM variable: An EEPROM variable can be declared as an un-initialized static variable located in the pre-defined ".eeprom" section.  For example, to create a 1-byte EEPROM variable named testEEVar use the following syntax:

char _eeprom testEEVar;

The char keyword causes a 1-byte value to be allocated.  The _eeprom tag instructs the linker to place the variable in the eeprom section.  You must initialize your EEPROM variable at runtime when your application starts up.

Type: kernel function
Forth name: (EEC!)
Header file: memory.h

void StoreEEFloat( float value, float * addr)

Stores the specified 32-bit floating point value at the specified addr in EEPROM.  The most significant word of val is stored at addr and the least significant word is stored at addr+2. Based on the prior contents at the one or two 4-byte aligned EEPROM cells corresponding to the specified addr, this routine determines if the contents will be changed by this operation.  If not, then no programming action is performed, and this helps lengthen the lifetime of the EEPROM.  Requires up to 30 msec per programmed 4-byte-aligned EEPROM cell.  Disables interrupts during the programming of each EEPROM cell.  Caution: The prolonged disabling of interrupts by this function can adversely affect real-time servicing of interrupts.

Creation of an EEPROM variable: An EEPROM variable can be declared as an un-initialized static variable located in the pre-defined ".eeprom" section.  For example, to create a 4-byte EEPROM variable named testEEFVar use the following syntax:

float _eeprom testEEVar;

The float keyword causes a 4-byte floating point eevariable to be allocated.  The _section(".eeprom") tag instructs the linker to place the variable in the eeprom section.  You must initialize your EEPROM variable at runtime when your application starts up.

Type: kernel function
Forth name: (EEF!)
Header file: memory.h

void StoreEEInt( int value, int * addr)

Stores the specified 16-bit value at the specified addr in EEPROM.  Based on the prior contents at the one or two 4-byte aligned EEPROM cells corresponding to the specified addr, this routine determines if the contents will be changed by this operation.  If not, then no programming action is performed, and this helps lengthen the lifetime of the EEPROM.  Requires up to 30 msec per programmed 4-byte-aligned EEPROM cell.  Disables interrupts during the programming of each EEPROM cell.  Caution: The prolonged disabling of interrupts by this function can adversely affect real-time servicing of interrupts.

Creation of an EEPROM variable: An EEPROM variable can be declared as an un-initialized static variable located in the pre-defined ".eeprom" section.  For example, to create a 2-byte EEPROM variable named testEEVar use the following syntax:

int _eeprom testEEVar;

The int keyword causes a 2-byte integer to be allocated.  The _section(".eeprom") tag instructs the linker to place the variable in the eeprom section.  You must initialize your EEPROM variable at runtime when your application starts up.

Type: kernel function
Forth name: (EE!)
Header file: memory.h

void StoreEELong( long value, int * addr)

Stores 32-bit value at the specified addr in EEPROM.  The most significant word of val is stored at addr and the least significant word is stored at addr+2. Based on the prior contents at the one or two 4-byte aligned EEPROM cells corresponding to the specified addr, this routine determines if the contents will be changed by this operation.  If not, then no programming action is performed, and this helps lengthen the lifetime of the EEPROM.  Requires up to 30 msec per programmed 4-byte-aligned EEPROM cell.  Disables interrupts during the programming of each EEPROM cell.  Caution: The prolonged disabling of interrupts by this function can adversely affect real-time servicing of interrupts.

Creation of an EEPROM variable: An EEPROM variable can be declared as an un-initialized static variable located in the pre-defined ".eeprom" section.  For example, to create a 4-byte EEPROM variable named testEELVar use the following syntax:

long _eeprom testEEVar;

The long keyword causes a 4-byte long to be allocated.  The _section(".eeprom") tag instructs the linker to place the variable in the eeprom section.  You must initialize your EEPROM variable at runtime when your application starts up.

Type: kernel function
Forth name: (EE2!)
Header file: memory.h

void StoreFloat( float value, xaddr address)

Stores a 32-bit floating point value at the specified extended address.  This function is useful for storing data in arrays located in paged memory, where the extended address is returned by ARRAYMEMBER().

Type: kernel function
Forth name: F!
Header file: memory.h

STORE_FLOAT_PROTECTED( VALUE, PTR )

Stores the floating point VALUE at the address in common memory specified by the float* PTR, with interrupts disabled to ensure integrity of data shared between tasks. This is a macro which calls StoreFloatProtected(), but allows a C pointer to common memory to be directly passed as the address parameter (i.e. a pointer to a float variable). See its glossary entry below.

Availability: Mosaic IDE+ Revision 1500 or greater
Type: macro
Header file: memory.h

STORE_LONG_PROTECTED( VALUE, PTR )

Stores the 32-bit integer VALUE at the address in common memory specified by the long* PTR, with interrupts disabled to ensure integrity of data shared between tasks. This is a macro which calls StoreLongProtected(), but allows a C pointer to common memory to be directly passed as the address parameter (i.e. a pointer to a long variable). See its glossary entry below.

Availability: Mosaic IDE+ Revision 1500 or greater
Type: macro
Header file: memory.h

void StoreFloatProtected( float value, xaddr address)

Stores the floating point value at the specified extended address.  Disables interrupts during the store to ensure that an interrupting routine or task will read valid data.  This function is useful for storing data in arrays located in paged memory, where the extended address is returned by ARRAYMEMBER().  Disables interrupts for 0.5 microseconds unless the specified 4 bytes straddle a page boundary, in which case interrupts are disabled for approximately 5.4 microseconds.  The most significant word of value is stored at address and the least significant is stored at address+2. Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.

See also FetchFloatProtected()

Type: kernel function
Forth name: |F!|
Header file: memory.h

void StoreInt( int value, xaddr address)

Stores a 16-bit value at the specified extended address.  The high order byte is stored at address and the low order byte at address+1. This function is useful for storing data in arrays located in paged memory, where the extended address is returned by ARRAYMEMBER().

Type: kernel function
Forth name: !
Header file: memory.h

void StoreLong( long value, xaddr address)

Stores a 32-bit value at the specified extended address.  The most significant word of val is stored at address and the least significant is stored at address+2. This function is useful for storing data in arrays located in paged memory, where the extended address is returned by ARRAYMEMBER().

Type: kernel function
Forth name: 2!
Header file: memory.h

void StoreLongProtected( long value, xaddr address)

Stores the 32-bit value at the specified extended address.  Disables interrupts during the store to ensure that an interrupting routine or task will read valid data.  This function is useful for storing data in arrays located in paged memory, where the extended address is returned by ARRAYMEMBER().  Disables interrupts for 0.5 microseconds unless the specified 4 bytes straddle a page boundary, in which case interrupts are disabled for approximately 5.4 microseconds.  The most significant word of val is stored at address and the least significant is stored at address+2. Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.  For floating point values, use StoreFloatProtected().

Type: kernel function
Forth name: |2!|
Header file: memory.h

int StorePages( 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.  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:

StorePages(0, 0x1E); 

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 also: LoadPage(); LoadPages(); LoadPagesAtStartup(), and the entries for STORE.PAGES(), LOAD.PAGE(), LOAD.PAGES(), and LOAD.PAGES.AT.STARTUP() in the interactive debugger glossary section.

Type: kernel function
Forth name: STORE.PAGES
Header file: memory.h

void StringMove( xaddr countedStrAddr, xaddr destination, long numBytes)

Moves the contents of the counted string specified by countedStrAddr to the specified 32-bit destination address.  Does not move the count byte.  The number of characters moved is clamped to a maximum of numBytes bytes.  To use this function to move a null-terminated C-style string into paged memory, first convert the string to a Forth-style counted string using CountedString(), and then move it with this function.  As explained in the glossary entry for CountedString(), the string should contain less than 86 characters.

Example of use: The following code copies a null-terminated C-style string to a buffer in paged memory:

#define DESTINATION = ( (xaddr) 0x071000)   // buffer in page 7 RAM
#define MAX_STRING_CHARS   85
char*  source_string = "This is the string we will move";
xaddr  counted_string = CountedString(source_string, THIS_PAGE);
StringMove(counted_string, DESTINATION, MAX_STRING_CHARS);

See also CountedString()

Type: kernel function
Forth name: $MOVE
Header file: memory.h

void SWAPARRAYS( FORTH_ARRAY* array1_ptr, FORTH_ARRAY* array2_ptr)

Interchanges the contents of the parameter fields of the two specified arrays and leaves the heap undisturbed, thus rapidly swapping the two arrays.  See the FORTH_ARRAY glossary entry for a description of how to define an array and its corresponding array_ptr.

See also FORTH_ARRAY, DIM(), ARRAYFETCH() and ARRAYSTORE()
Type: macro
Related Forth function: SWAP.ARRAYS
Header file: array.h

void SwapArrays( FORTH_ARRAY* array1_ptr, uint pfa_page, FORTH_ARRAY* array2_ptr, uint pfa_page, )

A subsidiary function called by the recommended macro SWAPARRAYS(); see SWAPARRAYS().

Type: kernel function
Forth name: SWAP.ARRAYS
Header file: array.h

SWI_ID

A constant that returns the interrupt identity code for the software interrupt (SWI).  Used as an argument for ATTACH().

Type: constant
Related Forth function: SWI.ID
Header file: interrupt.h

void SysAbort( void)

The default abort routine called by Abort() if the flag in CustomAbort is false.  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.

Type: kernel function
Forth name: (ABORT)
Header file: opsystem.h

TASK

A macro that names and allocates a medium_taskArea structure 2048 bytes total size at the bottom of common RAM for preferential placement in the on-chip region below 0x4000.  In other words, TASK is used to name and locate a new task.  To declare a new task named AnyTask, use the statement:

TASK AnyTask;

Also see the glossary entries for BUILD_C_TASK() and ACTIVATE() for a discussion of how to build and activate the new task.

#define REENT_PADBYTES       ( 512 - sizeof( struct _reent ) )
#define MEDIUM_BELOWPAD_SIZE ( 256 - sizeof( struct userArea ) )
#define MEDIUM_PAD_SIZE        128
#define MEDIUM_DSTACK_SIZE     128
#define MEDIUM_RSTACK_SIZE    1024
 
struct medium_taskArea                     // 2 k total
{
    struct userArea user_area;             // 186 byte user area struct
    char   belowpad[MEDIUM_BELOWPAD_SIZE]; // Up to 70 bytes below pad can be used
    char        pad[MEDIUM_PAD_SIZE];      // 128 bytes
    char     dstack[MEDIUM_DSTACK_SIZE];   // 128 bytes
    char     rstack[MEDIUM_RSTACK_SIZE];   // 1 k
    struct _reent _reent_placeholder;      // 501 bytes
    char reent_padding[REENT_PADBYTES];    // 11 bytes
};
 
#define  TASK       __attribute__((section (".taskareas"))) struct medium_taskArea

See also: FORTH_TASK, EXTRA_TASK, SMALL_TASK, LARGE_TASK

Type: macro
Related Forth function: ALLOCATE.TASK:
Header file: user.h

extern struct userArea* TASKBASE

A pointer to the current task's userArea structure, which contains pointers to its task-private variables, stacks, and buffers.  Each task in a multitasking application has a unique task area (typically decimal 2048 bytes long) named and allocated by the TASK, SMALL_TASK, or LARGE_TASK declaration, and the multitasker updates the contents of TASKBASE to point to the current user area at each task switch initiated by the timeslicer or the application calling Pause(). TASKBASE is defined at a specific location in linking C applications to match the location of the QED-Forth operating system pointer UP (for userArea pointer), and as such UP is defined in C as:

#define  UP             (&TASKBASE)

In other words, TASKBASE returns the contents of the QED-Forth operating system pointer referred to as UP, and TASKBASE is a pointer to the userArea struct associated with the task that is presently controlling program execution.  The base address returned by TASKBASE is also referred to as the task identifier or task id; it is the address in common memory used to identify a particular task.  It is passed as a parameter to BUILD_C_TASK() and ACTIVATE().

NOTE: Before building the tasks in a multitasked application, the current value returned by TASKBASE should be stored into the NEXT_TASK user variable to effectively empty the task loop and kill any extraneous tasks that may be running.  This can be accomplished by executing the statement:

NEXT_TASK = TASKBASE;

before invoking BUILD_C_TASK().

Type: system global variable
Related Forth function: STATUS
Header file: user.h

TCNT_OVERFLOW

A constant channel identifier that can be passed to ECTInterruptEnable() (to enable an interrupt when TCNT overflows), ECTInterruptDisable() (to disable interrupt generation when TCNT overflows) or ECTClearInterruptFlag() (to clear the flag bit associated with the TCNT overflow). TCNT is a free-running 16-bit counter that provides the time base for the Enhanced Capture Timer (ECT) resources including the input capture (IC), output compare (OC) and other timer-controlled channels. TCNT is readable using the TCNTRead() function. TCNT overflow occurs when the counter transitions from 0xFFFF to 0x0000. The overflow can generate an interrupt and/or toggle output compare (OC) lines; see OCToggleOnOverflow() and OCNoToggleOnOverflow().  The glossary entry for ECTPrescaler() includes a discussion of the TCNT period and overflow times.

Type: macro
Related Forth function: TCNT.OVERFLOW
Header file: timerio.h

uint TCNTRead( void )

Returns the contents of the free-running TCNT timer, a read-only 16-bit register that continously counts from 0x0000 to 0xFFFF without stopping. TCNT provides the time base for the Enhanced Capture Timer (ECT) including the input capture (IC), output compare (OC) and other timer-controlled channels.  The glossary entry for ECTPrescaler() presents a discussion of the TCNT period and overflow times, and includes some important notes regarding maintenance of the free-running counter.

See also TCNT_OVERFLOW, ECTPrescaler(), OCToggleOnOverflow() and OCNoToggleOnOverflow()

Type: kernel function
Forth name: TCNT.READ
Header file: timerio.h

THIS_PAGE

A macro that returns the contents of the PAGE_LATCH which indicates the current page. THIS_PAGE is equivalent to:

* PAGE_LATCH 

In general, the PAGE_LATCH may be read but not written to by application programs; only routines that are located in common memory (addresses below 0x8000 or above 0xBFFF) are allowed to write to the PAGE_LATCH.

Type: macro
Related Forth function: THIS.PAGE
Header file: types.h

TIB

A macro that returns the 16-bit start address of the Terminal Input Buffer.  The default size of the terminal input buffer is 96 bytes; it is used by the QED-Forth interpreter when C applications are not running.  C applications must not use the TIB; this area of memory is used internally by the C runtime environment while C applications are running.

Type: macro
Related Forth function: TIB
Header file: user.h

long TIMESLICE_COUNT

32-bit system variable containing the count of the number of timeslicer clock ticks.  The count is set to zero by InitElapsedTime(), and the period of the clock is set by ChangeTaskerPeriod(); the default is 1.024 milliseconds (ms).  TIMESLICE_COUNT must never be read directly (on the right-hand side of a '=' assignment statement) with the timeslicer enabled; use FetchTSCount() instead. To determine the elapsed time between two events in units of milliseconds, simply subtract the corresponding timeslice counts and pass the result to CountToMsec().

See also FetchTSCount(), ReadElapsedSeconds(), CountToMsec(), and InitElapsedTime()

Type: system global variable
Related Forth function: TIMESLICE.COUNT
Header file: mtasker.h

TO_EEPROM( PTR, DESTADDR, NUMBYTES )

Transfers NUMBYTES bytes (0 ≤ NUMBYTES ≤ 65,535) starting at the specified 16-bit common memory address PTR, to the specified destination 16-bit address in on-chip EEPROM, and returns a success flag.  This is a macro which calls ToEEPROM(), but allows a C pointer to common memory to be directly passed as the source address parameter (most commonly a C array or pointer to struct). See its glossary entry below.

Availability: Mosaic IDE+ Revision 1500 or greater
Type: macro
Header file: memory.h

int ToEEPROM( xaddr source, addr destination, uint numBytes)

Transfers numBytes bytes (0 ≤ numBytes ≤ 65,535) starting at the specified source extended address, to the specified destination 16-bit address in on-chip EEPROM, and returns a success flag.  This routine programs only on-chip EEPROM.  The source 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 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 these flash programming routines.

Type: kernel function
Forth name: TO.EEPROM
Header file: memory.h

int ToFlash( 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.

Type: kernel function
Forth name: TO.FLASH
Header file: memory.h

int ToFlashMany( xaddr source, xaddr destination, long numBytes)

Transfers numBytes bytes 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.

Type: kernel function
Forth name: TO.FLASH.MANY
Header file: memory.h

TOGGLE_BITS( MASK, PTR )

For each bit of MASK that is set, reverses the state of the corresponding bit of the 8 bit value at the 16-bit address PTR with interrupts disabled to ensure integrity of the read-modify-write operation.  This is a macro which calls ToggleBits(), but allows a C pointer to common memory to be directly passed as a parameter (most commonly a pointer to an IO port or configuration flag byte). See its glossary entry below.

Availability: Mosaic IDE+ revision 1500 or greater
Type: macro
Header file: memory.h

void ToggleBits( uchar mask, uchar address)

For each bit of mask that is set, reverses the state of the corresponding bit of the 8 bit value at addr.  Disables interrupts for 0.5 microseconds to ensure an uninterrupted read/modify/write operation.

Type: kernel function
Forth name: TOGGLE.BITS
Header file: memory.h

int ToHeap( xaddr xhandle)

If xhandle is a valid 32-bit handle (pointer to a pointer) in the current heap, the heap item associated with the xhandle is returned to the heap (de-allocated), the heap is compacted, and a true flag is returned.  If xhandle is not a valid handle in the current heap, no action is taken and a false flag is returned. ToHeap() is automatically invoked by DELETED().

Type: kernel function
Forth name: TO.HEAP
Header file: heap.h

void ToIO( uint base_addr, uint base_page, int offset, int module_num, uint numbytes)

Transfers +numbytes bytes starting at the specified base_addr on base_page in memory, to the Wildcard with hardware address module_num starting at an address specified by offset (0 ≤ offset ≤ 255), where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  Also works for smart processor-carrying Wildcards.

See also ToIORegister() and FromIO()

Type: kernel function
Forth name: TO.IO
Header file: ioaccess.h

void ToIORegister( uint base_addr, uint base_page, int offset, int module_num, uint numbytes)

Transfers +numbytes bytes starting at the specified base_addr on base_page in memory, to the Wildcard with hardware address module_num at a fixed address specified by offset (0 ≤ offset ≤ 255), where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  The destination Wildcard address is not incremented as the transfer proceeds.  Also works for smart processor-carrying Wildcards.

See also ToIO()

Type: kernel function
Forth name: TO.IO.REGISTER
Header file: ioaccess.h

void ToMemory( 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.  If the destination is in flash, this routine not re-entrant and it disables interrupts, as described in the glossary entries of ToFlash and ToXFlash.  The prolonged disabling of interrupts by this routine can adversely affect real-time servicing of interrupts.

Type: kernel function
Forth name: TO.MEMORY
Header file: memory.h

int ToXFlash( 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.

Type: kernel function
Forth name: TO.XFLASH
Header file: memory.h

xaddr TO_XADDR( void* address, int page )

This C macro combines the specified 16-bit address and page into a single 32-bit extended address.

Type: macro
Header file: types.h

TRAILING_ZEROS

A user variable that contains a 16-bit flag.  If the flag is false, trailing zeroes are not printed when a floating point number is displayed in fixed or floating format by FPtoString() and PrintFP().  If true, trailing zeros are displayed.

See also FPtoString(), PrintFP(), FIXED() and FLOATING()

Type: macro
Related Forth function: TRAILING.ZEROS
Header file: numbers.h

xaddr TransferHeapItem( xaddr xhandle, xaddr HeapEnd)

Copies the heap item specified by xhandle in the current heap into the heap whose CURRENT_HEAP is equal to HeapEnd.  If the operation is successful, returns the 32-bit handle of the new heap item; if unsuccessful, does nothing and returns zero.  To copy a heap item within a single heap, see DupHeapItem().

Type: kernel function
Forth name: TRANSFER.HEAP.ITEM
Header file: heap.h

TRAP_ID

A constant that returns the interrupt identity code for the illegal opcode trap.  Used as an argument for ATTACH().

Type: constant
Related Forth function: TRAP.ID
Header file: interrupt.h

TRIGGER_OFF

A 16-bit constant that returns an edge_identifier that can be passed as an argument to TriggerEdge(). TRIGGER_OFF disables the triggering of the specified input capture or pulse accumulator channel; this is the default after a power-up or hardware reset.

Type: macro
Related Forth function: TRIGGER.OFF
Header file: timerio.h

TRIGGER_ON_ANY_EDGE

A 16-bit constant that returns an edge_identifier that can be passed as an argument to TriggerEdge(). TRIGGER_ON_ANY_EDGE enables triggering on both rising (low-to-high) and falling (high-to-low) edges for the specified input capture or pulse accumulator channel.

Type: macro
Related Forth function: TRIGGER.ON.ANY.EDGE
Header file: timerio.h

TRIGGER_ON_FALLING_EDGE

A 16-bit constant that returns an edge_identifier that can be passed as an argument to TriggerEdge(). TRIGGER_ON_FALLING_EDGE enables triggering on falling (high-to-low) edges for the specified input capture or pulse accumulator channel.

Type: macro
Related Forth function: TRIGGER.ON.FALLING.EDGE
Header file: timerio.h

TRIGGER_ON_RISING_EDGE

A 16-bit constant that returns an edge_identifier that can be passed as an argument to TriggerEdge(). TRIGGER_ON_RISING_EDGE enables triggering on rising (low-to-high) edges for the specified input capture or pulse accumulator channel.

Type: macro
Related Forth function: TRIGGER.ON.RISING.EDGE
Header file: timerio.h

void TriggerEdge( int edge_identifier, int channel_id )

Based on the specified edge_identifier, configures the trigger edge for the input capture or pulse-accumulator specified by channel_id.  Valid edge identifier inputs are the named constants TRIGGER_OFF (the default after a power-up or hardware reset), TRIGGER_ON_RISING_EDGE, TRIGGER_ON_FALLING_EDGE, or TRIGGER_ON_ANY_EDGE.  Valid channel_id’s are input capture (IC) channels 0 through 7, 8-bit pulse accumulator channels 0 through 3, or the named 16-bit PULSE_B accumulator.  Do not use this function to configure PULSE_A.  The arguments PULSE_A, PULSE_A_FALLING_EDGE, PULSE_A_RISING_EDGE, or PULSE_A_GATED_HIGH PULSE_A_GATED_LOW are not valid inputs for this TriggerEdge() function; see PulseASetup().

Pulse accumulator notes: For all pulse accumulators except the 16-bit PULSE_A, the pins associated with a pulse accumulator should be configured as input captures using the InputCapture() routine and this TriggerEdge() routine, and then enabled for pulse counting using the PulseEnable() function (for 8 bit pulse accumulators) or the PulseBSetup() function (for 16 bit pulse accumulators).  To configure the PULSE_B trigger edge, make sure that channel 0 is an input capture by executing:

InputCapture(0);

or

InputCapture(PULSE_B);

and call TriggerEdge() with channel_id = 0 or PULSE_B.

Examples of use: To count rising-edge pulses on the 16-bit PULSE_B accumulator without generating interrupts, execute:

InputCapture(PULSE_B);
TriggerEdge(TRIGGER_ON_RISING_EDGE,  PULSE_B );
PulseBSetup(FALSE, TRUE);

To configure input capture 4 to record the value of TCNT on any rising or falling edge, execute:

TriggerEdge(TRIGGER_ON_ANY_EDGE,  4 );
InputCapture(4);

Implementation detail: Writes a 2-bit field associated with specified channel in TCTL3/4 registers to configure the specified input compare or pulse accumulator edge trigger.

Type: kernel function
Forth name: TRIGGER.EDGE
Header file: timerio.h

TRUE

A constant equal to 1.

Type: constant
Related Forth function: TRUE
Header file: utility.h

int TryToFSend( float message, float * mailboxAddr, uint mailboxPage)

A subsidiary Forth function that is called by the recommended macro TRY_TO_FSEND(); see TRY_TO_FSEND().

Type: Forth function
Forth name: ?SEND
Header file: mtasker.h

int TryToGet( xaddr * resourceAddr, uint resourcePage)

This function performs the actions of the macro TRY_TO_GET(); the macro version is recommended.  The function expects to be passed the parameter resourcePage, which must equal 0 for programs coded in C.

See also TRY_TO_GET()

Type: kernel function
Forth name: ?GET
Header file: mtasker.h

int TryToSend( long message, long * mailboxAddr, uint mailboxPage)

A subsidiary Forth function that is called by the macro TRY_TO_SEND(); see TRY_TO_SEND().

Type: Forth function
Forth name: ?SEND
Header file: mtasker.h

int TRY_TO_FSEND( float message, float * mailboxAddr)

If the mailbox with the specified mailboxAddress is empty (i.e., contains a floating point zero), this routine stores the 32-bit floating point message in mailboxAddr and returns a flag = -1. If xmailbox is not empty, this routine returns a flag = 0 and does not store the message.  Does not execute Pause().  The message can be any 32-bit floating point quantity except 0; use TRY_TO_SEND to send a non-floating-point value as a message.  To ensure that the state of the mailbox is correctly determined, TRY_TO_FSEND() disables interrupts for 0.75 to 1.55 microseconds.

See also FSEND(), FRECEIVE(), and MAILBOX

Type: macro
Related Forth function: ?SEND
Header file: mtasker.h

int TRY_TO_GET( xaddr * resourceAddr)

Checks the resource variable resourceAddr.  If the resource is available (i.e., if it contains 0\0 or the current task's user base address), TRY_TO_GET() claims the resource by storing the current task's 32-bit base address in resourceAddr, and returns a flag equal to -1. Otherwise, TRY_TO_GET() returns a false (0) flag.  Does not execute Pause().  To ensure that the state of the resource is correctly determined, TRY_TO_GET() disables interrupts for 0.25 to 1 microsecond.

See also GET(), RELEASE(), and RESOURCE

Type: macro; Related function: TryToGet()
Header file: mtasker.h

int TRY_TO_SEND( long message, long * mailboxAddr)

If the mailbox with the specified mailboxAddress is empty (ie., contains a 32-bit 0 value), this routine stores the 32-bit message in mailboxAddr and returns a flag = -1. If xmailbox is not empty, this routine returns a flag = 0 and does not store the message.  Does not execute Pause().  The message can be any 32-bit quantity except 0; use TRY_TO_FSEND to send a floating point value as a message.  For example, the message can be an array address returned by ARRAYMEMBER() that points to a block of data.  To ensure that the state of the mailbox is correctly determined, TRY_TO_SEND() disables interrupts for 0.75 to 1.55 microseconds.

See also SEND(), RECEIVE(), and MAILBOX

Type: macro
Related Forth function: ?SEND
Header file: mtasker.h

TWO_INTS

A union typedef that provides a way of converting two 16-bit integers into a 32-bit long, or vis versa.  The definition is:

typedef union { ulong int32;
      struct { int msInt;
               int lsInt;
      } twoNums;
} TWO_INTS;

For example, the following code splits a 32-bit result in longvar into two 16-bit integers in lower16bits and upper16bits:

ulong longvar;
int lower16bits, upper16bits;   // we want to set these
TWO_INTS temporary;   // allocate union to convert type
temporary.int32 = longvar;
lower16bits = temporary.twoNums.lsInt;
lower16bits = temporary.twoNums.msInt;

See also the source code in the TYPES.h file

Type: typedef
Header file: types.h

UABORT

A user variable (member of the currently active TASK.USER_AREA structure) that contains the 32-bit code field address of the user-supplied abort routine that is executed if the CUSTOM_ABORT flag is true (non-zero).  If CUSTOM_ABORT is false (zero), Abort() executes the default SysAbort() routine. UABORT is initialized by COLD to contain the code field address of SysAbort().

See also Abort(), SysAbort(), and CUSTOM_ABORT

Type: macro
Related Forth function: UABORT
Header file: user.h

UASK_KEY

A user variable (member of the currently active TASK.USER_AREA structure) that contains the 32-bit code field address of the AskKey() routine.

See also AskKey()

Type: macro
Related Forth function: U?KEY
Header file: user.h

UDEBUG

A user variable (member of the currently active TASK.USER_AREA structure) that contains a 16-bit flag.  If the flag is non-zero then error checking and diagnostic stack printing are enabled in the interactive QED-Forth interpreter/compiler.

Type: macro
Related Forth function: DEBUG
Header file: user.h

UEMIT

A user variable (member of the currently active TASK.USER_AREA structure) that contains the 32-bit code field address of the Emit() routine.

See also Emit()

Type: macro
Related Forth function: UEMIT
Header file: user.h

UERROR

A user variable (member of the currently active TASK.USER_AREA structure) that contains the 32-bit code field address of the error routine that is executed if the CUSTOM_ERROR flag is true (non-zero).  If CUSTOM_ERROR is false (zero), all system errors call the default system error routine which prints descriptive error messages. UERROR is initialized by COLD to contain the code field address of a simple default error handler that prints the hexadecimal system error number and executes Abort().  See CUSTOM_ERROR and Abort(), and consult the error message appendix in the Software Manual.

Type: macro
Related Forth function: UERROR
Header file: user.h

UKEY

A user variable (member of the currently active TASK.USER_AREA structure) that contains the 32-bit code field address of the Key() routine.

See also Key()

Type: macro
Related Forth function: UKEY
Header file: user.h

UP

A pointer to TASKBASE, which in turn is a pointer to the base of the current task's user area.  UP returns an address whose contents is the TASKBASE address of the current task.

See also TASKBASE

Type: macro
Related Forth function: UP
Header file: user.h

UPAD

User variable (member of the currently active TASK.USER_AREA structure) that holds the 32-bit base address of PAD.

See also PAD

Type: macro
Related Forth function: UPAD
Header file: user.h

USER_AREA

A struct typedef that declares the user area structure containing task-specific variables and pointers.  In turn, the USER_AREA structure is the first element in the TASK structure.  For a full definition of this structure, see the source code in the user.h file. 

See also: TASK

Type: typedef
Header file: user.h

void UseSerial1( void)

Installs the primary serial port (serial1) as the serial link called by Emit(), AskKey(), and Key() used by the default task that runs at startup.  The serial1 port is associated with the processor's primary on-chip hardware UART SCI0.  Stores the code address of Key1() in UKEY, the code address of AskKey1() in UASK_KEY, and the code address 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.

Type: kernel function
Forth name: USE.SERIAL1
Header file: serial.h

void UseSerial2( )

Installs the secondary serial port (serial2) as the serial link called by Emit(), AskKey(), and Key() used by the default task that runs at startup.  The serial2 port is associated with the processor's secondary on-chip hardware UART SCI1. UseSerial2() stores the code address of Key2() in UKEY, the code address of AskKey2() in UASK_KEY, and the code address of Emit2() in UEMIT.  Thus the vectored routines Key(), AskKey(), and Emit() will automatically execute the serial1 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.

See also Baud() and Serial2AtStartup()

Type: kernel function
Forth name: USE.SERIAL2
Header file: serial.h

UTIB

User variable (member of the currently active TASK.USER_AREA structure) that holds the 32-bit base address of the Terminal Input Buffer (TIB).

See also TIB

Type: macro
Related Forth function: UTIB
Header file: user.h

xaddr Version( void)

Returns the xaddress of a Forth-style counted ascii string that contains the version number of the kernel.  The count of the string is stored at xaddr, and the first byte of the string is at xaddr+1. This string is part of the prompt that is printed at cold and warm startup.

Type: kernel function
Forth name: VERSION
Header file: opsystem.h

int WaitTilMatch( int mask, int match_val, xaddr pointer, uint max_timeslice_counts)

This timing routine loops and calls Pause() until the following equation is true:

({mask} AND {16bit_contents_of_xaddr}) = match_value

In other words, on each pass through the loop, WaitTilMatch() fetches the 16-bit contents of the specified xaddr, performs the logical AND operation with the specified 16-bit mask parameter, and compares the result to the specified 16-bit match_value parameter.  If they are equal, the wait loop terminates; otherwise, the looping continues.  In addition, if StartTimeslicer() has been executed and interrupts are globally enabled, this routine loops and calls Pause() for a maximum of the specified max_timeslice_counts (a 16-bit unsigned value) and returns a true flag if a timeout occurred without the specified match occurring.  If the specified match occurs before the timeout, this function returns a zero flag.  The default timeslice count period is 1.024 milliseconds.

Example of use: Assume that the variable at xaddress 0x8000 on page 0x0C is being updated by an interrupt routine, and we want to wait until it has the value 0x1234. To test for this equality condition, we will pass the mask equal to 0xFFFF (so we examine all 16 bits at xaddr), and we specify the match_value as 0x1234. Assuming we want to enforce a timeout of approximately 9 milliseconds (9 timeslice counts), we would execute:

StartTimeslicer();       // this also globally enables interrupts
int timeout_flag = 0;    // declare a placeholder for the timeout error flag
timeout_flag = WaitTilMatch(0xFFFF, 0x1234, 0x0C8000, 9);

The WaitTilMatch() function will exit at the earlier one of the following two conditions: 1. the match is found (in which case the returned timeout flag is false), or, 2. the timeout occurred after 9 ms (in which case the returned timeout flag is true).

See also MsecTimeslicePeriod()

Type: kernel function
Forth name: WAIT.TIL.MATCH
Header file: mtasker.h

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.  Note that this function can be called interactively from the terminal by typing:

WARM

Calling WARM interactively before downloading a program is good practice, as it aborts any active multitasking program that may be in progress.

See also Cold()

Type: kernel function
Forth name: WARM
Header file: opsystem.h

WATCH_DATE

A structure element whose contents were updated by the most recent execution of ReadWatch().  When used as the right-hand side of an assignment statement, WATCH_DATE returns the current date (1…31). (Of course, this requires that a properly set battery-operated real-time clock is installed on the Board.) See the glossary entry for ReadWatch() for an example of use.

Type: macro
Header file: watch.h

WATCH_DAY

A structure element whose contents were updated by the most recent execution of ReadWatch().  When used as the right-hand side of an assignment statement, WATCH_DAY returns the current day (1…7). (Of course, this requires that a properly set battery-operated real-time clock is installed on the Board.) See the glossary entry for ReadWatch() for an example of use.

Type: macro
Header file: watch.h

WATCH_HOUR

A structure element whose contents were updated by the most recent execution of ReadWatch().  When used as the right-hand side of an assignment statement, WATCH_HOUR returns the current hour (0…23). (Of course, this requires that a properly set battery-operated real-time clock is installed on the Board.) See the glossary entry for ReadWatch() for an example of use.

Type: macro
Header file: watch.h

WATCH_HUNDREDTH_SECONDS

A structure element defined to maintain backwards compatibility with earlier kernel versions.  Always reads 0 after the execution of ReadWatch().  See the glossary entry for ReadWatch() for an example of use.

Type: macro
Header file: watch.h

WATCH_MINUTE

A structure element whose contents were updated by the most recent execution of ReadWatch().  When used as the right-hand side of an assignment statement, WATCH_MINUTE returns the current minute (0…59). (Of course, this requires that a properly set battery-operated real-time clock is installed on the Board.) See the glossary entry for ReadWatch() for an example of use.

Type: macro
Header file: watch.h

WATCH_MONTH

A structure element whose contents were updated by the most recent execution of ReadWatch().  When used as the right-hand side of an assignment statement, WATCH_MONTH returns the current month (1…12). (Of course, this requires that a properly set battery-operated real-time clock is installed on the Board.) See the glossary entry for ReadWatch() for an example of use.

Type: macro
Header file: watch.h

watch_results

This structure is an instance of the CALENDAR_TIME typedef that defines the bytes that hold the results of a read of the battery-backed real-time clock.  A set of macros (WATCH_SECONDS, WATCH_MINUTES, WATCH_HOUR, etc.) have been pre-defined to facilitate easy access to the watch results.

See also ReadWatch()

Type: system global structure instance
Header file: watch.h

WATCH_SECONDS

A structure element whose contents were updated by the most recent execution of ReadWatch().  When used as the right-hand side of an assignment statement, WATCH_SECONDS returns the current seconds (0…59). (Of course, this requires that a properly set battery-operated real-time clock is installed on the Board.) See the glossary entry for ReadWatch() for an example of use.

Type: macro
Header file: watch.h

WATCH_YEAR

A structure element whose contents were updated by the most recent execution of ReadWatch().  When used as the right-hand side of an assignment statement, WATCH_YEAR returns the current year (0…99). (Of course, this requires that a properly set battery-operated real-time clock is installed on the Board.) See the glossary entry for ReadWatch() for an example of use.

Type: macro
Header file: watch.h

void WriteEnable( int region_id)

Undoes the effect of WriteProtect 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. 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.

Type: kernel function
Forth name: WRITE.ENABLE
Header file: opsystem.h

void WriteProtect( 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. 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.

Type: kernel function
Forth name: WRITE.PROTECT
Header file: opsystem.h

long XaddrDifference( xaddr addr1, xaddr addr2)

Subtracts addr2 from addr1 to yield the signed double number result.  There is an unchecked error if one of the xaddresses is in common memory (addr ≤ 0x7FFF or addr ≥ 0xC000) and the other is in paged memory (0x8000 ≤ addr ≤ 0xBFFF).  Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.

Type: kernel function
Forth name: X1-X2>D
Header file: memory.h

XIRQ_ID

A constant that returns the interrupt identity code for the external non-maskable interrupt called XIRQ.  Used as an argument for ATTACH().  The XIRQ interrupt is activated by an active-low signal on the XIRQ input pin and is enabled by the X bit in the condition code register.

Type: constant
Related Forth function: XIRQ.ID
Header file: interrupt.h