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:
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:
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.
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 |
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. |
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 |
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. |
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 |
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 |
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 |
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 |
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 |
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 |
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. |
| 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.
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.
The tokioctl entry point, tokopen entry point, tokwrite entry point.
The CIO_HALT tokioctl Token-Ring Device Handler Operation, CIO_START tokioctl Token-Ring Device Handler Operation.