Quick Reference Table

PinBus	PinToggle	PIOMirrorList
PinClear	PinWrite	PIORead
PinIO	PIOBusFunct	PIOSet
PinMirror	PIOClear	PIOTestAssertClear
PinRead	PIOEnableErrTrap	PIOTestAssertSet
PinSet	PIOErrorSignal	PIOTestIsItBus
PinTestAssertClear	PIOMaxPin	PIOToggle
PinTestAssertSet	PIOInit	PIOWrite
PinTestIsItBus	PIOMirror

Background

There are essentially two suites of functions in the Pin I/O library. Those starting with PIO are C functions that control the status and behavior or any of the I/O pins on the CF1. These are standard C functions and incur the calling overhead of a C function. Also offered are the functions whose names begin with Pin. These functions are inline assembly macros that shave execution time by an order of magnitude but come with various restrictions. The penalties associated with using these macros are as follows: Firstly they require compile-time literal arguments. In other words you cannot pass a variable to a function starting with Pin. Secondly, because the Pin functions were designed solely for speed, they often do not verify the conditions that are verified by the PIO functions. For example PinRead does not check to see if the pin is performing its bus function before reading, and could return garbage if that turned out to be the case. The PIO functions check these sorts of things, as well as allow you to pass variables to them.

Introduction

The Pin I/O collection of drivers provide fast and convenient access to the I/O pins on the CF1.

typedef enum {
//  SIGNAL   PIN       DESCRIPTION          DIR     FUNCT       PU  R   WU  
    DS      =  1,   // Data Strobe/GPIO     Out     GPIO/BUS        OB  OB
    PCS2    = 15,   // SPI Chip Select 2    I/O     GPIO/QSPI       I?  O+
    SCK     = 16,   // SPI Serial Clock     I/O     GPIO/QSPI       I?  O+
    PCS3    = 17,   // SPI Chip Select 3    I/O     GPIO/QSPI       I?  O+
    MOSI    = 18,   // SPI Master Data Out  I/O     GPIO/QSPI       I?  O+
    PCS1    = 19,   // SPI Chip Select 1    I/O     GPIO/QSPI       I?  O+
    MISO    = 20,   // SPI Master Data In   I/O     GPIO/QSPI   1M  I+  I+
    PCS0    = 21,   // SPI Chip Select 0    I/O     GPIO/QSPI       I?  O+
    CTD10   = 22,   // Double Action Timer  I/O     GPIO/TMR        I?  I?
    CTD9    = 23,   // Double Action Timer  I/O     GPIO/TMR        I?  I?
    CTD7    = 24,   // Double Action Timer  I/O     GPIO/TMR        I?  I?
    CTD8    = 25,   // Double Action Timer  I/O     GPIO/TMR        I?  I?
    CTD6    = 26,   // Double Action Timer  I/O     GPIO/TMR        I?  I?
    CTD5    = 27,   // Double Action Timer  I/O     GPIO/TMR        I?  I?
    CTS14B  = 28,   // Single Action Timer  I/O     GPIO/TMR        I?  I?
    CTD4    = 29,   // Double Action Timer  I/O     GPIO/TMR        I?  I?
    CTS14A  = 30,   // Single Action Timer  I/O     GPIO/TMR        I?  I?
    CTS18A  = 31,   // Single Action Timer  I/O     GPIO/TMR        I?  I?
    CTS18B  = 32,   // Single Action Timer  I/O     GPIO/TMR        I?  I?
    CTD29   = 33,   // Double Action Timer  I/O     GPIO/TMR        I?  I?
    CTD28   = 34,   // Double Action Timer  I/O     GPIO/TMR        I?  I?
    CTD27   = 35,   // Double Action Timer  I/O     GPIO/TMR        I?  I?
    CTM31L  = 36,   // Timer Load/Clock     In      GPIO/TMR    1M  I+  I+
    CTD26   = 37,   // Double Action Timer  I/O     GPIO/TMR        I?  I?
    IRQ5    = 39,   // Interrupt Request 5  I/O     GPIO/IRQ    10K IB+ I+
    IRQ7    = 40,   // Interrupt Request 7  I/O     GPIO/IRQ    10K IB+ I+
    IRQ2    = 41,   // Interrupt Request 2  I/O     GPIO/IRQ    10K IB+ I+
    MODCLK  = 42,   // Clk Source Sel/GPIO  I/O     GPIO/CLK    10K I+  I+
    IRQ4RXD = 45,   // IRQ/CMOS RxD Sense   In      GPIO/UART       IB? I+
    TXD     = 46,   // CMOS Serial TxD      Out     GPIO/UART       I?  OB
    RTS     = 48,   // CMOS RTS Ouput       Out     GPIO/UART   1M  I+  O+  
    IRQ3CTS = 50    // IRQ/CMOS CTS Sense   in      GPIO/UART       IB? I+
    } PinID;  

PinBus -- Make an I/O pin perform its bus function (varies)

This is actually a preprocessor macro that expands to three words of inline machine code to directly configure one of the I/O ports to act as its bus function instead of as an I/O pin. The benefit is almost an order of magnitude speed improvement over the straight function call. The penalty is that because the macros are created at compile time, all arguments to the macro functions must be compile-time literals. Furthermore, if the pin is configured to its bus function with this macro it must be explicitly reconfigured to its use as an I/O function before using any of the I/O related macro functions.

Prototype:	void PinBus(short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin to act on.
Notes:
Timing:	??us at 16MHz/0wts, ??us at 8MHz/-1wts

PinClear -- Configure I/O pin as output and set low

This is actually a preprocessor macro that expands to three words of inline machine code to directly clear one of the I/O ports. The benefit is almost an order of magnitude speed improvement over the straight function call. The penalty is that because the macros are created at compile time, all arguments to the macro functions must be compile-time literals. Furthermore, while the macros will set the input or output configuration of the pin, it assumes that the pin is in Pin I/O mode as opposed to bus mode, and if the pin is configured for its bus function, the operation will fail.

Prototype:	void PinClear(PinID pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin to clear
Notes:
Timing:	CTx 0.7us, others 0.8us at 16MHz/0wts, CTx 1.1us, others 1.4us at 8MHz/-1wts

PinIO -- Make an I/O pin perform its digital I/O function

This is actually a preprocessor macro that expands to three words of inline machine code to directly configure one of the I/O ports to act as an I/O pin. The benefit is almost an order of magnitude speed improvement over the straight function call. The penalty is that because the macros are created at compile time, all arguments to the macro functions must be compile-time literals. This function would be used to explicitly reconfigure a pin to act as I/O after being configured to act as its bus function.

Prototype:	void PinIO(short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to act on
Notes:
Timing:	??us at 16MHz/0wts, ??us at 8MHz/-1wts

PinMirror -- Read an I/O pin, then configure as an output at the level read

This function first configures an individual bit of an I/O port as an input and reads its current state, then it reconfigures the line to an output at the level previously read. This is particularly useful for eliminating floating inputs which can cause the system to waste power. This is actually a preprocessor macro that expands to three words of inline machine code to directly mirror one of the I/O ports. The benefit is almost an order of magnitude speed improvement over the straight function call. The penalty is that because the macros are created at compile time, all arguments to the macro functions must be compile-time literals. Furthermore, while the macros will set the input or output configuration of the pin, it assumes that the pin is in Pin I/O mode as opposed to bus mode, and if the pin is configured for its bus function, the operation will fail.

Prototype:	void PinMirror(short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin inputs???
Notes:	pin is the pin number to act on
Timing:	CTx 33us, others 42us at 16MHz/0wts, CTx 55us, others 68us at 8MHz/-1wts

PinRead -- Configure I/O pin as input and read level

This is actually a preprocessor macro that expands to six words of inline machine code to directly read the bit setting of one of the I/O ports. The benefit is almost an order of magnitude speed improvement over the straight function call. The penalty is that because the macros are created at compile time, all arguments to the macro functions must be compile-time literals. Furthermore, while the macros will set the input or output configuration of the pin, it assumes that the pin is in Pin I/O mode as opposed to bus mode, and if the pin is configured for its bus function, the operation will fail.

Prototype:	short PinRead(short pin); see the text for restrictions
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number you wish to read
Returns:	the current level if the port pin has previously been defined as an input
Notes:	Notes-???
Timing:	1.2us at 16MHz/0wts, 2.1us at 8MHz/-1wts

PinSet -- Configure I/O pin as output and set high

This is actually a preprocessor macro that expands to three words of inline machine code to directly sets one of the I/O ports. The benefit is almost an order of magnitude speed improvement over the straight function call. The penalty is that because the macros are created at compile time, all arguments to the macro functions must be compile-time literals. Furthermore, while the macros will set the input or output configuration of the pin, it assumes that the pin is in Pin I/O mode as opposed to bus mode, and if the pin is configured for its bus function, the operation will fail.

Prototype:	void PinSet(PinID pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin to set.
Notes:
Timing:	CTx 0.7us, others 0.8us at 16MHz/0wts, CTx 1.1us, others 1.4us at 8MHz/-1wts

PinTestAssertClear -- Return true if I/O pin is currently an output asserting low

This function tests to see if the specified pin is configured as an output and is asserted low. This is actually a preprocessor macro that expands to three words of inline machine code to return a short that is nonzero if the designated pin is currently an output asserting low. The benefit is almost an order of magnitude speed improvement over the straight function call. The penalty is that because the macros are created at compile time, all arguments to the macro functions must be compile-time literals.

Prototype:	short PIOTestAssertSet (short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to test.
Returns:	Returns nonzero if the pin is set low, and zero if the pin is set high or is not an I/O output.
Notes:	At the time of this writing, this macro actually redirected to PIOTestAssertClear.
Timing:	??us at 16MHz/0wts, ??us at 8MHz/-1wts

PinTestAssertSet -- Return true if I/O pin is currently an output asserting high

This function tests to see if the specified pin is configured as an output and is asserted high. This is actually a preprocessor macro that expands to three words of inline machine code to return a short that is nonzero if the designated pin is currently an output asserting high. The benefit is almost an order of magnitude speed improvement over the straight function call. The penalty is that because the macros are created at compile time, all arguments to the macro functions must be compile-time literals.

Prototype:	short PIOTestAssertSet (short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to test.
Returns:	Returns nonzero if the pin is set high, and zero if the pin is set low or is not an I/O output.
Notes:	At the time of this writing, this macro actually redirected to PIOTestAssertSet.
Timing:	??us at 16MHz/0wts, ??us at 8MHz/-1wts

PinTestIsItBus -- Is a pin performing its bus function

This function allows you program to ascertain whether a pin is currently performing its bus function. This is actually a preprocessor macro that expands to three words of inline machine code to return a short that is nonzero if the designated pin is configured for its bus function. The benefit is almost an order of magnitude speed improvement over the straight function call. The penalty is that because the macros are created at compile time, all arguments to the macro functions must be compile-time literals. This function is only relevant to pins which have bus functions. These are all the pins that are not used by the counter/timer module.

Prototype:	short PinTestIsItBus (short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to act upon.
Returns:	Returns zero if the pin is configured for its I/O function and nonzero for its bus function
Notes:
Timing:	??us at 16MHz/0wts, ??us at 8MHz/-1wts

PinToggle -- Configure I/O pin as output and toggle current level

This is actually a preprocessor macro that expands to three words of inline machine code to directly toggle one of the I/O ports. The benefit is almost an order of magnitude speed improvement over the straight function call. The penalty is that because the macros are created at compile time, all arguments to the macro functions must be compile-time literals. Furthermore, while the macros will set the input or output configuration of the pin, it assumes that the pin is in Pin I/O mode as opposed to bus mode, and if the pin is configured for its bus function, the operation will fail.

Prototype:	void PinToggle(short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to act upon
Notes:
Timing:	CTx 33us, others 43us at 16MHz/0wts, CTx 54us, others 69us at 8MHz/-1wts

PinWrite -- Configure I/O pin as output and write level

This is actually a preprocessor macro that expands to three words of inline machine code to directly sets one of the I/O ports with the specified value. The benefit is almost an order of magnitude speed improvement over the straight function call. The penalty is that because the macros are created at compile time, all arguments to the macro functions must be compile-time literals. Furthermore, while the macros will set the input or output configuration of the pin, it assumes that the pin is in Pin I/O mode as opposed to bus mode, and if the pin is configured for its bus function, the operation will fail.

Prototype:	void PinWrite(short pin, short value);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to act on value is the value (0 or 1) that you wish to write to the pin.
Notes:
Timing:	CTx 32us, others 40us at 16MHz/0wts, CTx 53us, others 65us at 8MHz/-1wts

PIOBusFunct -- Make an I/O pin perform its alternate function (varies)

This function first configures an I/O line to perform its alternate function which will vary with each pin, and only applies interrupt request (IRQn) and QSM (port Q) lines. The CTS and CTD have much richer and more elaborate alternate functionality which is access with routines described in the CTM section. The pin argument can be specified as numerical value between 1 and 50 corresponding to the CF1 pinout on connector C, or one of the enumeration constants shown above.

Prototype:	short PIOBusFunct(short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to act on
Returns:	Returns the current level (after mirroring) or -1 if there's an error
Notes:
Timing:	33us at 16MHz/0wts, 52us at 8MHz/-1wts

PIOClear -- Configure I/O pin as output and set low

This function configures an individual bit of an I/O port as an output driving low. The pin argument can be specified as numerical value between 1 and 50 corresponding to the CF1 pinout on connector C, or one of the enumeration constants shown above. See the PinClear() macro ahead for a faster alternative with a few usage restrictions.

Prototype:	short PIOClear(short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to act on
Returns:	Returns the current level (after clearing) or -1 if there's an error
Notes:
Timing:	CTx 30us, others 38us at 16MHz/0wts, CTx 53us, others 61us at 8MHz/-1wts

PIOEnableErrTrap -- Enable/Disable PIO error trapping

This function is used to turn on and off the trapping of errors in the Pin I/O subsystem. If this function is called with TRUE for dotrap, then if there are any error, the machine will cease execution and print a debugging message. Otherwise, errors will be passed back through the return mechanism to be dealt with at the application level.

Prototype:	void PIOEnableErrTrap(bool dotrap);
Definition:	#include <cf1bios.h>
Inputs:	dotrap is a Boolean that indicates which of two actions should be taken in the event of a receive error. TRUE tells the Persistor to throw an exception and crash if there is a pin I/O error, and FALSE implies that the error should be ignored.
Notes:	See also PIOErrorSignal.
Timing:	4.4 µsecs

PIOErrorSignal -- Return error or crash and trap it.

This function will be called each time there is a receive error, such as a framing error or a parity error. The action it takes is determined by the PIOEnableErrTrap function.

Prototype:	short PIOErrorSignal(short code, long offense);
Definition:	#include <cf1bios.h>
Inputs:	code is the error thrown by the calling function offense is a long that will be printed in the debugging information if the error is to be trapped.
Returns:	Returns code
Notes:
Timing:	N/A

PIOMaxPin -- Return the highest pin number.

This function returns the maximum pin number that can be used when calling any of the Pin I/O related functions.

Prototype:	short PIOMaxPin(void);
Definition:	#include <cf1bios.h>
Returns:	Returns the maximum pin number
Notes:
Timing:	N/A

PIOInit -- Initialize I/O Pins States

This function is called by the BIOS initialization. User applications will never need to call this function.

Prototype:	void PIOInit(void);
Definition:	#include <cf1bios.h>
Notes:	called automatically at system startup
Timing:	unspecified

PIOMirror -- Read an I/O pin, then configure as an output at the level read

This function first configures an individual bit of an I/O port as an input and reads its current state, then it reconfigures the line to an output at the level previously read. This is particularly useful for eliminating floating inputs which can cause the system to waste power. The pin argument can be specified as numerical value between 1 and 50 corresponding to the CF1 pinout on connector C, or one of the enumeration constants shown above.

Prototype:	short PIOMirror(short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to act on
Returns:	the current level (after mirroring) or -1 if there's an error
Notes:
Timing:	CTx 33us, others 42us at 16MHz/0wts, CTx 55us, others 68us at 8MHz/-1wts

PIOMirrorList -- Read I/O pins, then configure as an output at the level read

This function acts on a zero terminated list of pin numbers and invokes PIOMirror() to convert possibly floating inputs to outputs.

Prototype:	void PIOMirrorList(uchar *pinlist);
Definition:	#include <cf1bios.h>
Inputs:	pinlist is a list of uchars which contain the pin numbers to mirror.
Notes:
Timing:	TBD

PIORead -- Configure I/O pin as input and read level

This function sets up an I/O pin as an input port and returns the current level. The pin argument can be specified as numerical value between 1 and 50 corresponding to the CF1 pinout on connector C, or one of the enumeration constants shown above. See the PinRead() macro ahead for a faster alternative with a few usage restrictions.

Prototype:	short PIORead(short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to act on
Returns:	the current level or -1 if there's an error
Notes:	Notes-???
Timing:	CTx 27us, others 35us at 16MHz/0wts, CTx 45us, others 56us at 8MHz/-1wts

PIOSet -- Configure I/O pin as output and set high

This function configures an individual bit of an I/O port as an output driving high. The pin argument can be specified as numerical value between 1 and 50 corresponding to the CF1 pinout on connector C, or one of the enumeration constants shown above. See the PinSet() macro ahead for a faster alternative with a few usage restrictions.

Prototype:	short PIOSet(short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to act on
Returns:	Returns the current level (after setting) or -1 if there's an error
Notes:
Timing:	CTx 30us, others 37us at 16MHz/0wts, CTx 49us, others 61us at 8MHz/-1wts

PIOTestAssertClear -- Return true if I/O pin is currently an output asserting low

This function tests to see if the specified pin is configured as an output and is asserted low.

Prototype:	short PIOTestAssertSet (short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to test.
Returns:	Returns nonzero if the pin is set low, and zero if the pin is set high or is not an I/O output.
Notes:
Timing:	??us at 16MHz/0wts, ??us at 8MHz/-1wts

PIOTestAssertSet -- Return true if I/O pin is currently an output asserting high

This function tests to see if the specified pin is configured as an output and is asserted high.

Prototype:	short PIOTestAssertSet (short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to test.
Returns:	Returns nonzero if the pin is set high, and zero if the pin is set low or is not an I/O output.
Notes:
Timing:	??us at 16MHz/0wts, ??us at 8MHz/-1wts

PIOTestIsItBus -- Is a pin performing its bus function

This function allows you program to ascertain whether a pin is currently performing its bus function. This function is only relevant to pins which have bus functions. These are all the pins that are not used by the counter/timer module.

Prototype:	short PinTestIsItBus (short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to act upon.
Returns:	Returns zero if the pin is configured for its I/O function and nonzero for its bus function
Notes:
Timing:	??us at 16MHz/0wts, ??us at 8MHz/-1wts

PIOToggle -- Configure I/O pin as output and toggle current level

This function configures an individual bit of an I/O port as an output driving at the opposite of the current level. The pin argument can be specified as numerical value between 1 and 50 corresponding to the CF1 pinout on connector C, or one of the enumeration constants shown above.

Prototype:	short PIOToggle(short pin);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to act on
Returns:	Returns the current level (after toggling) or -1 if there's an error
Notes:
Timing:	CTx 33us, others 43us at 16MHz/0wts, CTx 54us, others 69us at 8MHz/-1wts

PIOWrite -- Configure I/O pin as output and write level

This function configures an individual bit of an I/O port as an output driving at the specified level. The pin argument can be specified as numerical value between 1 and 50 corresponding to the CF1 pinout on connector C, or one of the enumeration constants shown above.

Prototype:	short PIOWrite(short pin, short value);
Definition:	#include <cf1bios.h>
Inputs:	pin is the pin number to act on
Returns:	Returns the current level (after setting) or -1 if there's an error
Notes:
Timing:	CTx 32us, others 40us at 16MHz/0wts, CTx 53us, others 65us at 8MHz/-1wts

Previous

Next

Top

Contents

Glossary

Index

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