tsread Multiprotocol (PCI MPQP) Device Handler Entry Point

Purpose

Provides the means for receiving data from the IBM® ARTIC960Hx PCI (PCI MPQP) device.

Syntax

#include <sys/uio.h>

int tsread (devno, uiop, chan, ext)
dev_t devno;
struct uio *uiop;
int chan, ext;

Description

Note: Only user-mode processes should use the tsread entry point.

The tsread entry point provides the means for receiving data from the PCI MPQP device. When a user-mode process user issues a read or readx subroutine, the kernel calls the tsread entry point.

The DNDELAY flag, set either at open time or later by an tsioctl operation, controls whether tsread calls put the caller to sleep pending completion of the call. If a program issues an tsread entry point with the DNDELAY flag clear (the default), program execution is suspended until the call completes. If the DNDELAY flag is set, the call always returns immediately. The user must then issue a poll and a CIO_GET_STAT operation to be notified when read data is available.

When user application programs invoke the tsread operation through the read or readx subroutine, the returned length value specifies the number of bytes read. The status field in the read_extension parameter block should be checked to determine if any errors occurred on the read. One frame is read into each buffer. Therefore, the number of bytes read depends on the size of the frame received.

For a nonkernel process, the device handler copies the data into the buffer specified by the caller. The size of the buffer is limited by the size of the internal buffers on the adapter. If the size of the use buffer exceeds the size of the adapter buffer, the maximum number of bytes on a tsread entry point is the size of the internal buffer. For the PCI MPQP adapter, the maximum frame size is defined in the /usr/include/sys/mpqp.h file.

Data is not always returned on a read operation when an error occurs. In most cases, the error causes an error log to occur. If no data is returned, the buffer pointer is null. On errors such as buffer overflow, a kernel-mode process receives the error status and the data.

There are also some cases where network data is returned (usually during a CIO_START operation). Network data is distinguished from normal receive data by the status field in the read_extension structure. A nonzero status in this field indicates an error or information about the data.

The PCI MPQP device handler uses a fixed length buffer for transmitting and receiving data. The maximum supported buffer size is 4096 bytes.

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

Note: The PCI MPQP device handler uses fixed length buffers for transmitting and receiving data. The RX_BUF_LEN field in the /usr/include/sys/mpqp.h file defines the maximum buffer size.

read_extension Parameter Block

For the tsread entry points, the ext parameter may point to a read_extension structure. This structure is found in the /usr/include/sys/comio.h file and contains this field:

Item Description
status Specifies the status of the port. There are six possible values for the returned status parameter. The following status values accompany a data buffer:
CIO_OK
Indicates that the operation was successful.
MP_BUF_OVERFLOW
Indicates receive buffer overflow. For the MP_BUF_OVERFLOW value, the data that was received before the buffer overflowed is returned with the overflow status.
Note: When using the X.21 physical interface, X.21 centralized multiport (multidrop) operation on a leased-circuit public data network is not supported.

Parameters

Item Description
devno Specifies the major and minor device numbers.
uiop Pointer to an uio structure that provides variables to control the data transfer operation. The uio structure is defined in the /usr/include/sys/uio.h file.
chan Specifies the channel number assigned by the tsmpx routine.
ext Specifies the address of the read_extension structure. If the ext parameter is null, then no parameter block is specified.

Execution Environment

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

Return Values

The tsread entry point returns the number of bytes read. In addition, this entry point may return one of the following:

Item Description
ECHRNG Indicates the channel number was out of range.
ENXIO Indicates the port is not in the proper state for a read.
EINTR Indicates the sleep was interrupted by a signal.
EINVAL Indicates the read was called by a kernel process.