C Function Glossary

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

FIXME : Definitions for the following functions are missing:

ReadElapsedTime
ChangeTaskerPeriod and
_writeTerminal

Listed functions are alphabetized in the following ASCII order:

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

_peekTerminal

uchar _peekTerminal( void)

A serial I/O primitive called by printf() and other C printing functions. Checks the serial1 input port (the processor’s primary hardware UART SCI0). If an input character is present, adds it to an input buffer. _peekTerminal() returns the number of pending characters in the input buffer. Use _readTerminal to access the contents of the input buffer.

See also AskKey(), _readChar() and _writeChar()

Type: C function
Header file: serial.h

_Q

_Q

This macro is used to enable the interactive debugging features offered by the PDQ Board. Functions declared with the _Q specifier may be individually executed in an interactive fashion from your terminal; this greatly speeds debugging. Without the interactive capability, a compiled C program can only execute one function (main), and if you want to test individual functions in the program you must continually recode main to call the function and then recompile the program. Using the _Q debugging feature offers a simpler alternative. Instead of having to revector the "main" routine to execute the function of interest, you can interactively execute each function in the program with a variety of input parameters of your choice. This lets you test each function to isolate bugs.

Example of use:

_Q float Square( float input)
{   return (input * input);
}

After this function is compiled in a program and the .DLF download file is sent to the PDQ Board, you can test the function with any input. For example, to test the Square() function with an input of 3.5, simply execute from the terminal

Square(  float  3.5)

Note that there is no space between the "e" and the "(", and there must be at least one space between the "(" and the next character. The "float" keyword is required to tell the interpreter that the input parameter is a floating point number. The PDQ Board will respond with a summary of the return value in several formats:

Rtn: 0x4144 0x0 = 0x41440000 =fp:  12.25   ok

We know that this routine returns a floating point number, so we see that the return value is 12.25, which is the correct answer.

Type: macro
Header file: compiler_util_macros.h

_QV

_QV

This macro is used to enable interactive debugging features for variables on the PDQ Board. Variables declared with the _QV specifier may be individually accessed from the terminal. _QV is similar in function to _Q, and they may be used together for excellent debugging results.

Example of use:

_QV unsigned int my_var;

After this variable is compiled in a program and the .DLF download file is sent to the PDQ Board, you can read and write this variable with any value. For example, to store the number 42 into my_var, simply execute from the terminal

decimal
42 my_var !

To read back the value of my_car, simply execute from the terminal

my_var @

The PDQ board will respond with

ok ( 1 ) \ 42

Showing that there is "( 1 )" item on the stack with the value of 42.

_readChar

uchar _readChar( void)

A serial I/O primitive called by printf() and other C printing functions. Calls _readTerminal to retrieve the latest input character from the primary serial port (the processor’s primary hardware UART SCI0), and then calls _writeChar to echo the character. Returns the input character. Does not execute Pause() while waiting for the input character.

See also Key(), _readTerminal(), _peekTerminal() and _writeChar()

Type: C function
Header file: serial.h

_readTerminal

uchar _readTerminal( void)

A serial I/O primitive called by printf() and other C printing functions. Removes one character from the input buffer associated with the serial1 input port [see _peekTerminal()] and returns the character. If the input buffer is empty, waits until the next input character appears.

See also _readChar() and _writeChar()

Type: C function
Header file: serial.h

_writeChar

void _writeChar( uchar chr)

A serial I/O primitive called by printf() and other C printing functions. Writes the specified character chr to the primary serial port (the processor’s primary hardware UART SCI0). If chr is a linefeed (ascii 10), writes a carriage return (ascii 13) to the serial port before writing the linefeed. Does not execute Pause().

See also Emit(), _peekTerminal(), _readChar() and _writeTerminal()

Type: C function
Header file: serial.h

Abort

void Abort( void)

If the CUSTOM_ABORT flag is true (non-zero), executes the abort routine whose xcfa (32-bit extended code field address) is stored in the user variable UABORT, and then returns to the routine that called ABORT. If CUSTOM_ABORT is false (zero), executes the default routine SysAbort() which clears the data and return stacks, and sets the page to the default page (0). If an autostart vector has been installed [see IsAutostart() and IsPriorityAutostart()], 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

ABS

ABS( num)

Returns the absolute value of num; the input can be of any type. This macro is defined as:

#define ABS(A)  (((A) >=0) ? (A) : (-A))

Type: macro
Header file: utility.h

ACTIVATE

void ACTIVATE( void(*action)(), int* task_base_addr)

Sets up the specified routine as the action function of the task whose TASKBASE address equals task_base_addr, and leaves the specified task AWAKE with the I bit in its CCR register clear so that it will be entered with interrupts globally enabled on the next pass through the round robin task list. The ACTIVATE() macro may be used in all applications whose code compiles onto a single page of the PDQ controller; for multi-page applications, use the functional form named Activate() which allows you to specify the page of the action routine.

ACTIVATE() assumes that the specified task has already been declared using a TASK statement and added to the task list by BUILD_C_TASK(). The task's action function is typically either an infinite loop or a finite routine that ends with a Halt() instruction (which is itself an infinite loop). ACTIVATE() buries a call to Halt() in the return stack frame to ensure graceful termination of a finite activation routine. If cooperative multitasking is used exclusively (that is, if the timeslicer is not used), then the loop of the action function must contain at least one Pause() statement, or invoke a function that in turn executes Pause(). Otherwise, no task switching occurs. If timeslicing is used, incorporation of Pause() statements in the loop of the action function is optional. The typical form of an action function is:

void action_name(void)
  { while(1)
    { statements to be executed infinitely;
      Pause();
      statements to be executed infinitely;
    }
  }

or:

void action_name(void)
  { statements to be executed;
    Pause();
    statements to be executed;
    Halt();
  }

Once the action routine has been defined, the task can be named, built and activated as follows:

TASK  ReadInputTask;                   // name and allocate the task area
BUILD_C_TASK(0,0,&ReadInputTask);      // build the task in RAM
ACTIVATE(action_name, &ReadInputTask); // activate the task

Note that action_name is passed without parentheses to the ACTIVATE routine; this tells the compiler that action_name is a pointer to a function. The turnkey application program in the documentation provides working examples of how to define, build and activate tasks in a multitasking program.

Activate

void Activate( void(*action)(), uint actionPage, xaddr taskBase)

Sets up the specified routine on the specified actionPage as the action function of the task whose TASKBASE address is taskBase, and leaves the specified task AWAKE with the I bit in its CCR register clear so that it will be entered with interrupts globally enabled on the next pass through the round robin task list. For application programs that are compiled on a single page, the macro form ACTIVATE() is highly recommended; consult its glossary entry for a complete description of what this routine does. For programs whose code occupies multiple pages of memory on the PDQ controller, this functional form of Activate() allows the page of the action routine (actionPage) to be specified.

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

AddXaddrOffset

xaddr AddXaddrOffset( xaddr baseAddr, long offset)

Adds the specified signed offset to baseAddr and returns the resulting address. Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.

Type: kernel function
Forth name: XD+
Header file: xmem.h

ARRAYBASE

xaddr ARRAYBASE( FORTH_ARRAY* array_ptr)

Returns the base address (that is, the address of the first element) of the specified array. Returns zero if the array is undimensioned. No error checking is performed.

Example of use:

To define an array of unsigned longs named MyArray with 3 rows and 5 columns, execute:

FORTH_ARRAY  Myarray;
DIM(ulong, 3, 5, &Myarray);

Now to assign the base address of the array to a variable, execute:

static xaddr  Myarray_base_address;
Myarray_base_address = ARRAYBASE(&Myarray);

Note that the & (address-of) operator in front of the array's name tells the compiler that a pointer is being passed. If you forget the & operator, the compiler will warn you that you are attempting to pass an entire structure (the array's parameter field structure) as an argument to a function.

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

See also FORTH_ARRAY, DIM(), ARRAYSTORE() and ARRAYFETCH()

Type: macro
Related Forth function: [0]
Header file: array.h

ArrayBase

xaddr ArrayBase( FORTH_ARRAY* array_ptr, uint pfa_page)

A subsidiary Forth function called by the recommended macro ARRAYBASE().

ARRAYFETCH

ulong ARRAYFETCH( type, uint row, uint col, FORTH_ARRAY* array_ptr)

Fetches the contents of the element at row, col in the specified 2-dimensional array. The size of the data that is fetched from the array may be 1 byte, 2 bytes, or 4 bytes depending upon the number of bytes per element of the array as specified by the DIM() command. The type parameter passed to the function causes the specified type-cast to be performed on the fetched data; this is necessary to inform the compiler of the type of the data stored in the array. Examples of valid type parameters are standard identifiers and pre-defined types such as:

int       unsigned int    uint
char      unsigned char   uchar
long      unsigned long   ulong

Typically, the specified type corresponds to the type of the data stored in the array. Note that the uint, uchar, and ulong types are defined in the types.h file. For floating point data, use FARRAYFETCH(). There is an unchecked error if the specified array does not have 2 dimensions or if the number of bytes per element does not equal 1, 2, or 4. If UDEBUG is true (its default state after a COLD startup) and if the indices are out of range, Abort() is called.

Example of use:

To define an array of unsigned longs named MyArray with 3 rows and 5 columns, execute:

FORTH_ARRAY  Myarray;
DIM(ulong, 3, 5, &Myarray);

Now to fetch the contents of the item at row=1, column=2 into a variable, execute:

static ulong  the_contents;
the_contents = ARRAYFETCH(1,2,&Myarray);

Note that the & (i.e., address-of) operator in front of the array's name tells the compiler that a pointer is being passed. If you forget the & operator, the compiler will warn you that you are attempting to pass an entire structure (the array's parameter field structure) as an argument to a function.

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

See also FORTH_ARRAY, DIM(), FARRAYFETCH() and ARRAYSTORE()

Type: macro
Related Forth function: ArrayFetch()
Header file: array.h

ArrayFetch

ulong ArrayFetch( uint row, uint col, FORTH_ARRAY* array_ptr, uint pfa_page)

A subsidiary function called by the recommended ARRAYFETCH() macro.

ARRAYMEMBER

xaddr ARRAYMEMBER( uint row, uint col, FORTH_ARRAY* array_ptr)

Returns the 32-bit extended address of the element at the specified row and column in the 2-dimensional array specified by array_ptr. If UDEBUG is true (its default state after a COLD startup) and if the indices are out of range, calls Abort(). Example of use:

FORTH_ARRAY  Myarray;   // define an array named Myarray
DIM(ulong, 3, 5, &Myarray);   // dimension it as 3 rows by 5 columns

To calculate the extended address of the element at row=0, column = 1, execute:

static xaddr  element_address;
element_address = ARRAYMEMBER( 0, 1, &Myarray);

element_address could now be passed as a parameter to FetchLong() or StoreLong() to access the array member. Note that ARRAYFETCH() and ARRAYSTORE() provide a more direct means for fetching from and storing to an array element.

Caution: Recall that Forth function calls cannot be nested, so it is not legal to use ARRAYMEMBER() as an input parameter for another function such as StoreLong(). Rather, the return value of ARRAYMEMBER() must be saved in a variable which in turn is passed as a parameter to another Forth function.

Type: macro
Related Forth function: M[]
Header file: array.h

ArrayMember

xaddr ArrayMember( uint row, uint col, FORTH_ARRAY* array_ptr, uint pfa_page)

A subsidiary function called by the recommended macro ARRAYMEMBER().

ARRAYSIZE

uint ARRAYSIZE( FORTH_ARRAY* array_ptr)

A macro that returns the number of elements d (not the number of bytes!) 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);   // dimension it as 3 rows by 5 columns
static uint  size_of_the_array;
size_of_the_array = ARRAYSIZE(&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: ?ARRAY.SIZE
Header file: array.h

ARRAYSTORE

void ARRAYSTORE( ulong value, uint row, uint col, FORTH_ARRAY* array_ptr)

Stores the specified value at row, col in the 2-dimensional FORTH_ARRAY specified by array_ptr. The size of the data that is stored to the array may be 1 byte, 2 bytes, or 4 bytes depending upon the number of bytes per element of the array as specified by the DIM() command. Valid data types for value include signed and unsigned char, int and long. To store a floating point value, use FARRAYSTORE(). There is an unchecked error if the specified array does not have 2 dimensions or if the number of bytes per element does not equal 1, 2, or 4.

Example of use:

To define an array of unsigned longs named MyArray with 3 rows and 5 columns, execute:

FORTH_ARRAY  Myarray;
DIM(ulong, 3, 5, &Myarray);

Now to store 0x12345 into the element at row=1, column=2 into a variable, execute:

ARRAYSTORE(0x12345, 1,2,&Myarray);

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

See also FORTH_ARRAY, DIM(), FARRAYSTORE() and ARRAYFETCH()

Type: macro
Related Forth function: ArrayStore()
Header file: array.h

ArrayStore

void ArrayStore( ulong value, uint row, uint col, FORTH_ARRAY* array_ptr, uint pfa_page)

A subsidiary Forth function called by the recommended macro ARRAYSTORE();

AskKey

int AskKey( void)

Returns a flag indicating receipt of a character. If flag equals -1, a character has been received; if the flag equals 0 (false), no character has been received. Executes GET(SERIAL) and, depending on the value in SERIAL_ACCESS, may execute RELEASE(SERIAL). AskKey() is a vectored routine that executes the function whose xcfa (32-bit code field address) is stored in the user variable UASK_KEY. Thus the programmer may install a different routine to tailor the behavior of AskKey() to the application's needs. For example, AskKey() could access a serial port other than that on the 68HCS12 processor chip, or different tasks could use different AskKey() routines.

See also Key(), AskKey1(), AskKey2(), _peekTerminal(), and SERIAL_ACCESS

Type: C function;
Related Forth function name: ?KEY
Header file: serial.h

AskKey1

int AskKey1( void)

Returns a flag indicating whether a character has been received on the primary serial port (serial1) associated with the processor’s primaray on-chip hardware UART channel SCI0. If a character has been received a flag equal to -1 is returned; otherwise a false flag (=0) is returned. AskKey1() is the default AskKey() routine installed in the UASK_KEY user variable after the special cleanup mode is invoked, or if Seral1AtStartup has been executed. If the value in SERIAL_ACCESS is RELEASE_AFTER_LINE, AskKey1() does not GET(SERIAL1_RESOURCE) or RELEASE(SERIAL1_RESOURCE). If SERIAL_ACCESS contains RELEASE_ALWAYS, AskKey1() executes GET(SERIAL1_RESOURCE) and RELEASE(SERIAL1_RESOURCE). If SERIAL_ACCESS contains RELEASE_NEVER, AskKey1() GETs but does not RELEASE() the SERIAL1_RESOURCE.

See also SERIAL_ACCESS, AskKey(), UASK_KEY, AskKey2()

Type: kernel function
Forth name: ?KEY1
Header file: serial.h

AskKey2

int AskKey2( void)

Returns a flag indicating whether a character has been received on the on the secondary serial port (serial2). The serial2 port is associated with the processor’s secondary on-chip hardware UART channel SCI1. If a character has been received a flag equal to -1 is returned; otherwise a false flag (=0) is returned. AskKey2() can be made the default AskKey() routine installed in the UASK_KEY user variable after each reset or restart by executing Serial2AtStartup(). If the value in SERIAL_ACCESS is RELEASE_AFTER_LINE, AskKey2() does not GET(SERIAL2_RESOURCE) or RELEASE(SERIAL2_RESOURCE). If SERIAL_ACCESS contains RELEASE_ALWAYS, AskKey2() executes GET(SERIAL2_RESOURCE) and RELEASE(SERIAL2_RESOURCE). If SERIAL_ACCESS contains RELEASE_NEVER, AskKey2() GETs but does not RELEASE() the SERIAL2_RESOURCE.

See also SERIAL_ACCESS, AskKey(), UASK_KEY, AskKey1()

Type: kernel function
Forth name: ?KEY2
Header file: serial.h

ASLEEP

ASLEEP

A constant that returns the value 1. When stored into a task's STATUS user variable, indicates to the multitasking executive that the task is asleep and cannot be entered.

The following example illustrates how to put another task to sleep. Assume that we have pre-defined an infinite loop task function named GatherData(), and that we have named, built and activated a task with the following statements:

TASK  ReadInputTask;      // name and allocate the task area
BUILD_C_TASK(0,0,&ReadInputTask);   // build the task in RAM
ACTIVATE(GatherData, &ReadInputTask);   // activate the task

Now the task is AWAKE and running, and the TASK command has defined &ReadInputTask as a pointer to the task's TASK structure, of which the USER_AREA structure is the first element. Note that the task's STATUS address (whose contents control whether the task is AWAKE) is the first element in the task's USER_AREA structure; its element name is user_status. Thus, to put the task ASLEEP we simply execute

ReadInputTask.USER_AREA.user_status = ''ASLEEP'' ;

If a given task wants to put itself asleep, it can simply execute the commands:

STATUS = ASLEEP;
Pause();

The Pause() command ensures that the multitasking executive immediately exits the task after it is put ASLEEP.

ATD0_7_RESULTS

ATD0_7_RESULTS

A constant that returns a 16-bit address in common memory, declared as a pointer to an unsigned 16-bit integer. This address is the base of a result register frame that contains up to eight 16-bit Analog-to-Digital (ATD) registers holding the results of a conversion sequence intitiated by ATDStartSample() or ATDSample() (see their glossary entries). A sequence is a set of up to 8 channels converted in order with rollover modulus 8, specified by starting_channel_id (an integer in the range 0 to 7) and numchannels (an integer in the range 1 to 8) parameters passed to one of the initiating routines. As its name suggests, ATD0_7_RESULTS contains results only from analog channels 0 through 7. The channel after 7 in a sequence is 0, not 8. The ATD8_15_RESULTS register frame holds results acquired from channels 8 through 15. Once started, the ATD automatically converts each of the channels in the sequence (up to the specified numchannels in the range 1 to 8). For example, if the starting channel is 4 and numchannels equals 8, then samples are stored in the result registers in the following order:

4 5 6 7 0 1 2 3

In this case, the 2-byte channel 4 result is stored at ATD0_7_RESULTS, the channel 5 result is stored at the next sequential 2-byte location in memory, and so on. In other words, the first result in the sequence (corresponding to starting_channel) is at byte offset 0, the next at offset 2 bytes, then offset 4 bytes, etc., for the specified numchannels; however, make sure you take account of C’s pointer arithmetic when fetching data, as the return type is declared as a pointer to an unsigned 16-bit integer. Note that the conversion uses the current data format, which is set by ATDOn() as 10-bit resolution, with the 10-bit data left justified in a 16-bit unsigned result; the least significant 6 bits of each result equal zero. For mathematical simplicity each result can be interpreted as a 16-bit unsigned number spanning the range 0x0000 to 0xFFFF (decimal 0 to 65,535). For example, converting a 2.5 Volt signal (representing half the 0 to 5V ATD input span) yields a result of 0x8000 (decimal 32768).

Type: macro
Related Forth function: ATD0-7.RESULTS
Header file: analog.h

ATD0_ID

ATD0_ID

A constant that returns the interrupt identity code for Analog-to-Digital converter #0 subsystem on the HCS12 chip. Used as an argument for ATTACH().

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

ATD1_ID

ATD1_ID

A constant that returns the interrupt identity code for Analog-to-Digital converter #1 subsystem on the HCS12 chip. Used as an argument for ATTACH().

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

ATD8_15_RESULTS

ATD8_15_RESULTS

A constant that returns a 16-bit address in common memory, declared as a pointer to an unsigned 16-bit integer. This address is the base of a result register frame that contains up to eight 16-bit Analog-to-Digital (ATD) registers holding the results of a conversion sequence intitiated by ATDStartSample() or ATDSample() (see their glossary entries). A sequence is a set of up to 8 channels converted in order with rollover modulus 8, specified by starting_channel_id (an integer in the range 8 to 15) and numchannels (an integer in the range 1 to 8) parameters passed to one of the initiating routines. As its name suggests, ATD8_15_RESULTS contains results only from analog channels 8 through 15. The channel after 15 in a sequence is 8, not 16. The ATD0_7_RESULTS register frame holds results acquired from channels 0 through 7. Once started, the ATD automatically converts each of the channels in the sequence (up to the specified numchannels in the range 1 to 8). For example, if the starting channel is 12 and numchannels equals 8, then samples are stored in the result registers in the following order:

12 13 14 15 8 9 10 11

In this case, the 2-byte channel 12 result is stored at ATD8_15_RESULTS, the channel 13 result is stored at the next sequential 2-byte location in memory, and so on. In other words, the first result in the sequence (corresponding to starting_channel) is at byte offset 0, the next at offset 2 bytes, then offset 4 bytes, etc., for the specified numchannels; however, make sure you take account of C’s pointer arithmetic when fetching data, as the return type is declared as a pointer to an unsigned 16-bit integer. Note that the conversion uses the current data format, which is set by ATDOn() as 10-bit resolution, with the 10-bit data left justified in a 16-bit unsigned result; the least significant 6 bits of each result equal zero. For mathematical simplicity each result can be interpreted as a 16-bit unsigned number spanning the range 0x0000 to 0xFFFF (decimal 0 to 65,535). For example, converting a 2.5 Volt signal (representing half the 0 to 5V ATD input span) yields a result of 0x8000 (decimal 32768).

Type: macro
Related Forth function: ATD8-15.RESULTS
Header file: analog.h

ATDDigitalInputs

void ATDDigitalInputs( int mask16 )

The input parameter is a 16-bit mask. Each 1 bit in the mask configures the corresponding AN0-AN15 bit on the processor’s PortAD0 and PortAD1 as a digital input, and each 0 bit configures the corresponding pin as an analog input. If you are using some of the AN0-AN15 pins as analog inputs and others as digital inputs, call this routine after invoking the ATDOn() function, as ATDOn() configures a set of 8 pins (either PORTAD0 or PORTAD1) as analog inputs; consult the ATDOn() glossary entry.

CAUTION: If an analog voltage is present on a given input pin, it is not advisable to configure the pin as a digital input, as this can cause high current draw in the processor chip if the analog signal puts the digital input buffer in its “linear mode” midway between logic levels.

Implementation details: This routine transfers the specified bitmask from the input parameter to the PORTAD0_MODE and PORTAD1_MODE digital-enable registers (synonyms for ATD0DIEN and ATD1DIEN, respectively); consult their glossary entries.

Type: kernel function
Forth name: ATD.DIGITAL.INPUTS
Header file: analog.h

ATDMultiple

void ATDMultiple( xaddr buffer, uint utime, int one_byte, int numsequences, int starting_channel_id, int numchannels )

This is the most versatile routine for performing multiple Analog-To-Digital (ATD) conversions using either of the two 8-input ATD ports on the HCS12 processor. This routine converts multiple sequences comprising the specified numchannels per sequence, and stores the conversion results as 8- or 16-bit values into a memory buffer starting at the specified xaddr. If the one_byte flag is true, each sample occupies 1 byte in the buffer, and this constrains the results to 8-bit resolution per sample, with each sample result in the range 0 to 255. If the one_byte flag is false, each sample occupies 2 bytes in the buffer, each sample has 10-bit resolution, with the 10-bit data left justified in a 16-bit unsigned result, and the least significant 6 bits of each result equal zero. For mathematical simplicity each 2-byte result can be interpreted as a 16-bit unsigned number spanning the range 0x0000 to 0xFFFF (decimal 0 to 65,535). For example, converting a 2.5 Volt signal (representing half the 0 to 5V ATD input span) yields a 2-byte result of 0x8000 (decimal 32768) if the one_byte flag is false, or an equivalent 1-byte result of 0x80 (decimal 128) if the one_byte flag is true. If the one_byte flag is true, the buffer at xaddr must be at least one byte larger than the number of samples; that is:

buffer_size = (numsequences * numchannels) + 1   // if one_byte flag is true

This is because ATDMultiple() actually stores 2 bytes per sample, and, if the one_byte flag is true, overwrites the least significant byte of the prior sample with the next sample’s most significant byte. If the one_byte flag is false, the required buffer size is:

buffer_size = 2 * (numsequences * numchannels)   // if one_byte flag is false

This routine performs multiple analog-to-digital conversions with the unsigned integer utime input parameter specifying a programmable inter-sequence sampling time with 2.5 microseconds (us) quantization as explained below. The starting_channel_id parameter in the range 0 to 15, and the numchannels parameter in the range 1 to 8, together specify a sequence of up to 8 channels converted in order with modulus 8 rollover. Note that channels 0 to 7 are on the ATD0_7_RESULTS converter, and channels 8 to 15 are on the ATD8_15_RESULTS converter, so the channel after 7 in a sequence is 0, not 8. Similarly, the channel after 15 is 8. Once started, the ATD automatically converts each of the channels in the sequence (up to the specified numchannels in the range 1 to 8) one time at 7 us per conversion. In other words, the conversion time between channels within a sequence is always 7 microseconds. The numsequences parameter is an unsigned integer that specifies the number of such sequence conversions that are performed. The conversion results are stored in the buffer starting at the specified xaddr. After all the conversions within a sequence have been performed, there is an additional inter-sequence delay of

inter-sequence_delay = (2.5us * utime) + overhead_delay

where the overhead_delay averages 3 us if xaddr is in common RAM, or 6.5 us if xaddr is in paged RAM. Inter-sequence timing jitter (that is, the variation in overhead_delay from sequence to sequence) is less than 0.2 us, and there is no jitter within a sequence. If a page crossing occurs between sequences, add 1 us of overhead_delay and an additional 0.2 us of potential jitter to the inter-sequence time. The user-specified utime parameter is an unsigned integer which is multiplied by 2.5 us and added to the overhead_delay after each sequence to specify the conversion timing.

Before calling this routine, make sure that you have called ATDOn() for the specified ATD port. If you are using channels in the range 0 to 7, execute:

 ATDOn(0);

If you are using channels in the range 8 to 15, execute:

ATDOn(8);

If you are using channels from both converters, execute:

ATDOn(0);
ATDOn(8);

Calling this routine aborts any prior unfinished ATD conversions on the specified ATD subsystem (channels 0-7 or 8-15). The conversion uses the current data format, which is set by ATDOn() as 10-bit resolution, left justified unsigned data (although if the 1byte_flag is true, the resolution of the stored data is only 8 bits). This routine assumes that the AFFC (fast flag clear) bit in ATD0CTL2 or ATD1CTL2 is set as configured by ATDOn(). Clearing this AFFC register bit or modifying other ATD control bits can result in unpredictable operation.

Timing Analysis: This routine uses a software timing delay to set the inter-sequence timing interval. The following timing analysis is accurate for a single-task application with no interrupts running. Multitasking or interrupt service routines will increase the sampling intervals. The simplest timing case involves calling this routine with 1 channel per sequence (numchannels = 1), in which case the inter-sample time depends on whether the xaddr buffer is in common RAM or paged RAM, as follows: sampling_period = 7us + (2.5us * utime) + 3 us if xaddr is in common RAM <code>sampling_period = 7us + (2.5us * utime) + 6.5 us if xaddr is in paged RAM</code>

In the first case, with utime = 0, sampling occurs every 10us = 100KHz sampling. In the second case, with utime = 0, sampling occurs every 13.5us = 74KHz sampling. Increasing the utime parameter increases the inter-sequence sample time and decreases the sampling frequency. For example, with numchannels = 1 (1 channel per sequence), utime = decimal 96, and xaddr in common RAM, the inter-sample time is:

7us + (2.5us * 96) + 3us = 250us

which corresponds to a sampling frequency of 4 KHz. If there is more than 1 channel per sequence, then the sampling process can be thought of as a burst of samples within the sequence separated by 7 us per sample, followed by an inter-sequence delay. For example, assume that the starting channel is 4, numchannels = 8, utime = 0, and the storage xaddress is in paged memory. In this case, the samples are stored in memory in the following order:

4 5 6 7 0 1 2 3   4 5 6 7 0 1 2 3  4 5 6 7 0 1 2 3 ...

Each sample within the sequence takes 7us, and the inter-sequence delay is:

inter-sequence_delay = 0 * 2.5us + 6.5us = 6.5us.

Thus the total time between samples of a given channel equals

sampling_period = numsamples * 7us + 6.5us = 56 us + 6.5us = 62.5us,

corresponding to a 16KHz sampling rate for each channel. If we modify this example by changing utime to decimal 15, then the total time between samples of a given channel equals:

sampling_period = 8 * 7us + (2.5us * 15) + 6.5us = 56us + 37.5us + 6.5us = 100 us

corresponding to a 10KHz sampling rate for each channel.

Type: kernel function
Forth name: ATD.MULTIPLE
Header file: analog.h

ATDOff

void ATDOff( int channel_id )

The input is any integer channel number between 0 and 15. This routine turns off the associated Analog To Digital (ATD) converter. The entire 8-channel ATD0_7_RESULTS converter is turned off if the input channel_id is between 0 and 7. The entire 8-channel ATD8_15_RESULTS converter is turned off if the input channel_id is between 8 and 15. To turn off both converters (all 16 ATD channels) on the HCS12 processor, execute:

ATDOff(0);
ATDOff(8);

This routine powers down the ATD converter subsystem, but it does not affect the analog-versus-digital input mode of the associated pins. After a power up or hardware reset, the ATD converters are off by default, and PortAD0 and PortAD1 are not configured for digital inputs.

See also ATDOn() and ATDDigitalInputs()

Type: kernel function
Forth name: ATD.OFF
Header file: analog.h

ATDOn

void ATDOn( int channel_id )

The input is any integer channel number between 0 and 15. This routine turns on the associated Analog To Digital (ATD) converter and configures the pins as analog inputs by clearing all 8 bits in either PORTAD0_MODE (if the input parameter is between 0 and 7) or PORTAD1_MODE (if the input parameter is between 8 and 15). If the input channel_id is between 0 and 7, the ATD0_7_RESULTS converter is turned on and channels 0 through 7 are configured as analog inputs. If the input channel_id is between 8 and 15, the ATD8-15_RESULTS converter is turned on and channels 8 through 15 are configured as analog inputs. To turn on both converters (all 16 ATD channels) on the HCS12 processor, execute:

ATDOn(0);
ATDOn(8);

To configure some pins as analog inputs and some as digital inputs, first call ATDOn() for the specified set of 8 inputs, then call ATDDigitalInputs() with the appropriate bitmask. After a power up or hardware reset, the ATD converters are off by default, and PortAD0 and PortAD1 are not configured for digital inputs. ATDOn() configures the converter to return 10-bit data left justified in a 16-bit field, with the 6 least significant bits equal to 0. ATDOn() puts the converter in “fast clear mode” so that the driver routines do not have to explicitly clear the conversion complete flag. The other ATD software driver routines rely on these initializations by ATDOn().

See also ATDOff() and ATDDigitalInputs()

Type: kernel function
Forth name: ATD.ON
Header file: analog.h

ATDSample

uint* ATDSample( int starting_channel_id, int numchannels )

This routine converts a single sequence of up to 8 Analog To Digital (ATD) channels, waits for the conversions to complete, and returns the 16-bit base address of the result register frame in common RAM. The starting_channel_id (an integer in the range 0 to 15) and numchannels (an integer in the range 1 to 8) parameters specify a sequence of up to 8 channels converted in order with rollover modulus 8. Note that channels 0 to 7 are on the ATD0_7_RESULTS converter, and channels 8 to 15 are on the ATD8_15_RESULTS converter, so the channel after 7 in a sequence is 0, not 8. Similarly, the channel after 15 is 8. Once started, the ATD automatically converts each of the channels in the sequence (up to the specified numchannels in the range 1 to 8) one time at 7 microseconds (us) per conversion. In other words, the conversion time between channels within a sequence is always 7 us. The total execution time of this routine is approximately:

(7us * numsamples) + 3.5 us

Before starting a new conversion, results should be fetched out of the returned result register frame which starts at either the 16-bit address ATD0_7_RESULTS or ATD8_15_RESULTS; the relevant 16-bit address is returned by this routine. This result register frame contains eight 16-bit result registers. The first result in the sequence (corresponding to starting_channel) is at byte offset 0, the next at offset 2 bytes, then offset 4 bytes, etc., for the specified numchannels; however, make sure you take account of C’s pointer arithmetic when fetching data, as the return type is declared as a pointer to an unsigned 16-bit integer. For example, if the starting channel is 4 and numchannels equals 8, then samples are stored in the result registers in the following order:

4 5 6 7 0 1 2 3

Before calling this routine, make sure that you have called ATDOn() for the specified ATD port. If you are using channels in the range 0 to 7, execute:

ATDOn(0);

If you are using channels in the range 8 to 15, execute:

ATDOn(8);

If you are using channels from both converters, execute:

ATDOn(0);
ATDOn(8);

Note that the conversion uses the current data format, which is set by ATDOn() as 10-bit resolution, with the 10-bit data left justified in a 16-bit unsigned result; the least significant 6 bits of each result equal zero. For mathematical simplicity each result can be interpreted as a 16-bit unsigned number spanning the range 0x0000 to 0xFFFF (decimal 0 to 65,535). For example, converting a 2.5 Volt signal (representing half the 0 to 5V ATD input span) yields a result of 0x8000 (decimal 32768). Calling this routine aborts any prior unfinished ATD conversions on the specified ATD subsystem (channels 0-7 or 8-15). This routine assumes that the AFFC (fast flag clear) bit in ATD0CTL2 or ATD1CTL2 is set as configured by ATDOn(). Clearing this register bit or modifying other ATD control bits can result in unpredictable operation.

Type: kernel function
Forth name: ATD.SAMPLE
Header file: analog.h

ATDSingle

uint ATDSingle( int channel_id )

This routine converts a single specified Analog To Digital (ATD) channel (0 ≤ channel_id ≤ 15), waits for the conversion to complete, and returns the result. Note that the conversion uses the current data format, which is set by ATDOn() as 10-bit resolution, with the 10-bit data left justified in a 16-bit unsigned result; the least significant 6 bits of each result equal zero. For mathematical simplicity each result can be interpreted as a 16-bit unsigned number spanning the range 0x0000 to 0xFFFF (decimal 0 to 65,535). For example, converting a 2.5 Volt signal (representing half the 0 to 5V ATD input span) yields a result of 0x8000 (decimal 32768). Before calling this routine, make sure that you have called ATDOn() for the specified ATD port. If you are using channels in the range 0 to 7, execute:

ATDOn(0);

If you are using channels in the range 8 to 15, execute:

ATDOn(8);

If you are using channels from both converters, execute:

ATDOn(0);
ATDOn(8);

Calling this routine aborts any prior unfinished ATD conversions on the specified ATD subsystem (channels 0-7 or 8-15). This routine assumes that the AFFC (fast flag clear) bit in ATD0CTL2 or ATD1CTL2 is set as configured by ATDOn(). Clearing this register bit or modifying other ATD control bits can result in unpredictable operation.

Type: kernel function
Forth name: ATD.SINGLE
Header file: analog.h

ATDStartSample

void ATDStartSample( int starting_channel_id, int numchannels )

This routine starts the conversion of a single sequence of up to 8 Analog To Digital (ATD) channels and exits without waiting for the conversion(s) to complete. This is useful in customer-coded interrupt service routines: you can read the prior conversion results from the result registers, then start the next conversion without waiting for results. This makes for fast operation, as the conversions take place between the interrupt services at the rate of 7 microseconds (us) per channel. Prior results should be fetched out of the appropriate result register set, starting at either ATD0_7_RESULTS or ATD8_15_RESULTS; consult their glossary entries. Each of these constants is the base address of eight 16-bit result registers. The first result in the sequence (corresponding to starting_channel) is at byte offset 0, the next at offset 2 bytes, then offset 4 bytes, etc., for the specified numchannels; however, make sure you take account of C’s pointer arithmetic when fetching data, as the return type is declared as a pointer to an unsigned 16-bit integer. The starting_channel_id (an integer in the range 0 to 15) and numchannels (an integer in the range 1 to 8) parameters specify a sequence of up to 8 channels converted in order with rollover modulus 8. Note that channels 0 to 7 are on the ATD0_7_RESULTS converter, and channels 8 to 15 are on the ATD8_15_RESULTS converter, so the channel after 7 in a sequence is 0, not 8. Similarly, the channel after 15 is 8. This routine takes under 3.5 us to start the conversions and exit. Once started, the ATD automatically converts each of the channels in the sequence (up to the specified numchannels in the range 1 to 8) one time at 7 us per conversion. For example, if the starting channel is 4 and numchannels equals 8, then samples are stored in the result registers in the following order:

4 5 6 7 0 1 2 3

Before calling this routine, make sure that you have called ATDOn() for the specified ATD port. If you are using channels in the range 0 to 7, execute:

ATDOn(0);

If you are using channels in the range 8 to 15, execute:

ATDOn(8);

If you are using channels from both converters, execute:

ATDOn(0);
ATDOn(8);

Type: kernel function
Forth name: ATD.START.SAMPLE
Header file: analog.h

ATTACH

void ATTACH( void(*action)(), int interrupt_id)

Posts an interrupt handler routine specified by the function pointer (*action)() for the interrupt with identity number interrupt_id (for example, SWI_ID, etc). This macro form of the Attach() function is recommended for applications whose object code fits on a single page. For example, suppose you have defined a standard C function named ECT1_Service() to service the Enhanced Counter/Timer #1 interrupt. To install the interrupt handler, two steps are needed. After the definition of ECT1_Service(), call MAKE_ISR() in the global scope, like this:

MAKE_ISR( ECT1_Service );

Then, from within a function, simply execute

ATTACH( ECT1_Service, ECT1_ID);

Note that the name of the service routine is passed as a parameter without parentheses; this tells the C compiler to pass a pointer to the ECT1_Service() function. ATTACH() compiles a code sequence at the EEPROM location associated with the specified interrupt. When the interrupt is serviced, the code specified by the function pointer will be executed. The service routine should NOT be declared as an interrupt function; the ATTACH() routine compiles the needed RTI (return from interrupt) instruction. Interrupt latency is 3.75 microseconds until the service routine is entered. Exit latency after the service routine returns is 2.8 microseconds, resulting in a total latency of 6.55 microseconds.

Attach

void Attach( void(*action)(), uint actionPage, int interrupt_id)

Posts an interrupt handler routine specified by the function pointer (*action)() whose code is compiled on actionPage for the interrupt with identity number interrupt_id (for example, SWI_ID, etc). This functional form (as opposed to the ATTACH() macro) is recommended for applications whose object code resides on more than one memory page. For example, suppose you have defined a standard C function named ECT1_Service() on memory page 5 to service the Enhanced Counter/Timer #1 interrupt. To install the interrupt handler, simply execute

Attach( ECT1_Service, 5, ECT1_ID);

Note that the name of the service routine is passed as a parameter without parentheses; this tells the C compiler to pass a pointer to the ECT1_Service() function. Attach() compiles a code sequence at the EEPROM location associated with the specified interrupt. When the interrupt is serviced, the code specified by the function pointer will be executed. The service routine NOT be declared as an interrupt function; the Attach() routine compiles the needed RTI (return from interrupt) instruction. Interrupt latency is 3.75 microseconds until the service routine is entered. Exit latency after the service routine returns is 2.8 microseconds, resulting in a total latency of 6.55 microseconds.

Type: kernel function
Forth name: ATTACH
Header file: interrupt.h

AWAKE

AWAKE

A constant that returns the value 0. When stored into a task's STATUS user variable, indicates to the multitasking executive that the task is awake and may be entered.

The following example illustrates how to wake up another task that was earlier put to sleep. Assume that we have pre-defined an infinite loop task function named GatherData(), and that we have named, built and activated a task with the following statements:

TASK ReadInputTask;      // name and allocate the task area
BUILD_C_TASK(0, 0, &ReadInputTask);   // build the task in RAM
ACTIVATE(GatherData, &ReadInputTask);   // activate the task

If the task has been put ASLEEP by a command such as

ReadInputTask.USER_AREA.user_status = ASLEEP ;

we can now wake it up with the following command:

ReadInputTask.USER_AREA.user_status = AWAKE ;

The TASK command has defined &ReadInputTask as a pointer to the task's TASK structure of which the USER_AREA structure is the first element. Note that the task's STATUS address (whose contents control whether the task is AWAKE) is the first element in the task's USER_AREA structure; its element name is user_status.

Baud

void Baud( int baud_over_100, int port_id)

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

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

Type: kernel function
Forth name: BAUD
Header file: serial.h

Beep

void Beep( void)

Emits the bell character, ascii 07. Setting the user variable QUIET (see user_quiet in the user.h file) to a true (non-zero) value silences the beep.

Type: kernel function
Forth name: BEEP
Header file: serial.h

BreakAll

BreakAll( void)

Sets a multitasking-aware software breakpoint that is useful for debugging multitasking applications. At execution time, BREAK.ALL suspends the program flow, saves the machine state and invokes a FORTH-style text interpreter that can be distinguished from the standard interpreter by the BREAK> prompt displayed at the start of each line. This routine suspends all tasks in the round-robing task list, disables interrupts, and calls Breakpoint(); consult its glossary entry for a complete description. After Breakpoint() exits, BreakAll() restores the interrupt state and the task loop and continues with program execution.

Type: kernel function
Forth name: BREAK.ALL
Header file: opsystem.h

Breakpoint

void Breakpoint( void)

The Breakpoint() function may be edited into any function that is being debugged to set a software breakpoint. It saves the machine state and invokes a FORTH-style interactive text interpreter that can be distinguished from the standard interpreter by the BREAK> prompt displayed at the start of each line. Any valid commands may be executed from within the Breakpoint interpreter. From within the Breakpoint interpreter, typing a carriage return alone on a line exits the Breakpoint mode, restores the machine registers to the values they held just before Breakpoint() was entered, and resumes execution of the program that was running when Breakpoint() was entered. The Breakpoint() routine's preservation of the register state and its ability to execute any valid command make it a very powerful debugging tool. Breakpoint() may be compiled into any definition to stop program flow in order to debug or analyze a function at the point where Breakpoint() was called. Once inside Breakpoint(), variables and memory locations may be displayed or altered using QED-Forth debugging routines such as DUMP, INT, =INT, etc.; consult the debugging glossary section of this document. To fully exit from the routine that called Breakpoint(), type ABORT (or any illegal command) from the terminal in response to the BREAK> prompt. Any error encountered while in the Breakpoint() routine executes ABORT which places the programmer back into the standard QED-Forth interpreter (unless ABORT has been revectored to perform some other action; see CUSTOM_ABORT).

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

BUILD_C_TASK

void BUILD_C_TASK( xaddr heapStart, xaddr heapEnd, TASK * taskbase)

Builds a task with a specified heap, locating its task area in a 1 kilobyte block starting at the specified taskbase address in common RAM. The TASK declaration is used to name and allocate the task area. BUILD_C_TASK() assigns the task's stacks, user area, and PAD, POCKET, and TIB buffers to a 1Kbyte block of common RAM starting at the base of the TASK structure. The task is appended to the round-robin task list and left ASLEEP running the default action routine Halt(). heapStart is the 32-bit heap starting address, and xaddr2 is the extended heap end address. For example, the following statements name, allocate and build a task whose heap (which is where arrays reside) extends from location 0x8000 on page 0x18 to 0xBFFF on page 0x19:

TASK Taskname;   // name and allocate task space
BUILD_C_TASK( 0x188000, 0x19BFFF, &Taskname);

TASK creates and allocates the new TASK structure. BUILD_C_TASK() first calls IsHeap() which initializes the heap accordingly. BUILD_C_TASK() then initializes the task's USER_AREA and task buffers in the 1 kilobyte area starting at the task's base address. The user area of the parent task (i.e., the task that is active when this command executes) is copied to create the new task's USER_AREA, so the parent's configuration is initially inherited by the new task. The variables that control the memory map of the new task are set so that the return stack extends downward for 512 bytes at &Taskname + 0x400, the Forth data stack extends downward for up to 128 bytes at &Taskname + 0x200, TIB (QED-Forth terminal input buffer) extends upward for 96 bytes starting at &Taskname + 0x180, POCKET (used by QED-Forth interpreter) extends upward for 64 bytes starting at &Taskname + 0x200, and PAD (scratchpad area, available for programmer) extends upward for 88 bytes and downward for 35 bytes starting at &Taskname + 0x100. To initialize CURRENT_HEAP without modifying the heap control variables, pass BUILD_C_TASK() a heapStart address that is equal to the heapEnd address; see IsHeap().

Type: macro
Related Forth function: BUILD.TASK
Header file: mtasker.h

BuildTask

void BuildTask( xaddr heapStart,xaddr heapEnd,xaddr vp,xaddr dp,xaddr np,xaddr tib,xaddr pad, xaddr pocket,xaddr r0,xaddr s0,xaddr taskBase, int n)

Subsidiary function called by the recommended macro BUILD_C_TASK; see BUILD_C_TASK.

Type: kernel function
Forth name: BUILD.TASK
Header file: mtasker.h

CalcChecksum

int CalcChecksum( xaddr base_addr, uint numbytes)

Calculates a 16-bit checksum for the buffer specified by base_addr and numbytes, where numbytes is even and 0 ≤ numbytes < 65,534. The buffer may cross one or more page boundaries. The checksum is calculated by initializing a 16-bit accumulator to zero, then adding in turn each 2-byte number in the buffer to the accumulator; the checksum is the final value of the accumulator. Using this routine provides a method of checking whether the contents of an area of memory have changed since a prior checksum was calculated. This routine is optimized for speed, and executes at less than 0.7 microseconds per byte. The number of bytes must be even; otherwise, an additional byte is included in the checksum. The result is undefined if numbytes = 0 or 1.

Type: kernel function
Forth name: CALC.CHECKSUM
Header file: opsystem.h

CalcChecksumMany

int CalcChecksumMany( xaddr base_addr, long numbytes )

Calculates a 16-bit checksum for the buffer specified by base_addr and numbytes, where numbytes is even. The buffer may cross one or more page boundaries. The checksum is calculated by initializing a 16-bit accumulator to zero, then adding in turn each 2-byte number in the buffer to the accumulator; the checksum is the final value of the accumulator. Using this routine provides a method of checking whether the contents of an area of memory have changed since a prior checksum was calculated. This routine is optimized for speed, and executes at less than 0.7 microseconds per byte. The number of bytes must be even; otherwise, an additional byte is included in the checksum. The result is undefined if numbytes = 0 or 1.

Type: kernel function
Forth name: CALC.CHECKSUM.MANY
Header file: opsystem.h

CALENDAR_TIME

CALENDAR_TIME

This struct typedef defines the bytes that hold the results of a read of the battery-backed real-time clock. The watch_results instance of this structure is initialized each time ReadWatch is executed. A set of macros (WATCH_SECONDS, WATCH_MINUTES, WATCH_HOUR, etc.) have been pre-defined to facilitate easy access to the watch results; consult the glossary entry for ReadWatch().

Type: typedef
Forth name: READ.WATCH
Header file: watch.h

Cat

void Cat( xaddr xlstring, uint max_count, xaddr xstring_to_add, int count_to_add, uint eol )

Concatenates onto the “long string” at xlstring the count_to_add bytes in the string specified by xstring_to_add, plus the specified eol (end of line) sequence and a terminating null byte (not included in the count), and updates the 16-bit count located in the first 2 bytes at xlstring. The number of bytes (not including the count) in the generated string is clamped to max_count, an unsigned 16-bit integer. A “long string” contains a 2-byte count followed by the string contents. The available long string buffer starting at xlstring should be at least 3 bytes larger than the specified max_count to allow for the 2-byte count and the terminating null byte. Note that the lstring can end up with up to 65,533 chars (65535 - 2byte count), but the string to be added must have a positive count ≤ 32767 bytes. The 16-bit eol parameter can specify 1 or 2 characters. If eol = -1, no eol data is stored in the string. If the most significant (ms) byte of eol is non-zero, two bytes are stored: first the ms byte, then the least significant byte. Typical eol parameters include 'crlf' = 0x0D0A, 'cr' = 0x0D, or the null character 0x00. The specified max_count should be at least 2 bytes less than the size of the buffer containing the long string, as the first 2 bytes of the buffer contain the 16-bit count. No bytes are moved into the long string in violation of the max_count constraint; thus, for example, if the 16-bit count is greater than the max_count, no action is taken. This function provides a way to build a long string in memory.

NOTE: Remember to zero the first 2 bytes (16-bit count) of the lstring xbuffer before the first call to this routine.

ChangeBits

void ChangeBits( uchar data, uchar mask, xaddr address)

At the byte specified by the 32-bit address, modifies the bits specified by 1's in the mask to have the values indicated by the corresponding bits in the data parameter. In other words, mask specifies the bits at xaddr that are to be modified, and the data parameter provides the data which is written to the modified bits. This function is useful for modifying data in arrays located in paged memory, where the extended address is returned by ARRAYMEMBER(). Disables interrupts for 0.65 microseconds to ensure an uninterrupted read/modify/write operation.

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

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

CheckstartDisable

void CheckstartDisable( void)

Undoes the effect of CheckstartEnable(). This function is invoked by the factory cleanup mode. Note that this function is typically executed interactively using the Forth operating system; see CHECKSTART.DISABLE in the Forth debugging section of this glossary. Implementation detail: Erases 8 bytes starting at 0xBFF0 on page 0x37 in on-chip flash.

CheckstartEnable

void CheckstartEnable( xaddr xcfa, uint numbytes)

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

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

ClearBits

void ClearBits( uchar mask, xaddr address)

For each bit of mask that is set, clears the corresponding bit of the 8 bit value at the 32bit address. This function is useful for modifying data in arrays located in paged memory, where the extended address is returned by ARRAYMEMBER(). Disables interrupts for 0.5 microseconds to ensure an uninterrupted read/modify/write operation.

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

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

ClearBootVectors

void ClearBootVectors( void )

Disables all boot vectors so that none will be executed at reset or restart. This function is called during a “factory cleanup”, but it is not called by NoAutostart(). See SetBootVector(). The Forth version of this function, CLEAR.BOOT.VECTORS, is typically invoked interactively from the QED-Forth prompt; see its entry in the Forth debugging section of the glossary. Implementation detail: Writes 0 to the most significant byte in each location in the vector table to disable all 16 boot vectors at 0xBFB0 to 0xBFFF in page 0x37 on-chip flash memory.

Type: kernel function
Forth name: CLEAR.BOOT.VECTORS
Header file: opsystem.h

CLOCK_MONITOR_ID

CLOCK_MONITOR_ID

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

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

CmoveMany

void CmoveMany( xaddr source, xaddr dest, long numBytes)

Moves a block of memory. If the 32-bit byte count numBytes is greater than 0, numBytes consecutive bytes are copied from addresses starting at source to addresses starting at dest. The source and destination extended addresses may be located on different pages and the move may cross page boundaries. If the source and destination regions overlap and source is less than dest, CmoveMany() starts at high memory and moves toward low memory to avoid propagation of the moved contents. CmoveMany() always moves the contents in such a way as to avoid memory, except that attempts to perform an overlapping-region copy to or from the kernel flash starting at the precise address 0xC000 may result in propagation. Speed is approximately 2.3 microseconds per byte.

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

CmoveManyCheck

int CmoveManyCheck( xaddr source, xaddr dest, long numBytes)

Performs the action of CmoveMany (see its glossary entry), and then calculates the source and destination checksums, returning a true flag (= -1) if they are equal, or a false flag if they are not equal. The source checksum is calculated by calling CalcChecksumMany with parameters xaddr1 and d, and the destination checksum is calculated by calling CalcChecksumMany with parameters xaddr2 and d. Note that the full CMOVE.MANY operation is performed whether d is even or odd, but the checksum count is forced via truncation to be even, which means that the last byte of an odd-count move is not checksum-verified.

Type: kernel function
Forth name: CMOVE.MANY.CHECK
Header file: memory.h

Cold

void Cold( void)

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

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

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

DP: 0x1D8000   NP: 0x1D9000   VP: 0x2000   EEP: 0x400   HEAP: 0x188000 to 0x1CBFFF

Initializes the timeslice increment to 1.024 msec, and initializes the system resource variables. Builds the Forth vocabulary’s hash table, and copies from xflash to ram by invoking LOAD.PAGES to copy the memory pages designated by the LOAD.PAGES.AT.STARTUP command(s). Unless an autostart is present, this routine prints the coldstart message, flash-to-ram pages loaded report, and memory map summary. Calls ABORT which clears the stacks and calls either the QED-Forth interpreter or an autostart routine that has been installed using PRIORITY.AUTOSTART:, IS.PRIORITY.AUTOSTART, AUTOSTART:, or IS.AUTOSTART. If COLD.ON.RESET has been executed, every reset or power-up will invoke a COLD (as opposed to a WARM) initialization sequence. Consult the documentation for more information about cold restarts, and see the Forth debugging section of the glossary for descriptions of the commands discussed in this glossary entry.

ColdOnReset

void ColdOnReset( void)

Initializes a flag in EEPROM that causes subsequent resets to execute a cold restart (as opposed to the standard warm-or-cold restart). This option is useful for turnkeyed systems that have an autostart routine installed; any error or reset causes a full Cold() restart which initializes all user variables, after which the autostart routine completes the system initialization and enters the application routine. To revert to the standard reset, call StandardReset(). Note that this function can be executed interactively from QED-Forth by typing at the terminal:

COLD.ON.RESET

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

COPYARRAY

void COPYARRAY( FORTH_ARRAY* src_array_ptr, FORTH_ARRAY* dest_array_ptr)

Dimensions the destination array specified by dest_array_ptr and copies the contents of the source array specified by src_array_ptr into the destination. The source and destination can be in the same or different heaps. See the FORTH_ARRAY glossary entry for a description of how to define an array and its corresponding array_ptr.

Type: macro
Related Forth function: COPY.ARRAY
Header file: array.h

CopyArray

void CopyArray( FORTH_ARRAY* src_array_ptr, uint pfa_page, FORTH_ARRAY* dest_array_ptr, uint pfa_page)

Subsidiary function called by the recommended macro COPYARRAY().

COP_ID

COP_ID

A constant that returns the interrupt identity code for the computer operating properly (COP) interrupt. Used as an argument for ATTACH().

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

CountedString

xaddr CountedString( char* stringAddr, uint strPage)

Converts the specified null-terminated string (located at stringAddr on strPage) into a Forth-style counted string with the count in the first byte and the non-null-terminated string in the remaining bytes. Returns the 32-bit address of PAD which is where the converted counted string is located. The resulting string can be moved to any desired location by the StringMove() function. Note that the size of the PAD buffer puts a limit on the string size; the input string length should be less than 86 bytes.

COUNTER_UNDERFLOW_ID

COUNTER_UNDERFLOW_ID ( -- n )

A constant that returns the interrupt identity code for the modulus down-counter (MCCNT register) underflow interrupt. Used as an argument for ATTACH().

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

CountToMsec

ulong CountToMsec( ulong elapsed_timeslice_count)

Returns the 32-bit number of milliseconds corresponding to the elapsed_timeslice_count input parameter. The input parameter can be a difference (elapsed count, calculated using the minus operator) between a prior time and a more recent timeslice count, or it can be the current value of the timeslice clock since it was initialized to zero by InitElapsedTime(). The resolution equals the period of the timeslice clock (the default is approximately 1 msec). Even though the timeslice clock has a period that is a multiple of 1.024 msec, this routine mathematically compensates for the non-integer period, reducing the reported error to 1 part in 5000, equivalent to reporting 17 too few seconds per day. The maximum time that the return value can represent is about 49.7 days.

See also ReadElapsedTime(), ReadElapsedSeconds(), TIMESLICE_COUNT, StartTimeslicer(), and MSecTimeslicePeriod()
Header file: mtasker.h

Cr

void Cr( void)

Causes subsequent output to appear at the beginning of the next line by emitting a carriage return (ascii 13) followed by a line feed (ascii 10).

CURRENT_HEAP

CURRENT_HEAP

A user variable (member of the currently active TASK.USER_AREA structure) that holds the 32-bit extended address that specifies the end of the current heap. Other heap control variables are stored just below this address in the heap.

CUSTOM_ABORT

CUSTOM_ABORT

A user variable (member of the currently active TASK.USER_AREA structure) that contains a 16-bit flag. If the flag is 0 (false), then the standard system SysAbort() routine is performed. If the flag is non-zero (true), then the function whose address is stored in the user variable UABORT is executed when Abort() runs.

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

Type: macro
Related Forth function: CUSTOM.ABORT
Header file: user.h

CUSTOM_ERROR

CUSTOM_ERROR

A user variable (member of the currently active TASK.USER_AREA structure) that contains a 16-bit flag. If the flag is 0 (false), then the default error routine is performed in response to every system error. If the flag is non-zero (true), then the function whose address is stored in the user variable UERROR when an error occurs.

DEFAULT_HEAPEND

DEFAULT_HEAPEND

A 32-bit constant that returns the value 0x1CBFFF cast as an xaddr. Used as an argument for IsHeap() to establish the default 80 Kbyte heap starting on page 0x18.

See also DEFAULT_HEAPSTART and INIT_DEFAULT_HEAP()

Type: constant
Header file: heap.h

DEFAULT_HEAPSTART

DEFAULT_HEAPSTART

A 32-bit constant that returns the value 0x188000 cast as an xaddr. Used as an argument for IsHeap() to establish the default 80 Kbyte heap starting on page 0x18.

See also DEFAULT_HEAPEND and INIT_DEFAULT_HEAP()

Type: constant
Header file: heap.h

DELETED

void DELETED( FORTH_ARRAY* array_ptr)

De-allocates the heap space assigned to the specified Forth array, and clears the parameter field to indicate that the data structure is no longer dimensioned. It is good programming practice to delete arrays that hold temporary data after the data has been used; this frees the space in the heap for use by other arrays. See the FORTH_ARRAY glossary entry for a description of how to define an array and its corresponding array_ptr, and see DIM() for a description of how to dimension arrays.

Type: macro
Related Forth function: DELETED
Header file: array.h

Deleted

void Deleted( FORTH_ARRAY* array_ptr, uint pfa_page)

Subsidiary function called by the recommended macro DELETED(); see DELETED().

Type: kernel function
Forth name: DELETED
Header file: array.h

DIM

void DIM( type, uint numrows, uint numcols, FORTH_ARRAY* array_ptr)

Dimensions the array specified by array_ptr to have the specified number of rows and columns, with each array element sized to hold a parameter of the specified type. Examples of valid type parameters are standard identifiers and pre-defined types such as:

int      unsigned int   uint
char     unsigned char  uchar
long     unsigned long  ulong

Note that the uint, uchar, and ulong types are defined in the types.h file.

DIM() first executes DELETED() to de-allocate any heap space previously allocated to the array, and then writes the dimensioning information into the array's parameter field in common RAM and allocates the required number of bytes in the heap. Calls Abort() if there is not enough heap space.

Example of use:

To define an array of unsigned longs named MyArray with 3 rows and 5 columns, execute:

FORTH_ARRAY  Myarray;
DIM(ulong, 3, 5, &Myarray);

Once an array is declared using FORTH_ARRAY, it may be dimensioned on the fly.

Warning: Be sure to dimension the array within a function that is called at runtime! Compile-time or link-time dimensioning does not work with Forth arrays!

Note that the & operator in front of the array's name tells the compiler that a pointer is being passed. If you forget the & operator, the compiler will warn you that you are attempting to pass an entire structure (the array's parameter structure) as an argument to a function.

To store the value 0x123456 at row=0, column = 1, execute:

ARRAYSTORE( 0x123456, 0, 1, &Myarray);

To fetch the value stored at row=0, column=1 and assign it to a variable, you could execute:

static ulong  retrieved_data;
retrieved_data = ARRAYFETCH( 0, 1, &Myarray);

Note: the dimensioned FORTH_ARRAY array is not a C array. It must be initialized and accessed via special fetch and store functions such as ARRAYFETCH(), FARRAYFETCH(), ARRAYSTORE() and FARRAYSTORE() as opposed to C-style pointer arithmetic. The dimensioned FORTH_ARRAY is stored in memory in row-primary order; in other words, sequential elements in a row are stored in sequential memory addresses. This is the same as standard C-style arrays. The functions related to FORTH_ARRAYs provide a convenient means of storing data in the large paged memory space of the controller.

See also FORTH_ARRAY, ARRAYSTORE(), FARRAYSTORE(), ARRAYFETCH(), FARRAYFETCH(), ARRAYMEMBER(), ARRAYBASE(), DELETED(), FILLARRAY(), and COPYARRAY()

Type: macro
Related Forth function: DIMMED()
Header file: array.h

Dimensioned

void Dimensioned( uint r, uint c, uint Numdims, uint bytesPerElement,

FORTH_ARRAY* array_ptr, uint pfa_page)

Subsidiary function called by the recommended macro DIM(). Dimensioned() initializes the parameter field in common memory and allocates space for the specified memory in the heap. The parameters specify the number of rows, number of columns, number of dimensions (must equal 2), and bytes per element (should be 1, 2, or 4 so the standard ARRAYFETCH() and ARRAYSTORE() functions can access the data).

See also DIM()

Type: kernel function
Forth name: DIMENSIONED
Header file: array.h

DISABLE_INTERRUPTS

DISABLE_INTERRUPTS( void)

Sets the interrupt mask bit (the I bit) in the condition code register to globally disable interrupts.

Type: Macro
Related Forth function: DISABLE.INTERRUPTS
Header file: interrupt.h

DisableBootVectors

void DisableBootVectors( void)

Prevents any boot vectors installed by SET.BOOT.VECTOR from being executed.

DLF_APPEND

DLF_APPEND( "text" )

This macro allows you to add arbitrary Forth commands to the end of the .DLF file generated by the Mosaic IDE Plus.

Example of use:

DLF_APPEND( "2 2 + ." );

Place this code near the top of your .C program, and compile the project. As you load the generated .DLF file, notice that the math equation "2 + 2 = 4" will be carried out in Forth after the binary section loads.

Warning: do not put any 'cr' (Carriage Return) words in this section as it will corrupt the download.

Type: macro
Header file: compiler_util_macros.h

DLF_APPEND_FILE

DLF_APPEND_FILE( "filename.txt" )

This macro performs the same function as DLF_APPEND, except that it takes a filename as an argument.

Example of use:

DLF_APPEND_FILE( "filename.txt" );

filename.txt must be saved inside the project folder for this command to work. Put any forth commands you want to execute inside filename.txt, and they will run after the binary section of the .DLF loads.

Warning: do not put any 'cr' (Carriage Return) words in filename.txt as it will corrupt the download.

Type: macro
Header file: compiler_util_macros.h

DLF_PREPEND

DLF_PREPEND( "text" )

This macro allows you to add arbitrary Forth commands to the beginning of the .DLF file generated by the Mosaic IDE Plus.

Example of use:

DLF_PREPEND( "2 2 + ." );

Place this code near the top of your .C program, and compile the project. As you load the generated .DLF file, these commands will be executed before the binary section loads.

Warning: do not put any 'cr' (Carriage Return) words in this section as it will corrupt the download.

Type: macro
Header file: compiler_util_macros.h

DLF_PREPEND_FILE

DLF_PREPEND_FILE( "filename.txt" )

This macro performs the same function as DLF_PREPEND, except that it takes a filename as an argument.

Example of use:

DLF_PREPEND_FILE( "filename.txt" );

filename.txt must be saved inside the project folder for this command to work. Put any forth commands you want to execute inside filename.txt, and they will run before the binary section of the .DLF loads.

Warning: do not put any 'cr' (Carriage Return) words in filename.txt as it will corrupt the download.

Type: macro
Header file: compiler_util_macros.h

Dump

void Dump( xaddr base_xaddr, uint numbytes)

Displays the contents of numbytes bytes starting at the specified base_xaddr. The contents are dumped as hexadecimal bytes regardless of the current number base, and the ascii equivalent contents are also displayed. The dump responds to XON/XOFF handshaking and can be aborted by typing a carriage return.

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

DumpBinary

void DumpBinary( xaddr base_xaddr, uint numbytes)

Emits numbytes bytes of memory starting at the specified base_xaddr as a binary (not ascii!) stream. The dump responds to XON/XOFF handshaking and can be aborted by typing a carriage return. Note that this routine does not GET the serial resource if SERIAL_ACCESS equals RELEASE_AFTER_LINE.

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

DumpManyS2

void DumpManyS2( xaddr base_xaddr, long reported_addr, long numbytes)

base_xaddr is the location of the first byte to be dumped, reported_addr specifies the 24 bit starting address reported in the dump, and numbytes is the number of bytes to be dumped. Dumps the contents of numbytes bytes starting at base_xaddr using the standard ascii Motorola S2 hex format which is useful for burning flash memory chips and transferring data between devices. Motorola S2 records report 24 bit addresses which are useful in capturing and transferring complete application programs to/from flash memory. Dumps an S0 header record which is

S00900004845414445524D

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

S9030000FC

The Motorola S2 hex line format is:

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

All numbers are in hexadecimal base. A maximum of 0x20 data bytes are dumped per line. Each line starts with the record type (S2 in this case), followed by a 2-digit number of bytes (typically 24, which equals 0x20 byte per line plus 4 bytes for the reported address and checksum), followed by a 6-digit starting address for the line, followed by the contents of the memory locations (2 hex digits per byte), and concluding with a checksum. The checksum is calculated by summing each of the bytes on the line (excluding the record type) into an 8-bit accumulator and (one's) complementing the result. The dump responds to XON/XOFF handshaking and can be aborted by typing a carriage return. See the entry for DUMP.MANY.S2 in the interactive debugger section of this glossary for an example of use.

Type: kernel function
Forth name: DUMP.MANY.S2
Header file: memory.h

DupHeapItem

xaddr DupHeapItem( xaddr xhandle)

Given the 32-bit handle (pointer to a pointer) named xhandle1 of a source heap item, creates a duplicate heap item with identical contents in the same heap and returns its handle. Returns zero if xhandle1 is not a valid handle or if there is insufficient memory in the heap. To copy a heap item into a different heap, use TransferHeapItem().

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

ECT0_ID

ECT0_ID

A constant that returns the interrupt identity code for the enhanced counter/timer (ECT) channel 0 interrupt. Used as an argument for ATTACH().

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

ECT1_ID

ECT1_ID

A constant that returns the interrupt identity code for the enhanced counter/timer (ECT) channel 1 interrupt. Used as an argument for ATTACH().

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

ECT2_ID

ECT2_ID

A constant that returns the interrupt identity code for the enhanced counter/timer (ECT) channel 2 interrupt. Used as an argument for ATTACH().

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

ECT3_ID

ECT3_ID

A constant that returns the interrupt identity code for the enhanced counter/timer (ECT) channel 3 interrupt. Used as an argument for ATTACH().

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

ECT4_ID

ECT4_ID

A constant that returns the interrupt identity code for the enhanced counter/timer (ECT) channel 4 interrupt. Used as an argument for ATTACH().

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

ECT5_ID

ECT5_ID

A constant that returns the interrupt identity code for the enhanced counter/timer (ECT) channel 5 interrupt. Used as an argument for ATTACH().

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

ECT6_ID

ECT6_ID

A constant that returns the interrupt identity code for the enhanced counter/timer (ECT) channel 6 interrupt. Used as an argument for ATTACH().

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

ECT7_ID

ECT7_ID

A constant that returns the interrupt identity code for the enhanced counter/timer (ECT) channel 7 interrupt. Used as an argument for ATTACH().

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

ECTClearInterruptFlag

void ECTClearInterruptFlag( int channel_id )

Clears the associated flag bit of the specified channel_id in the Enhanced Capture Timer (ECT) system. The channel_id can be the channel number in the range 0 to 7 of an input capture (IC) or output compare (OC), or it can be one of the constants TCNT_OVERFLOW, PULSE_A_EDGE, PULSE_A_OVERFLOW, PULSE_B_OVERFLOW, or MODULUS_UNDERFLOW. In general, any interrupt service routine prompted by the ECT system must clear the associated flag bit, unless ECTFastClear() has been called to automatically clear the flag bit when an associated result register is accessed.

Type: kernel function
Forth name: ECT.CLEAR.INTERRUPT.FLAG
Header file: timerio.h

ECTFastClear

void ECTFastClear( void )

Writes a 1 to the TFCCA bit in the TSCR1 register to configure the Enhanced Capture Timer (ECT) system for automatic clearing of the relevant flag bit when an associated result register is accessed. This eliminates the need for service code to explicitly clear the flag bit (for example, in an interrupt service routine) by invoking ECTClearInterruptFlag() or by a direct write to the flag register. After this routine is executed, the fast clear mode stays in effect until the next power-up or hardware reset.

ECTInterruptDisable

void ECTInterruptDisable( int channel_id )

Clears the associated interrupt bit of the specified channel_id in the Enhanced Capture Timer (ECT) system to disable the interrupt associated with the specified channel. The channel_id can be a channel number in the range 0 to 7 of an input capture (IC) or output compare (OC), or it can be TCNT_OVERFLOW, PULSE_A_EDGE, PULSE_A_OVERFLOW, PULSE_B_OVERFLOW, or MODULUS_UNDERFLOW. . After a power-up or hardware reset, the ECT interrupts are disabled.

ECTInterruptEnable

void ECTInterruptEnable( int channel_id )

Sets the associated interrupt bit of the specified channel_id in the Enhanced Capture Timer (ECT) system to enable the interrupt associated with the specified channel. The channel_id can be a channel number in the range 0 to 7 of an input capture (IC) or output compare (OC), or it can be TCNT_OVERFLOW, PULSE_A_EDGE, PULSE_A_OVERFLOW, PULSE_B_OVERFLOW, or MODULUS_UNDERFLOW. After a power-up or hardware reset, the ECT interrupts are disabled.

ECTPrescaler

void ECTPrescaler( int n )

Sets the specified divider n as the prescaler associated with the free-running TCNT counter in the Enhanced Capture Timer (ECT) system. The TCNT frequency is 20 MHz divided by n, and the corresponding TCNT period is 50 nanoseconds times n. Valid values for the prescaler n are decimal 1, 2, 4, 8, 16, 32, 64, 128; other values are converted to one of these values. The default prescaler set at warm/cold startup is 32, yielding a 1.6 microsecond TCNT period, and a 104.8576 ms rollover (overflow) time. The TCNT free-running counter is the master clock for the input captures, output compares, gated pulse accumulators, and modulus counter functions of the ECT system.

Implementation note: It is highly recommended that TCNT is maintained as a free-running counter that cannot be stopped. This implies that bits CLK1 and CLK0 bits in the PACTL register be kept equal to zero, the TEN (timer enable) bit in TSCR1 = 1 (set at warm/cold); and the TCRE (timer counter reset enable) bit in TSCR2 = 0 (cleared at warm/cold). The kernel drivers follow this rule; specifically, the TCSR1 and TSCR2 registers are properly initialized at startup, and the PulseASetup() function which writes to the PACTL register keeps the CLK1 and CLK0 bits zeroed. Writing other values to these bits may make it impossible to use TCNT for general purpose software timing by the application program. Note that none of the kernel (operating system) functions rely on TCNT for software timing; rather, the multitasker uses the RTI (real-time interrupt) as a time base.

Type: kernel function
Forth name: ECT.PRESCALER
Header file: timerio.h

ECTStandardClear

void ECTStandardClear( void )

Undoes the effect of ECTFastClear , and reverts to the default condition in which the flag bits of the Enhanced Capture Timer (ECT) must be explicitly cleared by the application program by invoking ECTClearInterruptFlag() or by a direct write to the relevant flag register.

Type: kernel function
Forth name: ECT.STANDARD.CLEAR
Header file: timerio.h

ECT_OVERFLOW_ID

ECT_OVERFLOW_ID

A constant that returns the interrupt identity code for the enhanced counter/timer (ECT) overflow interrupt. Used as an argument for ATTACH().

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

Emit

void Emit( uchar c)

Displays character c by sending it via the serial I/O port. Emit() is a vectored routine that executes the routine whose 32-bit execution address is installed in the user variable UEMIT. The default installed routine called is Emit1() which sends the character via the primary serial port (supported by the processor’s SCI0 hardware UART). Emit2() may be installed in UEMIT by UseSerial2 or Serial2AtStarup(); Emit2() sends the character via the secondary serial port (supported by the processor’s SCI1 hardware UART).

See also Emit1(), Emit2() and _writeChar()

Type: C function; related QED-Forth function name: EMIT
Header file: serial.h

Emit1

void Emit1( uchar c)

Displays a character by sending it via the primary serial port (serial1) associated with the processor’s on-chip SCI0 hardware UART. Before sending the character, Emit1() waits (if necessary) for the previous character to be sent, and executes Pause() while waiting to allow other tasks (if present) a chance to run. The most significant byte of the input data stack cell is ignored. Emit1() is the default Emit() routine installed in the UEMIT user variable after the special cleanup mode is invoked or if Serial1AtStartup() has been executed. If the value in the user variable SERIAL_ACCESS is RELEASE_AFTER_LINE, Emit1() does not GET(SERIAL1_RESOURCE) or RELEASE(SERIAL1_RESOURCE). If SERIAL_ACCESS contains RELEASE_ALWAYS, Emit1() GETs and RELEASEs the SERIAL1_RESOURCE. If SERIAL_ACCESS contains RELEASE_NEVER, Emit1() GETs but does not RELEASE the SERIAL1_RESOURCE.

See also Emit(), UEMIT, Emit2(), SERIAL_ACCESS

Type: kernel function
Forth name: EMIT1
Header file: serial.h

Emit2

void Emit2( uchar c)

Writes the specified ascii character c to the output buffer of the secondary serial port (serial2) for subsequent transmission. The serial2 port is supported by the processor’s SCI1 hardware UART. Before sending the character, Emit1() waits (if necessary) for the previous character to be sent, and executes Pause() while waiting to allow other tasks (if present) a chance to run. The most significant byte of the input data stack cell is ignored. Emit2() can be made the default Emit() routine installed in the UEMIT user variable after each reset or restart by executing Serial2AtStartup(). If the value in the user variable SERIAL_ACCESS is RELEASE_AFTER_LINE, Emit2() does not GET(SERIAL2_RESOURCE) or RELEASE(SERIAL2_RESOURCE). If SERIAL_ACCESS contains RELEASE_ALWAYS, Emit2() GETs and RELEASEs the SERIAL2_RESOURCE. If SERIAL_ACCESS contains RELEASE_NEVER, Emit2() GETs but does not RELEASE the SERIAL2_RESOURCE.

See also Emit(), UEMIT, Emit1(), and SERIAL_ACCESS

Type: kernel function
Forth name: EMIT2
Header file: serial.h

ENABLE_INTERRUPTS

ENABLE_INTERRUPTS( void)

Clears the interrupt mask bit (the I bit) in the condition code register to globally enable interrupts.

Type: Macro
Related Forth function: ENABLE.INTERRUPTS
Header file: interrupt.h

EnableBootVectors

EnableBootVectors( )

Undoes the effect of EnableBootVectors, allowing any boot vectors installed by SetBootVector to be executed upon subsequent restarts.

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

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

Execute

void Execute( void(*action)(), uint actionPage)

Executes (calls) the action function specified by the function pointer; the function code resides on the specified actionPage.

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

EXTENDED_ADDR

EXTENDED_ADDR

A union typedef that provides a way of converting a 16-bit address and associated page into a 32-bit xaddr type, or vis versa. The definition is:

typedef union { xaddr addr32;
                struct { uint   page16;
                         char*   addr16;
                       } sixteen_bit;
              } EXTENDED_ADDR;

For example, the following code converts the address of the variable varname in common RAM (which corresponds to a 16 bit address; the effective page = 0) into a 32 bit xaddr in xaddr_of_varname:

char varname;
xaddr  xaddr_of_varname;                   // we want this to hold a 32bit addr
EXTENDED_ADDR temporary;                   // allocate union to convert type
temporary.sixteen_bit.addr16 = &varname;
temporary.sixteen_bit.page16 = 0;          // common page = 0
xaddr_of_varname = temporary.addr32;       // here's the result

See also the source code in the TYPES.h file.

Type: typedef
Header file: types.h

FALSE

FALSE

A constant equal to 0.

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

FARRAYFETCH

float FARRAYFETCH( type, uint row, uint col, FORTH_ARRAY* array_ptr)

Fetches the contents of the floating point element at row#, column# in the specified 2-dimensional array and casts it to the specified type. Typically, the float type will be specified when this function is called, although other compatible types may be specified (see the glossary entry for ARRAYFETCH() which handles non-floating-point data). There is an unchecked error if the specified array does not have 2 dimensions or if the number of bytes per element does not equal 4. See the FORTH_ARRAY glossary entry for a description of how to define an array and its corresponding array_ptr.

See also DIM(), ARRAYFETCH() and FARRAYSTORE()

Type: macro
Related Forth function: ArrayFetch()
Header file: array.h

FArrayFetch

float FArrayFetch( uint row, uint col, FORTH_ARRAY* array_ptr, uint pfa_page)

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

Type: kernel function
Forth name: 2ARRAY.FETCH
Header file: array.h

FARRAYSTORE

void FARRAYSTORE( float value, uint row, uint col, FORTH_ARRAY* array_ptr)

Stores the specified floating point value at row, col in the 2-dimensional FORTH_ARRAY specified by array_ptr. Use ARRAYSTORE() to store non-floating-point data. There is an unchecked error if the specified array does not have 2 dimensions or if the number of bytes per element does not equal 4. See the FORTH_ARRAY glossary entry for a description of how to define an array and its corresponding array_ptr.

FArrayStore

void FArrayStore( float value, uint row, uint col, FORTH_ARRAY* array_ptr, uint pfa_page)

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

Type: kernel function
Forth name: 2ARRAY.STORE
Header file: array.h

FetchChar

char FetchChar( xaddr address)

Fetches an 8-bit value from the specified extended address. This function is useful for fetching data from arrays located in paged memory, where the extended address is returned by ARRAYMEMBER().

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

FetchFloat

float FetchFloat( fxaddr address)

Fetches a 32-bit floating point number from the specified extended address. This function is useful for fetching data from arrays located in paged memory, where the extended address is returned by ARRAYMEMBER().

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

FetchFloatProtected

float FetchFloatProtected( xaddr address)

Fetches a floating point value from the specified extended address. Disables interrupts during the fetch to ensure that an interrupting routine or task does not modify the contents while the fetch is in process. Disables interrupts for 0.55 microseconds unless the specified 4 bytes straddle a page boundary, in which case interrupts are disabled for approximately 5.4 microseconds. Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page. This function is useful for fetching data from arrays located in paged memory, where the extended address is returned by ARRAYMEMBER().

FetchInt

int FetchInt( xaddr address)

Fetches a 16-bit number from the memory location specified by address. The high order byte is taken from address and the low order byte from address+1. This function is useful for fetching data from arrays located in paged memory, where the extended address is returned by ARRAYMEMBER()

Type: Forth function
Forth name: @
Header file: memory.h

FetchLong

long FetchLong( xaddr address)

Fetches a 32-bit value from the specified extended address. This function is useful for fetching data from arrays located in paged memory, where the extended address is returned by ARRAYMEMBER().

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

FetchLongProtected

long FetchLongProtected( xaddr address)

Fetches a 32-bit value from the specified extended address. Disables interrupts during the fetch to ensure that an interrupting routine or task does not modify the contents while the fetch is in process. Disables interrupts for 0.55 microseconds unless the specified 4 bytes straddle a page boundary, in which case interrupts are disabled for approximately 5.4 microseconds. Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page. This function is useful for fetching data from arrays located in paged memory, where the extended address is returned by ARRAYMEMBER(). For floating point values, use FetchFloatProtected().

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

FILLARRAY

void FILLARRAY( FORTH_ARRAY* array_ptr, uchar c)

Stores c into each byte of the specified Forth array. For descriptions of how to define and dimension a Forth array that resides in paged memory, see the glossary entries for FORTH_ARRAY and DIM().

Type: macro
Related Forth function: FILL.ARRAY
Header file: array.h

FillArray

void FillArray( FORTH_ARRAY* array_ptr, uint pfa_page, uchar c)

A subsidiary function called by the recommended macro FILLARRAY().

FillMany

void FillMany( xaddr base, long numBytes, char contents)

The specified byte contents is stored in each of numBytes consecutive addresses beginning at the 32-bit extended address base. The specified address region may cross page boundaries. Does nothing if numBytes = 0.

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

FILL_FIELD

FILL_FIELD

A user variable that contains a 16-bit flag. If the flag is true (non-zero), floating point numbers converted to strings by FPtoString() or printed in FLOATING format by PrintFP() are padded with spaces to yield a constant field width irrespective of whether the number is printed in scientific notation or fixed notation, and numbers printed in fixed notation are decimal aligned. This leads to neat printouts of tabular data. If the flag is false, the field width is not padded out.

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

Type: macro
Related Forth function: FILL.FIELD
Header file: numbers.h

FIXED

void FIXED( void)

Sets the default printing format used by FPtoString() and PrintFP() to fixed. Numbers are decimal aligned, and RIGHT_PLACES and LEFT_PLACES determine the field width. See the glossary entry for FPtoString() for more details.

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

FLOATING

FLOATING( )

Sets the default printing format used by FPtoString() and PrintFP() to floating. This format displays the number in FIXED format if the number can be represented with the same or more significant digits as it would if it were represented in SCIENTIFIC format. Otherwise, it uses SCIENTIFIC format. See the glossary entry for FPtoString() for more details.

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

FMAILBOX

FMAILBOX

This typedef allocates a 32-bit mailbox in RAM which can be accessed by FSEND(), TRY_TO_FSEND() and FRECEIVE(). The mailbox can hold any floating-point message; for non-floating-point messages, use MAILBOX. Example of use:

FMAILBOX   latest_data;
SEND( 3.14159, &latest_data);

Mailboxes are used in multitasked systems to share information between tasks and to synchronize tasks to one another. If the mailbox's contents equal zero, the mailbox is empty; it contains a message if its contents are non-zero. Before its first use, the mailbox must be initialized to zero. After initialization to zero, the only operators that should access the floating point mailbox are FSEND(), TRY_TO_FSEND() and FRECEIVE().

Type: typedef
Related Forth function: MAILBOX:
Header file: mtasker.h

ForthAskKey

int ForthAskKey( void)

A subsidiary function to AskKey(); see AskKey().

Type: kernel function
Forth name: ?KEY
Header file: serial.h

ForthEmit

int ForthEmit( void)

A subsidiary function to Emit(); see Emit().

Type: kernel function
Forth name: EMIT
Header file: serial.h

ForthKey

int ForthKey( void)

A subsidiary function to Key(); see Key().

Type: kernel function
Forth name: KEY
Header file: serial.h

FORTH_ARRAY

FORTH_ARRAY

Declares a new Forth-style array. Use as:

FORTH_ARRAY   array_name;

where array_name is any name of your choosing. The declaration allocates a parameter field structure in the variable area. This structure is initialized by DIM() to hold the dimensioning information for the array (number of rows and columns, element size, etc.) as well as pointers to the Forth heap and heap item that contain the array data.

Example of use:

To define an array of unsigned longs named MyArray with 3 rows and 5 columns, execute:

FORTH_ARRAY  Myarray;
DIM(ulong, 3, 5, &Myarray);

To store the value 0x123456 at row=0, column = 1, execute:

ARRAYSTORE( 0x123456, 0, 1, &Myarray);

To fetch the value stored at row=0, column=1 and assign it to a variable, you could execute:

static ulong  retrieved_data;
retrieved_data = ARRAYFETCH( 0, 1, &Myarray);

See also DIM(), ARRAYSTORE(), FARRAYSTORE(), ARRAYFETCH(), FARRAYFETCH(), ARRAYMEMBER(), ARRAYBASE(), DELETED(), FILLARRAY(), and COPYARRAY()

Type: macro; related function: ARRAY:
Header file: array.h

FORTH_TASK

FORTH_TASK

A macro that represents the TASKBASE at address 0x1200 for the default QED-Forth task.

FPtoString

char* FPtoString( float ansi_fp_num)

Converts the specified ansi_fp_num floating point number to a standard null-terminated ascii string, and returns the address of the string. If the conversion fails, returns 0. The specified number is converted into one of three formats: FIXED, SCIENTIFIC, or FLOATING. To set the default format, execute one of the macros FIXED(), SCIENTIFIC(), or FLOATING(). FLOATING format is the default after a COLD restart. Each format is described in detail here:

FIXED()

If FIXED() has been executed, FPtoString() converts the input number into a text string using the following format: (an optional) sign, LEFT_PLACES digits, a decimal point, RIGHT_PLACES digits, and a trailing space, as

-xxx.yyy

If the user variable NO_SPACES is false (the default condition), the field size equals LEFT_PLACES + RIGHT_PLACES + 3 and numbers are decimal aligned. The size of the string is clamped to a maximum of 32 characters. Setting the user variable TRAILING_ZEROS true displays all trailing zeros to the right of the decimal point, to a maximum specified by the contents of the user variable RIGHT_PLACES. If the input number cannot be represented as an ascii string in FIXED format (that is, if the values of LEFT_PLACES and RIGHT_PLACES won't allow the number to be represented in FIXED format) then FPtoString() returns 0.

SCIENTIFIC()

If SCIENTIFIC() has been executed, FPtoString() converts the input number into a text string using the following format: (an optional) sign, single digit, decimal point, MANTISSA.PLACES digits, E, exponent sign, 2-digit exponent, and a trailing space, as

-1.xxxxE-yy

The field size is 8 plus the contents of the user variable MANTISSA_PLACES. The string includes a trailing space unless NO_SPACES is true. Any valid floating point number can be represented in the SCIENTIFIC format, so a valid string pointer is always returned.

FLOATING()

If FLOATING() has been executed, FPtoString() selects FIXED format unless the number can be displayed with greater resolution using scientific notation, in which case SCIENTIFIC() format is used. If the user variable FILL_FIELD equals zero (the default condition), the string is displayed using the minimum possible field size, and numbers are not decimal aligned. If FILL_FIELD is true (non-zero), the field size of the string is always equal to the scientific field size, which is MANTISSA_PLACES+8, and numbers are decimal aligned for neat display of tabular data. The string includes a trailing space unless NO_SPACES is true. A valid string address is always returned because any valid floating point number can be represented in the FLOATING format.

FP_FORMAT

FP_FORMAT

A 16-bit user variable (member of the currently active user structure) that specifies the format to be used by subsequent executions of PrintFP() and FPtoString. FP_FORMAT is typically accessed indirectly by means of the format specifiers FIXED(), FLOATING(), and SCIENTIFIC(); see their glossary entries for more details.

Type: macro
Header file: numbers.h

FRandom

float FRandom( void)

Returns a pseudo-random floating point number greater than or equal to 1.0 and less than 2.0.

See also RANDOM_SEED, Random and RandomGaussian

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

FRECEIVE

float FRECEIVE( float* mailboxAddr)

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

FReceive

float FReceive( float* mailboxAddr, uint mailboxPage)

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

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

FromHeap

xaddr FromHeap( ulong size)

If size bytes are available in the heap, allocates them and returns a 32-bit xhandle (pointer to a pointer) that indirectly points to the 32-bit base xaddress of the allocated heap item. Adjusts size upward so that it is an even multiple of 4, and allocates the heap item so that its base address is an even multiple of 4. Returns 0 if there is not enough heap space to perform the allocation, or if the allocated handle is within 5 bytes of the bottom of CURRENT_HEAP's page (handles must be on the same page as CURRENT_HEAP).

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

FromIO

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

Transfers numbytes bytes starting at the specified offset (0 ≤ offset ≤ 255) in the Wildcard with hardware address module_num, to the buffer starting at base_addr on base_page.

See also FromIORegister() and ToIO()

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

FromSmartIO

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

Transfers numbytes bytes starting at the specified offset (0 ≤ offset ≤ 255) in the smart processor-carrying Wildcard with hardware address module_num, to the buffer starting at base_addr on base_page.

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

FSEND

void FSEND( float message, float * mailboxAddr)

Executes Pause() until the mailbox with extended address mailboxAddr is empty (contains 0.0) and then stores the 32-bit floating point message in mailboxAddr. The message can be any 32-bit floating point number except zero; use SEND() to send a non-floating-point value as a message. To ensure that the state of the mailbox is correctly determined, FSEND() disables interrupts for 0.75 to 1.55 microseconds.

See also TRY_TO_FSEND, FRECEIVE() and MAILBOX

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

FSend

void FSend( float message, float * mailboxAddr, uint mailboxPage)

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

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

GET

void GET( xaddr* resourceAddr)

Used in a multitasking system to gain access to a shared resource. Executes Pause() until the resource variable whose address is resourceAddr is available, and then GETs the resource by storing the task ID (i.e., the base address of the TASK structure) of the requesting task into the resourceAddr. A 32-bit zero in resourceAddr indicates that the resource is available, and a non-zero value that is not equal to the requesting task's ID indicates that another task controls the resource. To ensure that the state of the resource is correctly determined, GET() disables interrupts for 0.25 to 1 microsecond.

See also TRY_TO_GET(), RELEASE(), TASK and RESOURCE

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

Get

void Get( xaddr* resourceAddr, uint resourcePage)

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

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

Halt

void Halt( void)

An infinite loop whose action is to put the calling task ASLEEP and execute Pause(). Typically used to terminate a task action that is not itself an infinite loop.

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

HoldingRegForceLatch

void HoldingRegForceLatch( void )

If enable_holding_flag and latch_mode_flag are true as set by the ICPulseConfig() function, then this routine forces the contents of the input capture registers TC0-TC3 and their corresponding 8-bit pulse accumulators to be latched into the holding registers.

Implementation detail: sets the ICLAT bit in the MCCTL register.

Type: kernel function
Forth name: HOLDING.REG.FORCE.LATCH
Header file: timerio.h

IC_1024_CYCLE_DELAY

IC_1024_CYCLE_DELAY

A constant that is passed to ICNoiseDelay() to configure the input capture noise suppression delay. Each cycle of delay corresponds to 50 nanoseconds, so passing this constant to ICNoiseDelay() sets up a 51.2 microsecond noise delay. In other words, pulses of less than 51.2 microseconds duration will not be captured when this option is configured, and this limits the effect of spurious noise. The noise suppression delay is disabled by default after a power-up or hardware reset.

Type: macro
Related Forth function: IC.1024.CYCLE.DELAY
Header file: timerio.h

IC_256_CYCLE_DELAY

IC_256_CYCLE_DELAY

A constant that is passed to ICNoiseDelay() to configure the input capture noise suppression delay. Each cycle of delay corresponds to 50 nanoseconds, so passing this constant to ICNoiseDelay() sets up a 12.8 microsecond noise delay. In other words, pulses of less than 12.8 microseconds duration will not be captured when this option is configured, and this limits the effect of spurious noise. The noise suppression delay is disabled by default after a power-up or hardware reset.

Type: macro
Related Forth function: IC.256.CYCLE.DELAY
Header file: timerio.h

IC_512_CYCLE_DELAY

IC_512_CYCLE_DELAY

A constant that is passed to ICNoiseDelay() to configure the input capture noise suppression delay. Each cycle of delay corresponds to 50 nanoseconds, so passing this constant to ICNoiseDelay() sets up a 25.6 microsecond noise delay. In other words, pulses of less than 25.6 microseconds duration will not be captured when this option is configured, and this limits the effect of spurious noise. The noise suppression delay is disabled by default after a power-up or hardware reset.

Type: macro
Related Forth function: IC.512.CYCLE.DELAY
Header file: timerio.h

IC_DELAY_DISABLED

IC_DELAY_DISABLED

A constant that is passed to ICNoiseDelay() to disable the input capture noise suppression delay. This is the default condition after a power-up or hardware reset.

Type: macro
Related Forth function: IC.DELAY.DISABLED
Header file: timerio.h

ICFirstPolarity

int ICFirstPolarity( void )

For the four latched input capture channels, returns a bit-encoded value n that represents the polarity of the first edge that has caused an input capture to occur after the corresponding capture latch has been read. Bit 0 corresponds to IC0, bit 1 corresponds to IC1, bit 2 corresponds to IC2, and bit3 corresponds to IC3. A bit value of 0 means that the first input capture has been caused by a falling edge, and a bit value of 1 means that the first input capture has been caused by a rising edge. The default result after a reset is 0.

Type: kernel function
Forth name: IC.FIRST.POLARITY
Header file: timerio.h

ICHoldingRead

uint ICHoldingRead( int channel_id )

For the specified buffered input capture channel_id in the range 0 to 3, reads and returns the 16-bit value uint from the corresponding input capture holding register TC0, TC1H, TC2H, or TC3H. The specified channel must be configured as an input capture (as opposed to an output compare) by invoking the InputCapture() function. See the glossary entries for ICPulseConfig(), ICOverwriteOK(), and ICNoOverwrite() for more information about the IC holding registers. Briefly, if the latch_mode flag passed to ICPulseConfig() is true, then the input capture register contents are latched into the holding register when the modulus counter equals zero, or when the HoldingRegForceLatch() function is invoked. If the latch_mode flag passed to ICPulseConfig() is false, then the captures are in “queued mode”, and the holding registers are loaded from the IC register upon each new capture, subject to the ICOverwriteOK() or ICNoOverwrite() provision. Do not use this function for pulse accumulator channels; consult the glossary entry for PulseHoldingRead().

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

ICNoOverwrite

void ICNoOverwrite( int channel_id )

For a valid input capture channel_id in the range 0 to 7, configures the channel such that the input capture and its holding register (if present) cannot be overwritten until read by the application program; consult the OCICRegRead() and ICHoldingRead() functions.

Implementation detail: This routine sets the specified bit in the ICOVW register to prevent an IC register or IC holding register to be overwritten by a new event before it is empty. The default state at reset is that overrides are ok.

Type: kernel function
Forth name: IC.NO.OVERWRITE
Header file: timerio.h

ICNoiseDelay

void ICNoiseDelay( int delay_id )

Configures all of the input captures such that pulses shorter than the specified delay (relative to the 50 nanosecond E-clock period) are ignored. Valid input parameters are the constants IC_DELAY_DISABLED, IC_256_CYCLE_DELAY (12.8us), IC_512_CYCLE_DELAY (25.6us), or IC_1024_CYCLE_DELAY (51.2us); consult their glossary entries. The noise delay feature is disabled by default after a power-up or hardware reset.

Type: kernel function
Forth name: IC.NOISE.DELAY
Header file: timerio.h

ICOverwriteOK

void ICOverwriteOK( int channel_id )

For a valid input capture channel_id in the range 0 to 7, configures the channel such that the input capture and its holding register (if present) can be overwritten even though they have not been read by the application program; consult the OCICRegRead() and ICHoldingRead() functions.

Implementation detail: This routine clears the specified bit in the ICOVW register to allow an IC register or IC holding register to be overwritten by a new event before it is empty. The default state at reset is that overrides are ok.

Type: kernel function
Forth name: IC.OVERWRITE.OK
Header file: timerio.h

ICPulseConfig

void ICPulseConfig( int share37, int share26, int share15, int share04, int two_events, int pulse_255_max, int holding, int latch_mode)

Each of the eight input parameter flags specifies a single bit that is combined into a 8-bit value and written to the ICSYS register to configure the input capture and pulse accumulator subsystem. The default state after a reset is all flags equal to zero; in other words, all bits in the ICSYS register are 0 after a reset. ICSYS is a write-once register, so this function can only be executed one time after each power-up or hardware reset; attempting to execute it again will have no effect until the processor hardware is reset. The first four input parameters configure input capture sharing. If the share37 boolean flag is true (nonzero), then an input capture event on IC3 is also treated as a capture event on IC7. If the share26 flag is true, then an input capture event on IC2 is also treated as a capture event on IC6. If the share15 flag is true, then an input capture event on IC1 is also treated as a capture event on IC5. If the share04 flag is true, then an input capture event on IC0 is also treated as a capture event on IC4. If the pulse_255_max flag is true, all 8-bit pulse accumulators count to 0xFF and then stop. The remaining three flags (holding, latch_mode, and two_events) configure the holding registers for input captures IC0-3 and 8-bit pulse accumulators 0-3. If the holding and latch_mode flags are both false, then the two_events flag is relevant; when true, two_events specifies that the associated flag bit will not be set until 2 capture events have transpired (one capture is in the holding register, and the second is in the IC register). If either the holding or latch_mode flags is true, then a single input capture event sets the corresponding flag bit. If latch_mode is true, latching into the holding register (and clearing of 8-bit pulse accumulators) occurs when the modulus down counter reaches 0, or when a zero is written into the count register using ModCounterLoad() and ModCounterUpdate(), or when HoldingRegForceLatch() is executed. The pulse accumulators require that both the holding and latch_mode flags are true to utilize the holding registers, as the queued mode of transferring to the holding registers applies only to input captures, not the associated pulse accumulators. For more information on the Input Capture and Pulse Accumulator subsystems, see the ECT (Enhanced Capture Timer) Block User Guide published by Motorola.

Type: kernel function
Forth name: IC.PULSE.CONFIG
Header file: timerio.h

IIC_104KHZ_23PERCENT

IIC_104KHZ_23PERCENT

A constant that is passed to IICInit() to initialize the IIC (Inter-IC 2-wire serial bus) baud rate to 104 KHz, with a 23% data hold time as a percentage of the clock period. The value returned by the constant is stored by IICInit() into the IBFD register. The typical maximum IIC bus frequency is 100 KHz, and a good target for the data hold time as a percentage of the clock period is 25% (34.5% is the maximum allowed). While the IIC system cannot run at a master clock rate of exactly 100 KHz, the closest choices are the 104 KHz as set by this constant, and 96 KHz as set by the IIC_96KHZ_25PERCENT constant. For a 10 KHz IIC master, see the glossary entry for IIC_10KHZ_13PERCENT. To specify a customized IIC baud rate, see the glossary entry for IICFrequencies(). The maximum attainable IIC clock frequency on the PDQ hardware is 1000 KHz.

Type: macro
Related Forth function: IIC.104KHZ.23PERCENT
Header file: serial.h

IIC_10KHZ_13PERCENT

IIC_10KHZ_13PERCENT

A constant that is passed to IICInit() to initialize the IIC (Inter-IC 2-wire serial bus) baud rate to 10 KHz, with a 13% data hold time as a percentage of the clock period. The value returned by the constant is stored by IICInit() into the IBFD register. The typical maximum IIC bus frequency is 100 KHz, and the maximum data hold time as a percentage of the clock period is 34.5%. For a 100 KHz IIC master, see the glossary entries for IIC_96KHZ_25PERCENT and IIC_104KHZ_23PERCENT. To specify a customized IIC baud rate, see the glossary entry for IICFrequencies(). The maximum attainable IIC clock frequency on the PDQ hardware is 1000 KHz.

Type: macro
Related Forth function: IIC.10KHZ.13PERCENT
Header file: serial.h

IIC_96KHZ_25PERCENT

IIC_96KHZ_25PERCENT

A constant that is passed to IICInit() to initialize the IIC (Inter-IC 2-wire serial bus) baud rate to 96 KHz, with a 25% data hold time as a percentage of the clock period. The value returned by the constant is stored by IICInit() into the IBFD register. The typical maximum IIC bus frequency is 100 KHz, and a good target for the data hold time as a percentage of the clock period is 25% (34.5% is the maximum allowed). While the IIC system cannot run at a master clock rate of exactly 100 KHz, the closest choices are the 96 KHz as set by this constant, and 104 KHz as set by the IIC_104KHZ_23PERCENT constant. For a 10 KHz IIC master, see the glossary entry for IIC_10KHZ_13PERCENT. To specify a customized IIC baud rate, see the glossary entry for IICFrequencies(). The maximum attainable IIC clock frequency on the PDQ hardware is 1000 KHz.

Type: macro
Related Forth function: IIC.96KHZ.25PERCENT
Header file: serial.h

IIC_ARB_LOST_ERROR

IIC_ARB_LOST_ERROR

A constant equal to 2 which is logically OR’d together with any other error conditions encountered during an IIC (Inter-IC 2-wire serial bus) data transfer to indicate that IIC bus arbitration was lost during the data transfer. The resulting combined error result is placed into the IIC_ERROR variable and returned by the IIC send and receive functions. An error value of zero means that no error occurred. To analyze and respond to a nonzero error condition, the application program can perform a logical AND of the error result with this IIC_ARB_LOST_ERROR constant; a nonzero result means that bus arbitration was lost during the IIC data exchange. This typically results from a non-responsive slave or a multi-master conflict. See IIC_ERROR.

Type: macro
Related Forth function: IIC.ARB.LOST.ERROR
Header file: serial.h

IIC_ERROR

IIC_ERROR

A system variable that contains the 16-bit integer error result of the most recent IIC (Inter-IC 2-wire serial bus) data transfer. IIC_ERROR is cleared at the start of each IIC send or receive operation. If the contents of this variable equal zero after an IIC data transfer, there was no error. If the contents are non-zero, then an error occurred, and the contents equal the logical OR of the identifying error bitmasks. The error condition can be determined by sequentially performing a logical AND of the original contents of IIC_ERROR with the following bitmask error types: IIC_TIMEOUT_ERROR, IIC_ARB_LOST_ERROR, IIC_NAK_ERROR, IIC_XMIT_BUF_OVERFLOW, and IIC_RCV_BUF_OVERFLOW. Any AND operation whose result equals the tested-for error constant indicates that the named error was encountered.

Type: macro
Related Forth function: IIC.ERROR
Header file: serial.h

IIC_ID

IIC_ID

A constant that returns the interrupt identity code for the IIC (Inter-IC) bus 2-wire multi-drop) serial port. This bus is sometimes referred to as the I-squared-C (I2C) bus. Used as an argument for ATTACH().

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

IIC_MASTER_RECEIVER

IIC_MASTER_RECEIVER

A system variable that contains a 16-bit integer flag used to control an IIC (Inter-IC 2-wire serial bus) serial transfer. This flag is automatically set by IICReceive() and IICReceiveFrame(), and is cleared by the IIC sending routines. The application program typically does not have to access this low-level control flag.

Type: macro
Related Forth function: IIC.MASTER.RECEIVER
Header file: serial.h

IIC_NAK_ERROR

IIC_NAK_ERROR

A constant equal to 3 which is logically OR’d together with any other error conditions encountered during an IIC (Inter-IC 2-wire serial bus) data transfer to indicate that No AcKnowlegement was received during a data transfer before a timeout occurred. The resulting combined error result is placed into the IIC_ERROR variable and returned by the IIC send and receive functions. An error value of zero means that no error occurred. To analyze and respond to a nonzero error condition, the application program can perform a logical AND of the error result with this IIC_NAK_ERROR constant; a result equal to IIC_NAK_ERROR means that a timeout occurred without any acknowlegement during the IIC data exchange. This typically results from a non-responsive slave or a multi-master conflict.

See also IIC_ERROR

Type: macro
Related Forth function: IIC.NAK.ERROR
Header file: serial.h

IIC_NUM_BYTES_TO_RCV

IIC_NUM_BYTES_TO_RCV

A system variable that contains a 16-bit integer equal to the number of bytes to be received by a master on the IIC (Inter-IC 2-wire serial) bus during the next data reception. This variable is automatically initialized by IICReceive() and IICReceiveFrame(). The application program typically does not have to access this low-level control variable.

Type: macro
Related Forth function: IIC.NUM.BYTES.TO.RCV
Header file: serial.h

IIC_NUM_BYTES_TO_XMIT

IIC_NUM_BYTES_TO_XMIT

A system variable that contains a 16-bit integer equal to the number of bytes to be transmitted by a master on the IIC (Inter-IC 2-wire serial) bus. This variable is automatically initialized by IICSend(), IICSendFrame(), and IICSendNextFrame(). The application program typically does not have to access this low-level control variable.

Type: macro
Related Forth function: IIC.NUM.BYTES.TO.XMIT
Header file: serial.h

IIC_RCV_BUF_FULL

IIC_RCV_BUF_FULL

A system variable that contains a 16-bit integer status flag for the IIC (Inter-IC 2-wire serial bus) receiver. A true flag indicates that the master’s receive buffer is full based on the expected number of incoming bytes passed to the IICReceive() or IICReceiveFrame() functions. This variable is automatically set by the background IIC interrupt service routine running in the master. If you have used the IICReceive() function to initiate the master’s reception, the application program must monitor the IIC_RCV_BUF_FULL variable and, when it becomes true (non-zero), fetch the expected number of bytes out of the IIC_RCV_BUFFER starting at offset 0. To automate the process, use the IICReceiveFrame() function to initiate the reception; in this case, the function waits until the IIC_RCV_BUF_FULL flag is true, clears the flag, copies the received data to a private buffer, and exits. By calling IICReceiveFrame(), you can access the received data without the need to monitor the IIC_RCV_BUF_FULL flag.

Type: macro
Related Forth function: IIC.RCV.BUF.FULL
Header file: serial.h

IIC_RCV_BUF_OFFSET

IIC_RCV_BUF_OFFSET

A system variable that contains a 16-bit integer equal to the zero-based offset into the IIC_RCV_BUFFER, pointing to the next available byte. This variable is automatically incremented by the IIC (Inter-IC 2-wire serial bus) interrupt service routine during the reception of a frame by the IIC master or slave. This variable is typically not used during reception by the IIC master, but it is very useful for managing data reception in the IIC slave. The application program of a slave IIC receiver should monitor the contents of IIC_RCV_BUF_OFFSET until it equals the expected number of incoming bytes, then copy the received bytes out of the receive buffer starting at buffer offset 0 (in other words, starting at the address in common RAM returned by IIC_RCV_BUFFER).

Type: macro
Related Forth function: IIC.RCV.BUF.OFFSET
Header file: serial.h

IIC_RCV_BUF_OVERFLOW

IIC_RCV_BUF_OVERFLOW

A constant equal to 0x10 which is logically OR’d together with any other error conditions encountered during an IIC data reception to indicate that the number of bytes received exceeded the contents of IIC_RCV_BUF_SIZE, which specifies the size of the IIC_RCV_BUFFER. The default receive buffer size after executing IICInit() is decimal 32 bytes; consult the glossary entry for IICInit() if you want to declare a larger buffer. The resulting combined error result is placed into the IIC_ERROR variable and returned by the IIC (Inter-IC 2-wire serial bus) send and receive functions. An error value of zero means that no error occurred. To analyze and respond to a nonzero error condition, the application program can perform a logical AND of the error result with this IIC_RCV_BUF_OVERFLOW constant; a nonzero result means that a buffer overflow occurred during the IIC data reception.

See also IIC_ERROR

Type: macro
Related Forth function: IIC.RCV.BUF.OVERFLOW
Header file: serial.h

IIC_RCV_BUF_PTR

IIC_RCV_BUF_PTR

A system variable declared as a 16-bit pointer to a character buffer (the actual declaration is a pointer to a pointer to an unsigned character). It contains the 16-bit address of the IIC_RCV_BUFFER in common RAM. IICInit() initializes this variable to point to the default 32 byte IIC (Inter-IC 2-wire serial bus) receive buffer in reserved system RAM. If a 32 byte receive buffer is adequate, you never have to use the IIC_RCV_BUF_PTR. If, however, you need to declare a larger receive buffer, allocate the buffer in common RAM, call the IICInit() routine, then write the buffer size into IIC_RCV_BUF_SIZE, and write the 16-bit buffer base address into IIC_RCV_BUF_PTR. Note that:

* IIC_RCV_BUF_PTR

is equivalent to:

IIC_RCV_BUFFER

Type: macro
Related Forth function: IIC.RCV.BUF.PTR
Header file: serial.h

IIC_RCV_BUF_SIZE

IIC_RCV_BUF_SIZE

A system variable that contains a 16-bit integer equal to the size of the IIC_RCV_BUFFER. IICInit() initializes this variable to 32. If a 32 byte receive buffer is adequate, you never have to use the IIC_RCV_BUF_SIZE variable. If, however, you need to declare a larger receive buffer, allocate the buffer in common RAM, call the IICInit() routine, then write the buffer size into IIC_RCV_BUF_SIZE, and write the 16-bit buffer base address into IIC_RCV_BUF_PTR.

Type: macro
Related Forth function: IIC.RCV.BUF.SIZE
Header file: serial.h

IIC_RCV_BUFFER

IIC_RCV_BUFFER

Declared as a pointer to an unsigned character, this macro returns the 16-bit address of the IIC receive buffer in common RAM by fetching the 16-bit contents of IIC_RCV_BUF_PTR. By default, this buffer is decimal 32 bytes long after IICInit() is executed. If you need to create a larger receive buffer, see the glossary entry for IIC_RCV_BUF_PTR. A master on the IIC (Inter-IC 2-wire serial) bus should fetch received data out of the IIC_RCV_BUFFER starting at offset 0 after calling IICReceive(). A slave on the IIC bus should fetch received data out of the IIC_RCV_BUFFER starting at offset 0 after monitoring the IIC_RCV_BUF_OFFSET variable until it equals the expected number of incoming bytes. Note that:

IIC_RCV_BUFFER

is equivalent to:

* IIC_RCV_BUF_PTR

Type: macro
Related Forth function: IIC.RCV.BUFFER
Header file: serial.h

IIC_TIMEOUT_ERROR

IIC_TIMEOUT_ERROR

A constant equal to 1 which is logically OR’d together with any other error conditions encountered during an IIC (Inter-IC 2-wire serial bus) data transfer to indicate that a timeout error occurred. The resulting combined error result is placed into the IIC_ERROR variable and returned by the IIC send and receive functions. An error value of zero means that no error occurred. To analyze and respond to a nonzero error condition, the application program can perform a logical AND of the error result with this IIC_TIMEOUT_ERROR constant; a nonzero result means that a timeout occurred during the IIC data exchange. This typically results from a non-responsive slave or a multi-master conflict.

See also IIC_ERROR

Type: macro
Related Forth function: IIC.TIMEOUT.ERROR
Header file: serial.h

IIC_XMIT_BUF_EMPTY

IIC_XMIT_BUF_EMPTY

A system variable that contains a 16-bit integer status flag for the IIC (Inter-IC 2-wire serial bus) transmitter. A true flag indicates that the master’s transmit buffer is empty based on a comparison with the contents of the IIC_NUM_BYTES_TO_XMIT variable as initialized by IICSend(), IICSendFrame(), or IICSendNextFrame(). This variable is also set if the master was not properly acknowleged by the IIC slave during the attempted data transmission. This variable is not used by the slave in an IIC data transfer. IIC_XMIT_BUF_EMPTY is a low level system variable that is typically not accessed by the application program.

Type: macro
Related Forth function: IIC.XMIT.BUF.EMPTY
Header file: serial.h

IIC_XMIT_BUF_OFFSET

IIC_XMIT_BUF_OFFSET

A system variable that contains a 16-bit integer equal to the zero-based ooffset into the IIC.XMIT.BUFFER, pointing to the next byte to be transmitted by the IIC (Inter-IC 2-wire serial bus) master. This variable is initialized by by IICSend(), IICSendFrame(), or IICSendNextFrame() and maintained by the IIC interrupt service routine; it is a low level system variable that is typically not accessed by the application program.

Type: macro
Related Forth function: IIC.XMIT.BUF.OFFSET
Header file: serial.h

IIC_XMIT_BUF_OVERFLOW

IIC_XMIT_BUF_OVERFLOW

A constant equal to 8 which is logically OR’d together with any other error conditions encountered during an IIC (Inter-IC 2-wire serial bus) data transmission to indicate that the offset to the next byte to be transmitted in the IIC_XMIT_BUFFER exceeds the allowed number of bytes in the buffer as indicated by the contents of the IIC_XMIT_BUF_SIZE variable. The default transmit buffer size after executing IICInit() is decimal 32 bytes; consult the glossary entry for IIC_XMIT_BUF_PTR if you need to declare a larger buffer. The resulting combined error result is placed into the IIC_ERROR variable and returned by the IIC send functions. An error value of zero means that no error occurred. To analyze and respond to a nonzero error condition, the application program can perform a logical AND of the error result with this IIC_XMIT_BUF_OVERFLOW constant; a nonzero result means that a buffer overflow occurred during the IIC data transmission.

See also IIC_ERROR

Type: macro
Related Forth function: IIC.XMIT.BUF.OVERFLOW
Header file: serial.h

IIC_XMIT_BUF_PTR

IIC_XMIT_BUF_PTR

A system variable declared as a 16-bit pointer to a character buffer (the actual declaration is a pointer to a pointer to an unsigned character). It contains the 16-bit address of the IIC_XMIT_BUFFER in common RAM. IICInit() initializes this variable to point to the default 32 byte IIC transmit buffer in reserved system RAM. If a 32 byte transmit buffer is adequate, you never have to use the IIC_XMIT_BUF_PTR. If, however, you need to declare a larger transmit buffer, allocate the buffer in common RAM, call the IICInit() routine, then write the buffer size into IIC_XMIT_BUF_SIZE, and write the 16-bit buffer base address into IIC_XMIT_BUF_PTR. Note that:

* IIC_XMIT_BUF_PTR

is equivalent to:

IIC_XMIT_BUFFER

Type: macro
Related Forth function: IIC.XMIT.BUF.PTR
Header file: serial.h

IIC_XMIT_BUF_SIZE

IIC_XMIT_BUF_SIZE

A system variable that contains a 16-bit integer equal to the size of the IIC_XMIT_BUFFER. IICInit() initializes this variable to 32. If a 32 byte transmit buffer is adequate, you never have to use the IIC_XMIT_BUF_SIZE variable. If, however, you need to declare a larger transmit buffer, allocate the buffer in common RAM, call the IICInit() routine, then write the buffer size into IIC_XMIT_BUF_SIZE, and write the 16-bit buffer base address into IIC_XMIT_BUF_PTR.

Type: macro
Related Forth function: IIC.XMIT.BUF.SIZE
Header file: serial.h

IIC_XMIT_BUFFER

IIC_XMIT_BUFFER

Declared as a pointer to an unsigned character, this macro returns the 16-bit address of the IIC receive buffer in common RAM by fetching the 16-bit contents of IIC_XMIT_BUF_PTR. By default, this buffer is decimal 32 bytes long after IICInit() is executed. To create a larger transmit buffer, see the glossary entry for IIC_XMIT_BUF_PTR. An application program can perform an IIC (Inter-IC 2-wire serial bus) master transmission by writing the data to be transmitted into the IIC transmit buffer (starting at the address returned by this IIC_XMIT_BUFFER macro) and then calling IICSend(). Alternatively, the data to be transmitted can reside in a buffer anywhere in memory, and this private buffer xaddress and the associated number of bytes to be transmitted can be passed to either IICSendFrame() or IICSendNextFrame(); both of these functions automatically copy the data to be transmitted into the IIC_XMIT_BUFFER. A slave on the IIC bus should place any data bytes to be transmitted to the master into the IIC transmit buffer (buffer (starting at the address returned by this IIC_XMIT_BUFFER macro) before they are demanded by the master, and then let the master retrieve them. Note that:

IIC_XMIT_BUFFER

is equivalent to:

* IIC_XMIT_BUF_PTR

Type: macro
Related Forth function: IIC.XMIT.BUFFER
Header file: serial.h

IICFrequencies

void IICFrequencies( void )

This function prints a formatted table of all 192 possible contents of the IBFD (IIC Bus Frequency Divider) register in both hex and decimal, followed by the corresponding decimal IIC bus frequency in kHz (rounded to the nearest kHz) and the corresponding decimal data hold time as a percentage of clock period. This function is useful if you do not want to use one of the three named baud rate constants (IIC_96KHZ_25PERCENT, IIC_104KHZ_23PERCENT, or IIC_10KHZ_13PERCENT). The typical maximum IIC (Inter-IC 2-wire serial bus) frequency is 100 KHz, and a good target for the data hold time as a percentage of the clock period is 25% (34.5% is the maximum allowed). The maximum attainable IIC clock frequency on the PDQ hardware is 1000 KHz. While the IIC system cannot run at a master clock rate of exactly 100 KHz, the closest choices are 96 KHz and 104 KHz as set by the IIC_96KHZ_25PERCENT and IIC_104KHZ_23PERCENT constants. For a 10 KHz IIC master, use IIC_10KHZ_13PERCENT. To use this function, type:

IIC.FREQUENCIES

(the Forth version of the function name) interactively at the terminal and examine the resulting data table to select the IBFD register contents that yield the desired IIC bus clock frequency and the data hold time as a percentage of the clock period, and then pass the selected IBFD constant to the IICInit() function. If you prefer to work strictly in C, you can invoke the IICFrequencies() function from a compiled C program to create the printout. When executed, the first few lines of the resulting printout look like this:

Pass the selected IBFD constant to IICInit (or to IIC.INIT in Forth).
0xIBFD  IBFD  SCL.KHZ  SDA.HOLD%  (decimal)
 0x0     0      1000      35
 0x1     1       909      32
 0x2     2       833      33
 …

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

IICInit

void IICInit( int ibfd_contents, int my_slave_address)

This routine initializes and configures the IIC (Inter-IC 2-wire multi-drop serial bus) software for interrupt-based operation compatible with the IIC driver functions built into the operating system.

The input parameters are the contents to be written to the IBFD baud rate register, and the slave IIC address. The ibfd_contents parameter is typically one of the pre-defined constants IIC_96KHZ_25PERCENT, IIC_104KHZ_23PERCENT, or IIC_10KHZ_13PERCENT; if a different baud rate is required, see the glossary entry for IICFrequencies(). The my_slave_address input parameter should be an even number between 2 and 254. In other words, the address should occupy a single byte with the least significant bit equal to zero; this satisfies the requirements of the IIC protocol as implemented on the HCS12 processor. To prevent contention, the assigned slave address must be unique on the connected IIC network.

The IIC control register is configured for interrupt-enabled IIC transfers starting in the slave reception mode with standard acknowledgement. PORTJ pins 6 and 7 are set high if they are outputs to ensure that they idle in the inactive high state.

This routine ATTACHes the IIC interrupt service routine which runs during data transfers; note that the Attach() routine disables interrupts for many milliseconds the first time it runs while EEPROM is being programmed; be careful to ensure that this does not adversely affect your application. After the EEPROM is initialized by this routine, subsequent invocations of this function will not need to re-write the EEPROM, so interrupts will not be disabled.

This IICInit() routine does NOT globally enable interrupts; the application must invoke ENABLE_INTERRUPTS or some equivalent interrupt-enabling function such as StartTimeslicer() before attempting an IIC data transfer.

This function erases all of the IIC control variables and buffers, including:

IIC_XMIT_BUF_EMPTY      IIC_RCV_BUF_FULL        IIC_ERROR              IIC_XMIT_BUF_OFFSET
IIC_RCV_BUF_OFFSET      IIC_MASTER_RECEIVER     IIC_NUM_BYTES_TO_XMIT  IIC_NUM_BYTES_TO_RCV
IIC_XMIT_BUFFER         IIC_RCV_BUFFER

The IIC_XMIT_BUF_SIZE and IIC_RCV_BUF_SIZE variables are set to their default values of decimal 32 bytes each, and the IIC_XMIT_BUF_PTR and IIC_RCV_BUF_PTR variables are initialized to point to the default 32-byte buffers in reserved system RAM. If you need to create larger transmit and receive buffers, allocate the new buffers in common RAM, call this IICInit() routine, then write the buffer sizes into IIC_XMIT_BUF_SIZE and IIC_RCV_BUF_SIZE, and write the respective 16-bit buffer base addresses into IIC_XMIT_BUF_PTR and IIC_RCV_BUF_PTR.

Note that the transmit and receive buffers are linear frame buffers, as opposed to circular ring buffers. The received data must be extracted from the IIC_RCV_BUFFER before the next receive operation begins, and the data in the IIC_XMIT_BUFFER must be transmitted before writing a new frame into the transmit buffer.

Type: kernel function
Forth name: IIC.INIT
Header file: serial.h

IICReceive

int IICReceive( uint timeout_cnt, int numbytes, int slave_iic_address)

This routine receives numbytes of data from a remote slave on the IIC (Inter-IC 2-wire serial) bus having the specified slave_iic_address, and places the received data into the IIC_RCV_BUFFER. IICReceive() sets up the control variables and registers, waits and pauses until the IIC bus is not busy, and, if the timeslicer is running, enforces a maximum waiting time of timeout_cnt timeslice counts, where the default timeslice period is 1.024 milliseconds; see MsecTimeslicePeriod(). If a timeout occurs, the IIC_TIMEOUT_ERROR error flag is returned. Note that if the timeslicer is not running (that is, if StartTimeslicer() was not executed), then no timeout is enforced, and if the slave is not responding for some reason, this routine will Pause() indefinitely. When the IIC bus becomes available, this routine initiates the reception by sending the slave_iic_address with its least significant bit set to indicate that we (the master) are reading. This routine does not wait for the reception to end; rather, the calling routine should monitor the IIC_RCV_BUF_FULL system variable and, when it goes true (nonzero), get the data out of the IIC_RCV_BUFFER. For a simpler way to receive data without monitoring the IIC_RCV_BUF_FULL variable, see IICReceiveFrame(). Note that there is a slight chance that the IIC bus will be busy when we start receiving (if someone else grabbed the bus just as we were about to grab it); this condition will be detected by the interrupt service routine and will result in an error code containing IIC_ARB_LOST_ERROR being returned by this function. If the returned error flag is nonzero, the calling routine must test for and respond to the following error conditions: IIC_TIMEOUT_ERROR, IIC_ARB_LOST_ERROR, IIC_NAK_ERROR, and IIC_RCV_BUF_OVERFLOW. See the glossary entries of these error constants and of IIC_ERROR for more details.

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

IICReceiveFrame

int IICReceiveFrame( uint timeout_cnt, xaddr buffer, int numbytes, int slave_iic_address)

This routine receives numbytes of data from a remote slave on the IIC (Inter-IC 2-wire serial) bus having the specified slave_iic_address, and places the received data into the IIC_RCV_BUFFER. IICReceiveFrame() sets up the control variables and registers, waits and PAUSEs until the IIC bus is not busy, and, if the timeslicer is running, enforces a maximum waiting time of timeout_cnt timeslice counts, where the default timeslice period is 1.024 milliseconds; see MsecTimeslicePeriod(). If a timeout occurs, the IIC_TIMEOUT_ERROR error flag is returned. When the IIC bus becomes available, this routine initiates the reception by sending the slave_iic_address with its least significant bit set to indicate that we (the master) are reading. This routine then waits and pauses until the IIC_RCV_BUF_FULL flag is set, and, if the timeslicer is running, again enforces the timeout_cnt timeslice counts maximum waiting period while waiting for the receive buffer to fill. If there is no timeout, IICReceiveFrame() moves the contents of the IIC_RCV_BUFFER to the location specified by the xaddr buffer input parameter. This routine retains control until the received bytes have been moved out of the IIC_RCV_BUFFER so the next requested reception can't corrupt prior data. The specified timeslice count is used both while waiting for the IIC bus to be available, and again for the receive buffer to fill, so the maximum timeout is twice the specified timeout period. Note that if the timeslicer is not running (that is, if StartTimeslicer() was not executed), then no timeout is enforced, and if the slave is not responding for some reason, this routine will Pause() indefinitely. Note that there is a slight chance that the IIC bus will be busy when we start receiving (if someone else grabbed the bus just as we were about to grab it); this condition will be detected by the interrupt service routine and will result in an error code containing IIC_ARB_LOST_ERROR being returned. If the returned error flag is nonzero, the calling routine must test for and respond to the following error conditions: IIC_TIMEOUT_ERROR, IIC_ARB_LOST_ERROR, IIC_NAK_ERROR, and IIC_RCV_BUF_OVERFLOW. See the glossary entries of these error constants and of IIC_ERROR for more details.

IICSend

int IICSend( uint timeout_cnt, int numbytes, int slave_iic_address)

This routine sends data to a remote slave on the IIC (Inter-IC 2-wire serial) bus having the specified slave_iic_address. IICSend() transmits numbytes of data that have been pre-loaded into the IIC_XMIT_BUFFER, sets up the control variables and registers, waits and calls Pause() until the IIC bus is not busy, and, if the timeslicer is running, enforces a maximum waiting time of timeout_cnt timeslice counts, where the default timeslice period is 1.024 milliseconds; see MsecTimeslicePeriod(). If a timeout occurs, the IIC_TIMEOUT_ERROR error flag is returned. Note that if the timeslicer is not running (that is, if StartTimeslicer() was not executed), then no timeout is enforced, and if the slave is not responding for some reason, this routine will Pause() indefinitely. If there is no timeout error, IICSend() initiates the transmission by sending the slave_iic_address with its least significant bit cleared to indicate that we (the master) are writing. Note that, while this routine waits for the hardware IIC bus to be not-busy, this routine can still step on the control variables of a previous write by this processor which has not yet completed. To avoid this problem, use IICSendNextFrame() to wait until the prior frame transmission initiated by this (master) processor has completed before sending another one. Note that there is a slight chance that the IIC bus will be busy when we start transmitting (if someone else grabbed the bus just as we were about to grab it); this condition will be detected by the interrupt service routine and will set the IIC_ARB_LOST_ERROR variable. Also note that errors posted during the frame transmission by the background interrupt service routine may not be included in the error flag returned by this routine, as transmission may continue after this routine exits. If the returned error flag is nonzero, the calling routine must test for and respond to the following error conditions: IIC_TIMEOUT_ERROR, IIC_ARB_LOST_ERROR, IIC_NAK_ERROR, and IIC_XMIT_BUF_OVERFLOW. See the glossary entries of these error constants for more details.

See also IICSendFrame and IICSendNextFrame

Type: kernel function
Forth name: IIC.SEND
Header file: serial.h

IICSendFrame

int IICSendFrame( uint timeout_cnt, xaddr buffer, int numbytes, int slave_iic_address)

This routine copies numbytes of data from the specified xaddr buffer into the IIC_XMIT_BUFFER and calls IICSend() to send the data to the specified remote slave on the IIC bus. The timeout_cnt parameter specifies the maximum time in timeslice counts (typically 1.024ms, see MsecTimeslicePeriod) to wait for the IIC bus to become available. See the glossary entries for IICSend() for a detailed description of operation. For a more bullet-proof transmission function that returns only after the transmission has completed,

IICSendNextFrame

int IICSendNextFrame( uint timeout_cnt, xaddr buffer, int numbytes, int slave_iic_address)

IICSendNextFrame() first waits and calls Pause() until the IIC_XMIT_BUF_EMPTY flag is true to ensure that any prior transfer is complete. If no timeout error occurred while waiting, it copies numbytes bytes of data from the specified buffer at xaddr into the IIC_XMIT_BUFFER and sends the data to the specified remote slave on the IIC (Inter-IC 2-wire serial) bus having the specified slave_iic_address. The timeout_cnt parameter specifies the maximum time in timeslice counts (typically 1.024ms per count) to wait for the transmit buffer to empty, and for the IIC bus to become available. The advantage of this routine is that it sends a new frame only after the prior transmission has ended, thereby avoiding contention between sequential transmissions and ensuring data integrity. After waiting for any prior transmission to complete, IICSendNextFrame() sets up the control variables and registers, waits and calls Pause() until the IIC bus is not busy, and, if the timeslicer is running, enforces a maximum waiting time of timeout_cnt timeslice counts, where the default timeslice period is 1.024 milliseconds; see MsecTimeslicePeriod(). If a timeout occurs, the IIC_TIMEOUT_ERROR error flag is returned. The specified timeslice count is used both while waiting for the xmit buffer to empty, and again for the IIC bus to become not-busy, so the maximum timeout is twice the specified timeout period. Note that if the timeslicer is not running (that is, if StartTimeslicer() was not executed), then no timeout is enforced, and if the slave is not responding for some reason, this routine will Pause() indefinitely. If there is no timeout error, IICSendNextFrame() initiates the transmission by sending the slave_iic_address with its least significant bit cleared to indicate that we the master are writing. Note that there is a slight chance that the IIC bus will be busy when we start transmitting (if someone else grabbed the bus just as we were about to grab it); this condition will be detected by the interrupt service routine and will set the IIC_ARB_LOST_ERROR variable. Also note that errors posted during the frame transmission by the background interrupt service routine may not be included in the error flag returned by this routine, as transmission may continue after this routine exits. If the returned error flag is nonzero, the calling routine must test for and respond to the following error conditions: IIC_TIMEOUT_ERROR, IIC_ARB_LOST_ERROR, IIC_NAK_ERROR, and IIC_XMIT_BUF_OVERFLOW. See the glossary entries of these error constants and of IIC_ERROR for more details.

See also IICSend() and IICSendFrame()

Type: kernel function
Forth name: IIC.SEND.NEXT.FRAME
Header file: serial.h

InitElapsedTime

void InitElapsedTime( void)

Initializes the 32-bit contents of the system variable TIMESLICE_COUNT to zero.

See also ReadElapsedSeconds(), CountToMsec(), StartTimeslicer() and StopTimeslicer()

Type: kernel function
Forth name: INIT.ELAPSED.TIME
Header file: mtasker.h

InitIPSPI

void InitIPSPI( void)

Initializes SPI channels SPI1 and SPI2 for interprocessor (IP) communications. These SPI channels are reserved for inter-processor communications on multi-processor systems such as the PDQScreen. If multiprocessing is not required, the SPI1 and SPI2 channels may be used to communicate with other peripherals. The Master2_bar jumper (labeled SPI#2) on the PDQ Board determines which port this routine designates as the master and which as the slave. If the SPI#2 jumper cap is installed, then SPI2 is the master SPI and SPI1 is the slave. If the SPI#2 jumper is not installed, then SPI1 is the master and SPI2 is the slave. The SPI1 and SPI2 clocks idle low, data is sampled/valid on the falling/trailing clock edge, and data is transferred on the rising leading clock edge. The default baud rate is set to 5 MHz. This routine is called upon each power-up or restart.

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

InitSPI

void InitSPI( void)

Configures and enables the serial peripheral interface channel SPI0 so that it can transfer data on the Wildcard bus stacks and to/from the on-board battery-backed real-time clock. Initializes the 68HCS12 as the SPI master with 2 MHz data transfer, with clock idling low, valid data present/sampled on the falling trailing edge of the SPI clock, and data transferred on the rising/leading clock edge. Also initializes the resource variable SPI_RESOURCE to zero. This routine is called upon each power-up or restart.

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

InitVitalIRQsOnCold

void InitVitalIRQsOnCold( void)

Undoes the effect of the NoVitalIRQInit() command, and causes subsequent cold restarts to perform the default action of checking the interrupt vectors for the COP, clock monitor, illegal opcode trap and RTI (timeslicer) interrupts and initializing them if they do not contain the standard interrupt service vectors.

Type: kernel function
Forth name: INIT.VITAL.IRQS.ON.COLD
Header file: opsystem.h

INIT_DEFAULT_HEAP

INIT_DEFAULT_HEAP( )

A macro that initializes an 80 Kbyte heap in pages 0x18 through 0x1C, inclusive. This is the default heap after a COLD restart.

See also IsHeap(), DEFAULT_HEAPSTART and DEFAULT_HEAPEND

Type: macro
Header file: heap.h

InputCapture

void InputCapture( int channel_id )

For the specified channel_id in the range 0 to 7, configures the corresponding bit of the PORTT timer register as an input capture (as opposed to an output compare). An input capture memorizes the value of the free-running TCNT counter at the instant of the triggering input transition in its associated timer/counter register TCx (TC0 through TC7); see OCICRegRead(). An input capture can also optionally cause an interrupt when the triggering input transition occurs. After a power-up or hardware reset, all 8 PORTT pins are configured as input captures by default, with no triggering action. To configure a trigger action, pass one of the action constants (TRIGGER_OFF, TRIGGER_ON_RISING_EDGE, TRIGGER_ON_FALLING_EDGE, or TRIGGER_ON_ANY_EDGE) and the specified channel_id to the TriggerEdge() function. To enable or disable an interrupt, pass the channel_id to ECTInterruptEnable() or ECTInterruptDisable().

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 this routine and the TriggerEdge() routine, and then enabled for pulse counting using the PulseEnable() function (for 8 bit pulse accumulators) or PulseBSetup() function (for 16 bit pulse accumulators). Use channel_id = 0 to 3 for the 8 bit accumulators PA0 through PA3, and channel_id = 0 (or pass the PULSE_B channel_id constant) for the 16-bit PULSE_B accumulator. Do not pass PULSE_A as a channel_id input parameter to this InputCapture() function. See PulseASetup() for more details regarding the 16-bit PULSE_A accumulator.

Implementation detail: The InputCapture() routine clears the bit of the specified channel in the TIOS register.

Type: kernel function
Forth name: INPUT.CAPTURE
Header file: timerio.h

InstallMultitasker

void InstallMultitasker( void)

Installs the timeslice multitasker timer by initializing the interrupt vector of the real-time interrupt (RTI). This command is automatically executed upon a COLD restart (unless the command NoVitalIRQInit() has been executed) and by the command StartTimeslicer(). Because the interrupt vector is in non-volatile EEPROM, it is usually not necessary to invoke this command unless the RTI interrupt vector has been modified.

Type: kernel function
Forth name: INSTALL.MULTITASKER
Header file: mtasker.h

IOChangeBits

void IOChangeBits( uchar data, uchar mask, int offset, int module_num)

At the byte specified by the offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, modifies the bits specified by 1's in the mask parameter to have the values indicated by the corresponding bits in the data parameter. module_num range 0-7 implements standard speed modules, and module_num range 8-15 implements slow-access-timing modules. Disables interrupts for 2.7 microseconds to ensure an uninterrupted read/modify/write operation. Does not work for smart processor-carrying Wildcards.

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

IOClearBits

void IOClearBits( uchar mask, int offset, int module_num)

At the byte specified by the offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, clears the bits specified by 1's in mask. module_num range 0-7 implements standard speed modules, and module_num range 8-15 implements slow-access-timing modules. Disables interrupts for 2.35 microseconds to ensure an uninterrupted read/modify/write operation. Does not work for smart processor-carrying Wildcards.

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

IOFetchChar

char IOFetchChar( int offset, int module_num)

Fetches a byte from the specified offset (0 ≤ offset ≤ 255) in the 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. To fetch from a smart processor-carrying Wildcard, use SmartIOFetchChar.

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

IOFetchFloat

float IOFetchFloat( int offset, int module_num)

Fetches a 32-bit floating point number from the specified offset (0 ≤ offset ≤ 255) in the 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. To fetch from a smart processor-carrying Wildcard, use SmartIOFetchFloat.

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

IOFetchInt

int IOFetchInt( int offset, int module_num)

Fetches a 16-bit integer from the specified offset (0 ≤ offset ≤ 255) in the 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. To fetch from a smart processor-carrying Wildcard, use SmartIOFetchInt.

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

IOFetchLong

long IOFetchLong( int offset, int module_num)

Fetches a 32-bit long number from the specified offset (0 ≤ offset ≤ 255) in the 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. To fetch from a smart processor-carrying Wildcard, use SmartIOFetchLong.

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

IOSetBits

void IOSetBits( uchar mask, int offset, int module_num)

At the byte specified by the offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, sets the bits specified by 1's in mask. module_num range 0-7 implements standard speed modules, and module_num range 8-15 implements slow-access-timing modules. Disables interrupts for 2.35 microseconds to ensure an uninterrupted read/modify/write operation. Does not work for smart processor-carrying Wildcards.

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

IOStoreChar

void IOStoreChar( char c, int offset, int module_num)

Stores c at the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules. Also works for smart processor-carrying Wildcards.

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

IOStoreFloat

void IOStoreFloat( float f, int offset, int module_num)

Stores the 32-bit floating point number f at the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules. Also works for smart processor-carrying Wildcards.

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

IOStoreInt

void IOStoreInt( int i, int offset, int module_num)

Stores the 16-bit value i at the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules. Also works for smart processor-carrying Wildcards.

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

IOStoreLong

void IOStoreLong( long l, int offset, int module_num)

Stores the 32-bit number l at the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules. Also works for smart processor-carrying Wildcards.

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

IRQ_ID

IRQ_ID

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

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

IsAutostart

void IsAutostart( void(*action)(), uint actionPage)

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

CFA.FOR  MAIN  IS.AUTOSTART

or,

AUTOSTART: MAIN

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

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

Type: kernel function
Forth name: IS.AUTOSTART
Header file: opsystem.h

IsHeap

void IsHeap( xaddr start, xaddr end)

Initializes the heap control variables to set up a heap starting at the specified 32-bit start address and ending 1 byte below the specified 32-bit end address. All of the bytes between start and end must be modifiable RAM. The size of the heap and of individual heap items is limited only by available memory. If the specified heap size (end - start) is greater than or equal to 16 bytes, IsHeap() initializes the user variable CURRENT_HEAP to end, and initializes heap variables (located near the top of the heap) to indicate that the specified memory region can be used for the heap and that there are no allocated heap items. If the specified heap size (end - start) is less than 16 bytes, only the user variable CURRENT_HEAP is initialized, and the heap control variables that are stored in the heap itself are not initialized. This allows tasks to share a heap which has already been initialized without disturbing the values of the heap control variables. The maximum size of a heap is limited only by the amount of available contiguous RAM. A heap can flow over page boundaries. Likewise, the size of a data structure in the heap is limited only by the available memory in the heap. The only heap limitation is that the list of handles which is maintained near the top of the heap must be on the last page of the heap, and the handle list cannot flow over a page boundary. Because each handle requires only 4 bytes, this poses very little limitation for most practical applications.

Caution: sharing a heap among tasks may lead to hard-to-diagnose multitasking failures. Consult the Software Manual when designing multitasking programs.

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

IsPriorityAutostart

void IsPriorityAutostart( void(*action)(), uint actionPage)

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

CFA.FOR MAIN IS.AUTOSTART

or,

AUTOSTART: MAIN

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

See also PRIORITY.AUTOSTART: and AUTOSTART:

Type: kernel function
Forth name: IS.PRIORITY.AUTOSTART
Header file: opsystem.h

KERNEL_ARRAY_ADDR

KERNEL_ARRAY_ADDR

A constant equal to the SEGMENT_ARRAY_ADDR() of the kernel, which has segment_ID 0. This low-level constant is used to facilitate calls to the QED-Forth kernel functions from C.

Type: macro
Header file: segments.h

KERNEL_ID

KERNEL_ID

A constant equal to zero. The operating system assigns an integer ID to each segment that is defined, and the kernel itself has the reserved ID of zero.

Type: macro
Header file: segments.h

Key

uchar Key( void)

Waits (if necessary) for receipt of a character from the serial port and places the character on the data stack. Key() is a vectored routine that executes the routine whose xcfa is stored in the user variable UKEY. The default installed routine called is Key1() which receives the character from the primary serial port (supported by the processor’s hardware UART SCI0). Key2() may be installed in UKEY by UseSerial2() or Serial2AtStartup(); Key2() receives the character from the secondary serial port (supported by the processor’s hardware UART SCI1).

See also Key1(), Key2() and _readTerminal()

Type: C function; related QED-Forth function name: KEY
Header file: serial.h

Key1

uchar Key1( void)

Waits (if necessary) for receipt of a character from the primary serial port (serial1) and returns the received character. Key1() does not echo the character. The serial1 port is associated with the processor’s hardware UART SCI0. Key1() is the default Key() routine installed in the UKEY user variable if Serial1AtStartup() has been executed (and after the special cleanup mode is invoked). If the value in SERIAL_ACCESS is RELEASE_AFTER_LINE, Key1() does not execute GET(SERIAL1_RESOURCE) or RELEASE(SERIAL1_RESOURCE). If SERIAL_ACCESS contains RELEASE_ALWAYS, Key1() GETs and RELEASEs the SERIAL1_RESOURCE. If SERIAL_ACCESS contains RELEASE_NEVER, Key1() GETs but does not RELEASE the SERIAL1_RESOURCE.

See also Key(), UKEY, Key2(), and SERIAL_ACCESS

Type: kernel function
Forth name: KEY1
Header file: serial.h

Key2

uchar Key2( void)

Waits (if necessary) for receipt of a character from the secondary serial port (serial2) and returns the received character. Key2() does not echo the character. The serial2 port is associated with the processor’s hardware UART SCI1. Key2() can be made the default Key() routine installed in the UKEY user variable after each reset or restart by executing Serial2AtStartup(). If the value in SERIAL_ACCESS is RELEASE_AFTER_LINE, Key2() does not execute GET(SERIAL2_RESOURCE) or RELEASE(SERIAL2_RESOURCE). If SERIAL_ACCESS contains RELEASE_ALWAYS, Key2() GETs and RELEASEs the SERIAL2_RESOURCE. If SERIAL_ACCESS contains RELEASE_NEVER, Key2() GETs but does not RELEASE the SERIAL2_RESOURCE.

See also Key(), UKEY, Key1(), and SERIAL_ACCESS

Type: kernel function
Forth name: KEY2
Header file: serial.h

KillTask

void KillTask( TASK* taskBase, uint taskPage)

Puts ASLEEP and removes from the round robin multitasking loop the task whose TASKBASE address is taskBase. The task to be killed must be installed in the round robin loop when KillTask() is called. If it isn't, or if a task attempts to kill itself, the results are unpredictable. Aborts if taskBase is not in common RAM. Note that input parameter taskPage always equals 0, indicating that the task is located in common RAM.

LEFT_PLACES

LEFT_PLACES

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

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

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

LoadPage

void LoadPage( int src_flash_page, int dest_ram_page)

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

Type: kernel function
Forth name: LOAD.PAGE
Header file: memory.h

LoadPages

void LoadPages( int starting_page, int num_pages)

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

See also WriteEnable and LoadPagesAtStartup

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

LoadPages(0, 0x1E);

Memory map summary:

XFlash Pages RAM Pages DEFAULT.MAP Typical Use

@addr=0-3FFF @addr=8000-BFFF and write-protect (WP) area ID

00-0F 00-0F Typically code (DP); WP region 1

10-13 10-13 Typically names (NP); WP region 2

14-1D 14-1D: Always RAM, not write-protectable

1E-1F – RAM pages 1E, 1F are not implemented.

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

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

LoadPagesAtStartup

void LoadPagesAtStartup( int starting_page, int num_pages, int area_id)

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

MAILBOX

MAILBOX

This typedef allocates a 32-bit mailbox in RAM which can be accessed by SEND(), TRY_TO_SEND() and RECEIVE(). The mailbox can hold any non-floating-point message up to 32 bits in size; for floating point messages, use FMAILBOX. Example of use:

MAILBOX   comm_flag;
SEND( 0x12345, &comm_flag);

Mailboxes are used in multitasked systems to share information between tasks and to synchronize tasks to one another. If the mailbox's contents equal zero, the mailbox is empty; it contains a message if its contents are non-zero. Before its first use, the mailbox must be initialized to zero. After initialization to zero, the only operators that should access the mailbox are SEND(), TRY_TO_SEND() and RECEIVE().

Type: typedef
Related Forth function: MAILBOX:
Header file: mtasker.h

MAKE_ISR

MAKE_ISR( function )

This macro must be used whenever ATTACH() is used. The MAKE_ISR() macro provides support variables for the ATTACH() function.

Example of use:

_Q void my_isr(void)
{
  // body of a functional interrupt service routine
}
MAKE_ISR(my_isr);

main()
{
  ATTACH(my_isr, ECT3_ID);  // post the interrupt service routine
}

Place MAKE_ISR() in the global scope, after the last '}' of the function you would like use with ATTACH.

MANTISSA_PLACES

MANTISSA_PLACES

A user variable that holds the number of digits to be displayed in the mantissa when a floating point number is displayed in SCIENTIFIC format.

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

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

MAX

MAX( num1, num2)

Returns the greater of num1 and num2; the inputs can be of any compatible type. This macro is defined as:

#define MAX(A,B)  (((A) > (B)) ? (A) : (B))

Type: macro
Header file: utility.h

MicrosecDelay

void MicrosecDelay( uint numMicroseconds)

Enters a software timing loop for u microseconds. It can time to a 1 microsecond resolution with an overhead of under 1 microsecond. Note that the elapsed time will be increased by the duration of any interrupt routines that are serviced while MICROSEC.DELAY is running. Consequently, this routine does not guarantee accurate timing when the timesliced multitasker is running.

Type: kernel function
Forth name: MICROSEC.DELAY
Header file: mtasker.h

MIN

MIN( num1, num2)

Returns the lesser of num1 and num2; the inputs can be of any compatible type. This macro is defined as:

#define MIN(A,B)  (((A) < (B)) ? (A) : (B))

Type: macro
Header file: utility.h

ModCounterLoad

void ModCounterLoad( uint value )

Writes the specified value to the MCCNT modulus down-counter count register associated with the Enhanced Capture Timer (ECT) system. If the modulus down counter has been enabled by passing a true enable flag to ModCounterSetup() (that is, if the MODMC bit in the MCCTL register is set), then the write of the specified value is automaticaly directed by the hardware to the load counter associated with the 16-bit modulus down counter (as opposed to the modulus counter itself). To force an immediate write of the counter, execute this routine, then call ModCounterUpdate(). If the input parameter value equals 0, the modulus counter will remain at 0 without setting the modulus underflow flag (MCZF in MCFLG). If the holding and latch_mode flags passed to ICPulseConfig() are both true (that is, if the LATQ and BUFEN bits in the ICSYS register are set), the input capture and pulse accumulator registers will be latched when the modulus counter count equals zero.

Type: kernel function
Forth name: MOD.COUNTER.LOAD
Header file: timerio.h

ModCounterRead

uint ModCounterRead( void )

Reads the 16-bit modulus down counter and returns its value. The modulus counter is associated with the Enhanced Capture Timer (ECT) system. If the read_load_val flag passed to ModCounterSetup() was false (that is, if the RDMCL bit in the MCCTL register = 0), then this routine returns the present value of the modulus down counter; otherwise, this routine returns the contents of the modulus counter load register.

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

ModCounterSetup

void ModCounterSetup( int underflow_irq, int modulus_mode, int read_load_val,

   int enable, int scaler)

Writes to the MCCTL register to configure the modulus down counter according to the five integer input parameters. The modulus counter is associated with the Enhanced Capture Timer (ECT) system. Allowed values for the scaler parameter are 1,4, 8 or 16; the modulus down-counter is clocked at 20 MHz (the E-clock frequency) divided by the specified scaler. The enable flag parameter enables the modulus down counter if true, and disables it if false. If true, the read_load_val flag parameter configures ModCounterRead() to return the contents of the modulus load counter; if read_load_val is false, ModCounterRead() returns the down counter contents. A true modulus_mode flag means that when the counter reaches 0 it is loaded with the latest value written by ModCounterLoad(); if modulus_mode is false, the counter counts down once and stops at 0x0000. If true, the underflow_irq flag enables an interrupt whenever the modulus counter equals 0. After a power-up or hardware reset, the default condition is all flags false and the scaler equal to 1 (this corresponds to the MCCTL register = 0).

Type: kernel function
Forth name: MOD.COUNTER.SETUP
Header file: timerio.h

ModCounterUpdate

void ModCounterUpdate( void )

To force an immediate write of the modulus down counter, execute ModCounterLoad(), then invoke ModCounterUpdate() routine. The modulus counter is associated with the Enhanced Capture Timer (ECT) system; see ModCounterSetup().

Implementation detail: sets the FLMC bit in the MCCTL register.

Type: kernel function
Forth name: MOD.COUNTER.UPDATE
Header file: timerio.h

MODULUS_UNDERFLOW

MODULUS_UNDERFLOW

A channel identification constant associated with the modulus down-counter underflow condition. This constant can be passed to the ECTClearInterruptFlag(), ECTInterruptEnable(), or ECTInterruptDisable() to manipulate the interrupt and/or flag bits associated with the modulus down counter. The modulus counter is associated with the Enhanced Capture Timer (ECT) system; see ModCounterSetup().

Type: macro
Related Forth function: MODULUS.UNDERFLOW
Header file: timerio.h

MsecTimeslicePeriod

void MsecTimeslicePeriod( int num_milliseconds)

Sets num_milliseconds as the period of the timeslice clock (the RTI interrupt) in units of 1.024 milliseconds. For example, to set the timeslice period to just over 5 msec, execute

MsecTimeslicePeriod(5);

The allowed input range is from 1 to decimal 15. Note that the default timeslice increment set after a COLD restart is 1.024 msec.

Implementation detail: Writes to the RTICTL register to configure the time base of the real-time interrupt that is used by the timeslicer. The period of the RTI timer determines the timeslice period and also the resolution of the elapsed time clock (see CountToMsec, ReadElapsedTime and ReadElapsedSeconds).

Type: kernel function
Forth name: MSEC.TIMESLICE.PERIOD
Header file: mtasker.h

NEXT_TASK

NEXT_TASK

A user variable (member of the currently active TASK.USER_AREA structure) that contains the 16-bit TASKBASE address of the next task in the round-robin task list; in other words, NEXT_TASK contains the base address of the next task's user area. Before building all of the tasks in the top level routine of a multitasking application, the command

NEXT_TASK = TASKBASE;

must be executed to empty the round-robin task loop (by making NEXT_TASK point to its own TASKBASE address).

NoAutostart

void NoAutostart( void)

Undoes the effect of the Forth commands PRIORITY.AUTOSTART:, IS.PRIORITY.AUTOSTART, AUTOSTART:, and IS.AUTOSTART, and the C commands IsAutostart and IsPriorityAutostart. Attempts to ensure that the standard QED-Forth interpreter will be entered after subsequent resets. Does not affect startup configurations set by CheckstartEnable or SetBootVector. Implementation detail: Erases the 0x1357 pattern at location 0x0FBFFA in RAM and shadow flash put there by priority autostart, and erases the 0x1357 pattern at location 0x37BFFA in on-chip flash put there by autostart. Note that the RAM-based priority autostart vector cannot be erased if the memory is write-protected (see WriteEnable). NoAutostart is invoked by the special cleanup mode.

Type: kernel function
Forth name: NO.AUTOSTART
Header file: opsystem.h

NoStatusAtStartup

void NoStatusAtStartup( void)

Writes a pattern into EEPROM so that subsequent cold restarts will not print the status startup message. This function can be interactively executed using QED-Forth syntax by typing from the terminal:

NO.STATUS.AT.STARTUP

Type: kernel function
Forth name: NO.STATUS.AT.STARTUP
Header file: opsystem.h

NoVitalIRQInit

void NoVitalIRQInit( void)

Writes a pattern into EEPROM so that subsequent cold restarts will not initialize the COP, clock monitor, illegal opcode, and OC2 interrupt vectors. This option is provided for programmers interested in installing their own interrupt service routines in any of these four vectors. Can be undone by InitVitalIRQsOnCold(). This function can be interactively executed using QED-Forth syntax by typing from the terminal:

NO.VITAL.IRQ.INIT

Type: kernel function
Forth name: NO.VITAL.IRQ.INIT
Header file: opsystem.h

NO_SPACES

NO_SPACES

A 16-bit user variable that contains a flag. If the flag is true (non-zero), leading and trailing spaces are not printed when a floating point number is displayed. If the flag is false (zero), the spaces are printed.

NUMCOLUMNS

uint NUMCOLUMNS( FORTH_ARRAY* array_ptr)

A macro that returns the number of columns 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  number_of_columns;
number_of_columns = NUMCOLUMNS(&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
Header file: array.h

NUMDIMENSIONS

uint NUMDIMENSIONS( FORTH_ARRAY* array_ptr)

A macro that returns the number of dimensions in the Forth array designated by array_ptr. The result is typically 2, because the DIM() macro specifies 2-dimensional arrays. 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  number_of_dimensions;
number_of_dimensions= NUMDIMENSIONS(&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
Header file: array.h

NUMROWS

uint NUMROWS( FORTH_ARRAY* array_ptr)

A macro that returns the number of rows 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  number_of_rows;
number_of_rows = NUMROWS(&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
Header file: array.h

OC7ClearsIt

void OC7ClearsIt( int channel_id )

For the PORTT timer bit specified by channel_id in the range 0 to 7, configures the pin to go low upon a successful output compare on the OC7 (output compare 7) channel. Note that OC7 must be configured separately by passing the parameter 7 to the OutputCompare() function. The specified channel_id must either be configured as an output compare using OutputCompare() (which automatically makes it an output), or explicitly declared as an output pin by writing a 1 to its bit in PORTT_DIRECTION. After a power-up or hardware reset, OC7 is disconnected from the other PORTT pins by default. A successful OC7 compare overrides any other compare action specified for the pin.

Implementation detail: This function sets the bit of the specified channel in the OC7M register and clears the corresponding bit in the OC7D register.

Type: kernel function
Forth name: OC7.CLEARS.IT
Header file: timerio.h

OC7Disconnect

void OC7Disconnect( int channel_id )

For the PORTT timer bit specified by channel_id in the range 0 to 7, undoes the effect of the OC7SetsIt() and OC7ClearsIt() functions, disconnecting the specified pin from an action resulting from a successful compare on output compare 7 (OC7). After a power-up or hardware reset, OC7 is disconnected from the other PORTT pins by default.

Implementation detail: This function clears the bit of the specified channel in the OC7M register.

Type: kernel function
Forth name: OC7.DISCONNECT
Header file: timerio.h

OC7SetsIt

void OC7SetsIt( int channel_id )

For the PORTT timer bit specified by channel_id in the range 0 to 7, configures the pin to go high upon a successful output compare on the OC7 (output compare 7) channel. Note that OC7 must be configured separately by passing the parameter 7 to the OutputCompare() function. The specified channel_id must either be configured as an output compare using OutputCompare() (which automatically makes it an output), or explicitly declared as an output pin by writing a 1 to its bit in PORTT_DIRECTION. After a power-up or hardware reset, OC7 is disconnected from the other PORTT pins by default. A successful OC7 compare overrides any other compare action specified for the pin.

Implementation detail: This function sets the bit of the specified channel in the OC7M register and sets the corresponding bit in the OC7D register.

Type: kernel function
Forth name: OC7.SETS.IT
Header file: timerio.h

OC_CLEAR_ACTION

OC_CLEAR_ACTION

A constant equal to 2 that is passed as an argument to the OCAction() function. Configures the output compare action of the specified PORTT timer pin such that it clears to the zero state when there is a match between the free-running TCNT register and the 16-bit value in the TC register associated with the specified channel_id. See OCAction(), see OCRegWrite(), OCICRegRead(), and TCNTRead(). Note that the specified channel should be declared as an output compare by invoking the OutputCompare() function; see its glossary entry.

Type: macro
Related Forth function: OC.CLEAR.ACTION
Header file: timerio.h

OC_NO_ACTION

OC_NO_ACTION

A constant equal to 0 that is passed as an argument to the OCAction() function. Configures the output compare action of specified the PORTT timer pin to take no action when there is a match between the free-running TCNT register and the 16-bit value in the TC register associated with the specified channel_id. See OCAction(), OCRegWrite(), OCICRegWrite(), and TCNTRead(). Note that the specified channel should be declared as an output compare by invoking the OutputCompare() function; see its glossary entry. The no-action state is the default after a power-up or hardware reset.

Type: macro
Related Forth function: OC.NO.ACTION
Header file: timerio.h

OC_SET_ACTION

OC_SET_ACTION

A constant equal to 3 that is passed as an argument to the OCAction() function. Configures the output compare action of specified the PORTT timer pin to set to the high state when there is a match between the free-running TCNT register and the 16-bit value in the TC register associated with the specified channel_id; see OCAction(), OCRegWrite(), OCICRegRead(), and TCNTRead(). Note that the specified channel should be declared as an output compare by invoking the OutputCompare() function; see its glossary entry.

Type: macro
Related Forth function: OC.SET.ACTION
Header file: timerio.h

OC_TOGGLE_ACTION

OC_TOGGLE_ACTION

A constant equal to 1 that is passed as an argument to the OCAction() function. Configures the output compare action of specified the PORTT timer pin to toggle to the opposite state each there is a match between the free-running TCNT register and the 16-bit value in the TC register associated with the specified channel_id; see OCAction(), OCRegWrite(), OCICRegRead(), and TCNTRead(). Note that the specified channel should be declared as an output compare by invoking the OutputCompare() function; see its glossary entry. Using the toggle action is a simple way to create a 50% duty-cycle square wave on a PORTT output pin with no ongoing processor intervention required: the pin will toggle to the opposite state at the periodicity of the TCNT rollover (104.8ms if the default prescaler of 32 is retained; consult the ECTPrescaler() function to change the rollover period). If the channel is also configured by OCToggleOnOverflow(), variable duty cycles can be synthesized with no ongoing processor intervention by modifying the value in the output compare register TCx; see OCRegWrite().

Type: macro
Related Forth function: OC.TOGGLE.ACTION
Header file: timerio.h

OCAction

void OCAction( int oc_action_id, int channel_id )

Configures the output compare (OC) action of the PORTT timer bit specified by channel_id in the range 0 to 7. The allowed values for the oc_action_id are the constants OC_NO_ACTION (the default after a power-up or hardware reset), OC_TOGGLE_ACTION, OC_CLEAR_ACTION, and OC_SET_ACTION. See the glossary entries for these constants for descriptions of their actions. Briefly, each action constant specifies what happens to the specified PORTT pin when there is a match between the free-running TCNT register and the 16-bit value in the TC register associated with the specified channel_id; see OCRegWrite(), OCICRegRead(), and TCNTRead(). Note that the specified channel should be declared as an output compare by invoking the OutputCompare() function; see its glossary entry.

Implementation detail: OCAction() writes the 2-bit field associated with the specified oc_action_id constant to the specified channel bits in the TCTL1 and TCTL2 registers.

Type: kernel function
Forth name: OC.ACTION
Header file: timerio.h

OCForce

void OCForce( int channel_id )

Forces the action configured by the OCAction() function to occur immediately on the PORTT pin specified by channel_id (0 ≤ channel_id ≤ 7). Note that the specified channel must have been pre-configured by invoking the OutputCompare() and OCAction() functions; consult their glossary entries.

Implementation detail: writes a 1 to the bit of the specified channel in the CFORC register to force the programmed output compare action to occur immediately. Note that a read of the CFORC register always returns 0, as the '1' is transient. Forcing is disabled by default after a power-up or hardware reset.

Type: kernel function
Forth name: OC.FORCE
Header file: timerio.h

OCICRegRead

uint OCICRegRead( int channel_id )

For the specified PORTT timer channel_id in the range 0 to 7, reads and returns the 16-bit contents from the specified output compare/input capture register (TC0 - TC7). This function reads the TCx register of both output compare (OC) and input capture (IC) channels; use the OutputCompare() and InputCapture() functions to configure the channels. Do not use OCICRegRead() to read pulse accumulator channels; see PulseRegRead().

Type: kernel function
Forth name: OC.IC.REG.READ
Header file: timerio.h
Pronunciation: o-c-i-c-reg-read

OCNoToggleOnOverflow

void OCNoToggleOnOverflow( int channel_id )

Configures the PORTT pin specified by channel_id (in the range 0 to 7) to not toggle when the free-running TCNT timer overflows from 0xFFFF to 0x0000. No toggle is the default at power-up or after a hardware reset. Note that the specified channel should be declared as an output compare by invoking the OutputCompare() function; see its glossary entry. This function reverses the effect of OCToggleOnOverflow().

Implementation detail: This function clears the bit of the specified OC channel in the TTOV register.

Type: kernel function
Forth name: OC.NO.TOGGLE.ON.OVERFLOW
Header file: timerio.h

OCRegWrite

void OCRegWrite( uint value, int channel_id )

For the specified PORTT timer channel_id in the range 0 to 7, writes the specified value to the corresponding output compare register (TC0 - TC7). Writes to the TCx registers only have meaning if the channel has been configured as an output compare (OC); consult the OutputCompare() glossary entry. Do not use this function for pulse accumulator channels; see PulseRegWrite().

Type: kernel function
Forth name: OC.REG.WRITE
Header file: timerio.h

OCToggleOnOverflow

void OCToggleOnOverflow( int channel_id )

Configures the PORTT pin specified by channel_id (in the range 0 to 7) to toggle when the free-running TCNT timer overflows from 0xFFFF to 0x0000. Note that the specified channel should be declared as an output compare by invoking the OutputCompare() function; see its glossary entry. This function reverses the effect of OCNoToggleOnOverflow() which is the default at power-up or after a hardware reset. Using the toggle on overflow action is a simple way to create a 50% duty-cycle square wave on a PORTT output pin with no ongoing processor intervention required: the pin will toggle to the opposite state at the periodicity of the TCNT rollover (104.8ms if the default prescaler of 32 is retained; consult the ECTPrescaler() function to change the rollover period). If the channel is also configured by passing OC_TOGGLE_ACTION to OCSetAction(), variable duty cycles can be synthesized with no ongoing processor intervention by modifying the value in the output compare register TCx; see OCRegWrite().

Implementation detail: This function sets the bit of the specified OC channel in the TTOV register.

Type: kernel function
Forth name: OC.TOGGLE.ON.OVERFLOW
Header file: timerio.h

OutputCompare

void OutputCompare( int channel_id )

For the specified channel_id in the range 0 to 7, configures the corresponding bit of the PORTT timer register as an output compare (as opposed to an input capture). An output compare (OC) can trigger an interrupt and/or modify the associated pin’s state when the value of the free-running TCNT counter matches the value in the channel’s timer/counter register TCx (TC0 through TC7). To configure a pin action, pass one of the action constants (OC_NO_ACTION, OC_TOGGLE_ACTION, OC_CLEAR_ACTION, or OC_SET_ACTION) and the specified channel_id to the OCAction() function. Other pin control functions are OCToggleOnOverflow(), OCNoToggleOnOverflow(), OC7SetsIt(), OC7ClearsIt(), and OC7Disconnect(); consult their glossary entries for details. To enable or disable an interrupt, pass the channel_id to ECTInterruptEnable() or ECTInterruptDisable(). Note that, after a power-up or hardware reset, all 8 PORTT pins are configured as input captures by default, with no triggering action.

Implementation detail: This routine sets the bit of the specified channel in the TIOS register.

Type: kernel function
Forth name: OUTPUT.COMPARE
Header file: timerio.h

PAD

PAD

A macro that returns the 16-bit start address of the PAD scratchpad area in the active task's task-private area in common RAM. The 32 bytes below PAD are used for floating point and integer string/number conversion, and the 88 bytes above PAD are available as scratchpad memory for the programmer (Note that the QED-Forth routines ASK.NUMBER, ASK.FNUMBER, INPUT.STRING, and RECEIVE.HEX write text strings into the PAD buffer; however, this should not be a problem for C-programmed applications).

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

PAGE_LATCH

PAGE_LATCH

A constant that returns 0x0030 which is the address of the page latch whose contents indicate the current page. See THIS_PAGE which returns the contents of the 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: constant
Forth name: (PAGE.LATCH)
Header file: types.h

Pause

void Pause( void)

Stacks the state of the current task and passes control to the next AWAKE task in the round-robin task list. You can embed calls to PAUSE in any task when you wish to give other tasks a chance to run. PAUSE may be used in multitasked systems whether or not the timeslicer is active. PAUSE switches tasks in 6 + 0.5n microseconds, where n is the number of ASLEEP tasks encountered in the round robin task list. Interrupts are disabled for most of the task switch time.

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

PauseOnKey

void PauseOnKey( void)

Suspends execution of the calling function when a character is received and, with the exceptions noted below, resumes execution of the calling function when a second character is received. Typically coded into a loop structure to allow control of execution during debugging, or to control a data dump. PauseOnKey() checks whether a character has been received. If no character has been received, it does nothing. If a character has been received and it is a carriage return, executes Abort() which clears the stacks and returns to the QED-Forth interpreter or the autostart routine (if installed). If the character received is a . (dot) executes QUIT which returns to the QED-Forth interpreter without clearing the data stack. If any other character is received, suspends execution until another character other than carriage return or . is received. This function effectively responds to XON/XOFF flow Control-Characters from a host terminal; a function running on the controller that dumps data and calls PauseOnKey() repeatedly will pause when the XOFF is received and resume when XON is received. PauseOnKey() does not know that the XON/XOFF characters are special; it just stops when receiving the first and resumes after the second.

Type: kernel function
Forth name: PAUSE.ON.KEY
Header file: serial.h

PLL_LOCK_ID

PLL_LOCK_ID

A constant that returns the interrupt identity code for the phase-locked-loop (PLL) lock detector. Used as an argument for ATTACH().

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

PORTAD0

PORTAD0

A macro that returns the contents of the 8 bit PORTAD0 digital input register in the 68HCS12, corresponding to hardware lines AD0-7. This port is available to the user as a read-only digital I/O port. The analog input functions associated with this port are supported by a separate device driver library. To read the digital input pins of PORTAD0, store 1’s into the bit locations of each digital input in the PORTAD0_MODE register, and then use the PORTAD0 macro in an expression or as the right hand side of an assignment statement. Note: After a reset or power-up, the PORTAD0 inputs are in analog mode, and can not be read as digital inputs until the corresponding bits are set to 1 by writing to PORTAD0.MODE.

Type: macro
Related Forth function: PORTAD0
Header file: hcs12regs.h

PORTAD0_MODE

PORTAD0_MODE

A macro that returns the contents of the 8 bit PortAD0-digital-input-enable register in the 68HCS12. Writing a 1 to a bit in this port configures the corresponding PORTAD0 signal on the AN0-AN7 lines as a digital input, while writing a 0 configures the corresponding PORTAD0 bit as an analog input. Any bits in PORTAD0 corresponding to 0’s in this port will be read as a digital 1. This port is cleared by a reset or power-up, placing the PORTAD0 inputs in analog mode. Note that enabling digital reads on analog input channels can cause high current draw, as the input pin buffer may operate in linear mode.

Example of use: To use AN0-3 as digital inputs while using AN4-7 as analog inputs, write 0x0F to this port as:

PORTAD0.MODE = 0x0F;

In this example, only the lower 4 bits of the result are valid digital inputs.

Type: macro
Related Forth function: PORTAD0.MODE
Header file: hcs12regs.h

PORTAD1

PORTAD1

A macro that returns the contents of the 8 bit PORTAD1 digital input register in the 68HCS12, corresponding to hardware lines AD8-15. This port is available to the user as a read-only digital I/O port. The analog input functions associated with this port are supported by a separate device driver library. To read the digital input pins of PORTAD1, store 1’s into the bit locations of each digital input in the PORTAD1_MODE register, and then use the PORTAD1 macro in an expression or as the right hand side of an assignment statement. Note: After a reset or power-up, the PORTAD1 inputs are in analog mode, and can not be read as digital inputs until the corresponding bits are set to 1 by writing to PORTAD1.MODE.

Type: macro
Related Forth function: PORTAD1
Header file: hcs12regs.h

PORTAD1_MODE

PORTAD1_MODE

A macro that returns the contents of the 8 bit PortAD1-digital-input-enable register in the 68HCS12. Writing a 1 to a bit in this port configures the corresponding PORTAD1 signal on the AN8-AN15 lines as a digital input, while writing a 0 configures the corresponding PORTAD1 bit as an analog input. Any bits in PORTAD1 corresponding to 0’s in this port will be read as a digital 1. This port is cleared by a reset or power-up, placing the PORTAD1 inputs in analog mode. Note that enabling digital reads on analog input channels can cause high current draw, as the input pin buffer may operate in linear mode.

Example of use: To use AN8-11 as digital inputs while using AN12-15 as analog inputs, write 0x0F to this port as:

PORTAD1.MODE = 0x0F;

In this example, only the lower 4 bits of the result are valid digital inputs.

Type: macro
Related Forth function: PORTAD1.MODE
Header file: hcs12regs.h

PORTH_ID

PORTH_ID

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

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

PORTJ

PORTJ

A macro that returns the contents of the 8 bit PTJ (Port J) digital I/O register in the 68HCS12. To read the digital input pins of PORTJ, simply use the PORTJ macro in an expression or as the right hand side of an assignment statement. To write to the port, PORTJ can be used as the left-hand side of an assignment statement to control the PORTJ pins that have been configured as outputs using the PORTJ_DIRECTION register (see its glossary entry). PORTJ is a synonym for the PTJ register defined in the hcs12regs.h file. On most hardware implementations, only the upper 2 bits (bits 6 and 7) are available: bit6 is SDA.IIC and bit 7 is SCL.IIC. If the IIC bus is not being used, these pins can be used as general purpose I/O with direction controlled by the PORTJ.DIRECTION register. Note that each of these signals is conditioned by a pull-up to +5V and a series resistor. Make sure that you do not change the values of any other PORTJ pins when writing to this port, as the other pins may be dedicated to other hardware functions.

Type: macro
Related Forth function: PORTJ
Header file: hcs12regs.h

PORTJ_DIRECTION

PORTJ_DIRECTION

A macro that returns the contents of the 8 bit DDRJ (Data Direction Register J) direction control register in the 68HCS12. To configure a PORTJ pin to be an output, simply use an assignment statement to write a 1 to the coresponding bit position in PORTJ_DIRECTION. To configure a PORTJ pin to be an input, write a 0 to the corresponding bit position in PORTJ_DIRECTION. PORTJ_DIRECTION is a synonym for DDRJ in the hcs12regs.h file. On most hardware implementations, only the upper 2 bits (bits 6 and 7) are available: bit6 is SDA.IIC and bit 7 is SCL.IIC. If the IIC bus is not being used, these pins can be used as general purpose I/O with direction controlled by the PORTJ.DIRECTION register. Note that each of these signals is conditioned by a pull-up to +5V and a series resistor. Make sure that you do not change the values of any other PORTJ pins when writing to this port, as the other pins may be dedicated to other hardware functions.

Type: macro
Related Forth function: PORTJ.DIRECTION
Header file: hcs12regs.h

PORTJ_ID

PORTJ_ID

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

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

PORTM

PORTM

A macro that returns the contents of the 8 bit PTM (Port M) digital I/O register in the 68HCS12. To read the digital input pins of PORTM, simply use the PORTM macro in an expression or as the right hand side of an assignment statement. To write to the port, PORTM can be used as the left-hand side of an assignment statement to control the PORTM pins that have been configured as outputs using the PORTM_DIRECTION register (see its glossary entry). PORTM is a synonym for the PTM register defined in the hcs12regs.h file.

Type: macro
Related Forth function: PORTM
Header file: hcs12regs.h

PORTM_DIRECTION

PORTM_DIRECTION

A macro that returns the contents of the 8 bit DDRM (Data Direction Register M) direction control register in the 68HCS12. To configure a PORTM pin to be an output, simply use an assignment statement to write a 1 to the coresponding bit position in PORTM_DIRECTION. To configure a PORTM pin to be an input, write a 0 to the corresponding bit position in PORTM_DIRECTION. PORTM_DIRECTION is a synonym for DDRM in the hcs12regs.h file.

Type: macro
Related Forth function: PORTM.DIRECTION
Header file: hcs12regs.h

PORTP

PORTP

A macro that returns the contents of the 8 bit PTP (Port P) digital I/O register in the 68HCS12. To read the digital input pins of PORTP, simply use the PORTP macro in an expression or as the right hand side of an assignment statement. To write to the port, PORTP can be used as the left-hand side of an assignment statement to control the PORTP pins that have been configured as outputs using the PORTP_DIRECTION register (see its glossary entry). PORTP is a synonym for the PTP register defined in the hcs12regs.h file. PortP pins also implement the processor’s PWM (pulse width modulation) outputs.

Type: macro
Related Forth function: PORTP
Header file: hcs12regs.h

PORTP_DIRECTION

PORTP_DIRECTION

A macro that returns the contents of the 8 bit DDRP (Data Direction Register P) direction control register in the 68HCS12. To configure a PORTP pin to be an output, simply use an assignment statement to write a 1 to the coresponding bit position in PORTP_DIRECTION. To configure a PORTP pin to be an input, write a 0 to the corresponding bit position in PORTP_DIRECTION. PORTP_DIRECTION is a synonym for DDRP in the hcs12regs.h file. PortP pins also implement the processor’s PWM (pulse width modulation) outputs.

Type: macro
Related Forth function: PORTP.DIRECTION
Header file: hcs12regs.h

PORTP_ID

PORTP_ID

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

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

PORTP_IN

PORTP_IN

Returns the contents of the 8-bit PTIP input register of the PWM (pulse-width modulation) and general purpose digital I/O PortP in the 68HCS12 whose direction is controlled by the PORTP_DIRECTION register. For any pins that have been configured as outputs by writing a 1 to the corresponding bit position in PORTP_DIRECTION, a read of the associated PORTP register (see its glossary entry) returns the last value written to PORTP, not the actual signal level on the pin. If the pin is under the control of the PWM subsystem, reads of the PORTP register can be misleading, and this PORTP_IN register should be read instead to ascertain the actual logic level at the pin.

Type: macro
Related Forth function: PORTP.IN
Header file: hcs12regs.h

PORTT

PORTT

A macro that returns the contents of the 8 bit PTT (Port T) digital I/O register in the 68HCS12. To read the digital input pins of PORTT, simply use the PORTT macro in an expression or as the right hand side of an assignment statement. To write to the port, PORTT can be used as the left-hand side of an assignment statement to control the PORTT pins that have been configured as outputs using the PORTT_DIRECTION register (see its glossary entry). PORTT is a synonym for the PTT register defined in the hcs12regs.h file. PortT pins also implement the processor’s ECT (Enhanced Coutput/Timer) capabilities.

Type: macro
Related Forth function: PORTT
Header file: hcs12regs.h

PORTT_DIRECTION

PORTT_DIRECTION

A macro that returns the contents of the 8 bit DDRT (Data Direction Register T) direction control register in the 68HCS12. To configure a PORTT pin to be an output, simply use an assignment statement to write a 1 to the coresponding bit position in PORTT_DIRECTION. To configure a PORTP pin to be an input, write a 0 to the corresponding bit position in PORTT_DIRECTION. PORTT_DIRECTION is a synonym for DDRT in the hcs12regs.h file. PortT pins also implement the processor’s ECT (Enhanced Coutput/Timer) capabilities.

Type: macro
Related Forth function: PORTT.DIRECTION
Header file: hcs12regs.h

PORTT_IN

PORTT_IN

Returns the contents of the 8-bit PTIT input register of the ECT (Enhanced Capture Timer) and general purpose digital I/O PortT in the 68HCS12 whose direction is controlled by the PORTT_DIRECTION register. For any pins that have been configured as outputs by writing a 1 to the corresponding bit position in PORTT_DIRECTION, a read of the associated PORTT register returns the last value written to PORTT, not the actual signal level on the pin. If the pin is under the control of the ECT (Enhanced Capture Timer) subsystem, reads of the PORTT register can be misleading, and this PORTT_IN register should be read instead to ascertain the actual logic level at the pin.

Type: macro
Related Forth function: PORTT.IN
Header file: hcs12regs.h

PrintFP

void PrintFP( float ansi_fp_num)

Displays the specified floating point number using the format specified by the most recent execution of FIXED(), SCIENTIFIC(), or FLOATING(). FLOATING format is the default after a COLD restart. If the specified format is FIXED() and if the ansi_fp_num does not fit in the allowed number of LEFT_PLACES and RIGHT_PLACES, PrintFP() prints the string won'tfit. See the glossary entry for FPtoString() for a detailed description of the FIXED(), SCIENTIFIC() and FLOATING() formats.

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

PULSE_A

PULSE_A

A constant equal to 0x100 used to identify the PULSE_A 16-bit accumulator on PORTT pin 7. This constant is used as an input parameter to PulseRegRead() and PulseRegWrite(). The PULSE_A accumulator is configured by the PulseASetup() function. When PULSE_A is in use, the associated 8-bit pulse accumulators 2 (forming the least significant byte of PULSE_A) and 3 (forming the most significant byte of PULSE_A) on PORTT pins 2 and 3 are not available.

PULSE_A_EDGE

PULSE_A_EDGE

A constant channel identifier that can be passed to ECTClearInterruptFlag(), ECTInterruptEnable(), or ECTInterruptDisable() to manipulate the interrupt and/or flag bits associated with the PULSE_A 16-bit accumulator edge detector. The PULSE_A accumulator is part of the Enhanced Capture Timer (ECT) system and is available on pin 7 of PORTT.

PULSE_A_EDGE_ID

PULSE_A_EDGE_ID

A constant that returns the interrupt identity code for the 16-bit pulse accumulator A input edge detector on pin 7 of PORTT. Used as an argument for ATTACH().

Type: constant
Related Forth function: PULSE.A.EDGE.ID
Header file: interrupt.h

PULSE_A_FALLING_EDGE

PULSE_A_FALLING_EDGE

A constant that identifies the desired trigger edge for the 16-bit PULSE_A pulse accumulator as a falling edge present on PORTT pin 7. The pulse accumulator is incremented each time the qualifying edge occurs. This constant can be passed as the pulse_mode parameter to the PulseASetup() function (see its glossary entry). This constant must not be used as an argument to the TriggerEdge() function.

Type: macro
Related Forth function: PULSE.A.FALLING.EDGE
Header file: timerio.h

PULSE_A_GATED_HIGH

PULSE_A_GATED_HIGH

A constant that identifies the operational mode for the 16-bit PULSE_A pulse accumulator on PORTT pin 7. The pulse accumulator is incremented by a constant-period clock every 3.2 microseconds (= 64 * E-clock-period) whenever a high (gating) signal is present at the input pin. This constant can be passed as the pulse_mode parameter to the PulseASetup() function (see its glossary entry). This constant must not be used as an argument to the TriggerEdge() function.

Type: macro
Related Forth function: PULSE.A.GATED.HIGH
Header file: timerio.h

PULSE_A_GATED_LOW

PULSE_A_GATED_LOW

A constant that identifies the operational mode for the 16-bit PULSE_A pulse accumulator on PORTT pin 7. The pulse accumulator is incremented by a constant-period clock every 3.2 microseconds (= 64 * E-clock-period) whenever a low (gating) signal is present at the input pin. This constant can be passed as the pulse_mode parameter to the PulseASetup() function (see its glossary entry). This constant must not be used as an argument to the TriggerEdge() function.

Type: macro
Related Forth function: PULSE.A.GATED.LOW
Header file: timerio.h

PULSE_A_OVERFLOW

PULSE_A_OVERFLOW

A constant channel identifier that can be passed to ECTClearInterruptFlag(), ECTInterruptEnable(), or ECTInterruptDisable() to manipulate the interrupt and/or flag bits associated with the PULSE_A 16-bit accumulator overflow detector (from 0xFFFF to 0x0000). The PULSE_A accumulator is part of the Enhanced Capture Timer (ECT) system on the HCS12 processor.

PULSE_A_OVERFLOW_ID

PULSE_A_OVERFLOW_ID

A constant that returns the interrupt identity code for the pulse accumulator channel A overflow detector. Used as an argument for ATTACH().

Type: constant
Related Forth function: PULSE.A.OVERFLOW.ID
Header file: interrupt.h

PULSE_A_RISING_EDGE

PULSE_A_RISING_EDGE

A constant that identifies the desired trigger edge for the 16-bit PULSE_A pulse accumulator as a rising edge present on PORTT pin 7. The pulse accumulator is incremented each time the qualifying edge occurs. This constant can be passed as the pulse_mode parameter to the PulseASetup() function (see its glossary entry). This constant must not be used as an argument to the TriggerEdge() function.

Type: macro
Related Forth function: PULSE.A.RISING.EDGE
Header file: timerio.h

PULSE_B

PULSE_B

A constant equal to 0x101 used to identify the PULSE_B 16-bit accumulator on PORTT pin 0. This constant is used as an input parameter to PulseRegRead() and PulseRegWrite(). The PULSE_B accumulator is configured by the PulseBSetup() function. When PULSE_B is in use, the associated 8-bit pulse accumulators 0 (forming the least significant byte of PULSE_B) and 1 (forming the most significant byte of PULSE_B) on PORTT pins 0 and 1 are not available.

PULSE_B_OVERFLOW

PULSE_B_OVERFLOW

A constant channel identifier that can be passed to ECTClearInterruptFlag(), ECTInterruptEnable(), or ECTInterruptDisable() to manipulate the interrupt and/or flag bits associated with the PULSE_B 16-bit accumulator overflow detector (from 0xFFFF to 0x0000). The PULSE_B accumulator is part of the Enhanced Capture Timer (ECT) system on the HCS12 processor.

PULSE_B_OVERFLOW_ID

PULSE_B_OVERFLOW_ID

A constant that returns the interrupt identity code for the pulse accumulator channel B overflow detector. Used as an argument for ATTACH().

Type: constant
Related Forth function: PULSE.B.OVERFLOW.ID
Header file: interrupt.h

PulseASetup

void PulseASetup( int edge_irq, int overflow_irq, int pulse_mode, int pulse16_enable)

This function writes to the PACTL register to configure the 16-bit PULSE.A pulse accumulator on pin 7 of PORTT. Each input parameter is a flag. If the pulse16_enable flag is true, the 16-bit PULSE_A pulse accumulator on pin 7 of PORTT is enabled. If the pulse16_enable flag is false, then PULSE_A is disabled and the two component 8-bit pulse accumulators PA2 (forming the least significant byte of PULSE_A) and PA3 (forming the most significant byte of PULSE_A) on PORTT pins 2 and 3 are available. The pulse_mode input parameter is one of the following four constants: PULSE_A_FALLING_EDGE, PULSE_A_RISING_EDGE, PULSE_A_GATED_HIGH, or PULSE_A_GATED_LOW; consult their glossary entries. The former 2 modes increment the accumulator on the specified edge, while the latter modes enable the ECLK/64 clock to increment the pulse count every 3.2 microseconds while the input is in the specified gating state. If the overflow_irq flag is true, an interrupt occurs every time the pulse accumulator overflows from 0xFFFF to 0x0000. If the edge_irq flag is true, an interrupt is generated upon each qualifying input edge as configured by the pulse_mode parameter. The default state after a power-up or hardware reset is interrupts disabled and the 16-bit PULSE_A accumulator disabled.

Implementation note: To operate PULSE_A accumulator independently of the input capture/output compare channel IC7/OC7, set IOS7=1 in TIOS and set OM7=OL7= 0 in TCTL1/2 to disconnect the timer from pin PT7. You can accomplish this by executing:

OutputCompare(7);
OCAction(OC_NO_ACTION, 7);

Also, it is highly recommended that TCNT is maintained as a free-running counter that cannot be stopped. This implies that bits CLK1 and CLK0 bits in the PACTL register be kept equal to zero, the TEN (timer enable) bit in TSCR1 = 1 (set at warm/cold); and the TCRE (timer counter reset enable) bit in TSCR2 = 0 (cleared at warm/cold). The kernel drivers follow this rule; specifically, the TCSR1 and TSCR2 registers are properly initialized at startup, and the PulseASetup() function which writes to the PACTL register keeps these two bits zeroed. Writing other values to these bits may make it impossible to use TCNT for general purpose software timing by the application program. Note that none of the kernel functions relies on TCNT for software timing; rather, the multitasking operating system uses the RTI (real-time interrupt) as a time base.

Type: kernel function
Forth name: PULSE.A.SETUP
Header file: timerio.h

PulseBSetup

void PulseBSetup( int overflow_irq, int pulse16_enable )

This function writes to the PBCTL register to configure the 16-bit PULSE_B pulse accumulator on pin 0 of PORTT. If the pulse16_enable parameter is true (non-zero), the 16-bit PULSE_B pulse accumulator on pin 0 of PORTT is enabled. If the pulse16_enable flag is false, then PULSE_B is disabled and the two component 8-bit pulse accumulators PA0 (forming the least significant byte of PULSE_B) and PA1 (forming the most significant byte of PULSE_B) on PORTT pins 0 and 1 are available. If the overflow_irq parameter is true (non-zero), an interrupt occurs every time the pulse accumulator overflows from 0xFFFF to 0x0000. 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. For example, to count rising-edge pulses without generating interrupts, execute:

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

The PULSE_B 16-bit accumulator and its interrupt are disabled by default after a power-up or hardware reset.

Type: kernel function
Forth name: PULSE.B.SETUP
Header file: timerio.h

PulseDisable

void PulseDisable( int pulse8_channel_id )

Disables the 8-bit pulse accumulator specified by channel_id in the range 0 to 3 on corresponding bits 0 to 3 of the PORTT timer port.

Implementation detail: Clears the specified bit in the ICPAR register. Pulse accumulators are disabled by default after a power-up or harddware reset.

Type: kernel function
Forth name: PULSE.DISABLE
Header file: timerio.h

PulseEnable

void PulseEnable( int pulse8_channel_id )

Enables the 8-bit pulse accumulator specified by channel_id in the range 0 to 3 on corresponding bits 0 to 3 of the PORTT timer port. Do not pass PULSE_A or PULSE_B as a channel_id input parameter to this function; rather, use PulseASetup() and PulseBSetup() to configure the 16-bit accumulators. For all 8-bit pulse accumulators, the associated pins should be configured as input captures by leaving the pin in the default input capture state after a reset, or by invoking the InputCapture() function. The pulse accumulator trigger edge is configured using TriggerEdge(), and the pulse accumulator channel is enabled using the PulseEnable() function; consult their glossary entries. Use channel_id = 0 to 3 for the 8 bit accumulators PA0 through PA. See PulseASetup() and PulseBSetup() for more details regarding the 16-bit pulse accumulators.

Example of use: To configure the 8-bit pulse accumulator 1 on PORTT pin 1 to count rising edges, execute:

TriggerEdge(TRIGGER_ON_RISING_EDGE,  1 );
InputCapture(1);
PulseEnable(1);

Implementation detail: Sets the specified bit in the ICPAR register. Pulse accumulators are disabled by default after a power-up or hardware reset.

Type: kernel function
Forth name: PULSE.ENABLE
Header file: timerio.h

PulseHoldingRead

int PulseHoldingRead( int channel_id )

For the specified pulse accumulator channel_id in the range 0 to 3, reads and returns the value from the corresponding 8-bit pulse accumulator holding register PA0H, PA1H, PA2H, or PA3H. The channel_id cannot be PULSE_A or PULSE_B, as these do not have holding registers. The specified channel must be configured as an input capture (as opposed to an output compare) by leaving the pin in the default input capture state after a reset, or by invoking the InputCapture() function. The pulse accumulator trigger edge is configured using TriggerEdge(), and the pulse accumulator channel is enabled using the PulseEnable() function; consult the PulseEnable() glossary entry for an example. See the glossary entries for ICPulseConfig() for more information about the IC and pulse accumulator holding registers. Briefly, if the latch_mode flag passed to ICPulseConfig() is true, then the input capture register contents are latched into the holding register when the modulus counter equals zero, or when the HoldingRegForceLatch() function is invoked. If the latch_mode flag passed to ICPulseConfig() is false, then the captures are in “queued mode”, and the holding registers are loaded from the associated pulse accumulator register upon each read of the holding register. Do not use this function for input capture holding registers; consult the glossary entry for ICHoldingRead().

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

PulseRegRead

uint PulseRegRead( int channel_id )

For the specified pulse accumulator channel_id, reads and returns the value from the corresponding 8-bit or 16-bit pulse accumulator count register (or register pair) PACN0-3. The channel_id can be the numeric value 0, 1, 2, or 3 to identify the 8-bit accumulators, or PULSE_A or PULSE_B to identify the 16-bit pulse accumulators. See the glossary entries for PulseEnable(), ICPulseConfig(), PulseASetup(), and PulseBSetup() for details on how to configure the pulse accumulators. To access the holding registers, see PulseHoldingRead(). Do not use this function for input capture or output compare channels; consult the glossary entry for OCICRegRead().

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

PulseRegWrite

void PulseRegWrite( uint value, int channel_id )

For the specified pulse accumulator channel_id, writes the specified value to the corresponding 8-bit or 16-bit pulse accumulator count register (or register pair) PACN0-3. The channel_id can be the numeric value 0, 1, 2, or 3 to identify the 8-bit accumulators, or PULSE_A or PULSE_B to identify the 16-bit pulse accumulators. See the glossary entries for PulseEnable(), ICPulseConfig(), PulseASetup(), and PulseBSetup() for details on how to configure the pulse accumulators. Do not use this function for output compare channels; consult the glossary entry for OCRegWrite().

Type: kernel function
Forth name: PULSE.REG.WRITE
Header file: timerio.h

PWM01

PWM01

A 16-bit constant that returns the channel_id representing a concatenated PWM (pulse width modulated) channel. This channel_id can be passed as a parameter to many of the PWM configuration functions. While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution. The 16-bit PWM01 channel combines 8-bit PWM channels PWM0 and PWM1, and is present on PORTP pin 1. See the glossary entries for PWMConcatenate() and PWMSetup() to configure a concatenated channel. For the PWM01 channel_id, the second (numerically higher) channel mentioned in the name (channel 1) is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel. For example, if you execute

PWMConcatenate(PWM01);

then the 16-bit PWM output is available on PORTP pin 1, the control register bits associated with PWM1 configure the output, and all 16-bit configuration quantities use the associated PWM0 register as the most significant byte, and the associated PWM1 register as the least significant byte. The associated 8-bit PWM channels 0 and 1 are not available when the PWM01 channel is in use. PWM01 uses the PWM_CLOCKA or scaled PWM_CLOCKA clock source.

Type: macro
Related Forth function: PWM01
Header file: pwm.h

PWM23

PWM23

A 16-bit constant that returns the channel_id representing a concatenated PWM (pulse width modulated) channel. This channel_id can be passed as a parameter to many of the PWM configuration functions. While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution. The 16-bit PWM23 channel combines 8-bit PWM channels PWM2 and PWM3, and is present on PORTP pin 3. See the glossary entries for PWMConcatenate() and PWMSetup() to configure a concatenated channel. For the PWM23 channel_id, the second (numerically higher) channel mentioned in the name (channel 3) is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel. For example, if you execute

PWMConcatenate(PWM23);

then the 16-bit PWM output is available on PORTP pin 3, the control register bits associated with PWM3 configure the output, and all 16-bit configuration quantities use the associated PWM2 register as the most significant byte, and the associated PWM3 register as the least significant byte. The associated 8-bit PWM channels 2 and 3 are not available when the PWM23 channel is in use. PWM23 uses the PWM_CLOCKB or scaled PWM_CLOCKB clock source.

Type: macro
Related Forth function: PWM23
Header file: pwm.h

PWM45

PWM45

A 16-bit constant that returns the channel_id representing a concatenated PWM (pulse-width modulated) channel. This channel_id can be passed as a parameter to many of the PWM configuration functions. While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution. The 16-bit PWM45 channel combines 8-bit PWM channels PWM4 and PWM5, and is present on PORTP pin 5. See the glossary entries for PWMConcatenate() and PWMSetup() to configure a concatenated channel. For the PWM45 channel_id, the second (numerically higher) channel mentioned in the name (channel 5) is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel. For example, if you execute

PWMConcatenate(PWM45);

then the 16-bit PWM output is available on PORTP pin 5, the control register bits associated with PWM5 configure the output, and all 16-bit configuration quantities use the associated PWM4 register as the most significant byte, and the associated PWM5 register as the least significant byte. The associated 8-bit PWM channels 4 and 5 are not available when the PWM45 channel is in use. PWM45 uses the PWM_CLOCKA or scaled PWM_CLOCKA clock source.

Type: macro
Related Forth function: PWM45
Header file: pwm.h

PWM67

PWM67

A 16-bit constant that returns the channel_id representing a concatenated PWM (pulse-width modulated) channel. This channel_id can be passed as a parameter to many of the PWM configuration functions. While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution. The 16-bit PWM23 channel combines 8-bit PWM channels PWM6 and PWM7, and is present on PORTP pin 7. See the glossary entries for PWMConcatenate() and PWMSetup() to configure a concatenated channel. For the PWM67 channel_id, the second (numerically higher) channel mentioned in the name (channel 7) is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel. For example, if you execute

PWMConcatenate(PWM67);

then the 16-bit PWM output is available on PORTP pin 7, the control register bits associated with PWM7 configure the output, and all 16-bit configuration quantities use the associated PWM6 register as the most significant byte, and the associated PWM7register as the least significant byte. The associated 8-bit PWM channels 6 and 7 are not available when the PWM67 channel is in use. PWM67 uses the PWM_CLOCKB or scaled PWM_CLOCKB clock source.

Type: macro
Related Forth function: PWM67
Header file: pwm.h

PWM_CLOCKA

PWM_CLOCKA

A constant clock identifier (clock_id) that is passed to the PWMScaler() or PWMPrescaler() functions to identify the CLOCKA clock source; consult the glossary entries of these functions. 8-bit PWM (pulse-width modulated) channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM_CLOCKA or a scaled version of PWM_CLOCKA.

See also PWMScaledClock() and PWMUnscaledClock()

Type: macro
Related Forth function: PWM.CLOCKA
Header file: pwm.h

PWM_CLOCKB

PWM_CLOCKB

A constant clock identifier (clock_id) that is passed to PWMScaler() or PWMPrescaler() functions to identify the CLOCKB clock source; consult the glossary entries of these functions. 8-bit PWM (pulse-width modulated) channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM_CLOCKB or a scaled version of PWM_CLOCKB.

See also PWMScaledClock() and PWMUnscaledClock()

Type: macro
Related Forth function: PWM.CLOCKB
Header file: pwm.h

PWM_SHUTDOWN_ID

PWM_SHUTDOWN_ID

A constant that returns the interrupt identity code for the pulse width modulator (PWM) shutdown detector. Used as an argument for ATTACH().

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

PWMActiveHigh

void PWMActiveHigh( int channel_id )

Configures the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id to start in the active high state. Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals. For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero. This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s). In each case, when the counter value matches the duty value, the output changes state. Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Implementation detail: Writes a 1 to the bit of the specified channel in the PWMPOL register. After a power-up or hardware reset, the contents of PWMPOL is zero, causing the PWM outputs to be active low by default.

Type: kernel function
Forth name: PWM.ACTIVE.HIGH
Header file: pwm.h

PWMActiveLow

void PWMActiveLow( int channel_id )

Configures the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id to start in the active low state. Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals. For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero. This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s). In each case, when the counter value matches the duty value, the output changes state. Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Implementation detail: Writes a 0 to the bit of the specified channel in the PWMPOL register. After a power-up or hardware reset, the contents of PWMPOL is zero, causing the PWM outputs to be active low by default.

Type: kernel function
Forth name: PWM.ACTIVE.LOW
Header file: pwm.h

PWMCenterAlign

void PWMCenterAlign( int channel_id )

Configures the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id to to be center aligned (as opposed to left aligned). Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. Center alignment causes the output period to be double the value set by PWMPeriodWrite(), for the following reason. For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals. For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero. This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s). In each case, when the counter value matches the duty value, the output changes state. Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Implementation detail: Writes a 1 to the bit of the specified channel in the PWMCAE register. After a power-up or hardware reset, the contents of PWMCAE is zero and the signals are left aligned.

Type: kernel function
Forth name: PWM.CENTER.ALIGN
Header file: pwm.h

PWMConcatenate

void PWMConcatenate( int channel_id )

Creates a 16-bit PWM (pulse-width modulated) channel by concatenating two 8-bit PWM channels. Valid channel_id input parameters are PWM01 (combines PWM0 and PWM1, present on PORTP pin 1); PWM23 (combines PWM2 and PWM3, present on PORTP pin 3); PWM45 (combines PWM4 and PWM5, present on PORTP pin 5); and PWM67 (combines PWM6 and PWM7, present on PORTP pin 7). You can also use PWMSetup() to create a concatenated channel; see its glossary entry. To undo the effect of PWMConcatenate(), use PWMSeparate(). While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.

Note: Make sure that both PWM channels associated with the concatenation are disabled before calling this routine. If the relevant channels are active, they can be disabled using PWMDisable() or PWMDisableMultiple().

Implementation detail: This function sets the relevant bit in the PWMCTL register to create a concatenated 16bit PWM channel. After a power-up or hardware reset, the contents of PWMCTL equal zero and the signals are separated (not concatenated). For each channel_id, the second (numerically higher) channel mentioned in the name is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel. For example, if you execute

PWM01 PWM.CONCATENATE

Type: kernel function
Forth name: PWM.CONCATENATE
Header file: pwm.h

PWMCounterRead

uint PWMCounterRead( int channel_id )

Returns the contents of the specified PWM (pulse-width modulated) counter register. Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. This function returns an 8-bit count if the specified channel is a single PWM channel, and returns a 16-bit value if the channel_id specifies a concatenated channel. For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals. For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero. This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s). In each case, when the counter value matches the duty value, the output changes state. Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Type: kernel function
Forth name: PWM.COUNTER.READ
Header file: pwm.h

PWMCounterWrite

void PWMCounterWrite( uint value, int channel_id )

Resets the specified PWM (pulse-width modulated) counter register to zero. Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. This function stores an 8-bit count if the specified channel is a single PWM channel, and stores a 16-bit value if the channel_id specifies a concatenated channel. However, writing any value to the counter resets its value to zero and the value written is lost.

When a counter register is written with any value, the following events happen: the counter is reset to zero; the counter direction is set to up; the duty and period registers are loaded from buffers; and the output is set according to polarity bit.

For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals. For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero. This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s). In each case, when the counter value matches the duty value, the output changes state. Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Type: kernel function
Forth name: PWM.COUNTER.WRITE
Header file: pwm.h

PWMDisable

void PWMDisable( int channel_id )

Disables the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id. Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. If a concatenated channel_id is passed to this function, both associated 8-bit PWM channels are disabled.

PWMDisableMultiple

void PWMDisableMultiple( int bitmask )

Expects an 8-bit bitmask input parameter (promoted to a 16-bit int), where bit0 corresponds to PWM0, bit 1 corresponds to PWM1, and bit7 corresponds to PWM7. For each 1 bit in the input bitmask, this function clears the specified bits in the PWME register to disable the corresponding PWM (pulse-width modulated) channels. Channels associated with 0 bits in the bitmask are not modified. This function is useful for simultaneously disabling a number of PWM channels. For concatenated channels, it is typically best to disable both subsidiary PWM channels, but note that only the bit corresponding to the numerically higher member of the pair has an effect on the concatenated pair.

PWMDutyRead

uint PWMDutyRead( int channel_id )

Returns the contents of the specified PWM (pulse-width modulated) duty register. Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. This function returns an 8-bit duty value if the specified channel is a single PWM channel, and returns a 16-bit duty value if the channel_id specifies a concatenated channel. When the counter value matches the duty value, the output changes state. See PWMActiveHigh() and PWMActiveLow() to configure the starting polarity of the PWM output. For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals. For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero. This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s). Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Type: kernel function
Forth name: PWM.DUTY.READ
Header file: pwm.h

PWMDutyWrite

void PWMDutyWrite( uint value, int channel_id )

Writes the specified value to the specified PWM (pulse-width modulated) duty register. Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. This function writes an 8-bit duty value if the specified channel is a single PWM channel, and writes a 16-bit duty value if the channel_id specifies a concatenated channel. When the counter value matches the duty value, the output changes state. See PWMActiveHigh() and PWMActiveLow() to configure the starting polarity of the PWM output. For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals. For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero. This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s). Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Type: kernel function
Forth name: PWM.DUTY.WRITE
Header file: pwm.h

PWMEnable

void PWMEnable( int channel_id )

Enables the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id. Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. See PWMDisable() and PWMSetup(); the latter’s glossary entry describes a set of useful PWM configuration utiltities and provides an example of use. To enable multiple channels at once, use PWMEnableMultiple().

Implementation detail: Sets the relevant bit(s) in the PWME register. If a concatenated channel_id is passed to this function, only the numerically higher bit in the PWME register is set, as this controls the concatenated channel. After a power-up or hardware reset, the PWM channels are disabled by default.

Type: kernel function
Forth name: PWM.ENABLE
Header file: pwm.h

PWMEnableMultiple

void PWMEnableMultiple( int bitmask )

Expects an 8-bit bitmask input parameter (promoted to a 16-bit int), where bit0 corresponds to PWM0, bit 1 corresponds to PWM1, and bit7 corresponds to PWM7. For each 1 bit in the input bitmask, this function sets the specified bits in the PWME register to enable the corresponding PWM (pulse-width modulated) channels. Channels associated with 0 bits in the bitmask are not modified. For concatenated channels, note that only the bit corresponding to the numerically higher member of the pair has an effect on the concatenated pair. This function is useful for simultaneously enabling a number of PWM channels. See PWMDisableMultiple() and PWMSetup(); the latter’s glossary entry describes a set of useful PWM configuration utiltities and provides a code example. To enable a single PWM channel identified by its channel_id, use PWMEnable().

Implementation detail: Sets the specified bit(s) in the PWME register. After a power-up or hardware reset, the PWM channels are disabled by default.

Type: kernel function
Forth name: PWM.ENABLE.MULTIPLE
Header file: pwm.h

PWMLeftAlign

void PWMLeftAlign( int channel_id )

Configures the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id to to be left aligned (as opposed to center aligned). Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals. For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero. This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s). In each case, when the counter value matches the duty value, the output changes state. Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Implementation detail: Clears the bit of the specified channel in the PWMCAE register. After a power-up or hardware reset, the contents of PWMCAE is zero and the signals are left aligned.

Type: kernel function
Forth name: PWM.LEFT.ALIGN
Header file: pwm.h

PWMPeriodRead

uint PWMPeriodRead( int channel_id )

Returns the contents of the specified PWM (pulse-width modulated) period register. Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. This function returns an 8-bit period if the specified channel is a single PWM channel, and returns a 16-bit period value if the channel_id specifies a concatenated channel. For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals. For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero. This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s). In each case, when the counter value matches the duty value, the output changes state. Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Type: kernel function
Forth name: PWM.PERIOD.READ
Header file: pwm.h

PWMPeriodWrite

void PWMPeriodWrite( uint value, int channel_id )

Writes the specified value to the specified PWM (pulse-width modulated) period register. Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. This function writes an 8-bit period value if the specified channel is a single PWM channel, and writes a 16-bit period value if the channel_id specifies a concatenated channel. For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals. For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero. This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s). In each case, when the counter value matches the duty value, the output changes state. Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Type: kernel function
Forth name: PWM.PERIOD.WRITE
Header file: pwm.h

PWMPrescaler

void PWMPrescaler( int clock_id, int prescaler )

Sets the specified prescale factor for the clock specified by clock_id = PWM_CLOCKA or PWM_CLOCKB (see the PWM_CLOCKA and PWM_CLOCKB glossary entries). The prescaler factor is applied to both the scaled and unscaled versions of the specified clock in the PWM (pulse-width modulated) subsystem. Allowed values of the prescaler factor are : 1, 2, 4, 8, 16, 32, 64, and 128. The fundamental clock is the bus clock E, running at 20MHz, and the frequency is reduced (the period is increased) by the prescaler factor to create the specified PWM_CLOCKA or PWM_CLOCKB. For a slower clock, use the scaled clock source for a given PWM channel; consult the glossary entries for PWMScaler(), PWMScaledClock(), and PWMUnscaledClock(). 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM_CLOCKA or a scaled version of PWM_CLOCKA. 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM_CLOCKB or a scaled version of PWM_CLOCKB.

Example of use: The bus clock (E clock) has a period of 0.05 microseconds (us). To configure PWM_CLOCKA to have a period of 1.6 us, and PWM_CLOCKB to have a period of 6.4 us, execute:

PWMPrescaler(PWM_CLOCKA, 32);  // clockA period = 1.6us
PWMPrescaler(PWM_CLOCKB, 128);  // clockB period = 6.4us

As stated above, each PWM channel can also use the slower scaled clocks; see PWMScaledClock().

Type: kernel function
Forth name: PWM.PRESCALER
Header file: pwm.h

PWMScaledClock

void PWMScaledClock( int channel_id )

Configures the specified PWM (pulse-width modulated) channel to use the slower (longer period) scaled clock source. Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.

The 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM_CLOCKA or a scaled version of PWM_CLOCKA. If this routine is called for channel_id 0, 1, 4, 5, PWM01, or PWM45, that channel will use the scaled PWM_CLOCKA (SA).

The 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM_CLOCKB or a scaled version of PWM_CLOCKB. If this routine is called for channel_id 2, 3, 6, 7 PWM23, or PWM67, that channel will use scaled PWM_CLOCKB (SB).

The period of the unscaled PWM_CLOCKA is equal to the E-clock period (0.05 us) multiplied by a prescaler set by PWMPrescaler(). Allowed values of the prescaler are 1, 2, 4, 8, 16, 32, 64, and 128. The period of the scaled version of PWM_CLOCKA is equal to the unscaled PWM_CLOCKA period times the scaler set by PWMScaler(), where the scaler can be any even integer between 2 and 512.

The clock B sources are exactly parallel, and have their own unique prescaler and scaler values as set by PWMPrescaler() and PWMScaler().

Note that the default scale factor for the scaled PWM_CLOCKA and scaled PWM_CLOCKB clocks after a power-up or hardware reset is 512.

Example of use: The bus clock (E clock) has a period of 0.05 microseconds (us). To configure PWM channel 0 to have a 1.6 us clock (unscaled PWM_CLOCKA), PWM channel 1 to have a 64 us clock (scaled PWM_CLOCKA), PWM channel 2 to have a 6.4 us clock (unscaled PWM_CLOCKB), and PWM channels 3 and PWM67 to have a 512 us clock (scaled PWM_CLOCKB), execute:

// first set the clock periods…
PWMPrescaler(PWM_CLOCKA, 32);   // clockA period = 1.6us
PWMScaler(PWM_CLOCKA, 40);      // scaled clockA = 40 * 1.6 = 64us
PWMPrescaler(PWM_CLOCKB, 128);  // clockB period = 6.4us
PWMScaler(PWM_CLOCKB, 80);      // scaled clockB = 80 * 6.4 = 512us
PWMUnscaledClock(0);            // pwm0 uses clockA @ 1.6us
PWMScaledClock(1);              // pwm1 uses SA @ 64us
PWMUnscaledClock(2);            // pwm2 uses clockB @ 6.4us
PWMScaledClock(3);              // pwm3 uses SB @ 512us
PWMScaledClock(PWM67);          // PWM67 uses SB @ 512us

Implementation detail: Sets the bit corresponding to the specified PWM channel in the PWMCLK register to select the scaled (slower) clock source. To undo the effect of this function see PWMUnscaledClock().

Type: kernel function
Forth name: PWM.SCALED.CLOCK
Header file: pwm.h

PWMScaler

void PWMScaler( int clock_id, int scaler )

Sets the specified scaler (2 ≤ scaler ≤ 512, scaler is even) as the scale factor for the clock specified by clock_id PWM_CLOCKA or PWM_CLOCKB (see the PWM_CLOCKA and PWM_CLOCKB glossary entries). The fundamental clock is the bus clock E, running at 20MHz, and its frequency is reduced (the period is increased) by the prescale factor to create the two unscaled PWM clocks. The prescale factor set by PWMPrescaler() (see its glossary entry) is applied to both the scaled and unscaled versions of the specified clock. This PWMScaler() function applies a second scale factor to create a longer-period scaled PWM_CLOCKA (SA) and/or scaled PWM_CLOCKB (SB). Allowed values of the scaler are even integers in the range 2 to 512. For a slower clock, use the scaled clock source for a given PWM channel; consult the glossary entries for PWMPrescaler(), PWMScaledClock(), and PWUnscaledClock(). 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM_CLOCKA or a scaled version of PWM_CLOCKA (SA). 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM_CLOCKB or a scaled version of PWM_CLOCKB (SB). See the glossary entry for PWMScaledClock() for an example of use.

Implementation detail: If clock_id = PWM_CLOCKA, this routine writes to the PWMSCLA register. If clock_id = PWM_CLOCKB, this routine writes to the PWMSCLB register. Note that a value of 0 in the register corresponds to a scale factor of 512; this is the default scale factor for the scaled PWM_CLOCKA and scaled PWM_CLOCKB clocks after a power-up or hardware reset.

Type: kernel function
Forth name: PWM.SCALER
Header file: pwm.h

PWMSeparate

void PWMSeparate( int channel_id )

Undoes the concatenation of a 16-bit PWM (pulse-width modulated) channel to yield two 8-bit PWM channels. Valid channel_id input parameters are PWM01 (combines PWM0 and PWM1, present on PORTP pin 1); PWM23 (combines PWM2 and PWM3, present on PORTP pin 3); PWM45 (combines PWM4 and PWM5, present on PORTP pin 5); and PWM67 (combines PWM6 and PWM7, present on PORTP pin 7). You can also use PWMSetup() to configure a PWM channel; see its glossary entry. To undo the effect of PWMSeparate(), use PWMConcatenate(). While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.

Note: Make sure that both of the PWM channels associated with the concatenation are disabled before calling this routine. If the relevant channels are active, they can be disabled using PWMDisable() or PWMDisableMultiple().

Implementation detail: This function clears the relevant bit in the PWMCTL register. After a power-up or hardware reset, the contents of PWMCTL equal zero and the signals are separated (not concatenated). For each channel_id, the second (numerically higher) channel mentioned in the name is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel.

Type: kernel function
Forth name: PWM.SEPARATE
Header file: pwm.h

PWMSetup

void PWMSetup( int active_high, int scaled_clock, int centered, int period, int duty, int channel_id )

This function specifies the characteristics of a specified PWM channel.

While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.

If the PWM channel is enabled when this routine is invoked, the channel is disabled during configuration to prevent anomalous transient behavior. Then the specified parameters are written to the registers, and the specified PWM channel’s enable bit is restored to the state it was in before this routine was called.

channel_id – Valid channel_id parameters for 8-bit PWM (pulse width modulated) channels are in the range 0 to 7, and the PWM output is on the corresponding PORTP pins. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher PORTP channel pin mentioned in each named constant.
active_high – If the active_high flag is true, the signal is configured to start in the (active) high state; see PWMActiveHigh(). If active_high is false (the default after a hardware reset), the signal is configured to start in the (active) low state; see PWMActiveLow().
scaled_clock – If the scaled_clock flag is true, the channel is configured to use the (slower, longer-period) scaled clock; see PWMScaledClock(). If the scaled_clock flag is false (the default after a hardware reset), the channel is configured to use the unscaled clock; see PWMUnscaledClock(). 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM_CLOCKA or a scaled version of PWM_CLOCKA. 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM_CLOCKB or a scaled version of PWM_CLOCKB; see the glossary entries for PWMPrescaler() and PWMScaler().
centered – If the centered flag input parameter is true, the PWM channel is configured to be center aligned; see PWMCenterAligned(). If the centered flag is false (the default after a hardware reset), the PWM channel is configured to be left-aligned; see PWMLeftAligned(). For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals. For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero. This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s). In each case, when the counter value matches the duty value, the output changes state.
period – This function’s period input parameter is passed to the PWMPeriodWrite() function which stores the parameter into the period register (if the channel_id is an 8-bit PWM) or register pair (if the channel_id is a 16-bit PWM). Recall that the actual period will be double the specified period if the centered flag is true.
duty – This functions’s duty input parameter is passed to the PWMDutyWrite() function which stores the parameter into the duty register (if the channel_id is an 8-bit PWM) or register pair (if the channel_id is a 16-bit PWM).

Example of use:

The clock(s) should be configured before the specified channels are enabled. Typically, clocks are configured using the PWMPrescaler() and PWMScaler() functions, then PWMSetup() is called for each channel or channel pair, and then PWMEnable() or PWMEnableMultiple() is called to start the PWM signal(s).

For example, assume we want to simultaneously enable the two 8-bit channels PWM0 and PWM1. Both are to be left aligned active high signals. PWM0 is to have a 40% duty cycle with a 16 microsecond (us) period. PWM1 is to have a 60% duty cycle with a 640 us period. Since both PWM0 and PWM1 use the A clocks (unscaled or scaled PWM_CLOCKA), we must first configure these to facilitate the design. We’ll use the unscaled PWM_CLOCKA as the source for channel PWM0, and the scaled PWM_CLOCKA source for channel PWM1. The fundamental clock source is the E-clock with a period of 0.05 microseconds (us). Referring to the example in the glossary entry of PWMScaledClock(), we choose a prescaler of 32, resulting in an unscaled period of 1.6 us for PWM_CLOCKA; this sets the minimum time resolution of a PWM channel using this clock at 1.6 microseconds. For the slower PWM1 channel, we use the scaled PWM_CLOCKA (SA) with a period of 64 us. We’ll specify the period of each channel as 10 counts; thus the PWM0 period is 10 * 1.6us = 16 us, and the PWM1 period is 10 * 6.4us = 64 us, as desired. The required duty cycle of PWM0 is 40%, so we specify a duty parameter of 4 (4/10 = 40%). The required duty cycle of PWM1 is 60%, so we specify a duty parameter of 6 (4/10 = 60%). Finally, to simultaneously enable the two PWM channels we note that the bitmask for the combination of channels 0 and 1 equals decimal 3; that is, a bitmask with bits 0 and 1 set has a value of 3, and this is the parameter we will pass to PWMEnableMultiple() to simultaneously enable PWM0 and PWM1 after PWMSetup() has executed. We assume that this example starts after a power-up or hardware reset, with all of the PWM channels initially disabled. Here is the code that fulfills the requirements of this example:

// first set the clock periods…
PWMPrescaler(PWM_CLOCKA, 32);  // clockA period = 1.6us
PWMScaler(PWM_CLOCKA, 40);     // scaled clockA = 40 * 1.6 = 64us
PWMUnscaledClock(0);           // pwm0 uses clockA @ 1.6us
PWMScaledClock(1);             // pwm1 uses SA @ 64us
// now call PWMSetup() for PWM0, the next comment line recaps the prototype:
// PWMSetup( active_high, scaled_clock, centered, period, duty, channel_id )
PWMSetup(TRUE, FALSE, FALSE, 10, 4, 0);   // setup but don’t enable PWM0
// now call PWMSetup() for PWM1, the next comment line recaps the prototype:
// PWMSetup( active_high, scaled_clock, centered, period, duty, channel_id )
PWMSetup(TRUE, TRUE, FALSE, 10, 6, 1);   // setup but don’t enable PWM1
PWMEnableMultiple(3);        // simultaneously enable PWM0 and PWM1

This glossary entry and example show how the PWM control functions work together to facilitate the configuration of pulse-width modulated signals.

Type: kernel function
Forth name: PWM.SETUP
Header file: pwm.h

PWMUnscaledClock

void PWMUnscaledClock( int channel_id )

Configures the specified PWM (pulse-width modulated) channel to use the faster (shorter period) unscaled clock source.

Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.

The 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM_CLOCKA or a scaled version of PWM_CLOCKA (SA). The 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM_CLOCKB or a scaled version of PWM_CLOCKB (SB).

If this PWMUnscaledClock() routine is called for channel_id 0, 1, 4, 5, PWM01, or PWM45, that channel will use the unscaled PWM_CLOCKA. If this routine is called for channel_id 2, 3, 6, 7 PWM23, or PWM67, that channel will use unscaled PWM_CLOCKB.

The period of the unscaled PWM_CLOCKA is equal to the E-clock period (0.05 us) multiplied by a prescaler set by PWMPrescaler(); allowed values of the prescaler are 1, 2, 4, 8, 16, 32, 64, and 128. The period of the scaled version of PWM_CLOCKA is equal to the unscaled PWM_CLOCKA period times the scaler set by PWMScaler(), where the scaler can be any even integer between 2 and 512.

The clock B sources are exactly parallel, and have their own unique prescaler and scaler values as set by PWMPrescaler() and PWMScaler().

See PWMScaledClock() for an example of use.

Type: kernel function
Forth name: PWM.UNSCALED.CLOCK
Header file: pwm.h

Random

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

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.

RandomGaussian

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

ReadElapsedSeconds

ulong ReadElapsedSeconds( void)

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

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

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

ReadWatch

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.

RECEIVE

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.

Receive

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

ReceiveBinary

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

ReceiveHex

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

RELEASE

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.

Release

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

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;

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.AFTER.LINE
Header file: mtasker.h

RELEASE_ALWAYS

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.

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;

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

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.

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;

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

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

ResizeHandle

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

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

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

Room

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

RS485Init

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

RS485Receive

void RS485Receive( int id)

RS485Transmit

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

RS485TransmitDone

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.

RTI_ID

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

SCI0_ID

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

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

SCIENTIFIC

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

SEG_ARRAY_ADDR

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_BASE_ADDR

SEG_ARRAY_BASE_ADDR

A constant that specifies the base address of the segment array in EEPROM. See SEG_ARRAY_ADDR(). This low-level macro is typically not used by the programmer.

Type: macro
Header file: segments.h

SEG_ARRAY_ENTRY

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

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

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

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

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

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

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

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

SEND

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 TRY_TO_SEND(), RECEIVE() and MAILBOX

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

Send

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

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

Serial1AtStartup

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

SERIAL1_RESOURCE

A constant that returns the address of the 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.

Serial2AtStartup

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

SERIAL2_RESOURCE

A constant that returns the address of the 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.

SERIAL_ACCESS

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;

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

SetBits

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

SetBootVector

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

SetWatch

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.

SIZEOFMEMBER

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

SmartIOFetchChar

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

SmartIOFetchFloat

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

SmartIOFetchInt

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

SmartIOFetchLong

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

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: constant
Related Forth function: SPI0.ID
Header file: interrupt.h

SPI1_ID

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: constant
Related Forth function: SPI1.ID
Header file: interrupt.h

SPI2_ID

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: constant
Related Forth function: SPI2.ID
Header file: interrupt.h

SPI_FALLING_LEADING_EDGE

SPI_FALLING_LEADING_EDGE

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

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_RESOURCE

SPI_RESOURCE

A constant that returns the address of the 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 invoked by the battery-backed real-time clock device driver routines.

SPI_RISING_LEADING_EDGE

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

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

SPIConfig

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() and InitIPSPI() are called upon each reset and restart; 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 are reserved for interprocessor communications, and 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 SPI channel 0 that samples data on the SPI_RISING_TRAILING_EDGE of a clock that idles high, and can run at up to 4 MHz SPI clock frequencies. Using SPI.FREQUENCIES, we note that the fastest attainable baud rate under 4 MHz is 3.33 MHz, corresponding to an spibr_contents parameter of 0x20. 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, 0x20, 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

SPIExchange

void SPIExchange( uint base_addr, uint base_page, 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 on base_page, numbytes number of bytes (0 ≤ numbytes < 32,768). The buffer must not cross a page boundary. 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). Of course, if the readback flag is true, the buffer at xaddr must be in RAM. This routine does not GET or RELEASE the SPI_RESOURCE, nor does it modify the configuration of the specified SPI 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: kernel function
Forth name: SPI.EXCHANGE
Header file: serial.h

SPIFrequencies

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

SPIRestore

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

SPISave

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 the resource 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 4 MHz. Using SPI.FREQUENCIES or SPIFrequencies() (see its glossary entry), we note that the fastest attainable baud rate under 4 MHz is 3.33 MHz, corresponding to an spibr_contents parameter of 0x20. 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, 0x20, 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

StandardReset

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

StartTimeslicer

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.

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

STATUS

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

StatusAtStartup

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

StopTimeslicer

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 TIMESLICE_COUNT, CountToMsec() and ReadElapsedSeconds().

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

StoreChar

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

StoreEEChar

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

StoreEEFloat

void StoreEEFloat( float value, int * 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

StoreEEInt

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

StoreEELong

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

StoreFloat

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

StoreFloatProtected

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.

StoreInt

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

StoreLong

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

StoreLongProtected

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

StorePages

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 LoadPages and LoadPagesAtStartup, and the entries for STORE.PAGES, LOAD.PAGES and LOAD.PAGES.AT.STARTUP in the interactive debugger glossary section.

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

StringMove

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

SWAPARRAYS

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

SwapArrays

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

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

SysAbort

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

TASK

A structure typedef that names and allocates a 1 Kbyte TASK structure in common RAM. 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.

TASKBASE

TASKBASE

A pointer to the current task's TASK structure which holds the task's USER_AREA structure and its task-private stacks and buffers. The USER_AREA is a structure defined in the user.h file that contains task-private operating system pointers and variables. Each task in a multitasking application has a unique 1 Kbyte TASK area named and allocated by the TASK statement, and the multitasker periodically updates the contents of UP (the User Pointer) to point to the current user area. TASKBASE is a macro defined as:

((TASK *) *UP)

In other words, TASKBASE returns the contents of UP, and TASKBASE is cast as a pointer to the TASK structure. 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: macro
Related Forth function: STATUS
Header file: user.h

TCNT_OVERFLOW

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

TCNTRead

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

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

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. If Forth is not running in a given task and if high-level Forth serial I/O routines such as EXPECT, QUERY and INTERPRET are not being executed, a C application may use the TIB as a task-private buffer.

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

TIMESLICE_COUNT

TIMESLICE_COUNT

Returns the 32-bit count of the number of clock ticks on the timeslicer clock. 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). To determine the elapsed time between two events in units of ms, simply subtract the corresponding counts and multiply by the number of milliseconds per count.

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

Type: macro
Related Forth function: TIMESLICE.COUNT
Header file: mtasker.h

ToEEPROM

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

ToFlash

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

ToFlashMany

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

ToggleBits

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

ToHeap

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

ToIO

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

ToIORegister

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.

ToMemory

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

ToXFlash

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

TO_XADDR

xaddr TO_XADDR( uint 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

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

TransferHeapItem

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

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

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

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

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

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

TriggerEdge

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

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

TRUE

A constant equal to 1.

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

TryToFSend

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

TryToGet

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.

TryToSend

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

TRY_TO_FSEND

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

TRY_TO_GET

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

TRY_TO_SEND

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

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

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

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.

UDEBUG

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

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.

UERROR

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

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.

UP

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.

UPAD

UPAD

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

USER_AREA

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

UseSerial1

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

UseSerial2

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

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

Version

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

WaitTilMatch

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

Warm

void Warm( void)

Restarts the QED-Forth system, initializes key hardware registers (as listed in the Cold glossary entry), and clears the data and return stacks and executes Abort(). Unlike Cold(), Warm() does not initialize all of the user variables to their default values. 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.

WATCH_DATE

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

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

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

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

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

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

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.

WATCH_SECONDS

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

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

WriteEnable

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

WriteProtect

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

XaddrDifference

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

XADDR_TO_ADDR

uint XADDR_TO_ADDR( xaddr xaddress)

This C macro converts the specified 32-bit extended address into its constituent 16-bit address.

Type: macro
Header file: types.h

XADDR_TO_PAGE

int XADDR_TO_PAGE( xaddr xaddress)

This C macro converts the specified 32-bit extended address into its constituent page.

Type: macro
Header file: types.h

XIRQ_ID

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