CIO_GET_STAT (Get Status) tsioctl PCI MPQP Device Handler Operation

Purpose

Gets the status of the current IBM® ARTIC960Hx PCI adapter (PCI MPQP) and device handler.

Description

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

The CIO_GET_STAT operation gets the status of the current PCI MPQP adapter and device handler. For the PCI MPQP device handler, both solicited and unsolicited status can be returned.

Solicited status is status information that is returned as a completion status to a particular operation. The CIO_START, CIO_HALT, and tswrite operations all have solicited status returned. However, for many asynchronous events common to wide-area networks, these are considered unsolicited status. The asynchronous events are divided into three classes:

The CIO_GET_STAT operation functions with a 4-Port Multiprotocol Interface adapter that has been correctly configured for use on a qualified network. Consult the adapter specifications for more information on configuring the adapter and network qualifications.

Status Blocks for the Multiprotocol Device Handler

For the CIO_GET_STAT operation, the extptr parameter points to a status_block structure. When returned, the device handler fills this structure with the appropriate information. The status_block structure is defined in the /usr/include/sys/comio.h file and returns one of the possible status conditions:

Status blocks are used to communicate status and exception information to user-mode processes.

User-mode processes receive a status block whenever they request a CIO_GET_STAT operation. A user-mode process can wait for the next available status block by issuing a tsselect entry point with the specified POLLPRI event.

Status blocks contain a code field and possible options. The code field indicates the type of status block code (for example, CIO_START_DONE). The following possible PCI MPQP status blocks exist:

CIO_ASYNC_STATUS Status Block

Asynchronous status notifies the data link control of asynchronous events such as network and adapter failures.

Code CIO_ASYNC_STATUS
option[0] Can be one of the following:
  MP_DSR_DROPPED, MP_RCV_TIMEOUT, MP_RELOAD_CMPL, MP_RESET_CMPL, MP_X21_CLEAR
option[1] Not used
option[2] Not used
option[3] Not used
Note: The MP_RELOAD_C and MPLMP_RESET_CMPL values are for diagnostic use only.

CIO_HALT_DONE Status Block

The CIO_HALT operation ends a session with the PCI MPQP device handler. On a successfully completed Halt Device operation, the following status block is provided:

Code CIO_HALT_DONE
option[0] CIO_OK
option[1] MP_FORCED_HALT or MP_NORMAL_HALT
option[2] MP_NETWORK_FAILURE or MP_HW_FAILURE

A forced halt is a halt completed successfully in terms of the data link control is concerned, but terminates forcefully because of either an adapter error or a network error. This is significant for X.21 or other switched networks where customers can be charged if the call does not disconnect properly.

Note: When using the X.21 physical interface, X.21 centralized multiport (multidrop) operation on a leased-circuit public data network is not supported.

CIO_START_DONE Status Block

On a successfully completed CIO_START operation, the following status block is provided:

Code CIO_START_DONE
option[0] CIO_OK
option[1] Network ID
option[2] Not used
option[3] Not used

On an unsuccessful Start Device CIO_START tsioctl operation, the following status block is provided:

Code CIO_START_DONE
option[0] Can be one of the following:
MP_ADAP_NOT_FUNC
Adapter not functional
MP_TX_FAILSAFE_TIMEOUT
Transmit command did not complete.
MP_DSR_ON_TIMEOUT
DSR failed to come on.
MP_DSR_ALRDY_ON
DSR already on for a switched line.
MP_X21_CLEAR
Unexpected clear received from the DCE.
option[1] If the option[0] field is set to MP_X21_TIMEOUT, the option[1] field contains the specific X.21 timer that expired.
option[2] Not used.
option[3] Not used.

CIO_TX_DONE Status Block

On completion of a multiprotocol transmit, the following status block is provided:

Code CIO_TX_DONE
option[0] Can be one of the following:
CIO_OK
MP_TX_UNDERRUN
MP_X21_CLEAR
MP_TX_FAILSAFE_TIMEOUT
The transmit command did not complete.
MP_TX_ABORT
Transmit aborted due to CIO_HALT operation.
option[1] Identifies the write_id field supplied by the caller in the write command if TX_ACK was selected.
option[2] Points to the buffer with transmit data.
option[3] Not used.

MP_THRESH_EXC Status Block

A threshold for one of the counters defined in the start profile has reached its threshold.

Code MP_THRESH_EXC
option[0] Indicates the expired threshold.
  The following values are returned to indicate the threshold that was exceeded: MP_TOTAL_TX_ERR, MP_TOTAL_RX_ERR, MP_TX_PERCENT, MP_RX_PERCENT
option[1] Not used.
option[2] Not used.
option[3] Not used.

Execution Environment

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

Return Values

The return codes for the CIO_GET_STAT operation are:

Item Description
ENOMEM Indicates no mbufs or mbuf clusters are available.
ENXIO Indicates the adapter number is out of range.