.ds RH "Socket/protocol interface

The interface between the socket routines and the communication protocols is through the pr_usrreq routine defined in the protocol switch table. The following requests to a protocol module are possible: ._d #define PRU_ATTACH 0 /* attach protocol */ #define PRU_DETACH 1 /* detach protocol */ #define PRU_BIND 2 /* bind socket to address */ #define PRU_LISTEN 3 /* listen for connection */ #define PRU_CONNECT 4 /* establish connection to peer */ #define PRU_ACCEPT 5 /* accept connection from peer */ #define PRU_DISCONNECT 6 /* disconnect from peer */ #define PRU_SHUTDOWN 7 /* won't send any more data */ #define PRU_RCVD 8 /* have taken data; more room now */ #define PRU_SEND 9 /* send this data */ #define PRU_ABORT 10 /* abort (fast DISCONNECT, DETATCH) */ #define PRU_CONTROL 11 /* control operations on protocol */ #define PRU_SENSE 12 /* return status into m */ #define PRU_RCVOOB 13 /* retrieve out of band data */ #define PRU_SENDOOB 14 /* send out of band data */ #define PRU_SOCKADDR 15 /* fetch socket's address */ #define PRU_PEERADDR 16 /* fetch peer's address */ #define PRU_CONNECT2 17 /* connect two sockets */ /* begin for protocols internal use */ #define PRU_FASTTIMO 18 /* 200ms timeout */ #define PRU_SLOWTIMO 19 /* 500ms timeout */ #define PRU_PROTORCV 20 /* receive from below */ #define PRU_PROTOSEND 21 /* send to below */ A call on the user request routine is of the form, ._f error = (*protosw[].pr_usrreq)(so, req, m, addr, rights); int error; struct socket *so; int req; struct mbuf *m, *addr, *rights; The mbuf data chain m is supplied for output operations and for certain other operations where it is to receive a result. The address addr is supplied for address-oriented requests such as PRU_BIND and PRU_CONNECT. The rights parameter is an optional pointer to an mbuf chain containing user-specified capabilities (see the sendmsg and recvmsg system calls). The protocol is responsible for disposal of the data mbuf chains on output operations. A non-zero return value gives a UNIX error number which should be passed to higher level software. The following paragraphs describe each of the requests possible.

When a protocol is bound to a socket (with the socket system call) the protocol module is called with this request. It is the responsibility of the protocol module to allocate any resources necessary. The ``attach'' request will always precede any of the other requests, and should not occur more than once.

This is the antithesis of the attach request, and is used at the time a socket is deleted. The protocol module may deallocate any resources assigned to the socket.

When a socket is initially created it has no address bound to it. This request indicates that an address should be bound to an existing socket. The protocol module must verify that the requested address is valid and available for use.

The ``listen'' request indicates the user wishes to listen for incoming connection requests on the associated socket. The protocol module should perform any state changes needed to carry out this request (if possible). A ``listen'' request always precedes a request to accept a connection.

The ``connect'' request indicates the user wants to establish an association. The addr parameter supplied describes the peer to be connected to. The effect of a connect request may vary depending on the protocol. Virtual circuit protocols, such as TCP [Postel81b], use this request to initiate establishment of a TCP connection. Datagram protocols, such as UDP [Postel80], simply record the peer's address in a private data structure and use it to tag all outgoing packets. There are no restrictions on how many times a connect request may be used after an attach. If a protocol supports the notion of multi-casting, it is possible to use multiple connects to establish a multi-cast group. Alternatively, an association may be broken by a PRU_DISCONNECT request, and a new association created with a subsequent connect request; all without destroying and creating a new socket.

Following a successful PRU_LISTEN request and the arrival of one or more connections, this request is made to indicate the user has accepted the first connection on the queue of pending connections. The protocol module should fill in the supplied address buffer with the address of the connected party.

Eliminate an association created with a PRU_CONNECT request.

This call is used to indicate no more data will be sent and/or received (the addr parameter indicates the direction of the shutdown, as encoded in the soshutdown system call). The protocol may, at its discretion, deallocate any data structures related to the shutdown and/or notify a connected peer of the shutdown.

This request is made only if the protocol entry in the protocol switch table includes the PR_WANTRCVD flag. When a user removes data from the receive queue this request will be sent to the protocol module. It may be used to trigger acknowledgements, refresh windowing information, initiate data transfer, etc.

Each user request to send data is translated into one or more PRU_SEND requests (a protocol may indicate that a single user send request must be translated into a single PRU_SEND request by specifying the PR_ATOMIC flag in its protocol description). The data to be sent is presented to the protocol as a list of mbufs and an address is, optionally, supplied in the addr parameter. The protocol is responsible for preserving the data in the socket's send queue if it is not able to send it immediately, or if it may need it at some later time (e.g. for retransmission).

This request indicates an abnormal termination of service. The protocol should delete any existing association(s).

The ``control'' request is generated when a user performs a UNIX ioctl system call on a socket (and the ioctl is not intercepted by the socket routines). It allows protocol-specific operations to be provided outside the scope of the common socket interface. The addr parameter contains a pointer to a static kernel data area where relevant information may be obtained or returned. The m parameter contains the actual ioctl request code (note the non-standard calling convention). The rights parameter contains a pointer to an ifnet structure if the ioctl operation pertains to a particular network interface.

The ``sense'' request is generated when the user makes an fstat system call on a socket; it requests status of the associated socket. This currently returns a standard stat structure. It typically contains only the optimal transfer size for the connection (based on buffer size, windowing information and maximum packet size). The m parameter contains a pointer to a static kernel data area where the status buffer should be placed.

Any ``out-of-band'' data presently available is to be returned. An mbuf is passed to the protocol module, and the protocol should either place data in the mbuf or attach new mbufs to the one supplied if there is insufficient space in the single mbuf. An error may be returned if out-of-band data is not (yet) available or has already been consumed. The addr parameter contains any options such as MSG_PEEK to examine data without consuming it.

Like PRU_SEND, but for out-of-band data.

The local address of the socket is returned, if any is currently bound to it. The address (with protocol specific format) is returned in the addr parameter.

The address of the peer to which the socket is connected is returned. The socket must be in a SS_ISCONNECTED state for this request to be made to the protocol. The address format (protocol specific) is returned in the addr parameter.

The protocol module is supplied two sockets and requested to establish a connection between the two without binding any addresses, if possible. This call is used in implementing the socketpair (2) system call.

The following requests are used internally by the protocol modules and are never generated by the socket routines. In certain instances, they are handed to the pr_usrreq routine solely for convenience in tracing a protocol's operation (e.g. PRU_SLOWTIMO).

A ``fast timeout'' has occurred. This request is made when a timeout occurs in the protocol's pr_fastimo routine. The addr parameter indicates which timer expired.

A ``slow timeout'' has occurred. This request is made when a timeout occurs in the protocol's pr_slowtimo routine. The addr parameter indicates which timer expired.

This request is used in the protocol-protocol interface, not by the routines. It requests reception of data destined for the protocol and not the user. No protocols currently use this facility.

This request allows a protocol to send data destined for another protocol module, not a user. The details of how data is marked ``addressed to protocol'' instead of ``addressed to user'' are left to the protocol modules. No protocols currently use this facility.