C Function Glossary (A-H)
C language functions available for programming the 9S12/HCS12
on the PDQ Board using the Mosaic IDE Plus

Software development in C uses the Codeblocks-based Mosaic IDE Plus Integrated Development Environment. The IDE Plus provides a full-featured text editor, a GNU C (GCC) compiler, and customized terminal program for rapid code downloads and interactive debugging sessions with the 9S12 (HCS12) processor on the controller board. The Mosaic IDE Plus software development environment is ideal for programming embedded systems with real time operating systems (RTOS). You use it to program the PDQ Board, a low cost single board computer. Functions are provided to control all hardware systems of the board's Freescale 9S12 HCS12 68HCS12 MC9S12 MCU.

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

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

Listed functions are alphabetized in the following order. You can click on the following characters to be taken directly to the glossary entries starting with that character, or you can search this and other glossary pages using your browser's search command:

(this page) Page A-H:
Page I-Q:
Page R-Z:

_ 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

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

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)(), TASK* task_base_addr)

Sets up action 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. task_base_addr must be located in common memory, and ACTIVATE must be called in a function located in the same source code file in which action is defined.

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.

See also TASK, BUILD_C_TASK(), and KillTask()

Type: macro
Related Forth function: Activate()
Header file: mtasker.h

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.

It is recommended to use the ACTIVATE() macro in the same C source code file in which action is defined, instead of calling Activate() directly.

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

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 must be called in a function in the same source code file as the interrupt handler routine, and after calling MAKE_ISR. 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( xaddr action, int interrupt_id)

Posts an interrupt handler routine located at the extended memory address action for the interrupt with identity number interrupt_id (for example, SWI_ID, etc). Attach() compiles a code sequence at the EEPROM location associated with the specified interrupt. When the interrupt is serviced, the code specified by the extended address 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.

It is recommended to use the MAKE_ISR and ATTACH macros to post interrupt service routines instead of calling Attach directly.

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, starting at the specified taskbase address in common RAM. The TASK declaration is normally 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 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 a new struct medium_taskArea. BUILD_C_TASK() first calls IsHeap() which initializes the heap accordingly. BUILD_C_TASK() then initializes the task's struct userArea and task buffers in the area starting at the task's base address. The struct userArea of the parent task (i.e., the task that is active when this command executes) is copied to create the new task's struct userArea, so the parent's configuration is initially inherited by the new task.

If declared with TASK, the memory map of the new task is set so that the return stack extends downward for 1024 bytes at taskbase + 1536, the TIB (serial terminal input buffer) extends upwards for 96 bytes starting at taskbase + 512, the Forth data stack extends downward for up to 128 bytes at taskbase + 512, POCKET extends upwards for 32 bytes starting at taskbase + 384, PAD (scratchpad area) extends upward for 128 bytes and downward for 33 bytes starting at taskbase + 256. The newlib C runtime library uses a structure called struct _reent that occupies the area above the top of the return stack through taskbase + 2048.

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 eep, xaddr dp, xaddr np, xaddr tib, xaddr pad, xaddr pocket, xaddr r0, xaddr s0, xaddr taskBase, int userSize )

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

CALC_CHECKSUM

CALC_CHECKSUM( PTR, NUMBYTES )

Calculates a 16-bit checksum for the buffer specified by PTR and NUMBYTES, where PTR is a pointer of any type to common memory and NUMBYTES is even and 0 ≤ NUMBYTES < 65,534. This is a macro which calls CalcChecksum(), but allows a C pointer to common memory to be directly passed as a parameter (most commonly a C array or pointer to struct). See its glossary entry below.

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

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: memory.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: memory.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 )

Important: The specifed max_count must be four bytes less than the available space at xlstring, to account for:

Two-byte count at the beginning of the buffer;
Null byte written beyond the end of the resulting string; and
A known bug involving two-byte eol values; see below.

A QED-Forth “long string” contains a 2-byte count followed by the string contents. Cat() 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 any count), and updates the 16-bit count located in the first 2 bytes at xlstring. The available long string buffer starting at xlstring must be 4 bytes larger than the specified max_count to allow for the 2-byte count, the terminating null byte, and an extra byte that may be written due to a known bug (see below). 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 (unnecessary with Cat() since a null character is always added anyway).

If the long string resulting from concatenating xstring_to_add to the existing contents of xlstring would be longer than max_count, the result is truncated to max_count bytes plus the terminating null character.

Known Bug: If the length of the resulting string after appending xstring_to_add is equal to max_count, no eol bytes are written. However, if the resulting string is at least one byte shorter than max_count, the eol sequence is written, regardless of whether it is one or two bytes. In the case where one byte is available and eol is two bytes, both bytes will be written, and the stored count at the beginning of xlstring will be incremented to one more than max_count.

The terminating null byte is appended to the resulting long string regardless of whether or not there is room for it according to max_count, and is not included in the count at the beginning of xlstring.

NOTE: If assembling a long string from scratch, remember to zero the first 2 bytes (16-bit count) of xlstring before the first call to this routine.

CHANGE_BITS

CHANGE_BITS( DATA, MASK, PTR )

At the byte in common RAM specified by the 16-bit PTR, modifies the bits specified by 1's in MASK to have the values indicated by the corresponding bits in DATA. This is a macro which calls ChangeBits(), but allows a C pointer to common memory to be directly passed as the address parameter (most commonly a pointer to an IO port or configuration flag byte). See its glossary entry below.

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

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

ChangeTaskerPeriod

The deprecated ChangeTaskerPeriod has been superceded by MsecTimeslicePeriod().

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

CLEAR_BITS

CLEAR_BITS( MASK, PTR )

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

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

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 ColdOnReset() 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 InitElapsedTime(), 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, INIT_DEFAULT_HEAP(), and IsHeap()

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, INIT_DEFAULT_HEAP(), and IsHeap()

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

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

DUMP( PTR, NUMBYTES )

Displays the contents of NUMBYTES bytes starting at the specified PTR. This is a macro which calls Dump(), but allows a C pointer to common memory to be directly passed as the address parameter (most commonly a C array or pointer to struct). See its glossary entry below.

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

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

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, Emit2() 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

EXTRA_TASK

A task area declaration equivalent to TASK, but which places the task area in the otherwise-unused 2K area of common RAM at 0x800-0xFFF on the full PDQ Board (not the Lite version). Only one task area may be defined with EXTRA_TASK, and note that if you are using the Ethersmart Wildcard or WiFi Wildcard, the functions Ether_C_Task_Setup() and WiFi_C_Task_Setup() use this area. In general TASK should be used instead instead unless your application has a tight budget for common RAM, or enough tasks that task areas are being placed at or above 0x4000 outside the onchip RAM region, according the generated symbols file for your application. See TASK for more details on task areas.

Type: macro
Header file: user.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. The type argument is ignored (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

FETCH_FLOAT_PROTECTED

FETCH_FLOAT_PROTECTED( PTR )

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

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

FETCH_LONG_PROTECTED

FETCH_LONG_PROTECTED( PTR )

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

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

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

FetchTSCount

ulong FetchTSCount( void )

Fetches the 32-bit value of TIMESLICE_COUNT. Disables interrupts during the fetch to ensure that the value does not increment while the fetch is in process, since the upper and lower 16-bit words are read in two separate operations. Equivalent to FETCH_LONG_PROTECTED( &TIMESLICE_COUNT ) but coded in native C assembly to reduce timing inaccuracies due to the overhead time of calling a Forth kernel function. Disables interrupts for 0.4 microseconds.

Availability: Mosaic IDE Plus revision 1611 and greater
C only
Header file: mtasker.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

FLASH_IPRINTF

FLASH_IPRINTF( name, ... )

Loads a string previously saved to flash memory with SAVE_STRING into the Forth task pad, and then uses it as the format string for an iprintf statement. The first argument to FLASH_IPRINTF is the name that was originally passed to SAVE_STRING when saving the format string to flash, and the remaining arguments are passed as arguments to iprintf.

iprintf may be used instead of printf if there are no floating point arguments to be converted. It executes somewhat faster, and if all calls to printf and snprintf are replaced by calls to iprintf and sniprintf respectively, then the floating point conversion code will not be included in the final program, and this saves two pages of flash memory.

This macro must not be used within a task that uses a small_taskArea, or a custom task area with a pad size smaller than that of a medium_taskArea. The default TASK type is a synonym for medium_taskArea.

For more information on C string formatting functions, see: http://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html

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

FLASH_PRINT

FLASH_PRINT( name )

Loads a string previously saved to flash memory with SAVE_STRING into the Forth task pad, and then calls print( LOADED_STRING ) to send the string to the default serial port.

print executes faster than printf, and if all calls to various forms of printf are replaced with calls to print, then the printf code will not be included in the compiled program, and this saves three pages of flash memory.

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

FLASH_PRINTF

FLASH_PRINTF( name, ... )

Loads a string previously saved to flash memory with SAVE_STRING into the Forth task pad, and then uses it as the format string for a printf statement. The first argument to FLASH_PRINTF is the name that was originally passed to SAVE_STRING when saving the format string to flash, and the remaining arguments are passed as arguments to printf.

For more information on C string formatting functions, see: http://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html

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

FLASH_SNIPRINTF

FLASH_SNIPRINTF( str, size, name, ... )

Loads a string previously saved to flash memory with SAVE_STRING into the Forth task pad, and then uses it as the format string for an sniprintf statement. str is the location in common memory of a buffer to which the output will be written. size is the size of that buffer in bytes. name is the name that was originally passed to SAVE_STRING when saving the format string to flash. The remaining arguments are passed as arguments to sniprintf.

sniprintf may be used instead of snprintf if there are no floating point arguments to be converted. It executes somewhat faster, and if all calls to printf and snprintf are replaced by calls to iprintf and sniprintf respectively, then the floating point conversion code will not be included in the final program, and this saves two pages of flash memory.

For more information on C string formatting functions, see: http://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html

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

FLASH_SNPRINTF

FLASH_SNPRINTF( str, size, name, ... )

Loads a string previously saved to flash memory with SAVE_STRING into the Forth task pad, and then uses it as the format string for an snprintf statement. str is the location in common memory of a buffer to which the output will be written. size is the size of that buffer in bytes. name is the name that was originally passed to SAVE_STRING when saving the format string to flash. The remaining arguments are passed as arguments to snprintf.

For more information on C string formatting functions, see: http://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html

Type: macro
Header file: utility.h

FLOATING

FLOATING( void )

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 my_array with 3 rows and 5 columns, execute:

FORTH_ARRAY my_array;
void my_function( void ) {
    DIM( ulong, 3, 5, &my_array );
    ...

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

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

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

    ulong retrieved_data;
    retrieved_data = ARRAYFETCH( 0, 1, &my_array );

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 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 the MAILBOX located in common RAM at mailboxAddr is empty (ie., if it contains 0.0), executes Pause() until the MAILBOX contains a message. If the MAILBOX located at mailboxAddr contains a message (that is, if it does not contain zero), returns the floating point contents at mailboxAddr and stores 0.0 at 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, FRECEIVE() 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.

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 located in common RAM at mailboxAddr is empty (contains 0.0) and then stores the 32-bit floating point message at 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 at 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

This page is about: Library of C Language Functions for Freescale 9S12 HCS12 68HCS12 MC9S12 Microcontroller Board – Presents detailed glossary descriptions of each library function in the customized C library for the PDQ Board. These C functions are available using the Mosaic IDE Plus, a C language integrated development environment (IDE) and suite of software development tools including the CodeBlocks editor and the GNU-C compiler. These functions run on the PDQ Board, a Freescale 9S12 HCS12 68HCS12 MC9S12 MCU based single board computer.

C Function Glossary (A-H)C language functions available for programming the 9S12/HCS12on the PDQ Board using the Mosaic IDE Plus

_Q

_QV

Abort

ABS

ACTIVATE

Activate

AddXaddrOffset

ARRAYBASE

ArrayBase

ARRAYFETCH

ArrayFetch

ARRAYMEMBER

ArrayMember

ARRAYSIZE

ARRAYSTORE

ArrayStore

AskKey

AskKey1

AskKey2

ASLEEP

ATD0_7_RESULTS

ATD0_ID

ATD1_ID

ATD8_15_RESULTS

ATDDigitalInputs

ATDMultiple

ATDOff

ATDOn

ATDSample

ATDSingle

ATDStartSample

ATTACH

Attach

AWAKE

Baud

Beep

BreakAll

Breakpoint

BUILD_C_TASK

BuildTask

CALC_CHECKSUM

CalcChecksum

CalcChecksumMany

CALENDAR_TIME

Cat

CHANGE_BITS

ChangeBits

ChangeTaskerPeriod

CheckstartDisable

CheckstartEnable

CLEAR_BITS

ClearBits

ClearBootVectors

CLOCK_MONITOR_ID

CmoveMany

CmoveManyCheck

Cold

ColdOnReset

COPYARRAY

CopyArray

COP_ID

CountedString

COUNTER_UNDERFLOW_ID

CountToMsec

Cr

CURRENT_HEAP

CUSTOM_ABORT

CUSTOM_ERROR

DEFAULT_HEAPEND

DEFAULT_HEAPSTART

DELETED

Deleted

DIM

Dimensioned

DISABLE_INTERRUPTS

DisableBootVectors

DLF_APPEND

DLF_APPEND_FILE

DLF_PREPEND

C Function Glossary (A-H)
C language functions available for programming the 9S12/HCS12
on the PDQ Board using the Mosaic IDE Plus