Introduction

This section describes the ROM (flash) libraries and drivers that provide high level I/O services and C wrapper functions for your Persistor applications. These functions live in 192 KB of lower flash and use 32 KB of RAM near the base of the SRAM. 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.

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:

BIA	BigIDEA IDE Driver
BSD	Block Storage Device Functions
DBR	DOS Boot Record Functions
DIR	DOS Directory Functions
DSD	DOS Storage Device Functions
MBR	Master Boot Record Functions
PDX	PDX POSIX-Like Functions
PZ	PicoZOOM Functions
PPB	Ping-Pong Buffer Functions
PWR	Power Management Drivers and Functions
QR	Query/Reply Functions
QPB	Queued PicoBUS (QSPI) Drivers and Functions
SCB	SandwichCard Bus Driver
SCS	SandwichCard Supervisor Driver
SSD	Sector Storage Device Functions
CMD	Table Driven Command Processor
UTIL	Utility Functions
VEE	Virtual EEPROM Functions

API Functions

All of the driver and operating system services are contained in 256KB 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.  

<cf1pico.h>

The header file <cf1pico.h> is the other main link to the API. This include file is your primary interface to the PicoDOS 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.

Previous

Next

Top

Contents

Glossary

Index

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