C Function Summary

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 categorized list of all Control-C library functions;
• A categorized list of interactive debugger and system configuration functions; and,
• A listing of functions that temporarily disable interrupts. These routines are summarized to assist you in planning the time-critical aspects of your application.

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.

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

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.

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.

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:

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.

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.

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.

Certain Control-C library functions temporarily disable interrupts by setting the I bit in the condition code register. The glossary entries for these words detail the length of time that interrupts are disabled. These routines are summarized here to assist you in planning the time-critical aspects of your application.

The library provides a set of uninterruptable memory operators that disable interrupts for a few microseconds during the memory access. These are very useful in applications where several tasks or interrupt routines must access a shared memory location: