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:
  1. The DNDELAY flag is set (determined by its setting in the last uiop->uio_fmode field).
  2. The most recent ddwrite entry point for this channel returned an EAGAIN value.
  3. 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.