DISCLAIMER:
This documentation is mostly a cut and paste job from Windows.  A better
document is in the works, we promise.

-----------------------------------------------------------
Application Programmers Interface

The SeaIo drivers share a common API (application programmer interface) that is
implemented in libseaio.a. Our goal is to provide the developer with a single,
high-level programming interface that will function with a variety of hardware
products across several operating systems.  The library source code is provided
with the driver; however, all that is typically required by the application is
the static library (libseaio.a) and its header file (seaio.h).

This API provides two sets of calls for reading and writing relay and I/O ports:
SeaIo_WriteReg and SeaIO_ReadReg, and SeaIo_PutData and SeaIo_GetData.  The
"WriteReg" and "ReadReg" functions take a specific offset for the register to
access: i.e., to write to the first bank of a 3093, specify 2 for the register
parameter.  The "PutData" functions take a relative offset for the register to
access: to write to the first bank of a 3093 with SeaIO_PutData, specify 0 for
the register parameter.  The "GetData" function returns ALL valid inputs
contiguously in a buffer, starting at offset 0.

The "WriteReg" and "ReadReg" functions would be most useful for quickly porting
already written software to this API.  Using the "PutData" and "GetData"
functions permits ease of development, freeing the programmer from the specifics
of each card and allowing the same application to function across multiple
(similar) card types. 

This document covers the following API functions:
SeaIo_GetData
SeaIo_PutData
SeaIo_WriteReg
SeaIo_ReadReg
SeaIo_RelayClose
SeaIo_RelayOpen
SeaIo_GetAdapterInfo
SeaIo_GetAdapterState
SeaIo_SetAdapterState

SeaIo_OpenDevice and SeaIo_CloseDevice are functional, but deprecated.  Please
use the open() and close() system calls in all new development.
-----------------------------------------------------------
C Sample
SeaIOTST

Overview
SeaIOTst was originally a Win32 console application designed for testing all
calls to the driver. It has been roughly ported to Linux for the alpha release
of SeaIO/Linux.  This sample is very useful for verifying proper SeaIO
configuration and hardware settings. A main menu offers choices for reading and
writing ports, and setting and clearing relays.  Use this sample as a reference
for proper use of the SeaIO calls.
Since SeaIOTst uses the deprecated SeaIo_OpenDevice and SeaIo_CloseDevice calls,
it will only function properly if your SeaI/O devices are linked to by nodes
named /dev/dio*.  This is the default configuration when SeaI/O is first
installed, if you use the seaio-load script.

-----------------------------------------------------------
Return Codes (as enumerated in seaio.h)

SEAIO_ERROR_NONE			0	(0x00)
SEAIO_ERROR_PARAM			1	(0x01)
SEAIO_ERROR_NOT_SUPPORTED		2	(0x02)
SEAIO_ERROR_PORT_NOT_OPEN		3	(0x03)
SEAIO_ERROR_INVALID_NAME		4	(0x04)
SEAIO_ERROR_SHARING_VIOLATION		5	(0x05)
SEAIO_ERROR_BUFFER			6	(0x06)
SEAIO_ERROR_INCOMPLETE			7	(0x07)
SEAIO_ERROR_GENERAL			8	(0x08)
SEAIO_ERROR_IO_PENDING			9	(0x09)
SEAIO_ERROR_NO_TXBUFFER			10	(0x0A)
SEAIO_ERROR_INVALID_HANDLE		11	(0x0B)
SEAIO_ERROR_LAST			12	(0x0C)

-----------------------------------------------------------
SeaIo_GetData
   
Syntax:
int SeaIo_GetData(int hDevice, unsigned char * pBuffer, unsigned long dwLength,
unsigned long *pDwRetLength); 


Parameters
hDevice - the handle returned from the open() system call
pBuffer - the (application) buffer in which to return the data.
dwLength - the length of the application's buffer area specified by pBuffer.
Note that this length must be greater than or equal to the defined size of the
device's input capacity (2 bytes or 4 bytes) 
pDwRetLength - pointer to a unsigned long containing the number of bytes copied
to pBuffer 


Return ValueReturn_Codes
SEAIO_ERROR_NONE - success
SEAIO_ERROR_NOT_SUPPORTED - not supported under current operating system
SEAIO_ERROR_BUFFER - the pointer to the buffer is NULL or the caller's receive
buffer length is smaller than the device's defined input capacity. 
SEAIO_ERROR_GENERAL - general failure
SEAIO_ERROR_INVALID_HANDLE - handle failed validation.
SEAIO_ERROR_INVALID_DEVICE_REQUEST - not a valid operation for the device
target. 
SEAIO_ERROR_PARAM - invalid parameter


Remarks
Call this function to read all valid input ports for this device  


-----------------------------------------------------------
SeaIo_PutData
   
Syntax:
int SeaIo_PutData(int hDevice, unsigned char * pBuffer);


Parameters
hDevice - the handle returned from the open() system call
pBuffer - the buffer in which the data is sent from the application to the
driver and device. 
             This buffer must be at least two bytes long.  The first byte must
	     contain the relative offset of 
             the register to which the data should be output (i.e. 0 = 1st
	     output; 1 = 2nd output). 
             The second byte must contain the data to output.  


Return Value
SEAIO_ERROR_NONE - success
SEAIO_ERROR_NOT_SUPPORTED - not supported under current operating system, or
with the current device model
SEAIO_ERROR_BUFFER - the pointer to the buffer is NULL or the caller's receive
buffer length is smaller than the device's defined input capacity. 
SEAIO_ERROR_GENERAL - general failure
SEAIO_ERROR_INVALID_HANDLE - handle failed validation.
SEAIO_ERROR_PARAM - all other errors.


Remarks
Call this function to write one byte of data to one register for this device 


-----------------------------------------------------------
SeaIo_ReadReg
   
Syntax:
int SeaIo_ReadReg(int hDevice, unsigned char uPortIndex, unsigned char *
pBuffer, unsigned long dwLength, unsigned long *pDwRetLength); 


Parameters
hDevice - the handle returned from the open() system call
uPortIndex - the offset from the base IO address to read
pBuffer - the buffer in which the data will be returned to the application
dwLength - the length of the buffer
pDwRetLength - the number of bytes returned to the application in the buffer 


Return Value
SEAIO_ERROR_NONE - success
SEAIO_ERROR_INVALID_HANDLE - handle does not belong to open device or not valid
for calling process or thread 
SEAIO_ERROR_PARAM - invalid port or invalid operation for the port or device


Remarks
Call this function to read one byte of input from a specific register (give the
offset from the base adress) of the device 


-----------------------------------------------------------
SeaIo_RelayClose
   
Syntax:
int SeaIo_RelayClose(int hDevice, unsigned char uRelayNum);


Parameters
hDevice - the handle returned from the open() system call
uRelayNum - the relative offset from 0 for a given relay.  I.e., the first relay
on bank 0 would be relay 0; the eighth relay on bank 0 would be relay 7; the
first relay on bank 1 would be relay 8, etc.  


Return Value
SEAIO_ERROR_NONE - success
SEAIO_ERROR_GENERAL - could not access the device/device not ready for update
SEAIO_ERROR_INVALID_HANDLE - handle does not belong to open device or not valid
for calling process or thread 
SEAIO_ERROR_PARAM - invalid relay or invalid operation for the device


Remarks
Call this function to set (close) a single relay for the device


-----------------------------------------------------------
SeaIo_RelayOpen
   
Syntax:
int SeaIo_RelayOpen(int hDevice, unsigned char uRelayNum);


Parameters
hDevice - the handle returned from the open() system call
uRelayNum - the relative offset from 0 for a given relay.  I.e., the first relay
on bank 0 would be relay 0; the eighth relay on bank 0 would be relay 7; the
first relay on bank 1 would be relay 8, etc.  


Return ValueReturn_Codes
SEAIO_ERROR_NONE - success
SEAIO_ERROR_GENERAL - could not access the device/device not ready for update
SEAIO_ERROR_INVALID_HANDLE - handle does not belong to open device or not valid
for calling process or thread 
SEAIO_ERROR_PARAM - invalid relay or invalid operation for the device


Remarks
Call this function to clear (open) a single relay for the device


-----------------------------------------------------------
SeaIo_WriteReg
   
Syntax:
int SeaIo_WriteReg(int hDevice, unsigned char uRegNumber, unsigned char uData);


Parameters
hDevice - the handle returned from the open() system call
uRegNumber - the register on the card (specified relative to the card's base
address) to write 
uData - the data to write to the register


Return ValueReturn_Codes
SEAIO_ERROR_NONE - success
SEAIO_ERROR_INVALID_HANDLE - handle does not belong to open device or not valid
for calling process or thread 
SEAIO_ERROR_PARAM - invalid port or invalid operation for the port


Remarks
Call this function to write one byte of data to a port


-----------------------------------------------------------
SeaIo_GetAdapterInfo
   
Syntax:
int SeaIo_GetAdapterInfo(int hDevice, pADAPTER_INFO pAdapter_Info)


Parameters
int hDevice - the handle returned from the open() system call
pADAPTER_INFO pAdapter_Info - a pointer to a structure as follows:
typedef struct tagADAPTER_INFO
 { 	
	unsigned long	dwReserved0;		/* Reserved double words */
	unsigned long	dwReserved1;
	unsigned long	dwReserved2;
	unsigned long	dwReserved3;

	/* ...system resources */
	unsigned long	dwStateCapabilities;

	/* ... Adapter setup */
	WORD	wCardNumber;		 	/* Model of adapter     */
	WORD	wBaseIO;	 		/* Base I/O address	*/

	unsigned char	ucPortInCount;		/* This is a state parameter for
						 * programmable adapters;  a 
						 * boot parm for all others */
	unsigned char	ucPortOutCount;		/* This is a state parameter for 
						 * programmable	adapters;  a 
						 * boot parm for all others */
	unsigned char	ucPortCount;		/* The number of I/O addresses 
						 * this adapter uses */
	unsigned char	ucEnabled;		/* Enabled status:0-disabled; 
						 * non-zero-enabled */ 
 	WORD	wIRQ;				/* Hardware interrupt - here 
						 * for future use */
} ADAPTER_INFO, *pADAPTER_INFO;     
 
 
 	 	
Return Value
SEAIO_ERROR_NONE - success
SEAIO_ERROR_INVALID_HANDLE - handle does not belong to open device or not valid
for calling process or thread 
SEAIO_ERROR_PARAM - all other errors.


Remarks
This function cannot be called successfully until a port has been opened and a
valid handle has been returned. 


-----------------------------------------------------------
SeaIo_GetAdapterState
   
Syntax:
int SeaIo_GetAdapterState(int hDevice, pADAPTER_STATE pAdapter_Info)


Parameters
int hDevice - the handle returned from the open() system call
pADAPTER_STATE pAdapter_State - a pointer to a structure as folows:
typedef struct tagADAPTER_STATE 
{
	unsigned long	dwReserved0;		/* Reserved double words */
	unsigned long	dwReserved1;
	unsigned long	dwReserved2;
	unsigned long	dwReserved3;
	unsigned long	dwSampleInterval;	/* Time between samples, in microseconds */
	unsigned char	ucModeCW[9];		/* Mode Control Words 0 - [n-1]
						 * (only programmable cards) */
} ADAPTER_STATE, *pADAPTER_STATE;


Return Value
SEAIO_ERROR_NONE - success
SEAIO_ERROR_INVALID_HANDLE - handle does not belong to open device or not valid
for calling process or thread 
SEAIO_ERROR_PARAM - all other errors.


Remarks
This function cannot be called successfully until a port has been opened and a
valid handle has been returned. 

The ucModeCW array allows the user to modify the input/output settings on a
programmable card.  For 8255 based cards, there is an element in the array for
each 8255 chip.  In the case of the 4030, which has two 8255 chips, the first
two elements of ucModeCW are the Mode Control Words for the two chips.  For
non-8255 cards (ex: 8001), the first element of the array (ucModeCW[0]) is the
control register for the card.  Refer to the card manual for more details on how
to program the 8255 chips or the on-board configuration register. 


-----------------------------------------------------------
SeaIo_SetAdapterState
   
Syntax:
int SeaIo_SetAdapterState(int hDevice, pADAPTER_STATE pAdapter_Info)


Parameters
int hDevice - the handle returned from the open() system call
pADAPTER_STATE pAdapter_State - a pointer to a structure as follows:
typedef struct tagADAPTER_STATE 
{
	/*... Future */
	unsigned long	dwReserved0;		/* Reserved double words */
	unsigned long	dwReserved1;
	unsigned long	dwReserved2;
	unsigned long	dwReserved3;

	unsigned long	dwSampleInterval;	/* Time between samples */

	unsigned char	ucModeCW[9];	   /* Mode Control Words 0 - [n-1]*/
   
} ADAPTER_STATE, *pADAPTER_STATE;

 


Return Value
SEAIO_ERROR_NONE - success
SEAIO_ERROR_INVALID_HANDLE - handle does not belong to open device or not valid
for calling process or thread 
SEAIO_ERROR_PARAM - all other errors.


Remarks
This function cannot be called successfully until a port has been opened and a
valid handle has been returned. 

The ucModeCW array allows the user to modify the input/output settings on a
programmable card.  For 8255 based cards, there is an element in the array for
each 8255 chip.  In the case of the 4030, which has two 8255 chips, the first
two elements of ucModeCW are the Mode Control Words for the two chips.  For
non-8255 cards (ex: 8001), the first element of the array (ucModeCW[0]) is the
control register for the card.  Refer to the card manual for more details on how
to program the 8255 chips or the on-board configuration register. 
