mpopen Multiprotocol (MPQP) Device Handler Entry Point

Purpose

Note: This function is supported in AIX® 5.1 and earlier only.

Prepares the Multiprotocol Quad Port (MPQP) device for transmitting and receiving data.

Syntax

#include <sys/comio.h> #include <sys/mpqp.h> int mpopen (devno, devflag, chan, ext) dev_t devno; ulong devflag; int chan; STRUCT kopen_ext *ext;

Parameters

Item Description
devno Specifies the major and minor device numbers.
devflag Specifies the flag word. For kernel-mode processes, the devflag parameter must be set to the DKERNEL flag, which specifies that a kernel routine is making the mpopen call. In addition, the following flags can be set:
DWRITE
Specifies to open for reading and writing.
DREAD
Specifies to open for a trace.
DNDELAY
Specifies to open without waiting for the operation to complete. If this flag is set, write requests return immediately and read requests return with 0 length data if no read data is available. The calling process does not sleep. The default is DELAY or blocking mode.
DELAY
Specifies to wait for the operation to complete before opening. This is the default.
Note: For user-mode processes, the DKERNEL flag must be clear.
chan Specifies the channel number assigned by the mpmpx entry point.
ext Points to the kopen_ext parameter block for kernel-mode processes. Specifies the address to the mpopen parameter block for user-mode processes.

Description

The mpopen entry point prepares the MPQP device for transmitting and receiving data. This entry point is invoked in response to a fp_open kernel service call. The file system in user mode also calls the mpopen entry point when an open subroutine is issued. The device should be opened for reading and writing data.

Each port on the MPQP adapter must be opened by its own mpopen call. Only one open call is allowed for each port. If more than one open call is issued, an error is returned on subsequent mpopen calls.

The MPQP device handler only supports one kernel-mode process to open each port on the MPQP adapter. It supports the multiplex (mpx) routines and structures compatible with the communications I/O subsystem, but it is not a true multiplexed device.

The kernel process must provide a kopen_ext parameter block. This parameter block is found in /usr/include/sys/comio.h file.

For a user-mode process, the ext parameter points to the mpopen structure. This is defined in the /usr/include/sys/comio.h file. For calls that do not specify a parameter block, the default values are used.

If adapter features such as the read extended status field for binary synchronous communication (BSC) message types as well as other types of information about read data are desired, the ext parameter must be supplied. This also requires the readx or read subroutine. If a system call is used, user data is returned, although status information is not returned. For this reason, it is recommended that readx subroutines be used.

The mpopen entry point functions with a 4-Port Multiprotocol Interface Adapter that has been correctly configured for use on a qualified network. Consult the adapter specifications for more information on configuring the adapter and network qualifications.

Note: A CIO_START operation must be issued before the adapter is ready to transmit and receive data. Write commands are not accepted if a CIO_START operation has not been completed successfully.

Execution Environment

The mpopen entry point can be called from the process environment only.

Return Values

The common return codes for the mpopen entry point are the following:

Return Code Description
ENXIO Indicates that the port initialization was unsuccessful. This code could also indicate that the registration of the interrupt was unsuccessful.
ECHRNG Indicates that the channel number is out of range (too high).
ENOMEM Indicates that there were no mbuf clusters available.
EBUSY Indicates that the port is in the incorrect state to receive an open call. The port may be already opened or not yet configured.