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

CIO_START ddioctl Communications PDH Operation

Purpose

Opens a communication session on a channel opened by a ddopen entry point.

Syntax

#include <sys/device.h>
#include <sys/comio.h>
int ddioctl (devno, op, parmptr, devflag, chan, ext)
dev_t devno;
int op;
struct session_blk *parmptr;
ulong devflag;
int chan, ext;

Parameters

devno Specifies major and minor device numbers.
op Specifies the entry point for the CIO_START operation.
parmptr Points to a session_blk structure. This structure is defined in the /usr/include/sys/comio.h file.
devflag Specifies the DKERNEL flag. This flag is set by calling kernel-mode processes and cleared by calling user-mode processes.
chan Specifies the channel number assigned by the device handler's ddmpx entry point.
ext Indicates device-dependent.

Description

The CIO_START operation must be supported by each physical device handler (PDH) in the communication I/O subsystem. Its use varies from adapter to adapter. This operation opens a communication session on a channel opened by a ddopen entry point. Once a channel is opened, multiple CIO_START operations can be issued. For each successful start, a corresponding CIO_HALT operation must be issued later.

The CIO_START operation requires only the netid input parameter. This parameter is registered for the session. At least one network ID must be registered for this session before the PDH successfully accepts a call to the ddwrite or ddread entry point on this session. If this start is the first issued for this port or adapter, the appropriate hardware initialization is performed. Time-consuming initialization activities, such as call connection, are also performed.

This call returns immediately to the caller before the asynchronous command completes. If the return indicates no error, the PDH builds a CIO_START_DONE status block upon completion. For kernel-mode processes, the status block is passed to the associated status function (specified at open time). For user-mode processes, the status block is placed in the associated status or exception queue.

The session_blk Parameter Block

For the CIO_START operation, the ext parameter may be a pointer to a session_blk structure. This structure is defined in the /usr/include/sys/comio.h file and contains the following fields:

status Indicates the status of the port. This field may contain additional information about the completion of the CIO_START operation. Besides the status codes listed here, device-dependent codes can also be returned:
CIO_OK Indicates the operation was successful.
CIO_INV_CMD Indicates an issued command was not valid.
CIO_NETID_INV Indicates the network ID was not valid.
CIO_NETID_DUP Indicates the network ID was a duplicate of an existing ID already in use on the network.
CIO_NETID_FULL Indicates the network table is full.
netid Contains the network ID to register with the start.

Execution Environment

A CIO_START operation can be called from the process environment only.

Return Values

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

ENXIO Indicates an attempt to use an unconfigured device.
EFAULT Indicates a specified address is not valid.
EINVAL Indicates a parameter is not valid.
ENOSPC Indicates the network ID table is full.
EADDRINUSE Indicates a duplicate network ID.
EBUSY Indicates the maximum number of opens was exceeded.
ENODEV Indicates the device does not exist.

Related Information

The ddioctl device driver entry point in AIX Version 4.3 Technical Reference: Kernel and Subsystems Volume 1.

The CIO_GET_FASTWRT ddioctl Communications PDH Operation, CIO_GET_STAT ddioctl Communications PDH Operation, CIO_HALT ddioctl Communications PDH Operation.

The ddread entry point, ddwrite entry point.

[ Previous | Next | Contents | Home | Search ]