The Token-Ring device driver is a dynamically loadable device driver that runs on AIX Version 4.1 (or later). The device driver is automatically loaded into the system at device configuration time as part of the configuration process. The interface to the device is through the kernel services known as Network Services.
Interfacing to the device driver is achieved by calling the device driver's entry points for opening the device, closing the device, transmitting data, doing a remote dump, and issuing device control commands.
The Token-Ring device driver interfaces with the PCI Token-Ring High-Performance Network Adapter (14101800). The adapter is IEEE 802.5 compatible and supports both 4 and 16 megabit per second networks. The adapter supports only an RJ-45 connection.
The tok_config() entry point conforms to the AIX Version 4.1 (or later) kernel object file entry point.
The tok_open() function is called to open the specified network device.
The Token-Ring device driver does a synchronous open. The device is initialized at this time. When the resources are successfully allocated, the device starts the process of attaching the device to the network.
If the connection is successful, the NDD_RUNNING flag is set in the ndd_flags field, and an NDD_CONNECTED status block is sent.
If the device connection fails, the NDD_LIMBO flag is set in the ndd_flags field, and an NDD_LIMBO_ENTRY status block is sent.
If the device is eventually connected, the NDD_LIMBO flag is turned off, and the NDD_RUNNING flag is set in the ndd_flags field. Both NDD_CONNECTED and NDD_LIMBO_EXIT status blocks are set.
The tok_close() function is called to close the specified network device. This function resets the device to a known state and frees system resources associated with the device.
The device is not detached from the network until the device's transmit queue is allowed to drain.
The tok_output() function transmits data using the network device.
The device driver does not support mbufs from user memory that have the M_EXT flag set.
If the destination address in the packet is a broadcast address, the M_BCAST flag in the p_mbuf->m_flags field should be set prior to entering this routine. A broadcast address is defined as 0xFFFF FFFF FFFF or 0xC000 FFFF FFFF. If the destination address in the packet is a multicast address, the M_MCAST flag in the p_mbuf->m_flags field should be set prior to entering this routine. A multicast address is defined as a non-individual address other than a broadcast address. The device driver keeps statistics based on the M_BCAST and M_MCAST flags.
If a packet is transmitted with a destination address that matches the adapter's address, the packet is received. This is true for the adapter's physical address, broadcast addresses (0xC000 FFFF FFFF or 0xFFFF FFFF FFFF), enabled functional addresses, or an enabled group address.
When the Token-Ring device driver receives a valid packet from the network device, the Token-Ring device driver calls the nd_receive() function specified in the ndd_t structure of the network device. The nd_receive() function is part of a CDLI network demuxer. The packet is passed to the nd_receive() function in mbufs.
The Token-Ring device driver passes only one packet to the nd_receive() function at a time.
The device driver sets the M_BCAST flag in the p_mbuf->m_flags field when a packet is received that has an all-stations broadcast address. This address is defined as 0xFFFF FFFF FFFF or 0xC000 FFFF FFFF.
The device driver sets the M_MCAST flag in the p_mbuf->m_flags field when a packet is received that has a non-individual address that is different from the all-stations broadcast address.
The adapter does not pass invalid packets to the device driver.
When a status event occurs on the device, the Token-Ring device driver builds the appropriate status block and calls the nd_status() function specified in the ndd_t structure of the network device. The nd_status() function is part of a CDLI network demuxer.
The following status blocks are defined for the Token-Ring device driver.
When a hard failure occurs on the Token-Ring device, the following status blocks are returned by the Token-Ring device driver. One of these status blocks indicates that a fatal error occurred.
| NDD_HARD_FAIL | When a transmit error occurs, it tries to recover. If the error is unrecoverable, this status block is generated.
|
When the device driver detects an error that requires initiating recovery logic to make the device temporarily unavailable, the following status block is returned by the device driver.
Note: While the device driver is in this recovery logic, the device may not be fully functional. The device driver notifies users when the device is fully functional by way of an NDD_LIMBO_EXIT asynchronous status block:
| code | Set to NDD_LIMBO_ENTER. |
| option[0] | Set to one of the following: |
| option[ ] | The remainder of the status block can be used to return additional status information by the device driver. |
When the device driver has successfully completed recovery logic from the error that made the device temporarily unavailable, the following status block is returned by the device driver:
Note: The device is now fully functional.
| code | Set to NDD_LIMBO_EXIT. |
| option[ ] | The option fields are not used. |
The tok_ctl() function is used to provide device control functions.
The user should pass in the tok_ndd_stats_t structure as defined in <sys/cdli_tokuser.h>. The driver fails a call with a buffer smaller than the structure.
The structure must be in kernel heap so that the device driver can copy the statistics into it. Also, it must be pinned.
Setting promiscuous mode will not cause non-LLC frames to be received by the driver unless the user also enables those filters (Attention MAC frames, Beacon MAC frames).
The driver maintains a counter of requests.
This command releases a request from a user to PROMISCUOUS_ON; it will not exit the mode on the adapter if more requests are outstanding.
The arg parameter specifies the address of the token_ring_all_mib_t structure. This structure is defined in the /usr/include/sys/tokenring_mibs.h file.
The device driver does not support any variables for read_write or write only. If the syntax of a member of the structure is some integer type, the level of support flag is stored in the whole field, regardless of the size of the field. For those fields that are defined as character arrays, the value is returned only in the first byte in the field.
The arg parameter specifies the address of the token_ring_all_mib_t structure. This structure is defined in the /usr/include/sys/tokenring_mibs.h file.
This command enables the receipt of packets with a functional or a group address. The functional address indicator (bit 0 "the MSB" of byte 2) indicates whether the address is a functional address (bit 0) or a group address (bit 1). The length field is not used because the address must be 6 bytes in length.
This command disables the receipt of packets with a functional or a group address. The functional address indicator (bit 0 "the MSB" of byte 2) indicates whether the address is a functional address (bit 0) or a group address (bit 1). The length field is not used because the address must be 6 bytes in length.
The driver returns the address of the device driver's priority transmit routine.
The driver returns at least three addresses that are device physical addresses (or alternate addresses specified by the user), two broadcast addresses (0xFFFFFFFFFFFF and 0xC000 FFFF FFFF), and any additional addresses specified by the user, such as functional addresses and group addresses.
The counters kept by the device are zeroed.
The arg parameter specifies the address of the mon_all_stats_t structure. This structure is defined in the /usr/include/sys/cdli_tokuser.h file.
The statistics that are returned contain information obtained from the device. If the device is inoperable, the statistics returned are not the current device statistics. The copy of the ndd_flags field can be checked to determine the state of the device.
The Token-Ring device driver has four trace points. The IDs are defined in the /sys/cdli_tokuser.h file.
The Token-Ring error log templates are:
| ERRID_STOK_ADAP_CHECK | |
| The microcode on the device performs a series of diagnostic checks when the device is idle. These checks can find errors, and they are reported as adapter checks. If the device is connected to the network when this error occurs, the device driver goes into Network Recovery Mode in an attempt to recover from the error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists. | |
| ERRID_STOK_ADAP_OPEN | |
| Enables the device driver to open the device. The device driver goes into Network Recovery Mode in an attempt to recover from the error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists. | |
| ERRID_STOK_AUTO_RMV | |
| An internal hardware error following the beacon automatic removal process was detected. The device driver goes into Network Recovery Mode in an attempt to recover from the error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists. | |
| ERRID_STOK_RING_SPEED | |
| The ring speed (or ring data rate) is probably wrong. Contact the network administrator to determine the speed of the ring. The device driver only retries twice at 2-minute intervals after this error log entry is generated. | |
| ERRID_STOK_DMAFAIL | The device detected a DMA error in a TX or RX operation. The device driver goes into Network Recovery Mode in an attempt to recover from the error. The device is temporarily unavailable during the recovery procedure. User intervention is not required unless the problem persists. |
| ERRID_STOK_BUS_ERR | The device detected a Micro Channel bus error. The device driver goes into Network Recovery Mode in an attempt to recover from the error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists. |
| ERRID_STOK_DUP_ADDR | |
| The device detected that another station on the ring has a device address that is the same as the device address being tested. Contact the network administrator to determine why. | |
| ERRID_STOK_MEM_ERR | An error occurred while allocating memory or timer control block structures. |
| ERRID_STOK_RCVRY_EXIT | |
| The error that caused the device driver to go into error recovery mode was corrected. | |
| ERRID_STOK_RMV_ADAP | |
| The device received a remove ring station MAC frame indicating that a network management function directed this device to get off the ring. Contact the network administrator to determine why. | |
| ERRID_STOK_WIRE_FAULT | |
| There is a loose (or bad) cable between the device and the MAU. There is a chance that it might be a bad device. The device driver goes into Network Recover Mode in an attempt to recover from the error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists. | |
| ERRID_STOK_TX_TIMEOUT | |
| The transmit watchdog timer expired before transmitting a frame. The device driver goes into Network Recovery Mode in an attempt to recover from the error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists. | |
| ERRID_STOK_CTL_ERR | The ioctl watchdog timer expired before the device driver received a response from the device. The device driver goes into Network Recovery Mode in an attempt to recover from the error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists. |