RFC_0007

GRINJ-Driver-API

   TOC
---------------------------------------------------
1. RFC-Notes
2. Definition
3. Example 
--------------------------------------------------

1. RFC-Notes
--------------------------------------------------
A GRINJ-device-driver is used as an interface to
the "outer world" of a GRINJ-binary. The driver can
be attached to different hardware-resources and pro-
vide therefore things like:
- OS-interface
	- Timer
	- RPC (Semaphore, SHM)
- Additional Hardware
	- LPT
	- Bus-Systems
etc.

2. Definition
--------------------------------------------------
A driver has to implement the following functions:

/*!
  State of the resource:
   0 : Ok
   1 : Temporary unavailable
   2 : Fatal-error, resource not available

   Example for a socket-implementation:
   0 : Server ok und connected
   1 : Server ok but no client
   3 : Socket-error (z.B. bind) 
*/
int getState();

/*!
  Constructor
  Is used at load-time.
  Same return-value as in "getState"
*/
int init();

/*!
  Destructor
  Is used at unload-time.
*/ 
void destroy();

/*!
  Type of driver (as integer-bitset):
  Bits  |  Meaning    | Values
  ------+-------------+--------------------
  0-1   |  Data       | 00 : Integer-Device
  2-3   |  Input-Type | 00 : Non-Blocking
        |             | 01 : Blocking
  4-5   |  Output-Type| 00 : Non-Blocking
        |             | 01 : Blocking
  6-31  |  reserved   | 
  ------+-------------+--------------------
*/
unsigned getType();

/*!
  Out-method
*/
void setInt(int i);

/*!
  In-methode
*/
int  getInt();

3. Example
--------------------------------------------------

loopback.c
Loopback-Device, stores an integer-value
-----------------------------------------

int glbInt;

int      init()     { return 0; }  // always ok
void     destroy()  {}
int      getState() { return 0; }  // always ok
unsigned getType()  { return 0; }  // non-blocking integer-device

void     setInt(int i) { glbInt = i;     }
int      getInt()      { return glbInt;  }

-----------------------------------------

Compile with
$ gcc -fPIC -c loopback.c
$ gcc -shared -Wl,-soname,libLoopback.so -o libLoopback.so *.o