Provides the means for receiving data from the IBM® ARTIC960Hx PCI (PCI MPQP) device.
#include <sys/uio.h>
int tsread (devno, uiop, chan, ext)
dev_t devno;
struct uio *uiop;
int chan, ext;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.
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:
|
| 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. |
The tsread entry point can be called from the process environment only.
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. |