[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 2

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

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:

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:

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.

Related Information

The CIO_GET_FASTWRT ddioctl Communications PDH Operation, ddclose entry point, ddopen entry point for user-mode processes, ddwrite entry point.

The ddmpx entry point.

Status Blocks for Communication Device Handlers Overview in AIX Kernel Extensions and Device Support Programming Concepts.

Communications Physical Device Handler Model Overview in AIX Kernel Extensions and Device Support Programming Concepts.

[ Previous | Next | Contents | Home | Search ]