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

The Codeblocks-based Mosaic IDE Plus is a C-language, embedded systems software development environment for programming the PDQ Board, a low cost single board computer. This integrated development environment provides Codeblocks, a full-featured text editor, a GCC GNU C) compiler, and a custom terminal program for interactive debugging and fast code download. The C language functions described here are used for programming all aspects of the board hardware subsystems, including all I/O capability of the Freescale HCS12 9S12 MCU, as well as its real time operating system (RTOS).

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

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

IC_1024_CYCLE_DELAY

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

See also ICNoiseDelay(), IC_DELAY_DISABLED, IC_256_CYCLE_DELAY, and IC_512_CYCLE_DELAY

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

IC_256_CYCLE_DELAY

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

See also ICNoiseDelay(), IC_DELAY_DISABLED, IC_512_CYCLE_DELAY, and IC_1024_CYCLE_DELAY

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

IC_512_CYCLE_DELAY

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

See also ICNoiseDelay(), IC_DELAY_DISABLED, IC_256_CYCLE_DELAY, and IC_1024_CYCLE_DELAY

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

IC_DELAY_DISABLED

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

See also ICNoiseDelay(), IC_256_CYCLE_DELAY, IC_512_CYCLE_DELAY, and IC_1024_CYCLE_DELAY

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

int ICFirstPolarity( void )

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

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

uint ICHoldingRead( int channel_id )

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

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

void ICNoOverwrite( int channel_id )

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

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

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

void ICNoiseDelay( int delay_id )

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

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

void ICOverwriteOK( int channel_id )

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

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

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

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

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

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

IIC_104KHZ_23PERCENT

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

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

IIC_10KHZ_13PERCENT

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

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

IIC_96KHZ_25PERCENT

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

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

IIC_ARB_LOST_ERROR

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

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

IIC_ERROR

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

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

IIC_ID

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

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

IIC_MASTER_RECEIVER

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

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

IIC_NAK_ERROR

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

See also IIC_ERROR

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

IIC_NUM_BYTES_TO_RCV

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

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

IIC_NUM_BYTES_TO_XMIT

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

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

IIC_RCV_BUF_FULL

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

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

IIC_RCV_BUF_OFFSET

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

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

IIC_RCV_BUF_OVERFLOW

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

See also IIC_ERROR

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

IIC_RCV_BUF_PTR

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

* IIC_RCV_BUF_PTR

is equivalent to:

IIC_RCV_BUFFER

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

IIC_RCV_BUF_SIZE

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

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

IIC_RCV_BUFFER

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

IIC_RCV_BUFFER

is equivalent to:

* IIC_RCV_BUF_PTR

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

IIC_TIMEOUT_ERROR

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

See also IIC_ERROR

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

IIC_XMIT_BUF_EMPTY

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

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

IIC_XMIT_BUF_OFFSET

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

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

IIC_XMIT_BUF_OVERFLOW

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

See also IIC_ERROR

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

IIC_XMIT_BUF_PTR

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

* IIC_XMIT_BUF_PTR

is equivalent to:

IIC_XMIT_BUFFER

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

IIC_XMIT_BUF_SIZE

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

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

IIC_XMIT_BUFFER

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

IIC_XMIT_BUFFER

is equivalent to:

* IIC_XMIT_BUF_PTR

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

void IICFrequencies( void )

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

IIC.FREQUENCIES 

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

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

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

void IICInit( int ibfd_contents, int my_slave_address)

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

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

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

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

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

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

IIC_XMIT_BUF_EMPTY      IIC_RCV_BUF_FULL        IIC_ERROR              IIC_XMIT_BUF_OFFSET
IIC_RCV_BUF_OFFSET      IIC_MASTER_RECEIVER     IIC_NUM_BYTES_TO_XMIT  IIC_NUM_BYTES_TO_RCV
IIC_XMIT_BUFFER         IIC_RCV_BUFFER

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

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

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

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

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

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

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

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

See also IICReceive()

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

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

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

See also IICSendFrame and IICSendNextFrame

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

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

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

See also IICSendNextFrame()

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

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

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

See also IICSend() and IICSendFrame()

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

void InitElapsedTime( void)

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

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

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

void InitIPSPI( void)

Initializes SPI channels SPI1 and SPI2.  These SPI channels are used for inter-processor communications on custom parallel-processing systems.  If parallel processing is not required, the SPI1 and SPI2 channels may be used to communicate with other peripherals.  The SPI #2 jumper on the PDQ Board determines which port this routine designates as the master and which as the slave.  If the SPI #2 jumper cap is not installed, then SPI1 is the master and SPI2 is the slave.  If the SPI #2 jumper is installed, then SPI1 is the slave and SPI2 is the master.  The SPI1 and SPI2 clocks idle low, data is sampled/valid on the falling/trailing clock edge, and data is transferred on the rising leading clock edge.  The default baud rate is set to 5 MHz.  This routine is not called upon power-up or restart, and must be explicitly called by application code before calling SPIConfig().

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

void InitSPI( void)

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

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

void InitVitalIRQsOnCold( void)

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

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

INIT_DEFAULT_HEAP( )

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

See also IsHeap(), DEFAULT_HEAPSTART and DEFAULT_HEAPEND

Type: macro
Header file: heap.h

void InputCapture( int channel_id )

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

Pulse accumulator notes: For all pulse accumulators except the 16-bit PULSE_A, the pins associated with a pulse accumulator should be configured as input captures using this routine and the TriggerEdge() routine, and then enabled for pulse counting using the PulseEnable() function (for 8 bit pulse accumulators) or PulseBSetup() function (for 16 bit pulse accumulators).  Use channel_id = 0 to 3 for the 8 bit accumulators PA0 through PA3, and channel_id = 0 (or pass the PULSE_B channel_id constant) for the 16-bit PULSE_B accumulator.  Do not pass PULSE_A as a channel_id input parameter to this InputCapture() function.  See PulseASetup() for more details regarding the 16-bit PULSE_A accumulator.

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

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

void InstallMultitasker( void)

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

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

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

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

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

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

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

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

char IOFetchChar( int offset, int module_num)

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

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

float IOFetchFloat( int offset, int module_num)

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

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

int IOFetchInt( int offset, int module_num)

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

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

long IOFetchLong( int offset, int module_num)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

IRQ_ID

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

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

void IsAutostart( xaddr autostartXaddr)

Compiles a 6-byte sequence at 0xBFFA on page 0x37 in the HCS12 on-chip flash so that upon subsequent restarts and ABORTs, the function having the specified execution address will be automatically executed.  If you select "Set Autostart in download file" in Mosaic IDE Plus menu Project →  Project Compiler Options before compiling, you do not need to include this function call in your code nor enter the corresponding Forth command manually. This allows a finished application to be automatically entered upon power up and resets.  This function is typically executed from the terminal using QED-Forth syntax by typing:

CFA.FOR  MAIN  IS.AUTOSTART

or,

AUTOSTART: MAIN

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

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

void IsHeap( xaddr start, xaddr end)

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

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

See also INIT_DEFAULT_HEAP(), DEFAULT_HEAPSTART, and DEFAULT_HEAPEND

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

void IsPriorityAutostart( xaddr autostartXaddr)

Compiles a 6-byte sequence at 0xBFFA on page 0x0F in the external RAM and corresponding shadow flash memory so that upon subsequent restarts and ABORTs, the function having the specified execution address will be automatically executed.  If you select "Set Autostart in download file" in Mosaic IDE Plus menu Project →  Project Compiler Options before compiling, you do not need to include this function call in your code nor enter the corresponding Forth command manually. This allows a finished application to be automatically entered upon power up and resets.  This function is typically executed from the terminal using QED-Forth syntax by typing:

CFA.FOR MAIN IS.AUTOSTART

or,

AUTOSTART: MAIN

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

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

KERNEL_ARRAY_ADDR

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

Type: macro
Header file: segments.h

KERNEL_ID

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

Type: macro
Header file: segments.h

uchar Key( void)

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

See also Key1(), and Key2()

Type: C function
Related QED-Forth function: KEY
Header file: serial.h

uchar Key1( void)

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

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

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

uchar Key2( void)

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

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

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

void KillTask( TASK* taskBase, uint taskPage)

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

If you are using revision 1231 or later of Mosaic IDE Plus, it is recommended to use the KILLTASK macro instead.

See also TASK and TASKBASE

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

KILLTASK( taskBase )

Puts ASLEEP and removes from the round robin multitasking loop the task whose TASKBASE address is taskBase.  The task to be killed must be installed in the round robin loop when KILLTASK() is called.  If it isn't, or if a task attempts to kill itself, the results are unpredictable.  Aborts if taskBase is not in common RAM. 

See also TASK and TASKBASE

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

A task area declaration similar to TASK but with a return stack that is 1792 bytes, for a total task area of 2816 bytes. In general TASK should be used instead, except in the unlikely situation that your application requires more stack space than is available in a TASK, and you find the return stack is overflowing.

Type: macro
header file: user.h

LEFT_PLACES

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

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

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

LOAD_STRING( name )

Copies a string previously stored with SAVE_STRING into the Forth task pad, so that it may be referenced with LOADED_STRING. If the size of the string exceeds the space available in pad, it will be truncated and terminated with a Null character.

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.

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

LOAD_STRING_TO( name, address, size )

Copies a string literal name previously saved in flash ROM with SAVE_STRING( name ) to the common memory location address up to a maximum of size bytes. Do not pass this macro an address that is outside of common memory, or a size that defines a range that goes beyond the end of common memory. A Null character will always be written to the end of the specified destination memory area, to ensure that any string that is truncated is still terminated.

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

LOADED_STRING

A char* pointer to a string that has been copied into the Forth task pad with LOAD_STRING.

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

void LoadPage( int src_flash_page, int dest_ram_page)

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

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

void LoadPages( int starting_page, int num_pages)

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

See also WriteEnable and LoadPagesAtStartup

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

LoadPages(0, 0x1E);

Memory map summary:

XFlash Pages RAM Pages DEFAULT.MAP Typical Use

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

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

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

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

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

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

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

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

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

See also LoadPages

Memory map summary:

XFlash Pages RAM Pages DEFAULT.MAP Typical Use

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

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

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

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

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

Example of use: Assume that a program has code on pages 0 through 3, and names on pages 0x10 through 0x11, and a PRIORITY.AUTOSTART vector has been installed at the top of page 0x0F.  After the program has been loaded (compiled) into RAM on the board, we can save it to the shadow external flash using these Forth commands typed at the interactive monitor (see the interactive debugger glossary section):

0     4  STORE.PAGES   \ store code pages 0-3 in shadow flash
0x10  2  STORE.PAGES   \ store names pages 10-11 in shadow flash
\ PRIORITY.AUTOSTART already wrote to flash; no need to store page F

We also want to write protect area 1 (pages 0-0xF containing the code) and area 2 (pages 0x10-0x13 containing the names) as follows:

1 WRITE.PROTECT  \ protect pages 0-0xF
2 WRITE.PROTECT  \ protect pages 0x10-0x13

Recall that the shadow flash is not directly readable by the processor as program memory, so we must transfer the needed pages from external flash to RAM at startup.  The following commands accomplish this:

0     4  1 LOAD.PAGES.AT.STARTUP   \ load code pages 0-3 to RAM
0x10  2  2 LOAD.PAGES.AT.STARTUP   \ load names pages 0x10-11 to RAM
0xF   1  3 LOAD.PAGES.AT.STARTUP   \ load page containing priority autostart

CAUTION: This routine disables interrupts while programming the EEPROM.  Be sure to schedule the use of this routine so that it does not interfere with any interrupt-based runtime procedures.

Type: kernel function
Forth name: LOAD.PAGES.AT.STARTUP
Header file: opsystem.h

MAILBOX

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

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

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

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

MAKE_ISR( function )

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

Example of use:

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

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

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

See also ATTACH()

Type: macro
Header file: compiler_util_macros.h

MANTISSA_PLACES

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

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

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

MAX( num1, num2)

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

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

Type: macro
Header file: utility.h

void MicrosecDelay( uint numMicroseconds)

Enters a software timing loop for u microseconds.  Note that the elapsed time will be increased by the duration of any interrupt routines that are serviced while MICROSEC.DELAY is running.  Consequently, this routine does not guarantee accurate timing when the timesliced multitasker is running. In revisions of Mosaic IDE Plus prior to 1611, this is a wrapper for a Forth kernel function, with an overhead calling time of approximately six microseconds. In revisions of Mosaic IDE Plus 1611 and later, MicrosecDelay is a C assembly-coded function with an overhead calling time of 0.55 microseconds if a numeric literal argument is given, and 0.6 microseconds if a variable argument is given.

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

MIN( num1, num2)

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

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

Type: macro
Header file: utility.h

void ModCounterLoad( uint value )

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

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

uint ModCounterRead( void )

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

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

void ModCounterSetup( int underflow_irq, int modulus_mode, int read_load_val, int enable, int scaler)

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

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

void ModCounterUpdate( void )

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

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

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

MODULUS_UNDERFLOW

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

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

void MsecTimeslicePeriod( int num_milliseconds)

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

MsecTimeslicePeriod(5); 

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

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

(Note that there is a similar function in the v4.xx kernel called ChangeTaskerPeriod that sets the period in increments of 100 microseconds).

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

NEXT_TASK

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

NEXT_TASK = TASKBASE;

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

See also TASK and TASKBASE

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

void NoAutostart( void)

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

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

void NoStatusAtStartup( void)

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

NO.STATUS.AT.STARTUP

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

void NoVitalIRQInit( void)

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

NO.VITAL.IRQ.INIT

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

NO_SPACES

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

See also FPtoString() and PrintFP()

Type: macro
Related Forth function: NO.SPACES
Header file: numbers.h

uint NUMCOLUMNS( FORTH_ARRAY* array_ptr)

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

Example of use:

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

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

See also DIM()

Type: macro
Header file: array.h

uint NUMDIMENSIONS( FORTH_ARRAY* array_ptr)

A macro that returns the number of dimensions in the Forth array designated by array_ptr.  The result is typically 2, because the DIM() macro specifies 2-dimensional arrays.  An unpredictable result is returned if the array is not dimensioned.

Example of use:

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

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

See also DIM()

Type: macro
Header file: array.h

uint NUMROWS( FORTH_ARRAY* array_ptr)

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

Example of use:

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

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

See also DIM()

Type: macro
Header file: array.h

void OC7ClearsIt( int channel_id )

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

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

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

void OC7Disconnect( int channel_id )

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

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

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

void OC7SetsIt( int channel_id )

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

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

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

OC_CLEAR_ACTION

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

See also OC_NO_ACTION, OC_TOGGLE_ACTION, and OC_SET_ACTION

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

OC_NO_ACTION

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

See also OC_TOGGLE_ACTION, OC_CLEAR_ACTION, and OC_SET_ACTION

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

OC_SET_ACTION

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

See also OC_NO_ACTION, OC_TOGGLE_ACTION, and OC_CLEAR_ACTION

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

OC_TOGGLE_ACTION

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

See also OC_NO_ACTION, OC_SET_ACTION, and OC_CLEAR_ACTION

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

void OCAction( int oc_action_id, int channel_id )

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

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

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

void OCForce( int channel_id )

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

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

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

uint OCICRegRead( int channel_id )

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

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

void OCNoToggleOnOverflow( int channel_id )

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

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

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

void OCRegWrite( uint value, int channel_id )

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

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

void OCToggleOnOverflow( int channel_id )

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

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

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

void OutputCompare( int channel_id )

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

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

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

PAD

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

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

PAGE_LATCH

A constant that returns 0x0030 which is the address of the page latch whose contents indicate the current page.  See THIS_PAGE which returns the contents of the PAGE_LATCH.  In general, the PAGE_LATCH may be read but not written to by application programs; only routines that are located in common memory (addresses below 0x8000 or above 0xBFFF) are allowed to write to the PAGE_LATCH.

Type: constant
Forth name: (PAGE.LATCH)
Header file: types.h

void Pause( void)

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

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

void PauseOnKey( void)

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

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

PLL_LOCK_ID

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

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

PORTAD0

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

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

PORTAD0_MODE

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

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

PORTAD0.MODE = 0x0F;

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

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

PORTAD1

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

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

PORTAD1_MODE

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

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

PORTAD1.MODE = 0x0F;

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

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

PORTH_ID

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

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

PORTJ

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

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

PORTJ_DIRECTION

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

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

PORTJ_ID

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

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

PORTM

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

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

PORTM_DIRECTION

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

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

PORTP

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

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

PORTP_DIRECTION

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

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

PORTP_ID

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

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

PORTP_IN

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

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

PORTT

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

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

PORTT_DIRECTION

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

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

PORTT_IN

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

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

void PrintFP( float ansi_fp_num )

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

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

PULSE_A

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

See also PulseASetup() and PULSE_B

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

PULSE_A_EDGE

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

See also PULSE_A and PulseASetup()

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

PULSE_A_EDGE_ID

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

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

PULSE_A_FALLING_EDGE

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

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

PULSE_A_GATED_HIGH

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

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

PULSE_A_GATED_LOW

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

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

PULSE_A_OVERFLOW

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

See also PULSE_A and PulseASetup()

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

PULSE_A_OVERFLOW_ID

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

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

PULSE_A_RISING_EDGE

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

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

PULSE_B

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

See also PULSE_A

Type: macro
Related Forth function: PULSE.B
Header file: timerio.h

PULSE_B_OVERFLOW

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

See also PULSE_B and PulseBSetup()

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

PULSE_B_OVERFLOW_ID

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

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

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

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

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

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

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

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

void PulseBSetup( int overflow_irq, int pulse16_enable )

This function writes to the PBCTL register to configure the 16-bit PULSE_B pulse accumulator on pin 0 of PORTT.  If the pulse16_enable parameter is true (non-zero), the 16-bit PULSE_B pulse accumulator on pin 0 of PORTT is enabled.  If the pulse16_enable flag is false, then PULSE_B is disabled and the two component 8-bit pulse accumulators PA0 (forming the least significant byte of PULSE_B) and PA1 (forming the most significant byte of PULSE_B) on PORTT pins 0 and 1 are available.  If the overflow_irq parameter is true (non-zero), an interrupt occurs every time the pulse accumulator overflows from 0xFFFF to 0x0000. To configure the PULSE_B trigger edge, make sure that channel 0 is an input capture by executing:

InputCapture(0);

or:

InputCapture(PULSE_B);

and call TriggerEdge() with channel_id = 0. For example, to count rising-edge pulses without generating interrupts, execute:

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

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

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

void PulseDisable( int pulse8_channel_id )

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

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

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

void PulseEnable( int pulse8_channel_id )

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

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

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

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

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

int PulseHoldingRead( int channel_id )

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

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

uint PulseRegRead( int channel_id )

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

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

void PulseRegWrite( uint value, int channel_id )

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

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

PWM01

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

PWMConcatenate(PWM01);

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

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

PWM23

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

PWMConcatenate(PWM23);

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

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

PWM45

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

PWMConcatenate(PWM45);

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

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

PWM67

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

PWMConcatenate(PWM67);

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

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

PWM_CLOCKA

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

See also PWMScaledClock() and PWMUnscaledClock()

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

PWM_CLOCKB

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

See also PWMScaledClock() and PWMUnscaledClock()

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

PWM_SHUTDOWN_ID

A constant that returns the interrupt identity code for the pulse width modulator (PWM) shutdown detector.  Used as an argument for ATTACH().

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

void PWMActiveHigh( int channel_id )

Configures the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id to start in the active high state.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Implementation detail: Writes a 1 to the bit of the specified channel in the PWMPOL register.  After a power-up or hardware reset, the contents of PWMPOL is zero, causing the PWM outputs to be active low by default.

Type: kernel function
Forth name: PWM.ACTIVE.HIGH
Header file: pwm.h

void PWMActiveLow( int channel_id )

Configures the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id to start in the active low state.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Implementation detail: Writes a 0 to the bit of the specified channel in the PWMPOL register.  After a power-up or hardware reset, the contents of PWMPOL is zero, causing the PWM outputs to be active low by default.

Type: kernel function
Forth name: PWM.ACTIVE.LOW
Header file: pwm.h

void PWMCenterAlign( int channel_id )

Configures the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id to to be center aligned (as opposed to left aligned).  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  Center alignment causes the output period to be double the value set by PWMPeriodWrite(), for the following reason.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Implementation detail: Writes a 1 to the bit of the specified channel in the PWMCAE register.  After a power-up or hardware reset, the contents of PWMCAE is zero and the signals are left aligned.

Type: kernel function
Forth name: PWM.CENTER.ALIGN
Header file: pwm.h

void PWMConcatenate( int channel_id )

Creates a 16-bit PWM (pulse-width modulated) channel by concatenating two 8-bit PWM channels.  Valid channel_id input parameters are PWM01 (combines PWM0 and PWM1, present on PORTP pin 1); PWM23 (combines PWM2 and PWM3, present on PORTP pin 3); PWM45 (combines PWM4 and PWM5, present on PORTP pin 5); and PWM67 (combines PWM6 and PWM7, present on PORTP pin 7).  You can also use PWMSetup() to create a concatenated channel; see its glossary entry.  To undo the effect of PWMConcatenate(), use PWMSeparate().  While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.

Note: Make sure that both PWM channels associated with the concatenation are disabled before calling this routine.  If the relevant channels are active, they can be disabled using PWMDisable() or PWMDisableMultiple().

Implementation detail: This function sets the relevant bit in the PWMCTL register to create a concatenated 16bit PWM channel.  After a power-up or hardware reset, the contents of PWMCTL equal zero and the signals are separated (not concatenated).  For each channel_id, the second (numerically higher) channel mentioned in the name is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel.  For example, if you execute

PWM01 PWM.CONCATENATE

then the 16-bit PWM output is available on PORTP pin 1, the control register bits associated with PWM1 configure the output, and all 16-bit configuration quantities use the associated PWM0 register as the most significant byte, and the associated PWM1 register as the least significant byte.

Type: kernel function
Forth name: PWM.CONCATENATE
Header file: pwm.h

uint PWMCounterRead( int channel_id )

Returns the contents of the specified PWM (pulse-width modulated) counter register.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  This function returns an 8-bit count if the specified channel is a single PWM channel, and returns a 16-bit value if the channel_id specifies a concatenated channel.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Type: kernel function
Forth name: PWM.COUNTER.READ
Header file: pwm.h

void PWMCounterWrite( uint value, int channel_id )

Resets the specified PWM (pulse-width modulated) counter register to zero.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  This function stores an 8-bit count if the specified channel is a single PWM channel, and stores a 16-bit value if the channel_id specifies a concatenated channel.  However, writing any value to the counter resets its value to zero and the value written is lost.

When a counter register is written with any value, the following events happen: the counter is reset to zero; the counter direction is set to up; the duty and period registers are loaded from buffers; and the output is set according to polarity bit.

For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Type: kernel function
Forth name: PWM.COUNTER.WRITE
Header file: pwm.h

void PWMDisable( int channel_id )

Disables the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  If a concatenated channel_id is passed to this function, both associated 8-bit PWM channels are disabled.

See also PWMEnable()

Implementation detail: Clears the relevant bit(s) in the PWME register.  After a power-up or hardware reset, the PWM channels are disabled by default.

Type: kernel function
Forth name: PWM.DISABLE
Header file: pwm.h

void PWMDisableMultiple( int bitmask )

Expects an 8-bit bitmask input parameter (promoted to a 16-bit int), where bit0 corresponds to PWM0, bit 1 corresponds to PWM1, and bit7 corresponds to PWM7.  For each 1 bit in the input bitmask, this function clears the specified bits in the PWME register to disable the corresponding PWM (pulse-width modulated) channels.  Channels associated with 0 bits in the bitmask are not modified.  This function is useful for simultaneously disabling a number of PWM channels.  For concatenated channels, it is typically best to disable both subsidiary PWM channels, but note that only the bit corresponding to the numerically higher member of the pair has an effect on the concatenated pair.

See also PWMEnableMultiple()

Type: kernel function
Forth name: PWM.DISABLE.MULTIPLE
Header file: pwm.h

uint PWMDutyRead( int channel_id )

Returns the contents of the specified PWM (pulse-width modulated) duty register.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  This function returns an 8-bit duty value if the specified channel is a single PWM channel, and returns a 16-bit duty value if the channel_id specifies a concatenated channel.  When the counter value matches the duty value, the output changes state.  See PWMActiveHigh() and PWMActiveLow() to configure the starting polarity of the PWM output.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Type: kernel function
Forth name: PWM.DUTY.READ
Header file: pwm.h

void PWMDutyWrite( uint value, int channel_id )

Writes the specified value to the specified PWM (pulse-width modulated) duty register.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  This function writes an 8-bit duty value if the specified channel is a single PWM channel, and writes a 16-bit duty value if the channel_id specifies a concatenated channel.  When the counter value matches the duty value, the output changes state.  See PWMActiveHigh() and PWMActiveLow() to configure the starting polarity of the PWM output.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Type: kernel function
Forth name: PWM.DUTY.WRITE
Header file: pwm.h

void PWMEnable( int channel_id )

Enables the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  See PWMDisable() and PWMSetup(); the latter’s glossary entry describes a set of useful PWM configuration utiltities and provides an example of use.  To enable multiple channels at once, use PWMEnableMultiple().

Implementation detail: Sets the relevant bit(s) in the PWME register.  If a concatenated channel_id is passed to this function, only the numerically higher bit in the PWME register is set, as this controls the concatenated channel.  After a power-up or hardware reset, the PWM channels are disabled by default.

Type: kernel function
Forth name: PWM.ENABLE
Header file: pwm.h

void PWMEnableMultiple( int bitmask )

Expects an 8-bit bitmask input parameter (promoted to a 16-bit int), where bit0 corresponds to PWM0, bit 1 corresponds to PWM1, and bit7 corresponds to PWM7.  For each 1 bit in the input bitmask, this function sets the specified bits in the PWME register to enable the corresponding PWM (pulse-width modulated) channels.  Channels associated with 0 bits in the bitmask are not modified.  For concatenated channels, note that only the bit corresponding to the numerically higher member of the pair has an effect on the concatenated pair.  This function is useful for simultaneously enabling a number of PWM channels.  See PWMDisableMultiple() and PWMSetup(); the latter’s glossary entry describes a set of useful PWM configuration utiltities and provides a code example.  To enable a single PWM channel identified by its channel_id, use PWMEnable().

Implementation detail: Sets the specified bit(s) in the PWME register.  After a power-up or hardware reset, the PWM channels are disabled by default.

Type: kernel function
Forth name: PWM.ENABLE.MULTIPLE
Header file: pwm.h

void PWMLeftAlign( int channel_id )

Configures the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id to to be left aligned (as opposed to center aligned).  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Implementation detail: Clears the bit of the specified channel in the PWMCAE register.  After a power-up or hardware reset, the contents of PWMCAE is zero and the signals are left aligned.

Type: kernel function
Forth name: PWM.LEFT.ALIGN
Header file: pwm.h

uint PWMPeriodRead( int channel_id )

Returns the contents of the specified PWM (pulse-width modulated) period register.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  This function returns an 8-bit period if the specified channel is a single PWM channel, and returns a 16-bit period value if the channel_id specifies a concatenated channel.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Type: kernel function
Forth name: PWM.PERIOD.READ
Header file: pwm.h

void PWMPeriodWrite( uint value, int channel_id )

Writes the specified value to the specified PWM (pulse-width modulated) period register.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  This function writes an 8-bit period value if the specified channel is a single PWM channel, and writes a 16-bit period value if the channel_id specifies a concatenated channel.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWMSetup(), PWMEnable() or PWMEnableMultiple(); consult the PWMSetup() glossary entry for a list of useful PWM configuration functions and a code example.

Type: kernel function
Forth name: PWM.PERIOD.WRITE
Header file: pwm.h

void PWMPrescaler( int clock_id, int prescaler )

Sets the specified prescale factor for the clock specified by clock_id = PWM_CLOCKA or PWM_CLOCKB (see the PWM_CLOCKA and PWM_CLOCKB glossary entries).  The prescaler factor is applied to both the scaled and unscaled versions of the specified clock in the PWM (pulse-width modulated) subsystem.  Allowed values of the prescaler factor are : 1, 2, 4, 8, 16, 32, 64, and 128. The fundamental clock is the bus clock E, running at 20MHz, and the frequency is reduced (the period is increased) by the prescaler factor to create the specified PWM_CLOCKA or PWM_CLOCKB.  For a slower clock, use the scaled clock source for a given PWM channel; consult the glossary entries for PWMScaler(), PWMScaledClock(), and PWMUnscaledClock(). 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM_CLOCKA or a scaled version of PWM_CLOCKA. 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM_CLOCKB or a scaled version of PWM_CLOCKB.

Example of use: The bus clock (E clock) has a period of 0.05 microseconds (us).  To configure PWM_CLOCKA to have a period of 1.6 us, and PWM_CLOCKB to have a period of 6.4 us, execute:

PWMPrescaler(PWM_CLOCKA, 32);  // clockA period = 1.6us
PWMPrescaler(PWM_CLOCKB, 128);  // clockB period = 6.4us

As stated above, each PWM channel can also use the slower scaled clocks; see PWMScaledClock().

Type: kernel function
Forth name: PWM.PRESCALER
Header file: pwm.h

void PWMScaledClock( int channel_id )

Configures the specified PWM (pulse-width modulated) channel to use the slower (longer period) scaled clock source.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant. 

The 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM_CLOCKA or a scaled version of PWM_CLOCKA.  If this routine is called for channel_id 0, 1, 4, 5, PWM01, or PWM45, that channel will use the scaled PWM_CLOCKA (SA). 

The 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM_CLOCKB or a scaled version of PWM_CLOCKB.  If this routine is called for channel_id 2, 3, 6, 7 PWM23, or PWM67, that channel will use scaled PWM_CLOCKB (SB). 

The period of the unscaled PWM_CLOCKA is equal to the E-clock period (0.05 us) multiplied by a prescaler set by PWMPrescaler().  Allowed values of the prescaler are 1, 2, 4, 8, 16, 32, 64, and 128. The period of the scaled version of PWM_CLOCKA is equal to the unscaled PWM_CLOCKA period times the scaler set by PWMScaler(), where the scaler can be any even integer between 2 and 512.

The clock B sources are exactly parallel, and have their own unique prescaler and scaler values as set by PWMPrescaler() and PWMScaler(). 

Note that the default scale factor for the scaled PWM_CLOCKA and scaled PWM_CLOCKB clocks after a power-up or hardware reset is 512.

Example of use: The bus clock (E clock) has a period of 0.05 microseconds (us).  To configure PWM channel 0 to have a 1.6 us clock (unscaled PWM_CLOCKA), PWM channel 1 to have a 64 us clock (scaled PWM_CLOCKA), PWM channel 2 to have a 6.4 us clock (unscaled PWM_CLOCKB), and PWM channels 3 and PWM67 to have a 512 us clock (scaled PWM_CLOCKB), execute:

// first set the clock periods…
PWMPrescaler(PWM_CLOCKA, 32);   // clockA period = 1.6us
PWMScaler(PWM_CLOCKA, 40);      // scaled clockA = 40 * 1.6 = 64us
PWMPrescaler(PWM_CLOCKB, 128);  // clockB period = 6.4us
PWMScaler(PWM_CLOCKB, 80);      // scaled clockB = 80 * 6.4 = 512us
PWMUnscaledClock(0);            // pwm0 uses clockA @ 1.6us
PWMScaledClock(1);              // pwm1 uses SA @ 64us
PWMUnscaledClock(2);            // pwm2 uses clockB @ 6.4us
PWMScaledClock(3);              // pwm3 uses SB @ 512us
PWMScaledClock(PWM67);          // PWM67 uses SB @ 512us

Implementation detail: Sets the bit corresponding to the specified PWM channel in the PWMCLK register to select the scaled (slower) clock source.  To undo the effect of this function see PWMUnscaledClock().

Type: kernel function
Forth name: PWM.SCALED.CLOCK
Header file: pwm.h

void PWMScaler( int clock_id, int scaler )

Sets the specified scaler (2 ≤ scaler ≤ 512, scaler is even) as the scale factor for the clock specified by clock_id PWM_CLOCKA or PWM_CLOCKB (see the PWM_CLOCKA and PWM_CLOCKB glossary entries).  The fundamental clock is the bus clock E, running at 20MHz, and its frequency is reduced (the period is increased) by the prescale factor to create the two unscaled PWM clocks.  The prescale factor set by PWMPrescaler() (see its glossary entry) is applied to both the scaled and unscaled versions of the specified clock.  This PWMScaler() function applies a second scale factor to create a longer-period scaled PWM_CLOCKA (SA) and/or scaled PWM_CLOCKB (SB).  Allowed values of the scaler are even integers in the range 2 to 512. For a slower clock, use the scaled clock source for a given PWM channel; consult the glossary entries for PWMPrescaler(), PWMScaledClock(), and PWUnscaledClock(). 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM_CLOCKA or a scaled version of PWM_CLOCKA (SA). 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM_CLOCKB or a scaled version of PWM_CLOCKB (SB).  See the glossary entry for PWMScaledClock() for an example of use.

Implementation detail: If clock_id = PWM_CLOCKA, this routine writes to the PWMSCLA register.  If clock_id = PWM_CLOCKB, this routine writes to the PWMSCLB register.  Note that a value of 0 in the register corresponds to a scale factor of 512; this is the default scale factor for the scaled PWM_CLOCKA and scaled PWM_CLOCKB clocks after a power-up or hardware reset.

Type: kernel function
Forth name: PWM.SCALER
Header file: pwm.h

void PWMSeparate( int channel_id )

Undoes the concatenation of a 16-bit PWM (pulse-width modulated) channel to yield two 8-bit PWM channels.  Valid channel_id input parameters are PWM01 (combines PWM0 and PWM1, present on PORTP pin 1); PWM23 (combines PWM2 and PWM3, present on PORTP pin 3); PWM45 (combines PWM4 and PWM5, present on PORTP pin 5); and PWM67 (combines PWM6 and PWM7, present on PORTP pin 7).  You can also use PWMSetup() to configure a PWM channel; see its glossary entry.  To undo the effect of PWMSeparate(), use PWMConcatenate().  While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.

Note: Make sure that both of the PWM channels associated with the concatenation are disabled before calling this routine.  If the relevant channels are active, they can be disabled using PWMDisable() or PWMDisableMultiple().

Implementation detail: This function clears the relevant bit in the PWMCTL register.  After a power-up or hardware reset, the contents of PWMCTL equal zero and the signals are separated (not concatenated).  For each channel_id, the second (numerically higher) channel mentioned in the name is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel.

Type: kernel function
Forth name: PWM.SEPARATE
Header file: pwm.h

void PWMSetup( int active_high, int scaled_clock, int centered, int period, int duty, int channel_id )

This function specifies the characteristics of a specified PWM channel.

While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.

If the PWM channel is enabled when this routine is invoked, the channel is disabled during configuration to prevent anomalous transient behavior.  Then the specified parameters are written to the registers, and the specified PWM channel’s enable bit is restored to the state it was in before this routine was called.

• channel_id – Valid channel_id parameters for 8-bit PWM (pulse width modulated) channels are in the range 0 to 7, and the PWM output is on the corresponding PORTP pins.  Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher PORTP channel pin mentioned in each named constant.
• active_high – If the active_high flag is true, the signal is configured to start in the (active) high state; see PWMActiveHigh().  If active_high is false (the default after a hardware reset), the signal is configured to start in the (active) low state; see PWMActiveLow().
• scaled_clock – If the scaled_clock flag is true, the channel is configured to use the (slower, longer-period) scaled clock; see PWMScaledClock().  If the scaled_clock flag is false (the default after a hardware reset), the channel is configured to use the unscaled clock; see PWMUnscaledClock(). 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM_CLOCKA or a scaled version of PWM_CLOCKA. 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM_CLOCKB or a scaled version of PWM_CLOCKB; see the glossary entries for PWMPrescaler() and PWMScaler().
• centered – If the centered flag input parameter is true, the PWM channel is configured to be center aligned; see PWMCenterAligned().  If the centered flag is false (the default after a hardware reset), the PWM channel is configured to be left-aligned; see PWMLeftAligned().  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.
• period – This function’s period input parameter is passed to the PWMPeriodWrite() function which stores the parameter into the period register (if the channel_id is an 8-bit PWM) or register pair (if the channel_id is a 16-bit PWM).  Recall that the actual period will be double the specified period if the centered flag is true.
• duty – This functions’s duty input parameter is passed to the PWMDutyWrite() function which stores the parameter into the duty register (if the channel_id is an 8-bit PWM) or register pair (if the channel_id is a 16-bit PWM).

Example of use:

The clock(s) should be configured before the specified channels are enabled.  Typically, clocks are configured using the PWMPrescaler() and PWMScaler() functions, then PWMSetup() is called for each channel or channel pair, and then PWMEnable() or PWMEnableMultiple() is called to start the PWM signal(s). 

For example, assume we want to simultaneously enable the two 8-bit channels PWM0 and PWM1.  Both are to be left aligned active high signals. PWM0 is to have a 40% duty cycle with a 16 microsecond (us) period. PWM1 is to have a 60% duty cycle with a 640 us period.  Since both PWM0 and PWM1 use the A clocks (unscaled or scaled PWM_CLOCKA), we must first configure these to facilitate the design.  We’ll use the unscaled PWM_CLOCKA as the source for channel PWM0, and the scaled PWM_CLOCKA source for channel PWM1.  The fundamental clock source is the E-clock with a period of 0.05 microseconds (us).  Referring to the example in the glossary entry of PWMScaledClock(), we choose a prescaler of 32, resulting in an unscaled period of 1.6 us for PWM_CLOCKA; this sets the minimum time resolution of a PWM channel using this clock at 1.6 microseconds.  For the slower PWM1 channel, we use the scaled PWM_CLOCKA (SA) with a period of 64 us.  We’ll specify the period of each channel as 10 counts; thus the PWM0 period is 10 * 1.6us = 16 us, and the PWM1 period is 10 * 6.4us = 64 us, as desired.  The required duty cycle of PWM0 is 40%, so we specify a duty parameter of 4 (4/10 = 40%).  The required duty cycle of PWM1 is 60%, so we specify a duty parameter of 6 (4/10 = 60%).  Finally, to simultaneously enable the two PWM channels we note that the bitmask for the combination of channels 0 and 1 equals decimal 3; that is, a bitmask with bits 0 and 1 set has a value of 3, and this is the parameter we will pass to PWMEnableMultiple() to simultaneously enable PWM0 and PWM1 after PWMSetup() has executed.  We assume that this example starts after a power-up or hardware reset, with all of the PWM channels initially disabled.  Here is the code that fulfills the requirements of this example:

// first set the clock periods…
PWMPrescaler(PWM_CLOCKA, 32);  // clockA period = 1.6us
PWMScaler(PWM_CLOCKA, 40);     // scaled clockA = 40 * 1.6 = 64us
PWMUnscaledClock(0);           // pwm0 uses clockA @ 1.6us
PWMScaledClock(1);             // pwm1 uses SA @ 64us
// now call PWMSetup() for PWM0, the next comment line recaps the prototype:
// PWMSetup( active_high, scaled_clock, centered, period, duty, channel_id )
PWMSetup(TRUE, FALSE, FALSE, 10, 4, 0);   // setup but don’t enable PWM0
// now call PWMSetup() for PWM1, the next comment line recaps the prototype:
// PWMSetup( active_high, scaled_clock, centered, period, duty, channel_id )
PWMSetup(TRUE, TRUE, FALSE, 10, 6, 1);   // setup but don’t enable PWM1
PWMEnableMultiple(3);        // simultaneously enable PWM0 and PWM1

This glossary entry and example show how the PWM control functions work together to facilitate the configuration of pulse-width modulated signals.

Type: kernel function
Forth name: PWM.SETUP
Header file: pwm.h

void PWMUnscaledClock( int channel_id )

Configures the specified PWM (pulse-width modulated) channel to use the faster (shorter period) unscaled clock source.

Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.

The 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM_CLOCKA or a scaled version of PWM_CLOCKA (SA).  The 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM_CLOCKB or a scaled version of PWM_CLOCKB (SB).

If this PWMUnscaledClock() routine is called for channel_id 0, 1, 4, 5, PWM01, or PWM45, that channel will use the unscaled PWM_CLOCKA.  If this routine is called for channel_id 2, 3, 6, 7 PWM23, or PWM67, that channel will use unscaled PWM_CLOCKB.

The period of the unscaled PWM_CLOCKA is equal to the E-clock period (0.05 us) multiplied by a prescaler set by PWMPrescaler(); allowed values of the prescaler are 1, 2, 4, 8, 16, 32, 64, and 128. The period of the scaled version of PWM_CLOCKA is equal to the unscaled PWM_CLOCKA period times the scaler set by PWMScaler(), where the scaler can be any even integer between 2 and 512.

The clock B sources are exactly parallel, and have their own unique prescaler and scaler values as set by PWMPrescaler() and PWMScaler().

See PWMScaledClock() for an example of use.

Type: kernel function
Forth name: PWM.UNSCALED.CLOCK
Header file: pwm.h