[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts

Communications Physical Device Handler Model Overview

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.

Use of mbuf Structures in the Communications PDH

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.

Common Communications Status and Exception Codes

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.

Related Information

Status Blocks for Communications Device Handlers Overview.

MPQP Device Handler Interface Overview.

Serial Optical Link Device Handler Overview.

[ Previous | Next | Contents | Home | Search ]