honey@CITI.UMICH.EDU.UUCP (03/13/87)
IP Driver Interface Specification
Introduction
The IP driver layer, part of the CITI MacIP driver, implements the
Internet Protocol [RFC 791]. This document describes the program
interface to the IP layer. Driver requests are made by preparing a
driver parameter block and a protocol parameter block, and issuing a
driver control call. The driver parameter block is described in
[CITI MacIP].
Data Structures
The reader should be familiar with the common C derived types, such as
those described in <sys/types.h>, <sys/time.h>, MPW C, and Inside
Macintosh [MAC] All IP datagrams are described by an IP header
[RFC 791], described below in MPW C:
typedef struct ip_header {
u_char ip_ver:4;
u_char ip_ihl:4;
u_char ip_tsrv;
u_short ip_len;
short ip_id;
u_short ip_flgs:3;
u_short ip_foff:13;
u_char ip_time;
u_char ip_prot;
u_short ip_chksum;
u_long ip_src;
u_long ip_dst
} ip_header_t, *ip_header_p;
An IP client passes arguments to the driver in an IP protocol parameter
block, described as follows:
typedef struct ip_param {
struct timeval *io_timeout; /* I/O timeout */
caddr_t io_datagram; /* Pointer to datagram */
short io_datalen; /* Length of datagram */
caddr_t io_stream; /* Private IP data */
u_long io_src; /* Local IP address */
u_short io_dst; /* Destination IP address */
u_char io_prot; /* Protocol identifier */
ip_header_p io_iph; /* Raw IP header */
u_long io_options[11] /* IP options */
int io_optname; /* Name of a single option */
caddr_t io_optval; /* Option value */
int io_optlen; /* Length of io_optval */
} ip_param_t, *ip_param_p;
IP Functions
The following functions provide a program interface to the IP driver
layer. Each function has a single argument of type ip_param_p and
returns failure (-1) or success (non-negative). Upon failure, the
net_errno field of the driver parameter block indicates the cause of
the failure.
All datagrams used in the IP functions must be allocated and freed with
the IP allocation routines, ip_alloc and ip_free.
Right and left arrows indicate values passed to and from the driver
functions, respectively.
int ip_open(ip_pb)
<- io_stream
-> io_prot
csCode IP_OPEN_S
ip_open creates an IP stream. On success, ip_open prepares io_stream,
which carries the private, protocol specific description of the
stream. io_prot is a protocol number as defined in [RFC 997].
int ip_close(ip_pb)
-> io_stream
csCode IP_CLOSE_S
ip_close destroys an IP stream. ip_close frees any outstanding
datagram buffers.
int ip_alloc(ip_pb)
<- io_datagram
-> io_datalen
<-> io_stream
csCode IP_ALLOC_S
ip_alloc allocates an IP datagram buffer.
int ip_free(ip_pb)
-> io_datagram
<-> io_stream
csCode IP_FREE_S
ip_free frees an IP datagram buffer. io_datagram must point to a
datagram buffer allocated by ip_alloc or ip_get.
int ip_setopt(ip_pb)
<-> io_options
-> io_optname
-> io_optval
-> io_optlen
csCode IP_SETOPT_S
ip_setopt adds the specified IP option [RFC 791] to the io_options
list.
int ip_put(ip_pb)
-> io_datagram
-> io_datalen
-> io_stream
-> io_dst
-> io_options
csCode IP_PUT_S
ip_put sends a datagram to the address specified by io_dst.
io_datagram must be a datagram buffer allocated by ip_alloc.
io_datagram may be freed (with ip_free) immediately upon return from
ip_put.
int ip_get(ip_pb)
-> io_timeout
<- io_datagram
<- io_datalen
-> io_stream
<- io_src
<- io_dst
<- io_iph
<- io_options
csCode IP_GET_S
ip_get requests a datagram from an IP stream. If io_timeout is NULL,
ip_get blocks until a packet arrives. If io_timeout is not NULL and a
datagram is not available within the timeout period, ip_get returns
-1. io_datagram is allocated by the driver; it is the caller's
responsibility to free datagram buffers.
int ip_control(ip_pb)
<-> io_datagram
<-> io_datalen
csCode IP_CONTROL_S
To be specified.