Link here

C v4.4 Function Summary

A subject sorted list of all Control-C library functions

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:

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 this index
To see a definition of any of the functions listed on this page simply click on the function name and a definition from the appropriate glossary should popup. You can also go directly to the C V4.4 Function Glossary or the C V4.4 Interactive Debugger Glossary for full definitions.
 

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:

  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.

  1. A detailed definition of what the routine does.
  2. A Type: field that specifies whether the routine is a _forth function, a C function, a macro, a constant, or a typedef.
  3. 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.
  4. 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

DownloadMap() PageToRAM() ToFlash()
PageToFlash() StandardMap() WhichMap()
 

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

CreateRamp() SpeedToDuty() StepManager()
 

TYPES.H

EXTENDED_ADDR THIS_PAGE _Q
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() MAX() TRUE
FALSE MIN()
 

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

BufferToSPI() CalcChecksum() SetBootVector()
BytesToDisplay() ClearBootVector()
 

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.

 
This page is about: Sorted List of Embedded C Library Functions, Embedded C Functions for 68HC11 Microcontroller, C Tutorial, C Debugger and MCU Configuration Functions, C Functions that Disable Interrupts – Provides subject sorted lists of the C language library functions for Mosaic's controllers based on the Freescale 68HC11 microcontroller, including debugger and MCU configuration functions and functions that disable interrupts. C language software development, C functions for microcontroller I/O, C library routines, embedded commands, 68HC11 C language reference, C RTOS, embedded C debugging, embedded c language tutorial, embedded c library functions, embedded c functions, embedded c operating system, embedded c RTOS, embedded c runtime library, embedded c programming language, embedded C tutorial, embedded C language tutorial
 
 
Navigation