CIO_GET_STAT (Get Status) tokioctl Token-Ring Device Handler Operation

Purpose

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

Gets the current status of the token-ring adapter and device handler.

Description

The CIO_GET_STAT tokioctl operation returns the current status of the token-ring adapter and device handler. For this operation, the arg parameter points to the status_block structure. This structure is defined in the /usr/include/sys/comio.h file and takes the following status codes:

The CIO_GET_STAT operation functions with a Token-Ring High Performance Network 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 Token-Ring Device Handler

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 tokselect 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).

There are six possible token-ring status blocks:

CIO_ASYNC_STATUS Status Block

The token-ring device handler can return the following types of asynchronous status:

When a CIO_HARD_FAIL status block is returned, the token-ring adapter is no longer functional. The user should shut down the token-ring device handler.

Hard Failure Status Block Values

The following items describe the hard failure status block values for several types of errors.

Entered Network Recovery Mode Status Block

When the token-ring device handler has entered network Recovery mode, this status block is returned:

Code CIO_ASYNC_STATUS
option[0] CIO_NET_RCVRY_ENTER
option[1] Specifies the reason for entering network Recovery mode. Can be one of these seven options:
  • TOK_ADAP_CHECK
  • TOK_AUTO_REMOVE
  • TOK_CMD_FAIL
  • TOK_LOBE_WIRE_FAULT
  • TOK_MC_ERROR
  • TOK_REMOVE_RECEIVED
  • TOK_RING_STATUS
option[2] Specifies the adapter return code. For an adapter check, the adapter return code is in the two high-order bytes. The adapter returns three parameters when an adapter check occurs. The adapter check parameter 0 is returned in the two low-order bytes.
option[3] For an adapter check, the two high-order bytes contain parameter 1. The two low-order bytes contain parameter 2.

Exited Network Recovery Mode Status Block

When the token-ring device handler has exited network Recovery mode, the status block contains the following:

Code CIO_ASYNC_STATUS
option[0] CIO_NET_RCVRY_EXIT
option[1] Not used
option[2] Not used
option[3] Not used

Ring Beaconing Status Block Values

When the token-ring adapter detects a beaconing condition on the ring, it notifies the device handler. The device handler returns the following status block:

Code CIO_ASYNC_STATUS
option[0] TOK_RING_STATUS
option[1] TOK_RING_BEACONING
option[2] Specifies the adapter return code. The two low-order bytes contain the ring status.
option[3] Not used.

Ring Recovered Status Block Values

When the token-ring detects that the beaconing condition has ceased, it notifies the device handler. The device handler returns the following status block:

Code CIO_ASYNC_STATUS
option[0] TOK_RING_STATUS
option[1] TOK_RING_RECOVERED
option[2] Not used
option[3] Not used

Lost Data Status Block

The token-ring device handler has detected lost data due to the receive queue overflowing. The device handler returns the following status block:

Code CIO_ASYNC_STATUS
option[0] CIO_LOST_DATA
option[2] Not used
option[3] Not used

CIO_HALT_DONE Status Block

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

Code CIO_HALT_DONE
option[0] CIO_OK
option[1] The two low-order bytes contain the netid field passed with the CIO_HALT operation. If a medium access control (MAC) frame session was requested, this field is set to TOK_MAC_FRAME_NETID.
option[2] Not used
option[3] Not used

CIO_LOST_STATUS Status Block

This status block is returned when it is not available due to a status queue overflow:

Code CIO_LOST_STATUS
option[0] Not used
option[1] Not used
option[2] Not used
option[3] Not used

CIO_NULL_BLK Status Block

This is returned when the status block is not available.

Code CIO_NULL_BLK
option[0] Not used
option[1] Not used
option[2] Not used
option[3] Not used

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] The two low-order bytes contain the netid field passed with the CIO_START operation. If a MAC frame session was requested, this field is set to TOK_MAC_FRAME_NETID.
option[2] The two high-order bytes contain the two high-order bytes of the network address. The two low-order bytes are filled in with the 2 middle bytes of the network address.
option[3] The two high-order bytes contain the two low-order bytes of the network address.

If the CIO_START operation is unsuccessful, the status block contains the following:

Code CIO_START_DONE
option[0] Can be one of the following options:
  • CIO_TIMEOUT
  • TOK_ADAP_CONFIG
  • TOK_ADAP_INIT_FAIL
  • TOK_ADAP_INIT_PARMS_FAIL
  • TOK_ADAP_INIT_TIMEOUT
  • TOK_ADDR_VERIFY_FAIL
  • TOK_LOBE_MEDIA_TST_FAIL
  • TOK_PHYS_INSERT
  • TOK_REQ_PARMS
  • TOK_RING_POLL
option[1] The two low-order bytes contain the netid field passed with the CIO_START operation. If a MAC frame session was requested, this field is set to TOK_MAC_FRAME_NETID.
option[2] This is the adapter return code. For each of the device-specific codes returned in option[0], an adapter return code is placed in the two low-order bytes of this field. Possible values for the option[2] field are the adapter reset, initialization, and open completion codes.
option[3] Not used

CIO_TX_DONE Status Block

When a tokwrite entry point 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] CIO_OK or TOK_TX_ERROR
option[1] Contains the write_id field specified in the write_extension structure passed to the tokwrite operation.
option[2] For a kernel-mode process, contains the mbuf pointer passed in the tokwrite operation.
option[3] The two high-order bytes contain the adapter's transmit command complete code that the adapter returns. The two low-order bytes contain the adapter's transmit CSTAT completion code that is returned when a packet is transmitted by the adapter.

Return Values

Item Description
EACCES Indicates an illegal call from a kernel-mode user.
EFAULT Specifies an address is not valid.
EINVAL Indicates a parameter is not valid.

Execution Environment

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