ddopen (Kernel Mode) Communications PDH Entry Point

Purpose

Performs data structure allocation and initialization for a communications physical device handler (PDH).

Syntax

#include <sys/device.h>
#include <sys/comio.h>

int ddopen (devno, devflag, chan, extptr) dev_t devno; ulong devflag; int chan; struct kopen_ext * extptr;

Parameters for Kernel-Mode Processes

Item	Description
devno	Specifies major and minor device numbers.
devflag	Specifies the flag word with the following definitions: DKERNEL Set to call a kernel-mode process. DNDELAY When set, the PDH performs nonblocking writes for this channel. Otherwise, blocking writes are performed.
chan	Specifies the channel number assigned by the device handler's ddmpx entry point.
extptr	Points to the kopen_ext structure.

Description

The ddopen entry point performs data structure allocation and initialization. Hardware initialization and other time-consuming activities, such as call initialization, are not performed. This call is synchronous, which means it does not return until the ddopen entry point is complete.

kopen_ext Parameter Block

For a kernel-mode process, the extptr parameter points to a kopen_ext structure. This structure contains the following fields:

Field	Description
`status`	The status field may contain additional information about the completion of an open. Besides the status code listed here, the following device-dependent codes can also be returned: CIO_OK Indicates the operation was successful. CIO_NOMBUF Indicates the operation was unable to allocate mbuf structures. CIO_BAD_RANGE Indicates a specified address or parameter was not valid. CIO_HARD_FAIL Indicates a hardware failure has been detected.
`rx_fn`	Specifies the address of a kernel procedure. The PDH calls this procedure whenever there is a receive frame to be processed. The rx_fn procedure must have the following syntax: #include </usr/include/sys/comio.h> void rx_fn (open_id, rd_ext_p, mbufptr) ulong open_id; struct read_extension *rd_ext_p; struct mbuf *mbufptr; open_id Identifies the instance of open. This parameter is passed to the PDH with the ddopen entry point. rd_ext_p Points to the read extension as defined in the /usr/include/sys/comio.h file. mbufptr Points to an mbuf structure containing received data. The kernel procedure calling the ddopen entry point is responsible for pinning the rx_fn kernel procedure before making the open call. It is the responsibility of code scheduled by the rx_fn procedure to free the mbuf chain.
`tx_fn`	Specifies the address of a kernel procedure. The PDH calls this procedure when the following sequence of events occurs: The DNDELAY flag is set (determined by its setting in the last `uiop->uio_fmode` field). The most recent ddwrite entry point for this channel returned an EAGAIN value. Transmit queue for this channel now has room for a write. The tx_fn procedure must have the following syntax: #include </usr/include/sys/comio.h> void tx_fn (open_id) ulong open_id; open_id Identifies the instance of open. This parameter is passed to the PDH with the ddopen call. The kernel procedure calling the ddopen entry point is responsible for pinning the tx_fn kernel procedure before making the call.
`stat_fn`	Specifies the address of a kernel procedure to be called by the PDH whenever a status block becomes available. This procedure must have the following syntax: #include </usr/include/usr/comio.h> void stat_fn (open_id, sblk_ptr); ulong open_id; struct status_block *sblk_ptr open_id Identifies the instance of open. This parameter is passed to the PDH with the ddopen entry point. sblk_ptr Points to a status block defined in the /usr/include/sys/comio.h file. The kernel procedure calling the ddopen entry point is responsible for pinning the stat_fn kernel procedure before making the open call. The rx_fn, tx_fn, and stat_fn procedures are made synchronously from the off-level portion of the PDH at high priority from the PDH. Therefore, the called kernel procedure must return quickly. Parameter blocks are passed by reference and are valid only for the call's duration. After a return from this call, the parameter block should not be accessed.

Execution Environment

A ddopen (kernel mode) entry point can be called from the process environment only.

Return Values

In general, communication device handlers use the common codes defined for an entry point. However, device handlers for specific communication devices may return device-specific codes. The common return codes for the ddopen entry point are the following:

Return Code	Description
EINVAL	Indicates a parameter is not valid.
EIO	Indicates an error has occurred. The `status` field contains the relevant exception code.
ENODEV	Indicates there is no such device.
EBUSY	Indicates the maximum number of opens was exceeded, or the device was opened in exclusive-use mode.
ENOMEM	Indicates the PDH was unable to allocate the space that it needed.
ENXIO	Indicates an attempt was made to open the PDH before it was configured.
ENOTREADY	Indicates the PDH is in the process of shutting down the adapter.