tswrite Multiprotocol (PCI MPQP) Device Handler Entry Point

Purpose

Provides the means for transmitting data to the IBM® ARTIC960Hx PCI (PCI MPQP) device.

Syntax

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

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

Description

The tswrite entry point provides the means for transmitting data to the PCI MPQP device. The kernel calls it when a user-mode process issues a write or writex subroutine. The tswrite entry point can also be called in response to an fpwrite kernel service.

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

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

tswrite Parameter Block

For the tswrite operation, the ext parameter points to the mp_write_extension structure. This structure is defined in the /usr/include/sys/comio.h file. The mp_write_extension structure contains the following fields:

Item Description
status Identifies the status of the port. The possible values for the returned status field are:
CIO_OK
Indicates the operation was successful.
CIO_TX_FULL
Indicates unable to queue any more transmit requests.
CIO_HARD_FAIL
Indicates hardware failure.
CIO_INV_BFER
Indicates invalid buffer (length equals 0, invalid address).
CIO_NOT_STARTED
Indicates device not yet started.
write_id Contains a user-supplied correlator. The write_id field is returned to the caller by the CIO_GET_STAT operation if the CIO_ACK_TX_DONE flag is selected in the asynchronous status block.

For a kernel user, this field is returned to the caller with the stat_fn function which was provided at open time.

In addition to the common parameters, the mp_write_extension structure contains a field for selecting Transparent mode for binary synchronous communication (BSC). Any nonzero value for this field causes Transparent mode to be selected. Selecting Transparent mode causes the adapter to insert data link escape (DLE) characters before all appropriate control characters. Text sent in Transparent mode is unaltered. Transparent mode is normally used for sending binary files.

Note: If an mp_write_extension structure is not supplied, Transparent mode can be implemented by the kernel-mode process by imbedding the appropriate DLE sequences in the data buffer.

Parameters

Item Description
devno Specifies major and minor device numbers.
uiop Points to a 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 entry point.
ext Specifies the address of the mp_write_extension parameter block. If the ext parameter is null, no parameter block is specified.

Execution Environment

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

Return Values

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

Item Description
EAGAIN Indicates that the number of direct memory accesses (DMAs) has reached the maximum allowed or that the device handler cannot get memory for internal control structures.
Note: The PCI MPQP device handler does not currently support the tx_fn function. If a value of EAGAIN is returned by an tswrite entry point, the application is responsible for retrying the write.
ECHRNG Indicates that the channel number is too high.
EINVAL Indicates one of the following:
  • The port is not set up properly.
  • The PCI MPQP device handler could not set up structures for the write.
  • The port is not valid.
ENOMEM Indicates that no mbuf structure or clusters are available or the total data length is more than a page.
ENXIO Indicates one of the following:
  • The port has not been successfully started.
  • An invalid adapter number was passed.
  • The specified channel number is illegal.