honey@CITI.UMICH.EDU.UUCP (03/13/87)
CITI MacIP Driver Interface Guide
Introduction
This is an interface guide for the CITI MacIP driver. The protocols
supported are TCP, UDP, IP, and ancillary protocols ARP, ICMP, and
NBP. Included with the driver is a Berkeley UNIX style socket
interface, which supports such functions as sendto, recvfrom, and
select. The protocol layers, while separable, all reside in a single
driver. This guide gives an overview of the driver structure and
program interface.
Client Access to Protocol Layers
A client creates one or more protocol connections, called streams.
Every stream has an associated stream descriptor, which carries
information private to the protocol. For example, a UDP stream
descriptor contains the port number for the connection and references
to outstanding datagrams.
Driver Calls
Stream requests are made via driver control calls. The driver includes
a dispatcher that selects individual driver entry points, specified by
csCode. The header file that defines the values for csCode can be
found in an appendix.
Driver calls are immediate, i.e., they bypass the regular driver I/O
queue. Parameters for the driver calls are passed through a driver
parameter block; parameters to driver functions are passed in a
protocol parameter block. The following data structure describes a
driver parameter block:
typedef struct CallParam {
ParamBlockHeader;
short ioCRefNum; /* Unit table entry */
short csCode; /* Function selector */
long retVal; /* Returned by driver function */
long parSize; /* Length of parAddr */
Ptr parAddr; /* Ptr to function parameters */
u_long net_errno; /* Driver function error specifier */
u_long errno; /* UNIX style error specifier */
} CallParam_t;
To call the driver, a client prepares a parameter block, using csCode
to select individual driver functions, and passies control to the
selected driver function via the dispatcher. Driver calls treat the
parameters as follows, where right and left arrows indicate values
passed to and from the driver functions, respectively:
-> ParamBlockHeader
-> ioCRefNum
-> csCode
<- retVal
-> parSize
-> parAddr
<- net_errno
<- errno
parAddr usually contains the address of a pointer to a protocol
parameter block. On return from the driver, net_errno reflects the
reason for failure of a driver call.