Quick Reference Table

QPBClearInterrupt	QPBNotifyPostClockChange	QPBTestBusy
QPBFreeSlot	QPBNotifyPreClockChange	QPBTestLocked
QPBInit	QPBRepeatAsync	QPBTestRunning
QPBInitSlot	QPBReset	QPBTransact
QPBLockSlot	QPBSetup	QPBUnlockSlot

Background

PicoBUS defines the electrical, mechanical, and software specifications for a versatile interconnect system tailored to the rapid development of miniature, low power, custom instruments using SPI based controllers and peripherals. SPI stands for Serial Peripheral Interface and it defines a standard, high-speed, four-wire synchronous serial communications protocol. QSPI stands for the advanced queued version of SPI. The functions in this section of the reference describe the high level APIs offered by Persistor Instruments Inc. for making these peripheral interfaces easy to use.

We make use of several support structures and mechanisms. We recommend familiarizing yourself with the QPB and QPBDev structures outlined in cf1pico.h before using them here. Also when setting up your specific devices, pay attention to the clock phase and clock polarity enums we have provided (types cpol and cpha respectively.

QPBClearInterrupt -- Clear the QPB interrupt flag

When operating asynchronously, the function specified by the asynchf argument to either QPBSetup or QPBTransact, will be called upon completion of the transaction. This function must be called by the handler function so that the interrupt flag that forced the execution of the completion routine is cleared. If the flag is not cleared, then the completion routine will be executed for ever.

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

QPBFreeSlot -- Remove a PicoBUS device slot

QPBFreeSlot removes a device installed previously by QPBInitSlot. It also frees all memory allocated in relation to the device's QPBDev structure.

Prototype:	void QPBFreeSlot(QPBDev *qbpd);
Definition:	#include <cf1pico.h>
Notes:
Timing:	Timing-TBD

QPBInit -- Initialize the PicoBUS driver

Unlike the other initialization functions, this function needs to be called by your application if you wish to use the queued PicoBus. This is because once called, the behavior of any custom QSPI code is unpredictable and calling this function precludes the QSPI pins from use as I/O pins until a reset occurs. If the CF1 is being used in slave mode, then only the PCS0 pin is precluded from use as general I/O.

Prototype:	void QPBInit(bool master);
Definition:	#include <cf1pico.h>
Inputs:	The boolean master specifies whether the CF1 will be the master device or a slave device on the PicoBus.
Notes:	It is important to note that initializing the QPB as a master causes certain I/O lines to be driven as outputs. This can be dangerous if other devices are trying to drive these lines. Be sure to correctly specify the master/slave setting with respect to your other devices.
Timing:	approx. 40 µsecs @16 MHz 0ws

QPBInitSlot -- Initialize a PicoBUS device slot

This function takes device information that you provide in the QPBDev structure and initializes one of the QPB's 14 slots for use with that specified device. It is important to bear in mind however that using all 14 slots or arbitrarily picking slot numbers requires external multiplexing hardware. This hardware is discussed in (where).

Prototype:	QPB *QPBInitSlot(QPBDev *qbpd);
Definition:	#include <cf1pico.h>
Inputs:	qbpd is a QPBDev structure filled in by the user that will be assigned a slot for use in the QPB.
Returns:	Returns a pointer to a QPB structure that will be used when transacting with the device.
Notes:
Timing:	Timing-TBD

QPBLockSlot -- Lock the PicoBus for use by a particular slot.

This function allows one "slot" to lock the entire PicoBus for exclusive use. It is necessary to lock the bus when performing asynchronous reads using QPBRepeatAsynch.

Prototype:	bool QPBLockSlot (QPB *qpb);
Definition:	#include <cf1pico.h>
Inputs:	qpb is a pointer to the slot structure you wish to own the lock.
Returns:	Returns true if the bus locked or false if it was unable to lock.
Notes:
Timing:	Timing-TBD

QPBNotifyPostClockChange -- Update the SPI timing

This function allows the QPB to respond after a change in system clock. This function would not be called by a user application but rather is called automatically and is included here in the interest of a complete function reference and possibly for future patching of the clock change routines. This function in combination with QPBNotifyPreClockChange will recalibrate the baud rates for any slots/devices whose original QPBDev descriptor requested baud rate auto recalibration.

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

QPBNotifyPreClockChange -- Prepare the SPI for a pending clock change

This function prepares the QPB for a change in system clock. This function would not be called by a user application but rather is called automatically and is included here in the interest of a complete function reference and possibly for future patching of the clock change routine. This function in combination with QPBNotifyPostClockChange will recalibrate the baud rates for any slots/devices whose original QPBDev descriptor requested baud rate auto recalibration.

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

QPBRepeatAsync -- Execute a pre-set-up asynchronous transfer

This function executes a transaction on the PicoBus. The parameters of the transfer must have been first setup with QPBSetup or the call will fail an because it is an inline assembly macro with no return values or parameters, you will have little or no non-catastrophic indication of failure. The advantage of using QPBSetup with QPBRepeatAsync is that it allows the developer to reach the highest data rates ont he QPB. The other calls have much overhead but also provide more funcitonality. Furthermore the slot you wish to use QPBRepeatAsync with must be locked first with QPBLockSlot.

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

QPBReset -- Reset the Queued PicoBus

This function resets the PicoBus. This not only purges any setup information needed for asychronous transactions (See QPBSetup) but also resets all of the hardware QSM lines to their functions as general I/O lines and configures them as inputs.

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

QPBSetup -- Set up the QPB for future asynchronous transfers

This function sets up all of the internal registers of the PicoBus and prepares for an asychronous transaction. QPBTransact calls this function everytime it is called, but in a synchronous mode.

Prototype:	bool QPBSetup(QPB *qpb, vfptr asynchf, ushort count, ushort *spidata);
Definition:	#include <cf1pico.h>
Inputs:	qpb is the QPB structure that corresponds to the slot of the desired device. The device must either be unlocked or the lock must belong to the QPB struct passed here. asynchf is a volatile function pointer to the handler to be called when an asynchronous read completes. count is the number of 16 bit words that will be passed in the variable arguments. The maximum number of of words to be passed is 16, making count's maximum 16 also. spidata is a pointer to the data for the transaction.
Returns:	Returns true if the requested setup could be performed.
Notes:
Timing:	Timing-TBD

QPBTestBusy -- Set up the QPB for future asynchronous transfers

This functions allow you to test whether or not a transaction (obviously an asynchronous one) is currently occurring on the QPB. If the QPB is busy a pointer to the "owning" slot is returned, otherwise the function should return NULL.

Prototype:	QPB *QPBTestBusy (void);
Definition:	#include <cf1pico.h>
Returns:	Returns a pointer to the QPB structure that is currently transacting or NULL if the bus is free.
Notes:
Timing:	Timing-TBD

QPBTestLocked -- See if the QPB is locked

This functions allow you to test whether or not the QPB is currently locked. If it is locked, a pointer to the QPB structure that currently has the lock is returned. If the bus is not locked, the function should return NULL.

Prototype:	QPB *QPBTestLocked (void);
Definition:	#include <cf1pico.h>
Returns:	Returns a pointer to the QPB structure that is currently locking or NULL if the bus is free.
Notes:
Timing:	Timing-TBD

QPBTestRunning -- See if the QPB is locked

This functions allow you to test whether or not the QPB is currently executing a transaction. The return value will be 0 is there are no transactions currently occurring on the bus or non-zero if there are.

Prototype:	short QPBTestRunning (void);
Definition:	#include <cf1pico.h>
Returns:	Returns zero if the bus is not running a transaction and non-zero if it is.
Notes:
Timing:	Timing-TBD

QPBTransact -- Conduct a PicoBUS session

This function executes a transaction on the QPB. This function takes data as an array of up to 16 words (which are 16 bits wide in the 338 but each word will be truncated to your device's word size before transacting. In other words if you want to send 8 words to a device with an 8 bit word length, you would put 8 shorts with padded MSBs into spidata.) The QPB structure returned by QPBInitSlot designates which device is to receive the transaction and the count is the number of 16 bit words(up to 16) to read off the stack to be transmitted. You may also make this call asynchronous by providing a pointer to a completion routine in the asynchf parameter.

Prototype:	short *QPBTransact(QPB *qpb, vfptr asynchf, ushort count, ushort *spidata);
Definition:	#include <cf1pico.h>
Inputs:	qpb is the QPB structure that corresponds to the slot of the desired device. The device must either be unlocked or the lock must belong to the QPB struct passed here. asynchf is a volatile function pointer to the handler to be called when an asynchronous read completes. If it is 0 then the call will be synchronous. count is the number of 16 bit words that will be passed in the variable arguments. The maximum number of of words to be passed is 16, making count's maximum 16 also. spidata is a pointer to the data for the transaction.
Returns:
Notes:
Timing:	Timing-TBD

  QPBUnlockSlot -- Unlock PicoBus for unrestricted use.

This function allows you to unlock the PicoBus after it has been locked by a specific slot. See QPBLockSlot for more information. It is necessary to lock the bus when performing asynchronous reads using QPBRepeatAsynch.

Prototype:	bool QPBUnlockSlot (QPB *qpb);
Definition:	#include <cf1pico.h>
Inputs:	qpb is a pointer to the slot structure that owns the current lock
Returns:	Returns true if the bus was successfully unlocked or false if it was unable to unlock or the given QPB structure was not the owner of the lock..
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