sol_write Serial Optical Link Device Handler Entry Point

Purpose

Note: This function is supported in AIX® 5.1 and earlier only.

Provides the means for transmitting data to the Serial Optical Link (SOL) device handler.

Syntax

#include  <sys/device.h>
#include  <sys/comio.h>
#include  <sys/soluser.h>

int sol_write (devno, uiop, chan, arg)
dev_t devno;
struct uio *uiop;
int chan;
struct write_extension *arg;

Parameters

Item	Description
devno	Specifies major and minor device numbers.
uiop	Points to a uio structure specifying the location and length of the caller's data.
chan	Specifies the channel number assigned by the sol_mpx entry point.
arg	Points to a write_extension structure. If the arg parameter is null, default values are assumed.

Description

The sol_write entry point provides the means for transmitting data to the SOL device handler. The kernel calls this entry point when a user-mode caller issues a write, writex, writev, or writevx subroutine.

For a user-mode process, the kernel fills in the uio structure with the appropriate values. A kernel-mode process must fill in the uio structure as described by the ddwrite communications entry point.

For the sol_write entry point, the arg parameter may point to a write_extension structure. This structure is defined in the /usr/include/sys/comio.h file and contains the following fields:

Field	Description
`status`	Indicates the status condition that occurred. Possible values for the returned status field are: CIO_OK CIO_TX_FULL CIO_NOT_STARTED CIO_BAD_RANGE CIO_NOMBUF
`flag`	Consists of a possible bitwise OR of the following: CIO_NOFREE_MBUF Requests that the physical device handler (PDH) not free the mbuf structure after transmission is complete. The default is bit clear (free the buffer). For a user-mode process, the PDH always frees the mbuf structure. CIO_ACK_TX_DONE Requests that when done with this operation, the PDH acknowledges completion by building a CIO_TX_DONE status block. In addition, requests the PDH either call the kernel status function or (for a user-mode process) place the status block in the status/exception queue. The default is bit clear (do not acknowledge transmit completion).
`write_id`	For a user-mode caller, the `write_id` field is returned to the caller by the CIO_GET_STAT operation (if the CIO_ACK_TX_DONE option is selected). For a kernel-mode caller, the `write_id` field is returned to the caller by the stat_fn routine that was provided at open time.

The data packet must start with a 4-byte field for the destination processor ID (the ID goes in the low-order byte), followed by a 1-byte field for the destination netid. When the data is received at the destination, the 4-byte processor ID will be stripped off, so that the first byte is the 1-byte netid.

The maximum packet size allowed is SOL_MAX_XMIT, as defined in the /usr/include/sys/soluser.h file.

In case of a link failure, the device handler uses any link that is available. In-order reception of data frames is not guaranteed unless the S (serialized) option is specified on the open of the device. See the sol_mpx entry point for a description of this option.

The sol_write entry point functions with a Serial Link Adapter and Serial Optical Channel Converter that have been correctly configured for use on a qualified network. Consult hardware specifications for more information on configuring hardware and network qualifications.

Note: When the Network Systems Corp. DX Router is used for communication, in-order reception cannot be guaranteed even when using a serialized open.

Execution Environment

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

Return Values

Item	Description
ENODEV	Indicates the specified minor number is not valid.
ENETDOWN	Indicates the network is down. The device is not able to process the write.
ENOCONNECT	Indicates the device has not been started.
EAGAIN	Indicates the transmit queue is full.
EINVAL	Indicates the specified parameter is not valid.
ENOMEM	Indicates the device handler was not able to allocate the required memory.
EINTR	Indicates a system call was interrupted.
EFAULT	Indicates the address supplied is not valid.