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

CIO_GET_STAT (Get Status) sol_ioctl Serial Optical Link Device Handler Operation

Purpose

Gets the current status of the Serial Optical Link (SOL) device and device handler.

Description

Note: Only user-mode callers can use the CIO_GET_STAT operation.

The CIO_GET_STAT operation returns the current status of the SOL device and device handler. For this operation, the arg parameter points to a status_block structure.

Status Blocks for the Serial Optical Link Device Driver

Status blocks contain a code field and possible options. The code field indicates the type of status block (for example, CIO_START_DONE). The following are possible status blocks returned by the SOL device driver:

The status block structure is defined in the /usr/include/sys/comio.h file and includes the following status codes:

code Indicates one of the following status conditions:
  • CIO_ASYNC_STATUS
  • CIO_HALT_DONE
  • CIO_NULL_BLK
  • CIO_START_DONE
  • CIO_TX_DONE
option[4] Contains up to four words of additional information, depending on which of the codes listed above is returned.

Status blocks provide status and exception information to users of the SOL device driver.

User-mode processes receive a status block when they request a CIO_GET_STAT operation. A user-mode process can wait for the next available status block by issuing a select system call with the specified POLLPRI event.

Kernel-mode processes receive a status block by way of the stat_fn entry point that is specified at open time.

CIO_ASYNC_STATUS Status Block

The SOL device driver can return the following types of asynchronous status:

Hard Failure Status Block Values

When a CIO_HARD_FAIL status block is returned, the SOL device is no longer functional. The user should begin shutting down the SOL device driver.

Lost Data Status Block Value

For a user-mode process, when the receive queue overflows, the data is lost, and the following status block is returned:

code CIO_ASYNC_STATUS
option[0] CIO_LOST_DATA
option[1] Not used
option[2] Not used
option[3] Not used
Network Recovery Mode Status Block Values
Processor ID Status Block Values

CIO_HALT_DONE Status Block

On a successfully completed CIO_HALT operation, the status block is filled as follows:

code CIO_HALT_DONE
option[0] CIO_OK
option[1] Indicates the low-order bytes are filled in with the netid field passed with the CIO_START operation.
option[2] Not used.
option[3] Not used.

CIO_START_DONE Status Block

On a successfully completed CIO_START operation, the status block is filled as follows:

code CIO_START_DONE
option[0] CIO_OK
option[1] Indicates the low-order bytes are filled in with the netid field passed with the CIO_START operation.
option[2] Not used.
option[3] Not used.

If the CIO_START operation is unsuccessful, the status block is filled as follows:

code CIO_START_DONE
option[0] Specifies one of the following:
  • CIO_TIMEOUT
  • CIO_HARD_FAIL
option[1] Indicates the low-order bytes are filled in with the netid field passed with the CIO_START operation.
option[2] Not used.
option[3] Not used.

CIO_TX_DONE Status Block

When a write request completes for which transmit acknowledgment has been requested, the following status block is built and returned to the caller:

code CIO_TX_DONE
option[0] Specifies one of the following:
  • CIO_HARD_FAIL
  • CIO_OK
  • CIO_TIMEOUT
option[1] Contains the write_id field specified in the write_extension structure in the write operation.
option[2] For a kernel-mode process, contains the mbuf pointer that was passed in the write operation.
option[3] Specifies one of the following:
SOL_ACK Indicates the data was received by the destination processor.
SOL_DOWN_CONN Indicates the link to the destination has failed.
SOL_NACK_NB Indicates the destination processor ID cannot allocate enough buffers to receive the data.
SOL_NACK_NR Indicates the destination processor ID is currently not receiving.
SOL_NACK_NS Indicates the destination processor ID cannot allocate enough buffers to receive the data.
SOL_NEVER_CONN Indicates a connection has never been established with the destination processor ID.
SOL_NO_CONN Indicates the destination processor ID is currently not responding.

When the option[0] field indicates CIO_OK, the data is guaranteed to have been received into memory at the destination. If the S (serialized) option was specified on the open, and the connection is point-to-point, the data is guaranteed to have been received in the order in which it was sent.

Note: When communicating through the Network Systems Corp. DX Router, in-order guaranteed delivery to the destination is not possible. A successful transmission indicates only that the data was successfully received at the DX Router, not necessarily at the final destination. It is the application's responsibility to ensure the data arrives at the destination.

Execution Environment

The CIO_GET_STAT operation can be called from the process environment only.

Return Values

EACCES Illegal call from kernel user.
EFAULT Indicates the specified address is not valid.
EINVAL Indicates the parameter is not valid.

Implementation Specifics

The CIO_GET_STAT operation 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.

Related Information

The sol_ioctl entry point, sol_mpx entry point, sol_select entry point.

The stat_fn kernel procedure.

The CIO_START sol_ioctl Serial Optical Link Device Handler Operation, CIO_HALT sol_ioctl Serial Optical Link Device Handler Operation.

[ Previous | Next | Contents | Home | Search ]