Note: This function is supported in AIX® 5.1 and earlier only.
Gets the current status of the token-ring adapter and device handler.
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 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.
When an unrecoverable adapter check has occurred, this status block is returned:
| Code | CIO_ASYNC_STATUS |
|---|---|
| option[0] | CIO_HARD_FAIL |
| option[1] | TOK_ADAP_CHECK |
| option[2] | The adapter return code is in the two high-order bytes. The adapter returns three parameters when an adapter check occurs. Parameter 0 is returned in the two low-order bytes. |
| option[3] | The two high-order bytes contain parameter 1. The two low-order bytes contain parameter 2. |
When an unrecoverable PIO error has occurred, this status block is returned:
| Code | CIO_ASYNC_STATUS |
|---|---|
| option[0] | CIO_HARD_FAIL |
| option[1] | TOK_PIO_FAIL |
| option[2] | Not used |
| option[3] | Not used |
When the token-ring device handler has exceeded the network Recovery mode entry threshold, this status block is returned:
| Code | CIO_ASYNC_STATUS |
|---|---|
| option[0] | CIO_HARD_FAIL |
| option[1] | TOK_RCVRY_THRESH |
| option[2] | Not used |
| option[3] | Not used |
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:
|
| 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:
|
| 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. |
| 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. |
The CIO_GET_STAT tokioctl operation can be called from the process environment only.