High-Performance (8fc8) Token-Ring Device Driver

The 8fc8 Token-Ring device driver is a dynamically loadable device driver that will run on a system running AIX Version 4.1 (or later). The device driver will be 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 Token-Ring High-Performance Network Adapter (8fc8). It provides a Micro Channel-based connection to a Token-Ring network. The adapter is IEEE 802.5 compatible and supports both 4 and 16 megabit per second networks. The adapter supports only a Shielded Twisted-Pair (STP) Token-Ring connection.

Configuration Parameters for Token-Ring Device Driver

Device Driver Configuration and Unconfiguration

The tok_config entry point performs configuration functions Token-Ring device driver.

Device Driver Open

The tok_open function is called to open the specified network device.

The Token Ring device driver does an asynchronous open. It starts the process of attaching the device to the network, sets the NDD_UP flag in the ndd_flags field, and returns 0. The network attachment will continue in the background where it is driven by device activity and system timers.

Note: The Network Services ns_alloc routine which calls this open routine causes the open to be synchronous. It waits until the NDD_RUNNING flag is set in the ndd_flags field or 60 seconds have passed.

If the connection is successful, the NDD_RUNNING flag will be set in the ndd_flags field and a NDD_CONNECTED status block will be sent. The ns_alloc routine will return at this time.

If the device connection fails, the NDD_LIMBO flag will be set in the ndd_flags field and a NDD_LIMBO_ENTRY status block will be sent.

If the device is eventually connected, the NDD_LIMBO flag will be turned off and the NDD_RUNNING flag will be set in the ndd_flags field. Both NDD_CONNECTED and NDD_LIMBO_EXIT status blocks will be set.

Device Driver Close

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 will not be detached from the network until the device's transmit queue is allowed to drain.

Data Transmission

The tok_output function transmits data using the network device.

The device driver does not support mbufs from user memory (which 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 will keep statistics based upon the M_BCAST and M_MCAST flags.

If a packet is transmitted with a destination address which matches the adapter's address, the packet will be 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.

Data Reception

When the Token-Ring device driver receives a valid packet from the network device, the Token-Ring device driver calls the nd_receive function that is 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 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 which 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 which has a non-individual address that is different than the all-stations broadcast address.

The adapter does not pass invalid packets to the device driver.

Asynchronous Status

When a status event occurs on the device, the Token-Ring device driver builds the appropriate status block and calls the nd_status function that is 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.

Hard Failure

When a hard failure has occurred on the Token-Ring device, the following status blocks can be returned by the Token-Ring device driver. One of these status blocks indicates that a fatal error occurred.

NDD_PIO_FAIL

When a PIO error occurs, it is retried 3 times. If the error still occurs, it is considered unrecoverable and this status block is generated.

TOK_RECOVERY_THRESH

When most network errors occur, they are retried. Some errors are retried with no limit and others have a recovery threshold. Errors that have a recovery threshold and fail all the retries specified by the recovery threshold are considered unrecoverable and generate the following status block:

Enter Network Recovery Mode

When the device driver has detected an error which requires initiating recovery logic that will 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 will notify users when the device is fully functional by way of an NDD_LIMBO_EXIT asynchronous status block.

NDD_ADAP_CHECK

When an adapter check has occurred, this status block is generated.

NDD_AUTO_RMV

When an internal hardware error following the beacon automatic removal process has been detected, this status block is generated.

NDD_BUS_ERR

The device has detected a I/O channel error.

NDD_CMD_FAIL

The device has detected an error in a command the device driver issued to it.

NDD_TX_ERROR

The device has detected an error in a packet given to the device.

NDD_TX_TIMEOUT

The device has detected an error in a packet given to the device.

TOK_ADAP_INIT

When the initialization of the device fails, this status block is generated.

TOK_ADAP_OPEN

When a general error occurs during open of the device, this status block is generated.

TOK_DMA_FAIL

A d_complete has failed.

TOK_RING_SPEED

When an error code of 0x27 (physical insertion, ring beaconing) occurs during open of the device, this status block is generated.

TOK_RMV_ADAP

The device has received a remove ring station MAC frame indicating that a network management function had directed this device to get off the ring.

TOK_WIRE_FAULT

When an error code of 0x11 (lobe media test, function failure) occurs during open of the device, this status block is generated.

Exit Network Recovery Mode

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. This status block means the device is now fully functional.

Network Device Driver Status

When the device driver has status or event information to report, the following status block is returned by the device driver:

Ring Beaconing

When the Token-Ring device has detected a beaconing condition (or the ring has recovered from one), the following status block is generated by the Token-Ring device driver:

Device Connected

When the device is successfully connected to the network the following status block is returned by the device driver:

Device Control Operations

The tok_ctl function is used to provide device control functions.

NDD_GET_STATS

The user should pass in the tok_ndd_stats_t structure as defined in usr/include/sys/cdli_tokuser.h. The driver will fail a call with a buffer smaller than the structure.

The statistics which are returned contain statistics obtained from the device. If the device is inoperable, the statistics which are returned will not contain the current device statistics. The copy of the ndd_flags field can be checked to determine the state of the device.

NDD_MIB_QUERY

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 will be stored in the whole field, regardless of the size of the field. For those fields which are defined as character arrays, the value will be returned only in the first byte in the field.

NDD_MIB_GET

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.

If the device is inoperable, the upstream field of the Dot5Entry_t structure will be zero instead of containing the nearest active upstream neighbor (NAUN). Also the statistics which are returned contain statistics obtained from the device. If the device is inoperable, the statistics which are returned will not contain the current device statistics. The copy of the ndd_flags field can be checked to determine the state of the device.

NDD_ENABLE_ADDRESS

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 (the bit is a 0) or a group address (the bit is a 1). The length field is not used because the address must be 6 bytes in length.

Functional Address

The specified address is "or'ed" with the currently specified functional addresses and the resultant address is set as the functional address for the device. Functional addresses are encoded in a bit-significant format, thereby allowing multiple individual groups to be designated by a single address.

The Token-Ring network architecture provides bit-specific functional addresses for widely-used functions, such as configuration report server. Ring stations use functional address "masks" to identify these functions. For example, if function G is assigned a functional address of 0xC000 0008 0000, and function M is assigned a function address of 0xC000 0000 0040, then ring station Y, whose node contains function G and M, would have a mask of 0xC000 0008 0040. Ring station Y would receive packets addressed to either function G or M or to an address like 0xC000 0008 0048 since that address contains bits specified in the "mask".

Note: The device forces the first 2 bytes of the functional address to be 0xC000. In addition, bits 6 and 7 of byte 5 of the functional address are forced to a 0 by the device.

The NDD_ALTADDRS and TOK_RECEIVE_FUNC flags in the ndd_flags field are set.

Since functional addresses are encoded in a bit-significant format, reference counts are kept on each of the 31 least significant bits of the address. Reference counts are not kept on the 17 most significant bits (the 0xC000 of the functional address and the functional address indicator bit).

Group Address

If no group address is currently enabled, the specified address is set as the group address for the device. The group address will not be set and EINVAL will be returned if a group address is currently enabled.

The device forces the first 2 bytes of the group address to be 0xC000.

The NDD_ALTADDRS and TOK_RECEIVE_GROUP flags in the ndd_flags field are set.

NDD_DISABLE_ADDRESS

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 (the bit is a 0) or a group address (the bit is a 1). The length field is not used because the address must be 6 bytes in length.

Functional Address

The reference counts are decremented for those bits in the functional address that are a one (on). If the reference count for a bit goes to zero, the bit will be "turned off" in the functional address for the device.

If no functional addresses are active after receipt of this command, the TOK_RECEIVE_FUNC flag in the ndd_flags field is reset. If no functional or group addresses are active after receipt of this command, the NDD_ALTADDRS flag in the ndd_flags field is reset.

Group Address

If the group address which is currently enabled is specified, receipt of packets with a group address is disabled. If a different address is specified, EINVAL will be returned.

If no group address is active after receipt of this command, the TOK_RECEIVE_GROUP flag in the ndd_flags field is reset. If no functional or group addresses are active after receipt of this command, the NDD_ALTADDRS flag in the ndd_flags field is reset.

NDD_MIB_ADDR

The following addresses are returned:

• Device Physical Address (or alternate address specified by user)
• Broadcast Address 0xFFFF FFFF FFFF
• Broadcast Address 0xC000 FFFF FFFF
• Functional Address (only if a user specified a functional address)
• Group Address (only if a user specified a group address)

NDD_CLEAR_STATS

The counters kept by the device will be zeroed.

NDD_GET_ALL_STATS

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 which are returned contain statistics obtained from the device. If the device is inoperable, the statistics which are returned will not contain the current device statistics. The copy of the ndd_flags field can be checked to determine the state of the device.

Trace Points and Error Log Templates for 8fc8 Token-Ring Device Driver

The Token-Ring device driver has three trace points. The IDs are defined in the usr/include/sys/cdli_tokuser.h file.

The Token-Ring error log templates are: