[ Previous | Next | Contents | Search ]
AIXLink/X.25 1.1 for AIX: Guide and Reference

x25sopen X.25 Device Handler Entry Point

Purpose

Initializes a channel into the X.25 device handler.

Syntax

int x25sopen (devno, devflag, chan, ext)
dev_t devno;
ulong devflag;
int chan;
struct kopen_ext *ext;

Parameters

devno Specifies major and minor device numbers.
devflag Indicates how the device was opened and whether the caller is a user- or kernel-mode process. This parameter accepts the following flags:
DKERNEL Specifies a kernel-mode process called the entry point. This flag is clear if a user-mode process called the entry point.
DREAD Specifies open for reading. This is the default for the X.25 handler regardless of whether this flag is set.
DWRITE Specifies open for writing. This is the default for the X.25 handler regardless of whether this flag is set.
DAPPEND Specifies open for appending. The X.25 handler ignores this flag.
DNDELAY Specifies that the X.25 device handler performs nonblocking reads and writes. If this flag is not set, the X.25 device handler performs blocking reads and writes.
chan Identifies the channel number assigned by the x25smpx routine.
ext Specifies the extended system call. This parameter is required for kernel-mode processes and ignored for user-mode processes.

Description

The x25sopen entry point performs data-structure allocation and initialization. Time-consuming tasks, such as port initialization and connection establishment, are deferred until the first CIO_START operation is issued. This call is synchronous and does not return until the x25open entry point is complete.

Note: If this is the first open request to the X.25 device handler, the interrupt level and interrupt handler entry point are registered.

Parameter Block

For the x25sopen entry point, the ext parameter can be a pointer to the kopen_ext structure defined in the /usr/include/sys/comio.h file. This structure contains the following fields:

status Identifies the status of the open process. This value is meaningful only if the EIO code is returned.
open_id Specifies the channel correlator for kernel mode processes. This value is passed to kernel functions to identify which channel an event occurred on.
rx_fn
                          Specifies the address of a kernel procedure. This procedure is called by the X.25 device handler whenever received data is to be processed. This kernel procedure must be defined as follows: 
void rx_fn (open_id, read_ext, mbufptr)
ulong open_id;
struct x25_read_ext *read_ext;
struct mbuf *mbufptr;

The parameters in this kernel procedure are defined as follows:

open_id Specifies the ID of this instance of the x25sopen entry point. The device handler sets this parameter to the ID originally passed to the X.25 device handler with the x25sopen entry point.
read_ext Contains the status of the x25sopen entry point. Currently, this parameter accepts a value of CIO_OK or CIO_BUF_OVFLW.
mbufptr Points to received data. This data is in the form described by the mbuf structure.

The kernel-mode process making the call to the x25sopen entry point is responsible for pinning the rx_fn kernel procedure before making the call. When the X.25 device handler calls the kernel procedure, the X.25 device handler pins the mbuf structure. It is the responsibility of the rx_fn kernel procedure to free the pinned mbuf structure.

tx_fn
                          Identifies the address of a kernel procedure. The X.25 device handler calls this procedure when both the following conditions are true:
  • The most recent x25swrite entry point for this channel was unsuccessful with a return code of EAGAIN, indicating the write request was not performed.
  • The x25sopen entry point, or the most recent x25sioctl operation for this channel, indicates the nonblocking mode (DNDELAY) is set.

The tx_fn kernel process should be defined as follows:

void tx_fn (open_id)
ulong open_id;

The parameter in this kernel process is defined as follows:

open_id Identifies the ID of the x25sopen entry point. The device handler sets this value to the ID passed with the x25sopen entry point.

The kernel-mode process making the call to the x25sopen entry point is responsible for pinning the tx_fn kernel procedure before making the call.

stat_fn
                          The address of a kernel procedure to be called by the X.25 device handler whenever a status block becomes available. The kernel procedure should have the following structure: 
void stat_fn (open_id, sblk_ptr)
ulong open_id;
struct status_block *sblk_ptr;

The kernel procedure parameters have the following values:

open_id Identifies the ID of the open entry point. The device handler sets this value to the ID passed with the x25sopen entry point.
sblk_ptr Points to a status block.

The kernel-mode process that calls the x25sopen entry point is responsible for pinning the stat_fn kernel procedure before making the open call.

The rx_fn, tx_fn and stat_fn kernel procedures are all made synchronously at high priority. It is therefore imperative that the called kernel procedure return quickly. Until the return, the kernel procedure cannot call any other device entry point.

Note: Entry points are associated with a channel initialized by the x25sopen entry point. Sessions are initialized by the CIO_START operation. A single channel can support numerous sessions.

Execution Environment

An x25sopen entry point can be called from the process environment only.

Return Values

A return code of -1 indicates an unsuccessful operation. The kernel sets the errno global variable to one of the following values:

EINVAL Indicates a kernel user passed an invalid function.
EIO Indicates that an error has occurred. The sb.status field contains the CIO_HARD_FAIL return value, indicating a hardware failure was detected.
EINTR Indicates that the open subroutine was interrupted.
ENODEV Indicates that the device requested does not exist.
EBUSY Indicates that the maximum number of opens was exceeded. This error results from an attempt to open a channel in diagnostic mode while other channels on the minor device number are open. This error can also result from an attempt to open a channel while another channel is already open and running in monitor or router mode.
ENOMEM Indicates that the X.25 device handler was unable to allocate space required for the open.
ENXIO Indicates that one of the following occurred:
  • An attempt was made to open the X.25 device handler before it was configured.
  • The interrupt could not be registered.

Implementation Specifics

The x25sopen entry point functions with an X.25 Interface Co-Processor/2 that has been correctly configured for use on a qualified network. Consult adapter specifications for more information on configuring the adapter and network qualifications.

Related Information

The CIO_START x25ioctl X.25 Device Handler Operation.

The x25sioctl entry point, x25smpx entry point, x25swrite entry point.

The open subroutine.

X.25 Device Handler Modes in AIX Kernel Extensions and Device Support Programming Concepts.

[ Previous | Next | Contents | Search ]