Introduction

This section describes the ROM (flash) libraries and drivers that provide basic I/O services and C wrapper functions for your Persistor applications. Most of the low level APIs live in 32 KB of low flash and use 16 KB of RAM at the base of the SRAM. Certain portions of the API are contingent upon PicoDOS's presence and indicate this fact by including cf1pico.h. The API functions are accessed using C calling conventions through a fixed table in low RAM, and are not compiler specific, though non-Metrowerks systems will need to be aware of register usage and parameter/return conventions.

You will generally access the APIs after they have been initialized by PicoDOS (which makes extensive use of the API), but they are self-contained and independent of any other software, so you don't have to have PicoDOS installed or running to take advantage of most of the API services.

There are several hundred functions and macros that make up the Persistor API, but the majority of these exist to support PicoDOS and the standard C library and it's through these that most programmers will indirectly make use of the APIs. We suggest that you approach your program design by relying first on standard C functions, then moving into the Persistor APIs as necessary.

The routines in this section are grouped according to function, which, not coincidentally, also groups them somewhat alphabetically, as most API function names begin with their group identifier. This table below is your link to the full descriptions:

ATA	AT Attachment (CompactFlash) Device Drivers
BIOS	BIOS Initialization and Coordination Functions
CF	CompactFlash Low Level Drivers
CRC	Checksums and Cyclic Redundancy Check Functions
CS	Chip Select Wrapper Functions
CTM	Counter Timer Module Wrapper Functions
Flash	Flash Memory Functions
IEV	Interrupt and Exception Vector Wrapper Functions
LED	LED Signal Functions
PIO	Pin I/O Drivers, Functions, and Macros
PIT	Periodic Interrupt Timer Functions
RTC	Real Time Clock Drivers and Functions
SCI	Serial Controller Interface Drivers and Functions
TMG	System Clock Tming Functions

API Functions

All of the driver and operating system services are contained in 64KB at the base of the flash. Your application access these services using what appear to be convention C function calls, but which are actually short (six byte) inline macros which vector through a driver table contained in RAM. This technique offers the following advantages:

• Patchable Driver Functions
• Small Application Footprints
• Guaranteed Services
• Shared Services
• Fastest Call and Return Times

Each and every driver functions is fully patchable by your application. This extends even to other ROMmed driver functions that reference the patched driver. This implies that you can head or tail patch low level driver functions and have the effect ripple through to the higher level driver functions. For instance, you could head patch the RS232 routine (SCIRxRingBuffer) that moves data from the SCI UART to the queue buffers to filter incoming characters for sequence detection or replacement. With that in place, you're guaranteed to have first dibs on any incoming serial data, no matter who's next in line.

Because all of the driver software is ROMmed, your applications have a smaller footprint than if each had to link in the driver function object code, and the full compliment of system services are always guaranteed to be available. This results in smaller files, shorter load times, and more applications that be resident at any one time. Finally, this mechanism is fast, especially when compared to the trap mechanisms often used for operating system services. We add about 0.5us at 16MHz and less than 1 us at 8MHz over the fastest possible intra-function call that would come with direct linkage.

After the constants and typedefs in <cf1bios.h> comes the table of functions that your Persistor application uses to access driver system services. The table is constructed at compile time using several macros that precede the table. Most users will never need to know how this actually works, but since we force you to see this construct every time you scan through <cf1bios.h>, we thought some of the more curious programmers would like to know what's going on. If this is your first introduction to the CF1, we strongly recommend that you skip over the Driver Table Details, and perhaps revisit this section after you've discovered that the rest of the operating system software is much more simple.  

<cf1bios.h>

The header file <cf1bios.h> is the other main link to the API. This include file is your primary interface to the Persistor CF1 API. Every accessible function, and all of the necessary definitions are contained in this source file. Ideally, this file would only contain descriptions needed to let you build CF1 applications, but the header file also needs to provide additional to be useful to compilers, so you will often need to skim over the irrelevant portions to get to the gems of information.

All of the source files you compile for the Persistor which make use of BIOS or PicoDOS utility functions will want to include this file at, or very near the top of the source file. You can safely include this in other header files that rely on PicoDOS services, as it incorporates mechanisms to prevent multiple inclusion confusion. The reason to place this as the first include file, is to ensure that important definitions that relate to the hardware are correctly defined for the CF1.

You should never make modifications to this file. Tailor you application with custom header files that live in your project or private directories. Every time we issue an update to the driver or PicoDOS software, this header is likely to change. When you install the updates, they will overwrite the old <cf1bios.h> and obliterate any customizations you may have made.

While on the subject of changes, we will generally limit changes to the header file to include new features or capabilities that should not break your existing application - but this is not guaranteed. We will publish and maintain documentation describing what changed, when, why, and how to accommodate the changes, but you must take responsibility for creating archives and backups of all of your project build materials each time you release a new version of your application.

Standard Typedefs

The header file <cf1bios.h> opens with an abbreviated memory map of low ram where important globals and BIOS addresses are maintained. This is there primarily for the compiler and you will seldom, if ever, need to reference these directly. The map constants are followed by a block of standard typedefs that are used extensively by the API and PicoDOS. These are primarily abbreviations for the unsigned and volatile types which find lots of use in embedded controllers. The entire block is bracketed for conditional compilation with the definition VU-TYPES, and each sub-block is similarly bracketed to let <cf1bios.h> better coexist with older code that may collide with our naming conventions.

//--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--
//  typedefs    (used extensively by BIOS and PicoDOS functions)
//--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--
#ifndef     VU_TYPES
    #ifndef UCHAR
      typedef unsigned char     uchar;          // 8 bits, 0..255
      typedef volatile uchar    vuchar;         // "" "" volatile 
      typedef vuchar            *vucptr;        // "" "" pointer to
     #define UCHAR uchar
    #endif
    
    #ifndef USHORT
      typedef unsigned short    ushort;         // 16 bits, 0..65535
      typedef volatile ushort   vushort;        // "" "" volatile 
      typedef vushort           *vusptr;        // "" "" pointer to
     #define USHORT ushort
    #endif
    
    #ifndef ULONG
      typedef unsigned long     ulong;          // 32 bits, 0..4,294,967,296
      typedef volatile ulong    vulong;         // "" "" volatile
      typedef vulong            *vulptr;        // "" "" pointer to
     #define ULONG ulong
    #endif
    
    #ifndef VPTR
      typedef void              *vptr;          // generic pointer
      typedef void              vfv(void);      // generic void function
      typedef   vfv             *vfptr;         // "" "" pointer to
     #define VPTR vptr
    #endif
    
    #ifndef BOOL
      typedef enum {
        false = 0,      no = 0,     off = 0,    failure = 0,
        true = 1,       yes = 1,    on = 1,     success = 1
        }   bool;
     #define BOOL bool
    #endif
    
    #define VU_TYPES
#endif

Previous

Next

Top

Contents

Glossary

Index

Tel: 508-759-6434		Fax: 508-759-6436
Copyright (C) 1998 Persistor Instruments Inc. - All Rights Reserved