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

mpread Multiprotocol (MPQP) Device Handler Entry Point

Purpose

Provides the means for receiving data from the Multiprotocol Quad Port (MPQP) device.

Syntax

#include <sys/uio.h>
int mpread (devno, uiop, chan, ext)
dev_t devno;
struct uio *uiop;
int chan, ext;

Parameters

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 mpmpx routine.
ext Specifies the address of the read_extension structure. If the ext parameter is null, then no parameter block is specified.

Description

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

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

The DNDELAY flag, set either at open time or later by an mpioctl operation, controls whether mpread calls put the caller to sleep pending completion of the call. If a program issues an mpread 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 mpread 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 mpread entry point is the size of the internal buffer. For the 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 MPQP device handler uses a fixed length buffer for transmitting and receiving data. The maximum supported buffer size is 4096 bytes.

Note: The 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 mpread 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:

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.
MP_X21_CPS Holds an X.21 call progress signal.
MP_X21_DPI Holds information provided by X.21 Data Communications Equipment (DCE) (network data).
MP_MODEM_DATA Contains modem data (for example, an autodial sent by the modem).
MP_AR_DATA_RCVD Contains data received while in Autoresponse mode.
Note: When using the X.21 physical interface, X.21 centralized multiport (multidrop) operation on a leased-circuit public data network is not supported.

Execution Environment

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

Return Values

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

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.

Implementation Specifics

The mpread 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.

Related Information

The mpclose entry point, mpconfig entry point, mpioctl entry point, mpmpx entry point, mpopen entry point, mpselect entry point, mpwrite entry point.

The read or readx subroutine.

The CIO_START mpioctl operation, MP_START_AR mpioctl operation.

The uio structure.

Communications Physical Device Handler Model Overview in AIX Kernel Extensions and Device Support Programming Concepts.

MPQP Device Handler Interface Overview in AIX Kernel Extensions and Device Support Programming Concepts.

Communications I/O Subsystem: Programming Introduction in AIX Kernel Extensions and Device Support Programming Concepts.

[ Previous | Next | Contents | Home | Search ]