C v4.4 Function Summary
This document provides subject sorted lists of the functions described in detail in the C V4.4 Function Glossary. That glossary provides detailed descriptions of all of the library routines that customize Control-C for use with Mosaic's embedded controllers that use the Freescale 68HC11 processor:
- QScreen Controller, and,
These products carry an operating system firmware version number of the form V4.4x, where x is a numeric value.
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 introduction presents an overview of the header files and explains how to interpret the information that is presented in the C V4.4 Function Glossary and the C V4.4 Interactive Debugger Glossary.
- A categorized list of all Control-C library functions;
- A categorized list of QED-Forth debugger and system configuration functions;
- A list of functions that disable interrupts; and,
- A comparison of operating system firmware V4.4x versus prior V4.08 firmware.
Using header files
The names and contents of the header files are summarized in the following table. To access the five new C-callable functions in V4.40, you must #include V4_4Update.c and its companion header file V4_4Update.h as explained below.
| Header File | Contents |
|---|---|
ANALOG.H | Device drivers for the 8-bit A/D and SPI |
ARRAY.H | Routines that dimension, access and manipulate Forth Arrays in paged memory |
COMM.H | Serial communications driver functions |
FLASH.H | Flash memory functions |
HEAP.H | Heap memory manager functions |
INTERUPT.H | Interrupt identifiers and functions to facilitate posting interrupt handlers |
INTRFACE.H | Device drivers for the keypad and LCD display interfaces |
MTASKER.H | Multitasking executive and elapsed-time clock routines |
NUMBERS.H | Formatted output for QED floating point numbers, and ANSI/QED conversion |
QEDREGS.H | Macro definitions for all of the 68HC11F1 registers |
QEDSYS.H | Operating system functions for initialization, autostarting, and error handling |
STEPPER.H | Stepper motor control primitives |
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 and FALSE |
V4_4UPDATE.H | BufferToSPI, BytesToDisplay, CalcChecksum, ClearBootVector, SetBootVector |
WATCH.H | Routines that set and read the battery-backed real-time "smart watch" |
XMEM.H | Fetch, store and bit manipulation functions for extended memory and EEPROM |
The Categorized List of Control-C Library Functions on this page is organized according to these header files. To examine these files, use the Mosaic IDE Editor to open the files in the compiler's \MOSAIC\FABIUS\INCLUDE\MOSAIC directory.
Interpreting glossary definitions
Each entry in the C V4.4 Function Glossary includes the following elements:
- 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.
- A detailed definition of what the routine does.
- A Type: field that specifies whether the routine is a
_forthfunction, a C function, a macro, a constant, or atypedef. - 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.
- A Header file field that specifies where the routine is defined or declared.
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 four 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; |
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.
Glossary of Control-C library functions
The C V4.4 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 C V4.4 Function 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 of your application program.
Interactive debugger glossary
The C V4.4 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 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 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 of the C V4.4 Interactive Debugger Glossary provides further information.
Categorized List of Control-C Library Functions
ANALOG.H
| AD8Multiple() | AD8ToBuffer() | InitSPI() |
| AD8Off() | DIM_AD8_BUFFER() | SPIOff() |
| AD8On() | FastAD8Multiple() | |
| AD8Sample() | FastAD8Sample() |
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() |
COMM.H
| AskKey() | ForthEmit() | PauseOnKey() |
| AskKey1() | ForthKey() | RS485Receive() |
| AskKey2() | InitRS485() | RS485Transmit() |
| Baud1AtStartup() | InitSerial2() | Serial1AtStartup() |
| Baud2() | Key() | Serial2AtStartup() |
| Beep() | Key1() | TRANSMITTING |
| Cr() | Key2() | UseSerial1() |
| DisableSerial2() | NumInputChars() | UseSerial2() |
| Emit() | NumOutputChars() | _peekTerminal() |
| Emit1() | PARITY | _readChar() |
| Emit2() | PARITY_IN | _readTerminal() |
| ForthAskKey() | PARITY_OUT | _writeChar() |
FLASH.H
HEAP.H
| DEFAULT_HEAPEND | FromHeap() | Room() |
| DEFAULT_HEAPSTART | INIT_DEFAULT_HEAP() | ToHeap() |
| DupHeapItem() | IsHeap() | TransferHeapItem() |
INTERUPT.H
| ATTACH() | IC3_ID | PULSE_EDGE_ID |
| Attach() | IC4_OC5_ID | PULSE_OVERFLOW_ID |
| CLOCK_MONITOR_ID | ILLEGAL_OPCODE_ID | RTI_ID |
| COP_ID | IRQ_ID | SCI_ID |
| DISABLE_INTERRUPTS() | OC1_ID | SPI_ID |
| ENABLE_INTERRUPTS() | OC2_ID | SWI_ID |
| IC1_ID | OC3_ID | TIMER_OVERFLOW_ID |
| IC2_ID | OC4_ID | XIRQ_ID |
INTRFACE.H
| AskKeypad() | DisplayOptions() | PutCursor() |
| AskKeypress() | DISPLAY_HEAP | ScanKeypad() |
| BufferPosition() | GARRAY_XPFA | ScanKeypress() |
| CharsPerDisplayLine() | InitDisplay() | StringToDisplay() |
| CharToDisplay() | IsDisplay() | STRING_TO_DISPLAY() |
| ClearDisplay() | IsDisplayAddress() | UpdateDisplay() |
| CommandToDisplay() | Keypad() | UpdateDisplayLine() |
| DisplayBuffer() | LinesPerDisplay() | UpdateDisplayRam() |
MTASKER.H
| Activate() | Halt() | SEND() |
| ACTIVATE() | InitElapsedTime() | Send() |
| AD8_RESOURCE | InstallMultitasker() | SERIAL |
| ASLEEP | Kill() | SERIAL1_RESOURCE |
| AWAKE | MAILBOX | SERIAL2_RESOURCE |
| BuildTask() | MicrosecDelay() | SPI_RESOURCE |
| BUILD_C_TASK() | Pause() | StartTimeslicer() |
| ChangeTaskerPeriod() | ReadElapsedSeconds() | StopTimeslicer() |
| FMAILBOX | RECEIVE() | TIMESLICE_COUNT |
| FORTH_TASK | Receive() | TryToFSend() |
| FRECEIVE() | RELEASE() | TryToGet() |
| FReceive() | Release() | TryToSend() |
| FSEND() | RELEASE_AFTER_LINE | TRY_TO_FSEND() |
| FSend() | RELEASE_ALWAYS | TRY_TO_GET() |
| GET() | RELEASE_NEVER | TRY_TO_SEND() |
| Get() | RESOURCE |
NUMBERS.H
| FILL_FIELD | FP_QtoC() | RANDOM_SEED |
| FIXED() | LEFT_PLACES | RIGHT_PLACES |
| FLOATING() | MANTISSA_PLACES | SCIENTIFIC() |
| FPtoString() | NO_SPACES | TRAILING_ZEROS |
| FP_CtoQ() | PrintFP() | |
| FP_FORMAT | Random() |
QEDREGS.H
See the QEDREGS.H file. All registers are named using the standard names as described in the Motorola 68HC11F1 documentation. | ||||
| DDRA | DDRD | PORTA | PORTD | PORTE |
QEDSYS.H
| Abort() | DefaultRegisterInits() | NoVitalIRQInit() |
| Autostart() | Execute() | PriorityAutostart() |
| Breakpoint() | InitVitalIRQsOnCold() | StandardReset() |
| Cold() | InstallRegisterInits() | SysAbort() |
| ColdOnReset() | NoAutostart() | Warm() |
STEPPER.H
TYPES.H
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
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 |
V4_4UPDATE.H
XMEM.H
| AddXaddrOffset() | FetchLong() | StoreFloat() |
| ChangeBits() | FetchLongProtected() | StoreFloatProtected() |
| ClearBits() | FillMany() | StoreInt() |
| CmoveMany() | SetBits() | StoreLong() |
| CountedString() | StoreChar() | StoreLongProtected() |
| FetchChar() | StoreEEChar() | StringMove() |
| FetchFloat() | StoreEEFloat() | ToggleBits() |
| FetchFloatProtected() | StoreEEInt() | XaddrDifference() |
| FetchInt() | StoreEELong() |
QED-Forth debugger and system configuration functions
| Assignment, Fetching and Function Calling | ||
|---|---|---|
| =CHAR | CHAR | INT |
| =FLOAT | CHAR* | INT* |
| =INT | DO[] | LONG |
| =LONG | FLOAT | LONG* |
| CALL.CFN | FLOAT* | |
| EEPROM Storage | ||
|---|---|---|
| (EE!) | (EEC!) | |
| (EE2!) | (EEF!) | |
| Hex Dump and Receive | ||
|---|---|---|
| DUMP | DUMP.S1 | RECEIVE.HEX |
| DUMP.INTEL | DUMP.S2 | |
| Numeric I/O | ||
|---|---|---|
| . | FP_CtoQ | PrintFP |
| D. | FP_QtoC | U. |
| DECIMAL | HEX | |
| Operating System and Memory Management | ||
|---|---|---|
| ABORT | ENABLE.DOWNLOAD | SERIAL2.AT.STARTUP |
| ALL.TO.FLASH | INIT.VITAL.IRQS.ON.COLD | SET.BOOT.VECTOR |
| AUTOSTART | INSTALL.REGISTER.INITS | SP! |
| BAUD1.AT.STARTUP | MAIN | STANDARD.MAP |
| BAUD2 | NO.AUTOSTART | STANDARD.RESET |
| CALC.CHECKSUM | NO.VITAL.IRQ.INIT | TO.FLASH |
| CFA.FOR | PAGE.TO.FLASH | USE.SERIAL1 |
| CLEAR.BOOT.VECTOR | PAGE.TO.RAM | USE.SERIAL2 |
| COLD | PRIORITY.AUTOSTART | WARM |
| COLD.ON.RESET | RESTORE | WHICH.MAP |
| DEFAULT.REGISTER.INITS | SAVE | WORDS |
| DOWNLOAD.MAP | SERIAL1.AT.STARTUP | |
Functions that disable interrupts
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:
| ChangeBits() | ClearBits() | FetchFloatProtected() | SetBits() |
| StoreFloatProtected() | FetchLongProtected() | StoreLongProtected() | ToggleBits() |
Accessing the LCD display require the insertion of wait states, and the computer architecture requires that interrupts be disabled while a wait state memory access is in progress. The following routines disable interrupts to insert wait states:
| AskKeypad() | AskKeypress() | CharToDisplay() |
| ClearDisplay() | CommandToDisplay() | DisplayOptions() |
| InitDisplay() | IsDisplayAddress() | Keypad() |
| PutCursor() | ScanKeypad() | ScanKeypress() |
| StringToDisplay() | STRING_TO_DISPLAY() | UpdateDisplay() |
| UpdateDisplayLine() | UpdateDisplayRam() |
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:
| FRECEIVE() | FReceive() | FSEND() | FSend() |
| GET() | Get() | RECEIVE() | Receive() |
| SEND() | Send() | TryToFSend() | TryToGet() |
| TryToSend() | TRY_TO_FSEND() | TRY_TO_GET() | TRY_TO_SEND() |
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:
| BuildTask() | BUILD_C_TASK() |
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:
| ForthEmit() | ForthKey() | Emit() | Emit1() | Emit2() |
| Key() | Key1() | Key2() | Keypad() | ScanKeypad() |
The following device driver routines GET() and RELEASE() resource variables, and so disable interrupts for short periods of time:
| AD8Multiple() | AD8Sample() | AD8ToBuffer() |
| AskKey() | AskKey1() | AskKey2() |
| Emit() | Emit1() | Emit2() |
| ForthAskKey() | ForthEmit() | ForthKey() |
| Key() | Key1() | Key2() |
| PauseOnKey() | ReadWatch() | SetWatch() |
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:
| StoreEEChar() | StoreEEFloat() | StoreEEInt() | StoreEELong() |
These routines are smart enough to avoid programming a byte that already has the correct contents. The following routines may modify EEPROM locations:
| ATTACH() | Attach() | Autostart() |
| ColdOnReset() | DefaultRegisterInits() | DownloadMap() |
| InitVitalIRQsOnCold() | InstallMultitasker() | InstallRegisterInits() |
| IsDisplay() | NoAutostart() | Serial1AtStartup() |
| Serial2AtStartup() | StandardMap() | StandardReset() |
| StartTimeslicer() |
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:
PageToFlash() PageToRAM() ToFlash()
The following routines disable interrupts and do not re-enable them:
Cold() DISABLE_INTERRUPTS() Warm()
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.
Comparison with prior QED-Forth firmware
This section summarizes the changes to the V4.4x operating system firmware compared to the prior V4.08 firmware.
The QCard, QScreen Controller, and QED Handheld operating system firmware carries the version number V4.4x, where x represents a numeric value. Customers who are familiar with the prior V4.08 operating system software will notice that certain device driver functions have been removed from V4.4x because the corresponding hardware is not present. These functions comprise the hardware drivers for the 12-bit A/D, D/A, PIA, and high current drivers. We recommend the use of the many available WildCard I/O modules and their associated pre-coded kernel extension device drivers to add customized I/O to meet the needs of your application.
The V4.4x keypad scanner and character/graphics display drivers are available to support an optional Keypad/Display WildCard. These kernel-resident drivers work only if the Keypad/Display WildCard is assigned a WildCard module address of 0. On the QCard, this is accomplished by installing the Keypad/Display WildCard on module header 0, and leaving the jumper caps off the WildCard’s two on-board jumpers. The QScreen and Handheld products come complete with a graphical user interface that is controlled by pre-coded drivers.
The ReadWatch() and SetWatch() functions are backwardly compatible with prior versions, but they rely on different real-time clock hardware as described in their glossary entries.
The V4.4x kernel boots up at 19200 baud, compared to 9600 baud on many earlier products based on the V4.08 kernel.
Accessing the additional functions
The following QED-Forth functions have been added to the Forth debugging glossary:
| ALL.TO.FLASH | CALC.CHECKSUM | CLEAR.BOOT.VECTOR | ENABLE.DOWNLOAD | SET.BOOT.VECTOR |
The following five C-callable functions have been added:
| BufferToSPI() | BytesToDisplay() | CalcChecksum() | ClearBootVector() | SetBootVector() |
No additional software is needed to access the new functions using interactive Forth commands, as they are built into the kernel.
C programmers must include the files named v4_4update.c and v4_4update.h to gain access to the five new C-accessible functions. These files are located in the \Mosaic\Fabius\Include\Mosaic\v4_4Updatedirectory in the software distribution CD. Simply #include both the v4_4update.h and v4_4update.c files in one of your source files, and also #include v4_4update.h in any other source files that use these new kernel routines.
Summary of modified functions
A set of operating system functions makes it easy to manage the downloading of code into RAM and the transfer of the compiled code to flash. This is performed automatically by the Mosaic C IDE (Integrated Development Environment), so C programmers need not be aware of the details. For those who are interested, the Forth debugging glossary entries for the functions STANDARD.MAP, DOWNLOAD.MAP, TO.FLASH, PAGE.TO.FLASH and PAGE.TO.RAM describe how the new expanded amounts of flash memory are managed. The QCard has flash at pages 4-7 that swaps with RAM on parallel pages 1-3, plus flash at hex pages 10-17 that swaps with RAM on parallel hex pages 18-1F. In the "download map", flash and RAM are swapped: flash is present on pages 1-3 and 18-1F, and RAM is present on pages 4-6 and 10-17. On the QScreen Controller and Handheld, TO.FLASH can program the optional flash memory at pages 0x20-2F. The great majority of applications compile to less than 96 KBytes of code, which fits on pages 4, 5 and 6. For these applications, the new functions ENABLE.DOWNLOAD and ALL.TO.FLASH greatly simplify the downloading process. Simply insert the command ENABLE.DOWNLOAD at the top of the first file to be downloaded to the QCard. This function makes sure that any previously downloaded code is transferred to RAM, and calls DOWNLOAD.MAP to ensure a RAM-based memory map that enables compilation of code. At the end of the last file to be downloaded, insert the command ALL.TO.FLASH. This copies the compiled code in pages 4, 5 and 6 to flash, sets the STANDARD.MAP, and calls SAVE so that the RESTORE command can be used to recover after a crash or a COLD restart during the development process.
To support a "bullet-proof" kernel extension to enable firmware upgrades, an optional "boot vector" is implemented using the SET.BOOT.VECTOR operating system function. This allows the posting of a function that is executed before the autostart program is run; see the Forth debugging glossary entry of SET.BOOT.VECTOR for details. The boot vector and its code are located on page 0x0C, a page that can be hardware write protected with the "page-C write protect" jumper. Removal of the boot vector is accomplished by invoking CLEAR.BOOT.VECTOR or by using the special cleanup mode described in the hardware documentation.
The AskKeypad(), AskKeypress() and Keypad() functions have been upgraded to support more than 20 keys. They work identically to prior versions for keys 0 through 19, but add support for an additional 20 keys with numbers 20 through 39.
InitSPI() now configures the SPI to sample data on the falling trailing edge of the SPI clock. This is consistent with the data transfer protocol of the on-board battery-backed real-time clock. The user may freely change the SPI configuration to meet the needs of the application program.
When using the Forth debugger tools, numbers can now have a leading 0x or 0X to indicate that the numbers are hexadecimal.