Quick Reference Table

BIOSAddChore	_BIOSPatchInsert	BIOSResetToPBM
BIOSGetSerNum	BIOSPatchInsert	BIOSResetToPicoDOS
_BIOSHandlerAddress	BIOSRemoveChore	BIOSReturn
BIOSHandlerAddress	BIOSReset	BIOSVersionCheck
BIOSInit	BIOSResetToAddress

Background

  BIOSInit -- Initialize the BIOS (usually performed automatically by PicoDOS)

This function is called by the BIOS on power on or reset. It ploads and prepares all of the BIOS globals outlined in cf1bios.h for use by various programs. A user application will never need to call this function and it is included here for completeness.

Prototype:	void BIOSInit(void);
Definition:	#include <cf1bios.h>
Notes:
Timing:	Timing-TBD

BIOSVersionCheck -- Confirm application and BIOS compatability

This function exists to help programs determine at runtime if they are compatible with the currently installed version of the BIOS. By calling this function with the version information from the initial build of the software, a developer can make a runtime determination of the ability or lack thereof of their program to run on that specific Persistor.

Prototype:	bool BIOSVersionCheck(short ver, short rel, char *id, bool reset);
Definition:	#include <cf1bios.h>
Inputs:	ver is the major release number of the BIOS at build time rel is the minor release number of the BIOS at build time id reset nnn
Returns:	Returns true if the parameters supplied match the currently installed version of the BIOS, false otherwise.
Notes:
Timing:	Timing-TBD

BIOSGetSerNum -- Return the CF1 Serial Number

This function returns the serial number of the CF1 on which it is running. This funciton could be used fro a simpler form of license checking in the event of binary distribution. The serial number is burned into ROM and cannot be changed without destroying the CF1.

Prototype:	long *BIOSGetSerNum(void);
Definition:	#include <cf1bios.h>
Returns:	Returns a pointer to the serial number of the CF1
Notes:
Timing:	Timing-TBD

BIOSReturn -- Simple BIOS call that just returns to test and compare call timing overhead

This call is without practical function but exists to test the calling overhead of BIOS functions Because all BIOS calls are dispatched from a jump table to allow better update compatibility, several extra instructions are added to handle the dispatch table. This function can be used to test the effect of this overhead at any CPU speed or wait state configuration.

Prototype:	void BIOSReturn(void);
Definition:	#include <cf1bios.h>
Notes:
Timing:	Timing-TBD

BIOSReset -- Reset the Persistor

This function forces a hard hardware reset which include assertion of the external /RESET signal. On completion, the CF1 will take whatever reset action has been ordered by the PBM boot command. If the reset action goes beyond entering PBM, the BIOS will be completely re-initialized. If PicoDOS is invoked, PicoDOS will also be completely re-initialized.

This is the cleanest way to terminate a running application if the BIOS or PicoDOS vectors have been altered or you want to guarantee the state of the hardware for the next program run.

Prototype:	void BIOSReset(void);
Definition:	#include <cf1bios.h>
Notes:
Timing:	Timing-TBD

BIOSResetToPBM -- Reset the Persistor and force to PBM

This function resets the Persistor as described for the BIOSReset() function above, but forces the CF1 to enter and stay in PBM regardless of the boot settings.

Prototype:	void BIOSResetToPBM (void);
Definition:	#include <cf1bios.h>
Notes:
Timing:	Timing-TBD

BIOSResetToPicoDOS -- Reset the Persistor and force to PicoDOS

This function resets the Persistor as described for the BIOSReset() function above, but forces the CF1 to jump to 0xE10000 (PicoDOS) regardless of the boot settings.

Prototype:	void BIOSResetToPicoDOS (void);
Definition:	#include <cf1bios.h>
Notes:
Timing:	Timing-TBD

BIOSResetToAddress -- Reset the Persistor and jump to specified address

This function resets the Persistor as described for the BIOSReset() function above, but forces the CF1 to jump to the specified address regardless of the boot settings.

Prototype:	void BIOSResetToAddress (ulong target);
Definition:	#include <cf1bios.h>
Inputs:	target is the address you wish the persistor to boot to on the reset that will occur when this function is called.
Notes:
Timing:	Timing-TBD

_BIOSHandlerAddress -- Return a BIOS handlers actual address
BIOSHandlerAddress -- Return a BIOS handlers actual address

The BIOSHandlerAddress macro invokes the _BIOSHandlerAddress function to return the absolute address of the function that currently installed in the BIOS jump table to handle a specific BIOS API function. The drvrid argument to _BIOSHandlerAddress() is a non-obvious enumeration constant corrosponding to the relative location of the target API function in the BIOS function list at the top of <cf1bios.h>. You're much better off using the BIOSHandlerAddress macro which lets you simply specify the name of the API function whose address you want to find.

Prototype:	vptr _BIOSHandlerAddress(short drvrid);
Definition:	#include <cf1bios.h>
Inputs:	drvrid is the driver table id of the function whose address you seek. See cf1bios.h
Returns:	Returns the address in the specified slot of the driver table.
Notes:	1. use the BIOSHandlerAddress macro instead of the function call 2. see PICOHandlerAddress for similar operations with PicoDOS functions
Timing:	Timing-TBD

The example below shows how your application code might switch between the built-in SCI UART and some other I/O device using global function pointers and BIOSHandlerAddress macro/function inside of an initialization routine. The three necessary function pointers are declared at the top in global space, then initialized by a call to SerialOpen(). The BIOSHandlerAddress macro/function always returns pointer of type vfptr (defined in <cf1bios.h>) and these must be cast to the correct types to keep the compiler from complaining.

void (* SerialPutByte)(ushort data);
short (* SerialByteAvail)(void);
short (* SerialGetByte)(void);

//  SerialOpen()
void SerialOpen(bool sciuart)
    {
    if (sciuart)
        {
        SerialPutByte = (void (*)(ushort)) BIOSHandlerAddress(SCITxPutChar);
        SerialByteAvail = (short (*)(void)) BIOSHandlerAddress(SCIRxQueuedCount);
        SerialGetByte = (short (*)(void)) BIOSHandlerAddress(SCIRxGetChar);
        }
    else
        {
        extern void AuxPutByte(ushort data);
        extern short AuxByteAvail(void);
        extern short AuxGetByte(void);
        
        SerialPutByte = AuxPutByte;
        SerialByteAvail = AuxByteAvail;
        SerialGetByte = AuxGetByte;
        }

    }   //____ SerialOpen() ____//

_BIOSPatchInsert -- Insert a new handler in the BIOS table
BIOSPatchInsert -- Insert a new handler in the BIOS table

The BIOSPatchInsert macro invokes the _BIOSPatchInsert function to let you patch specific BIOS API functions in the BIOS jump table. The drvrid argument to _BIOSPatchInsert () is a non-obvious enumeration constant corrosponding to the relative location of the target API function in the BIOS function list at the top of <cf1bios.h>. You're much better off using the BIOSPatchInsert macro which lets you simply specify the name of the API function you want to patch.

The nature of the BIOS jump table is described in the Programming API Introduction and the actual mechanism is fully described in the the Driver Table Details.

Prototype:	vptr _BIOSPatchInsert(short drvrid, vptr newf);
Definition:	#include <cf1bios.h>
Inputs:	drvrid is the driver table id of the function you wish to replace. See cf1bios.h newf is a volatile pointer to the new address for the given BIOS routine.
Returns:	Returns the former contents of the specified driver table slot for future reference or for "unpatching."
Notes:
Timing:	Timing-TBD

The following example shows how you might use this capability to give a visual indication of when the calls to fetch UART characters are blocked while waiting for the input character to appear. We patch in a routine that orbits the on-board LEDs. The SCIRxBlocked() routine gets called repeatedly while waiting for data and this happens so quickly that the two LEDs would appear to glow orange. We add a very simple delay loop to slow down the update rate to something that's visible. After the period is typed, we reinstall the original SCIRxBlocked() to make the CF1 return to its normal behavior.

vfptr orgFunction;  // address of original handler

void showBlocked(void);
void showBlocked(void)
    {
    static ushort delay = 0;    // much too fast
    if (--delay == 0)           // without some
        LEDOrbit(true);         // long delay
    }   //____ showBlocked() ____//

void testfunct(void);
void testfunct(void)
    {
    uprintf("\n Testing BIOSPatchInsert \n");
    
    orgFunction = BIOSPatchInsert(SCIRxBlocked, showBlocked);

    while (getch() != '.')
        ;

    BIOSPatchInsert(SCIRxBlocked, orgFunction); // restore

    }   //____ testfunct() ____//

BIOSAddChore -- Add a BIOS interrupt chore

This function exists solely as a helper function for the other chore maintenance stacks and should never be called by a user application. It adds a chore to the internal chore stack.

Prototype:	bool BIOSAddChore(BIOSChore list[], ushort max, vfptr chore, ushort intReqLevel);
Definition:	#include <cf1bios.h>
Inputs:	list is an array of BIOSChore structs to which the chore is to be added max is the maximum number of chores that can be in the list. This is used to index the array of chores. chore is a volatile function pointer to the functio to be executed when the chore is to be done. intReqLevel is the interrupt level at which the chore will be executed. This may be lowered at interrupt time by whatever mechanism controls the interrupts for the given list.
Returns:	Returns TRUE if the chore could be added or FALSE if it could not for any reason.
Notes:
Timing:	Timing-TBD

BIOSRemoveChore -- Remove a bios interrupt chore (NULL vfptr for all)

This function exists solely as a helper function for the other chore maintenance stacks and should never be called by a user application. It removes a chore from the internal chore stack.

Prototype:	bool BIOSRemoveChore(BIOSChore list[], ushort max, vfptr chore);
Definition:	#include <cf1bios.h>
Inputs:	list an array of BIOSChore structs from which the chore is to be removed max is the maximum number of chores that can be in the list. This is used to index the array of chores. chore is the function pointer of the function to be removed from the chore list. If this is NULL all chores will be removed from the given list.
Returns:	Returns TRUE if the chore was successfully removed or FALSE if it could not be found.
Notes:
Timing:	Timing-TBD

Previous

Next

Top

Contents

Glossary

Index

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