tsopen Multiprotocol (PCI MPQP) Device Handler Entry Point

Purpose

Prepares the IBM® ARTIC960Hx PCI (PCI MPQP) device for transmitting and receiving data.

Syntax

#include <sys/comio.h>
#include <sys/mpqp.h>

int tsopen  (devno, devflag, chan, ext)
dev_t devno;
ulong devflag;
int chan;
STRUCT kopen_ext *ext;

Description

The tsopen entry point prepares the PCI 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 tsopen entry point when an open subroutine is issued. The device should be opened for reading and writing data.

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

The PCI MPQP device handler only supports one kernel-mode process to open each port on the PCI 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 tsopen 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 tsopen 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.

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 tsopen 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 tsmpx entry point.
ext	Points to the kopen_ext parameter block for kernel-mode processes. Specifies the address to the tsopen parameter block for user-mode processes.

Execution Environment

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

Return Values

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

Item	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.