Link here

C Function Summary

Summary of C language library functions for the PDQ Board controller.

The C Function Glossary provides detailed descriptions of all of the library routines that customize the GNU C (GCC) compiler for use with the PDQ Controller and its built-in QED-Forth RTOS (real time operating system). QED-Forth is both a programming language and a real-time embedded operating system. Many QED-Forth firmware functions are callable as libraries from the Mosaic IDE Plus, a Codeblocks-based Integrated Development Environment you use for your C software development. These C library routines are defined and declared in a set of header files in the compiler's \INCLUDE\MOSAIC directory. These functions run on the Freescale 9S12/HCS12 MCU.

This document presents an overview of the header files and explains how to interpret the information that is presented in the C Function Glossary and the Interactive Debugger Glossary. The glossary provides detailed descriptions of each library function as well as numerous C code examples.

In here you'll find:

A companion page provides a comparison with prior QED operating software; it summarizes the functions that have been added to this version of the QED operating system software compared to prior versions.

When you click on a library function name you should get a popup containing its detailed definition, taken from the C Function Glossary.

 

Using header files

The names and contents of the header files are as follows:

Header File Contents
ANALOG.h Analog-To-Digital (ATD) converter driver functions
ARRAY.h Routines that dimension, access and manipulate Forth Arrays in paged memory
HCS12REGS.h Macro definitions for the Freescale HCS12 (9S12) registers
HEAP.h Heap memory manager functions
INTERUPT.h Interrupt identifiers and functions to facilitate posting interrupt handlers
IOACCESS.h Memory access primitives for the Wildcard and Smart I/O modules
MEMORY.h Memory access functions for paged memory, flash and EEPROM
MTASKER.h Multitasking executive and elapsed-time clock routines
NUMBERS.h Formatted number-to-string and print routines
OPSYSTEM.h Operating system functions for initialization, autostarting, and error handling
PWM.h Pulse-Width Modulated (PWM) output driver functions
SEGMENTS.h Library and application segment management structures and macros
SERIAL.h Serial communications driver functions for RS232/485, SPI, and IIC buses
TIMERIO.h Timer-controlled I/O driver functions for the Enhanced Capture Timer (ECT)
TYPES.h Useful type definitions
USER.h Declarations of USER_AREA and TASK structures, and user variable definitions
UTILITY.h Defines macros such as MIN, MAX, ABS, TRUE, FALSE, SAVE_STRING and LOAD_STRING
WATCH.h Routines that set and read the battery-backed real-time "smart watch"

The Categorized list of Control-C library functions is organized according to these header files. To examine these files, use the Mosaic IDE Plus editor to open the files in the C:\MosaicPlus\c\libraries\include\mosaic directory.

 

Interpreting glossary definitions

Each entry in the Main Glossary of Control-C Library Functions includes the following elements:

  1. A declaration of the routine. If it is a constant or a macro that does not require any arguments, then the name of the routine is simply presented. If it is a function, or a macro that behaves like a function, then the declaration looks like an ANSI-C function prototype, such as:

    void Emit(uchar c)''

    where void tells us that there is no return value, and uchar c tells us that there is a single input parameter that is an unsigned character.

  2. A detailed definition of what the routine does.
  3. A "Type:" field that specifies whether the routine is a kernel function, a C function, a macro, a constant, or a typedef. Kernel functions are defined in the operating system ("kernel"), reside in flash on the PDQ hardware, and are called via a wrapper function and C prototype from the C environment. The remaining types are declared using standard C syntax.
  4. A "QED-Forth name" or "Related QED-Forth function" field that specifies the name of a closely related function or constant that is accessible via the QED-Forth interpreter/compiler using QED-Forth syntax.
  5. A "Header file" field that specifies where the routine is defined or declared. Most header files are in the \INCLUDE\MOSAIC directory.

 

Type abbreviations used in function declarations

Standard type specifiers such as char, int, long, and float are used in the glossary declarations. In addition, we use six convenient typedefs that are defined in the TYPES.h header file:

typedef unsigned char uchar;
typedef unsigned int uint;
typedef unsigned long ulong;
typedef unsigned long xaddr;
typedef int wchar;
typedef unsigned int uwchar;

The meanings of the first three typedefs are obvious; they are abbreviations for unsigned types. The "xaddr" typedef means "extended address", and is used when a 32-bit address parameter is passed. The "wchar" and "uwchar" stand for wide-char and unsigned wide-char. These types must be used when passing char types to any libraries or kernel functions.

 

Categorized list of Control-C library functions

The C Function Glossary presents definitions of all of the functions, constants and macros that are defined and declared in the \INCLUDE\ MOSAIC header files. This glossary does not describe standard ANSI-C library functions (such as functions in stdio.h); consult any ANSI-C text for descriptions of the ANSI standard library functions.

The routines described in the C Function Glossary facilitate control of the hardware on the PDQ controller, including the digital I/O lines, RS232/485 serial communications ports, and battery-backed real-time clock (also called the "watch"). Built-in high level I/O drivers control the processor’s Analog-To-Digital (ATD) converter, Pulse-Width-Modulated (PWM) output port (PORTP), and timer-controlled I/O implemented by the Enhanced Capture Timer on PORTT. The timer-controlled ECT subsystem includes Input Captures (IC), Output Compares (OC), pulse accumulators, a modulus down-counter, and a free-running counter (TCNT). Additional drivers control the fast 3-wire SPI (Serial Peripheral Interface) and the 2-wire IIC (Inter-IC) serial ports; these clocked serial buses enable the processor to communicate with multiple peripheral devices. In addition, the routines provide complete control over the built-in multitasking executive, heap memory manager, interrupt handling capabilities, and operating system features including autostarting of your application program.

 

ANALOG.h

ATD0_7_RESULTS ATDMultiple ATDSample
ATD8_15_RESULTS ATDOff ATDSingle
ATDDigitalInputs ATDOn ATDStartSample
 

ARRAY.h

ARRAYBASE CopyArray FillArray
ArrayBase DELETED FORTH_ARRAY
ARRAYFETCH Deleted NUMCOLUMNS
ArrayFetch DIM NUMDIMENSIONS
ARRAYMEMBER Dimensioned NUMROWS
ArrayMember FARRAYFETCH SIZEOFMEMBER
ARRAYSIZE FArrayFetch SWAPARRAYS
ARRAYSTORE FARRAYSTORE SwapArrays
ArrayStore FArrayStore
COPYARRAY FILLARRAY
 

HCS12REGS.h

PORTAD0 PORTJ_DIRECTION PORTP_IN
PORTAD0_MODE PORTM PORTT
PORTAD1 PORTM_DIRECTION PORTT_DIRECTION
PORTAD1_MODE PORTP PORTT_IN
PORTJ PORTP_DIRECTION
See the HCS12REGS.h file. All registers are named using the standard names as described in the Motorola documentation. The names in this table are synonyms for control of on-board digital I/O.
 

HEAP.h

DEFAULT_HEAPEND INIT_DEFAULT_HEAP ToHeap
DEFAULT_HEAPSTART IsHeap TransferHeapItem
DupHeapItem ResizeHandle
FromHeap Room
 

INTERRUPT.h

ATD0_ID ECT5_ID PULSE_B_OVERFLOW_ID
ATD1_ID ECT6_ID PWM_SHUTDOWN_ID
ATTACH ECT7_ID RTI_ID
Attach ECT_OVERFLOW_ID SCI0_ID
CLOCK_MONITOR_ID ENABLE_INTERRUPTS SCI1_ID
COP_ID IIC_ID SELF_CLOCK_ID
COUNTER_UNDERFLOW_ID IRQ_ID SPI0_ID
DISABLE_INTERRUPTS PLL_LOCK_ID SPI1_ID
ECT0_ID PORTH_ID SPI2_ID
ECT1_ID PORTJ_ID SWI_ID
ECT2_ID PORTP_ID TRAP_ID
ECT3_ID PULSE_A_EDGE_ID XIRQ_ID
ECT4_ID PULSE_A_OVERFLOW_ID
 

IOACCESS.h

FromIO IOFetchLong SmartIOFetchChar
FromSmartIO IOSetBits SmartIOFetchFloat
IOChangeBits IOStoreChar SmartIOFetchInt
IOClearBits IOStoreFloat SmartIOFetchLong
IOFetchChar IOStoreInt ToIO
IOFetchFloat IOStoreLong ToIORegister
IOFetchInt IOSetBits
 

MEMORY.h

AddXaddrOffset FetchInt StoreFloatProtected
CalcChecksum FetchLong StoreInt
CalcChecksumMany FetchLongProtected StoreLong
Cat FillMany StoreLongProtected
ChangeBits LoadPage StorePages
ClearBits LoadPages StringMove
CmoveMany ReceiveBinary ToEEPROM
CmoveManyCheck ReceiveHex ToFlash
CountedString SetBits ToFlashMany
Dump StoreChar ToggleBits
DumpBinary StoreEEChar ToMemory
DumpManyS2 StoreEEFloat ToXFlash
FetchChar StoreEEInt XaddrDifference
FetchFloat StoreEELong
FetchFloatProtected StoreFloat
 

MTASKER.h

Activate InitElapsedTime SEND
ACTIVATE InstallMultitasker Send
ASLEEP KillTask SERIAL
AWAKE MAILBOX SERIAL1_RESOURCE
BuildTask MicrosecDelay SERIAL2_RESOURCE
BUILD_C_TASK MsecTimeslicePeriod SPI_RESOURCE
CountToMsec Pause StartTimeslicer
FMAILBOX ReadElapsedSeconds StopTimeslicer
FORTH_TASK RECEIVE TIMESLICE_COUNT
FRECEIVE Receive TryToFSend
FReceive RELEASE TryToGet
FSEND Release TryToSend
FSend RELEASE_AFTER_LINE TRY_TO_FSEND
GET RELEASE_ALWAYS TRY_TO_GET
Get RELEASE_NEVER TRY_TO_SEND
Halt RESOURCE WaitTilMatch
 

NUMBERS.h

FILL_FIELD LEFT_PLACES RANDOM_SEED
FIXED MANTISSA_PLACES RIGHT_PLACES
FLOATING NO_SPACES SCIENTIFIC
FPtoString PrintFP TRAILING_ZEROS
FP_FORMAT Random
FRandom RandomGaussian
 

OPSYSTEM.h

Abort EnableBootVectors SetBootVector
BreakAll Execute StandardReset
Breakpoint InitVitalIRQsOnCold StatusAtStartup
CheckstartDisable IsAutostart SysAbort
CheckstartEnable IsPriorityAutostart Version
ClearBootVectors LoadPagesAtStartup Warm
Cold NoAutostart WriteEnable
ColdOnReset NoStatusAtStartup WriteProtect
DisableBootVectors NoVitalIRQInit
 

PWM.h

PWM01 PWMConcatenate PWMLeftAlign
PWM23 PWMCounterRead PWMPeriodRead
PWM45 PWMCounterWrite PWMPeriodWrite
PWM67 PWMDisable PWMPrescaler
PWM_CLOCKA PWMDisableMultiple PWMScaledClock
PWM_CLOCKB PWMDutyRead PWMScaler
PWMActiveHigh PWMDutyWrite PWMSeparate
PWMActiveLow PWMEnable PWMSetup
PWMCenterAlign PWMEnableMultiple PWMUnscaledClock
 

SEGMENTS.h

KERNEL_ARRAY_ADDR SEG_ARRAY_BASE_ADDR SEG_VARSTART
KERNEL_ID SEG_ARRAY_ENTRY SEG_XNFA
REQUIRED_SEGMENTS_MAX SEG_CODE_XBASE SEGMENT_STRUCT
SEG_ARRAY_ADDR SEG_EEVARSTART SEGMENTS_MAX
 

SERIAL.h

_peekTerminal IIC_NUM_BYTES_TO_RCV InitSPI
_readChar IIC_NUM_BYTES_TO_XMIT Key
_readTerminal IIC_RCV_BUF_FULL Key1
_writeChar IIC_RCV_BUF_OFFSET Key2
AskKey IIC_RCV_BUF_OVERFLOW PauseOnKey
AskKey1 IIC_RCV_BUF_PTR RS485Init
AskKey2 IIC_RCV_BUF_SIZE RS485Receive
Baud IIC_RCV_BUFFER RS485Transmit
Beep IIC_TIMEOUT_ERROR RS485TransmitDone
Cr IIC_XMIT_BUF_EMPTY Serial1AtStartup
Emit IIC_XMIT_BUF_OFFSET Serial2AtStartup
Emit1 IIC_XMIT_BUF_OVERFLOW SPI_FALLING_LEADING_EDGE
Emit2 IIC_XMIT_BUF_PTR SPI_FALLING_TRAILING_EDGE
ForthAskKey IIC_XMIT_BUF_SIZE SPI_RISING_LEADING_EDGE
ForthEmit IIC_XMIT_BUFFER SPI_RISING_TRAILING_EDGE
ForthKey IICFrequencies SPIConfig
IIC_104KHZ_23PERCENT IICInit SPIExchange
IIC_10KHZ_13PERCENT IICReceive SPIFrequencies
IIC_96KHZ_25PERCENT IICReceiveFrame SPIRestore
IIC_ARB_LOST_ERROR IICSend SPISave
IIC_ERROR IICSendFrame UseSerial1
IIC_MASTER_RECEIVER IICSendNextFrame UseSerial2
IIC_NAK_ERROR InitIPSPI
 

TIMERIO.h

ECTClearInterruptFlag ModCounterSetup PULSE_A_GATED_HIGH
ECTFastClear ModCounterUpdate PULSE_A_GATED_LOW
ECTInterruptDisable MODULUS_UNDERFLOW PULSE_A_OVERFLOW
ECTInterruptEnable OC7ClearsIt PULSE_A_RISING_EDGE
ECTPrescaler OC7Disconnect PULSE_B
ECTStandardClear OC7SetsIt PULSE_B_OVERFLOW
HoldingRegForceLatch OC_CLEAR_ACTION PulseASetup
IC_1024_CYCLE_DELAY OC_NO_ACTION PulseBSetup
IC_256_CYCLE_DELAY OC_SET_ACTION PulseDisable
IC_512_CYCLE_DELAY OC_TOGGLE_ACTION PulseEnable
IC_DELAY_DISABLED OCAction PulseHoldingRead
ICFirstPolarity OCForce PulseRegRead
ICHoldingRead OCICRegRead PulseRegWrite
ICNoiseDelay OCNoToggleOnOverflow TCNT_OVERFLOW
ICNoOverwrite OCRegWrite TCNTRead
ICOverwriteOK OCToggleOnOverflow TRIGGER_OFF
ICPulseConfig OutputCompare TRIGGER_ON_ANY_EDGE
InputCapture PULSE_A TRIGGER_ON_FALLING_EDGE
ModCounterLoad PULSE_A_EDGE TRIGGER_ON_RISING_EDGE
ModCounterRead PULSE_A_FALLING_EDGE TriggerEdge
 

TYPES.h

_Q THIS_PAGE XADDR_TO_ADDR
EXTENDED_ADDR TO_XADDR XADDR_TO_PAGE
PAGE_LATCH TWO_INTS
 

USER.h

CURRENT_HEAP TASK UERROR
CUSTOM_ABORT TASKBASE UKEY
CUSTOM_ERROR TIB UP
NEXT_TASK UABORT UPAD
PAD UASK_KEY USER_AREA
SERIAL_ACCESS UDEBUG UTIB
STATUS UEMIT
 

UTILITY.h

ABS FLASH_IPRINTF SAVE_STRING
MIN FLASH_PRINT LOAD_STRING
MAX FLASH_PRINTF LOADED_STRING
TRUE FLASH_SNIPRINTF LOAD_STRING_TO
FALSE FLASH_SNPRINTF
 

WATCH.h

CALENDAR_TIME WATCH_DAY WATCH_MONTH
ReadWatch WATCH_HOUR watch_results
SetWatch WATCH_HUNDREDTH_SECONDS WATCH_SECONDS
WATCH_DATE WATCH_MINUTE WATCH_YEAR
 

Interactive debugger and system configuration functions

The Interactive Debugger Glossary describes useful routines that allow you to interactively call C functions and manipulate variables and FORTH_ARRAY data. These versatile routines make it easy to thoroughly test each function in your program over its full range of allowed input parameters.

The environment for the interactive debugger is the QED-Forth interpreter. Thus, while the syntax of the debugger commands is similar to C function prototypes and assignment statements, you will in fact be "talking to" the debugger using the QED-Forth language. The PDQ C User Guide explains how to use QED-Forth and the debugger routines. Forth function names are not restricted to alphanumeric characters, and can contain periods, colons, semicolons, etc. Forth functions can be interactively typed at the terminal, and are always space-delimited: there must be at least one space between successive Forth commands.

In addition to the debugger keywords that were created for debugging C programs, the Debugger Glossary also describes some QED-Forth functions that can be interactively called. These useful functions let you write to EEPROM, view memory contents using a DUMP command, capture your application in a Motorola S-record file, change the baud rates of the serial ports, and configure the MAIN program to AUTOSTART each time the PDQ controller starts up.

The "Introductory Notes" section at the top of the Debugger Glossary provides further information.

 

Assignment, fetching and function calling

=CHAR CHAR INT
=FLOAT CHAR* INT*
=INT DO[] LONG
=LONG FLOAT LONG*
CALL.CFN FLOAT*
 

EEPROM storage

(EE!) (EEC!) TO.EEPROM
(EE2!) (EEF!)
 

Hex dump and receive

DUMP DUMP.S1 RECEIVE.HEX
DUMP.AUTOSTARTS DUMP.S2
DUMP.INTEL DUMP.MANY.S2
 

Numeric I/O

. HEX PrintFP
D. HEX. U.
DECIMAL HEXD.
 

Operating system and memory management

ABORT LOAD.PAGES SP!
AUTOSTART: LOAD.PAGES.AT.STARTUP STATUS.AT.STARTUP
BAUD MAIN STANDARD.RESET
CALC.CHECKSUM MAIN2 STORE.PAGES
CFA.FOR NO.AUTOSTART TO.FLASH
CHECKSTART.DISABLE NO.STATUS.AT.STARTUP TO.MEMORY
CHECKSTART.ENABLE NO.VITAL.IRQ.INIT TO.XFLASH