A physical device handler (PDH) must provide eight common entry points. An individual PDH names its entry points by placing a unique identifier in front of the supported command type.The following are the required eight communications PDH entry points:
|ddconfig||Performs configuration functions for a device handler. Supported the same way that the common ddconfig entry point is.|
|ddmpx||Allocates or deallocates a channel for a multiplexed device handler. Supported the same way as the common ddmpx device handler entry point.|
|ddopen||Performs data structure allocation and initialization for a communications PDH. Supported the same way as the common ddopen entry point. Time-consuming tasks, such as port initialization and connection establishment, are deferred until the (CIO_START) ddioctl call is issued. A PDH can support multiple users of a single port.|
|ddclose||Frees up system resources used by the specified communications device until they are needed again. Supported the same way as the common ddclose entry point.|
|ddwrite||Queues a message for transmission or blocks until the message can be queued. The ddwrite entry point can attempt to queue a transmit request (nonblocking) or wait for it to be queued (blocking), depending on the setting of the DNDELAY flag. The caller has the additional option of requesting an asynchronous acknowledgment when the transmission actually completes.|
|ddread||Returns a message of data to a user-mode process. Supports blocking or nonblocking reads depending on the setting of the DNDELAY flag. A blocking read request does not return to the caller until data is available. A nonblocking read returns with a message of data if it is immediately available. Otherwise, it returns a length of 0 (zero).|
|ddselect||Checks to see if a specified event or events has occurred on the device for a user-mode process. Supported the same way as the common ddselect entry point.|
|ddioctl||Performs the special I/O operations requested in an ioctl subroutine. Supported the same way as the common ddioctl entry point. In addition, a communications PDH must support the following four options:|
Individual PDHs can add additional commands. Hardware initialization and other time-consuming activities, such as call establishment, are performed during the CIO_START operation.
PDHs use mbuf structures to buffer send and receive data. These structures allow the PDH to gather data when transmitting frames and scatter for receive operations. The mbuf structures are internal to the kernel and are used only by kernel-mode processes and PDHs.
PDHs and kernel-mode processes require a set of utilities for obtaining and returning mbuf structures from a buffer pool.
Kernel-mode processes use the Berkeley mbuf scheme for transmit and receive buffers. The structure for an mbuf is defined in the /usr/include/sys/mbuf.h file.
In general, communication device handlers return codes from a group of common exception codes. However, device handlers for specific communication devices can return device-specific exception codes. Common exception codes are defined in the /usr/include/sys/comio.h file and include the following:
|CIO_OK||Indicates that the operation was successful.|
|CIO_BUF_OVFLW||Indicates that the data was lost due to buffer overflow.|
|CIO_HARD_FAIL||Indicates that a hardware failure was detected.|
|CIO_NOMBUF||Indicates that the operation was unable to allocate mbuf structures.|
|CIO_TIMEOUT||Indicates that a time-out error occurred.|
|CIO_TX_FULL||Indicates that the transmit queue is full.|
|CIO_NET_RCVRY_ENTER||Enters network recovery.|
|CIO_NET_RCVRY_EXIT||Indicates the device handler is exiting network recovery.|
|CIO_NET_RCVRY_MODE||Indicates the device handler is in Recovery mode.|
|CIO_INV_CMD||Indicates that an invalid command was issued.|
|CIO_BAD_MICROCODE||Indicates that the microcode download failed.|
|CIO_NOT_DIAG_MODE||Indicates that the command could not be accepted because the adapter is not open in Diagnostic mode.|
|CIO_BAD_RANGE||Indicates that the parameter values have failed a range check.|
|CIO_NOT_STARTED||Indicates that the command could not be accepted because the device has not yet been started by the first call to CIO_START operation.|
|CIO_LOST_DATA||Indicates that the receive packet was lost.|
|CIO_LOST_STATUS||Indicates that a status block was lost.|
|CIO_NETID_INV||Indicates that the network ID was not valid.|
|CIO_NETID_DUP||Indicates that the network ID was a duplicate of an existing ID already in use on the network.|
|CIO_NETID_FULL||Indicates that the network ID table is full.|
Status Blocks for Communications Device Handlers Overview.
MPQP Device Handler Interface Overview.
Serial Optical Link Device Handler Overview.