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 C:\MosaicPlus\c\libraries\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.

Companion pages provide a comparison with prior QED operating software, which summarizes the functions that have been added to this version of the QED operating system software compared to prior versions; and, links to documentation for the open-source implementation of the C standard libraries provided as part of the development environment for PDQ-line controllers.

For an overview of the functions provided by the Newlib open-source library of standard C functions, see the Tables of Contents of the standard and math library documentation pages:

• libc — The Newlib standard library Table of Contents
• libm — The Newlib math library Table of Contents

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

• C Function Glossary (A-H)
• C Function Glossary (I-Q)
• C Function Glossary (R-Z)

The names and contents of the QED-Forth C 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.

You can access these kernel functions as well as the the standard C library functions using the command

#include < mosaic\allqed.h >

as described in the section Accessing the standard (kernel) C library functions.

You can call any of these functions from within your C code using standard C syntax. There is one limitation however:

There are several reasons for this limitation:

1. The Forth operating system will not allow a function call to be included as a parameter in the function invocation of another Forth function call. Further, many functions that are callable from C are actually defined in the QED-Forth Kernel or a QED-Forth Kernel-extension library. This includes functions that are in the kernel on the PDQ Board, or are part of software distributions such as the Graphical User Interface (GUI) Toolkit. A call to one of these functions may not be made from within the parameter list of a call to another such function.
2. The C compiler does allow functions to be used as parameters in another function call, but doing so greatly increases the stack space needed for the function, making run time errors owing to stack overflow much more likely. Many function calls in C, particularly calls to math functions, use the runtime stack very greedily, often setting up temporary buffers on the stack. Nesting such functions piles up those buffers on the stack, while calling them sequentially does not.

There is always a straightforward way to avoid nesting function calls: simply use a variable to hold the required intermediate return value/parameter. For example, if you need to use the Kernel function StoreChar() to store at xaddress 0x0F8000 the contents fetched by FetchChar() from xaddress 0x0F8100 in paged memory, you could execute the following statements:

static char contents = FetchChar( (xaddr) 0x0F8100 );
StoreChar( contents, (xaddr) 0x0F8000 );

This code is correct, while nesting the call to FetchChar() inside the parameter list of StoreChar() would be incorrect.

Each entry in the Main Glossary of Control-C Library Functions may include 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. An "Availability" field that states the first revision of Mosaic IDE Plus in YYWW notation (post-2000 year and ISO week number) in which the routine was made available.
5. 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. Alternatively there may be a statement that the routine is "C only".
6. A "Header file" field that specifies where the routine is defined or declared. Most header files are in the C:\MosaicPlus\c\libraries\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 routines described here 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:

The multitasker mediates access to shared resources and ensures smooth transfer of information among tasks. The routines that manage resource variables and mailboxes must disable interrupts for short periods to ensure proper access to shared resources and messages. Consequently, the following routines temporarily disable interrupts:

Some of these routines also call Pause to give other tasks a chance to run while waiting for a resource or message; as explained below, Pause also disables interrupts. Consult their glossary entries for details.

The following routines temporarily disable interrupts to ensure that a new task is not corrupted while it is being built:

These functions disable interrupts to ensure that the elapsed time clock is not updated while it is being read:

The multitasker is charged with smoothly transferring control among tasks via timeslicing or cooperative task switching. The timeslicer is an interrupt service routine associated with the real-time interrupt (RTI). The timeslicer's interrupt service routine disables interrupts for the duration of a task switch which requires 3.6 microseconds, plus 0.5 microseconds for each ASLEEP task encountered in the task list. The cooperative task switch routine

also disables interrupts for the duration of the task switch time, which is just over 4 microseconds.

The Pause routine (which temporarily disables interrupts) is sometimes called by the following built-in device drivers:

The following device driver routines GET and RELEASE resource variables, and so may disable interrupts for short periods of time:

All of the routines that write to the EEPROM disable interrupts for 30 msec per programmed 4-byte aligned EEPROM cell. This results from the processor’s design which prohibits any EEPROM locations from being read while other EEPROM locations are being modified. Since all interrupts are vectored through EEPROM, interrupts cannot be serviced while an EEPROM storage operation is in progress. The fundamental EEPROM storage functions are:

These functions disable interrupts during EEPROM programming. The following routines may modify EEPROM locations:

All of the routines that write to the on-chip flash memory disable interrupts for 35 msec per programmed sector, where a sector is 512 bytes for a 256 KByte flash processor, or 1024 bytes for a 512 Kbyte processor. Routines that write to off-chip eXternal flash memory disable interrupts for 12 msec per programmed sector, where a standard sector is 256 bytes. The following flash routines disable interrupts:

The following routines disable interrupts and do not re-enable them:

DISABLE_INTERRUPTS and its assembly language counterpart SEI explicitly set the I bit in the condition code register. The routines ENABLE_INTERRUPTS and the assembler mnemonic CLI clear the I bit to globally enable interrupts. The restart routines Cold and Warm disable interrupts to ensure that the initialization process is not interrupted.