C V4.0/V4.2 Function Summary

The C V4.0/V4.2 Function Glossary provides detailed descriptions of all of the library routines that customize Control-C for use with the QVGA Controller, Panel-Touch Controller, and QED Board running the QED-Forth V4.0x or V4.2x operating system software targeted to the Freescale 68HC11 microcontroller. These C library routines are defined and declared in a set of header files in the compiler's \FABIUS\INCLUDE\MOSAIC directory. All files are included with the IDE (Integrated Development Environment) which simplifies software development. The IDE includes the Textpad editor and a toolbar that launches the C compiler and the terminal for easy code downloads. This document contains the following:

• An overview of the header files (Using Header Files);
• A description (Interpreting glossary definitions) of the definitions contained in the C V4.0/V4.2 Function Glossary and the C V4.0/V4.2 Interactive Debugger Glossary.
• A categorized List of all Control-C library functions;
• A categorized List of QED-Forth debugger and system configuration functions; and,
• A list of functions that disable interrupts.

All the functions described may be found in the C V4.0/V4.2 Function Glossary and the C V4.0/V4.2 Interactive Debugger Glossary.

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

The following Categorized List of Control-C Library Functions is organized according to these header files. To examine these files, use TextPad (the Mosaic IDE Editor) to open the files in the compiler's \MOSAIC\FABIUS\INCLUDE\MOSAIC directory.

Each entry in the C V4.0/V4.2 Function Glossary 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 _forth function, a C function, a macro, a constant, or a typedef.
4. A Related QED-Forth name 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.

Standard type specifiers such as char, int, long, and float are used in the glossary declarations. In addition, we use four 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 stands for "extended address", and is used when a 32-bit address must be passed as a parameter.

The C V4.0/V4.2 Function Glossary presents definitions of all of the functions, constants and macros that are defined and declared in the \FABIUS\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 glossary facilitate control of all of the hardware on the QED Board, including the analog and digital I/O lines, serial communications ports, keypad scanner, character and graphics display interfaces, and battery-backed real-time clock. 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 your application program.

The C V4.0/V4.2 Interactive Debugger Glossary describes a set of 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 Debugging chapter of the QVGA Manual explains how to use QED-Forth and the debugger routines.

In addition to the debugger keywords that were created for debugging C programs, the 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 to facilitate program transfer to flash memory on production boards, change the baud rates of the serial ports, and setup the MAIN program to AUTOSTART each time the QED Board starts up.

The introduction at the top of the C V4.0/V4.2 Interactive Debugger Glossary provides further information.

See the QEDREGS.H file. All registers are named using the standard names as described in the Motorola 68HC11F1 documentation.

This section summarizes the functions and macros that temporarily disable interrupts. These routines are summarized to assist you in planning the time-critical aspects of your application.

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:

Accessing the PIA (Peripheral Interface Adapter) and LCD display require the insertion of wait states, and the architecture of the QED Board requires that interrupts be disabled while a wait state memory access is in progress. In addition to the PIA routines listed above, the following routines disable interrupts to insert wait states:

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 of time 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:

ReadElapsedSeconds() disables 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 output compare#2. The timeslicer's interrupt service routine disables interrupts for the duration of a task switch which requires 25 microseconds, plus 3.25 microseconds for each ASLEEP task encountered in the task list. The cooperative task switch routine, Pause(), switches tasks in (27 + 3.25n) microseconds, where n is the number of ASLEEP tasks encountered in the round robin task list. Of this time, interrupts are disabled for (20 + 3.25n) microseconds.

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

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

The battery-backed real-time clock option shares the RAM socket on the QED Board. While the "watch" is being read or set by the routines

the RAM cannot be accessed, so interrupts cannot be properly serviced. Therefore these routines disable interrupts for approximately 0.5 msec while the watch is being accessed.

All of the routines that write to the EEPROM disable interrupts for 20 msec per programmed byte. This results from the 68HC11'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 following fundamental EEPROM storage functions:

disable interrupts for 20 msec per programmed byte. These routines are smart enough to avoid programming a byte that already has the correct contents. The following routines may modify EEPROM locations:

All of the routines that write to the Flash memory disable interrupts for 20 msec per programmed sector, where a standard sector is 256 bytes. This results from the flash architecture which prohibits any flash locations from being read while other flash locations are being modified. Since interrupts invoke flash-resident code, interrupts cannot be serviced while an flash storage operation is in progress. 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.