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

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.

Unrecoverable Hardware Failure
When an unrecoverable hardware failure has occurred, the following status block is returned:

code CIO_ASYNC_STATUS

option[0] CIO_HARD_FAIL

option[1] SOL_FATAL_ERROR

option[2] Not used

option[3] Not used
Exceeded Network Recovery Entry Threshold
When the SOL device driver has exceeded the entry threshold of the Network Recovery mode, the following status block is returned:

code CIO_ASYNC_STATUS

option[0] CIO_HARD_FAIL

option[1] SOL_RCVRY_THRESH

option[2] Not used

option[3] Not used

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

Entered Network Recovery Mode
When the SOL device driver has entered Network Recovery mode, the following status block is returned:

code CIO_ASYNC_STATUS

option[0] CIO_NET_RCVRY_ENTER

option[1] Not used

option[2] Not used

option[3] Not used
Exited Network Recovery Mode
When the SOL device driver has exited Network Recovery mode, the following status block is returned:

code CIO_ASYNC_STATUS

option[0] CIO_NET_RCVRY_EXIT

option[1] Not used

option[2] Not used

option[3] Not used

Processor ID Status Block Values

New Processor ID
When the SOL device driver detects a new processor ID that is now reachable, the following status block is returned:

code CIO_ASYNC_STATUS

option[0] SOL_NEW_PRID

option[1] Indicates the low-order byte contains the new processor ID.

option[2] Not used.

option[3] Not used.

Processor ID Conflict

When the SOL device driver detects a processor ID conflict, the following status block is returned. The network administrator should ensure that each machine connected to the optical network has a unique processor ID.

`code`	CIO_ASYNC_STATUS
`option[0]`	SOL_PRID_CONFLICT
`option[1]`	Indicates the low-order byte contains the processor ID that is in conflict.
`option[2]`	Indicates the low-order byte contains the local processor ID.
`option[3]`	Not used.

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.