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

mpwrite Multiprotocol (MPQP) Device Handler Entry Point

Purpose

Provides the means for transmitting data to the Multiprotocol Quad Port (MPQP) device.

Syntax 

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

Parameters

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 mpmpx entry point.
ext Specifies the address of the mp_write_extension parameter block. If the ext parameter is null, no parameter block is specified.

Description

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

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

mpwrite Parameter Block

For the mpwrite 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:

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.

Execution Environment

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

Return Values

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

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 MPQP device handler does not currently support the tx_fn function. If a value of EAGAIN is returned by an mpwrite 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 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.

Implementation Specifics

The mpwrite 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, mpread entry point, mpselect entry point.

The CIO_GET_STAT (Get Status) mpioctl MPQP Device Handler Operation.

The write or writex subroutine.

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.

Binary Synchronous Communication (BSC) with the MPQP Adapter in AIX Kernel Extensions and Device Support Programming Concepts.

[ Previous | Next | Contents | Home | Search ]