Kernel Extensions and Device Support Programming Concepts

PCI Token-Ring Device Drivers

The following Token-Ring device drivers are dynamically loadable. The device driver is automatically loaded into the system at device configuration time as part of the configuration process.

PCI Token-Ring High PerformanceDevice Driver (14101800)
PCI Token-Ring Device Driver (14103e00)

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 to perform the following actions:

Opening the device
Closing the device
Transmitting data
Performing a remote dump
Issuing device control commands

The PCI Token-Ring High Performance Device Driver (14101800) interfaces with the PCI Token-Ring High-Performance Network Adapter (14101800). The adapter is IEEE 802.5 compatible and supports both 4 and 16 Mbps networks. The adapter supports only an RJ-45 connection.

The PCI Token-Ring Device Driver (14103e00) interfaces with the PCI Token-Ring Network Adapter (14103e00). The adapter is IEEE 802.5 compatible and supports both 4 and 16 Mbps networks. The adapter supports both an RJ-45 and a 9 Pin connection.

Configuration Parameters

The following configuration parameter is supported by all PCI Token-Ring Device Drivers:

Ring Speed

The device driver supports a user-configurable parameter that indicates if the token-ring is to run at 4 or 16 Mbps.

The device driver supports a user-configurable parameter that selects the ring speed of the adapter. There are three options for the ring speed: 4, 16, or autosense.

If 4 is selected, the device driver opens the adapter with 4 Mbits. It returns an error if the ring speed does not match the network speed.
If 16 is selected, the device driver opens the adapter with 16 Mbits. It returns an error if the ring speed does not match the network speed.
If autosense is selected, the adapter guarantees a successful open, and the speed used to open is dependent on the following:
- If the adapter is opened on an existing network the speed is determined by the ring speed of the network.
- If the device is opened on a new network and the adapter is new, 16 Mbits is used. Or, if the adapter opened successfully, the ring speed is determined by the speed of the last successful open.

Software Transmit Queue

The device driver supports a user-configurable transmit queue that can be set to store between 32 and 2048 transmit request pointers. Each transmit request pointer corresponds to a transmit request that might be for several buffers of data.

Receive Queue

The device driver supports a user-configurable receive queue that can be set to store between 32 and 160 receive buffers. These buffers are mbuf clusters into which the device writes the received data.

Full Duplex

Indicates whether the adapter is operating in full-duplex or half-duplex mode. If this field is set to yes, the device driver programs the adapter to be in full-duplex mode. The default value is half-duplex.

Attention MAC Frames

The device driver supports a user-configurable parameter that indicates if attention MAC frames should be received.

Beacon MAC Frames

The device driver supports a user-configurable parameter that indicates if beacon MAC frames should be received.

Network Address

The driver supports the use of the device's hardware address as the network address or an alternate network address configured through software. When an alternate address is used, any valid individual address can be used. The most significant bit of the address must be set to zero.

In addition, the following configuration parameters are supported by the PCI Token-Ring High Performance Device Driver (14101800):

Priority Data Transmission: The device driver supports a user option to request priority transmission of the data packets.
Software Priority Transmit Queue: The device driver supports a user-configurable priority transmit queue that can be set to store between 32 and 160 transmit request pointers. Each transmit request pointer corresponds to a transmit request that might be for several buffers of data.

Device Driver Configuration and Unconfiguration

The configuration entry points of the device drivers conform to the guidelines for kernel object file entry points. These configuration entry points are as follows:

tok_config for the PCI Token-Ring High Performance Device Driver (14101800).
cs_config for the PCI Token-Ring Device Driver (14103e00).

Device Driver Open

The Token-Ring device driver performs 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 entry points are as follows:

tok_open for the PCI Token-Ring High Performance Device Driver (14101800).
cs_open for the PCI Token-Ring Device Driver (14103e00).

Device Driver Close

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 close entry points are as follows:

tok_close for the PCI Token-Ring High Performance Device Driver (14101800).
cs_close for the PCI Token-Ring Device Driver (14103e00).

Data Transmission

The device drivers do not support mbuf structures 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 must 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 must 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.

The output entry points are as follows:

tok_output for the PCI Token-Ring High Performance Device Driver (14101800).
cs_close for the PCI Token-Ring Device Driver (14103e00).

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 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 the mbuf structures.

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 that has an all-stations broadcast address is received. 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.

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 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 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 has occurred.

NDD_HARD_FAIL

When a transmit error occurs, it tries to recover. If the error is unrecoverable, this status block is generated.

code: Set to NDD_HARD_FAIL.
option[0]: Set to NDD_HARD_FAIL.
option[ ]: The remainder of the status block can be used to return additional status information.

Enter Network Recovery Mode

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 might 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: NDD_CMD_FAIL NDD_ADAP_CHECK NDD_TX_ERR NDD_TX_TIMEOUT NDD_AUTO_RMV TOK_ADAP_OPEN TOK_ADAP_INIT TOK_DMA_FAIL TOK_RING_SPEED TOK_RMV_ADAP TOK_WIRE_FAULT
option[ ]	The remainder of the status block can be used to return additional status information by the device driver.

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:

code	Set to NDD_LIMBO_EXIT.
option[ ]	The option fields are not used.

The device is now fully functional.

Device Control Operations

The ndd_ctl entry point is used to provide device control functions.

NDD_GET_STATS

The user should pass in the tok_ndd_stats_t structure as defined in the sys/cdli_tokuser.h file. 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.

NDD_PROMISCUOUS_ON

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.

NDD_PROMISCUOUS_OFF

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.

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 an 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.

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.

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

functional address

The specified address is ORed 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, such as 0xC000 0008 0048, because that address contains bits specified in the "mask."

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

Because functional addresses are encoded in a bit-significant format, reference counts are kept on each of the 31 least significant bits of the address.

group address

The device supports 256 general group addresses. The promiscuous mode is turned on when the group addresses to be set is more than 256. The device driver maintains a reference count on this operation.

The device supports 256 general group addresses. The promiscuous mode is turned on when the group address needed to be set are more than 256. The device driver will maintain a reference count on this operation.

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 (bit 0) or a group address (bit 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 1 (on). If the reference count for a bit goes to 0, the bit is "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 group address enable is less than 256, the driver sends a command to the device to disable the receipt of the packets with the specified group address. Otherwise, the group address is deleted from the group address table.

If there are less than 256 group addresses enabled after the receipt of this command, the promiscuous mode is turned off.

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_PRIORITY_ADDRESS

The driver returns the address of the device driver's priority transmit routine.

NDD_MIB_ADDR

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.

NDD_CLEAR_STATS

The counters kept by the device are zeroed.

NDD_GET_ALL_STATS

Used to gather all statistics for the specified device. The arg parameter specifies the address of the statistics structure for this particular device type. The folowing structures are available:

The sky_all_stats_t structure is available for the PCI Token-Ring High Performance Device Driver (14101800), and is defined in the device-specific /usr/include/sys/cdli_tokuser.h include file.
The cs_all_stats_t structure is available for the PCI Token-Ring Device Driver (14103e00), and is defined in the device-specific /usr/include/sys/cdli_tokuser.cstok.h include 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.

Reliability, Availability, and Serviceability (RAS)

Trace

For LAN device drivers, trace points enable error monitoring as well as tracking packets as they move through the driver. The drivers issue trace points for some or all of the following conditions:

Beginning and ending of main functions in the main path
Error conditions
Beginning and ending of each function that is tracking buffers outside of the main path
Debugging purposes (These trace points are only enabled when the driver is compiled with the -DDEBUG option turned, therefore, the driver can contain as many of these trace points as needed.)

Following is a list of trace hooks and location of definition files for the existing ethernet device drivers.

The PCI Token-Ring High Performance Device Driver (14101800)

Definition File: /sys/cdli_tokuser.h

Trace Hook IDs

Transmit 2A7
Receive 2A8
Error 2A9
Other 2AA

The PCI Token-Ring (14103e00) Device Driver

Definition File: /sys/cdli_tokuser.cstok.h

Trace Hook IDs

Transmit 2DA
Receive 2DB
General 2DC

Error Logging

PCI Token-Ring High Performance Device Driver (14101800)

The error IDs for the PCI Token-Ring High Performance Device Driver (14101800) are as follows:

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.
Note

Micro Channel is only supported on
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.

PCI Token-Ring Device Driver (14103e00)

The error IDs for the PCI Token-Ring Device Driver (14103e00) are as follows:

ERRID_CSTOK_ADAP_CHECK: The microcode on the device performs a series of diagnostic checks when the device is idle on initialization. These checks find errors and they are reported as adapter checks. If the device was connected to the network when this error occurred, the device driver will go into Network Recovery Mode in an attempt to recover from the error. The device is temporarily unavailable during the recovery procedure. After this error log entry has been generated, the device driver will retry 3 times with no delay between retries. User intervention is not required for this error unless the problem persists.
ERRID_CSTOK_ADAP_OPEN: The device driver was unable to open the device. The device driver will go into Network Recovery Mode in an attempt to recover from this error. The device is temporarily unavailable during the recovery procedure. The device driver will retry indefinitely with a 30 second delay between retries to recover. User intervention is not required for this error unless the problem persists.
ERRID_CSTOK_AUTO_RMV: An internal hardware error following the beacon automatic removal process has been detected. The device driver will go 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_CSTOK_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 will only retry twice at 2 minute intervals after this error log entry has been generated.
ERRID_CSTOK_DMAFAIL: The device detected a DMA error in a TX or RX operation. The device driver will go into Network Recovery Mode in an attempt to recover from this error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists.
ERRID_CSTOK_BUS_ERR: The device detected a PCI bus error. The device driver will go into Network Recovery Mode in an attempt to recover from this error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists.
ERRID_CSTOK_DUP_ADDR: The device has detected that another station on the ring has a device address which is the same as the device address being tested. Contact network administrator to determine why.
ERRID_CSTOK_MEM_ERR: An error occurred while allocating memory or timer control block structures. This usually implies the sytem has run out of available memory. User intervention is required.
ERRID_CSTOK_RCVRY_ENTER: An error has occurred which caused the device driver to go into network recovery.
ERRID_CSTOK_RCVRY_EXIT: The error which caused the device driver to go into Network Recovery Mode has been corrected.
ERRID_CSTOK_RMV_ADAP: The device has received a remove ring station MAC frame indicating that a network management function has directed this device to get off the ring. The device driver will only twice with 6 minute delay between retries after this error log entry has been generated. Contact network administrator to determine why.
ERRID_CSTOK_WIRE_FAULT: There is probably a loose ( or bad ) cable between the device and the MAU. There is some chance that it might be a bad device. The device driver will go into Network Recovery Mode in an attempt to recover from this error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists.
ERRID_CSTOK_RX_ERR: The device has detected a receive error. The device driver will go into Network Recovery Mode in an attempt to recover from this error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists.
ERRID_CSTOK_TX_ERR: The device has detected a transmit error. The device driver will go into Network Recovery Mode in an attempt to recover from this error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists.
ERRID_CSTOK_TX_TMOUT: The transmit watchdog timer has expired before the transmit of a frame has completed. The device driver will go into Network Recovery Mode in an attempt to recover from this error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists.
ERRID_CSTOK_CMD_TMOUT: The ioctl watchdog timer has expired before the device driver received a response from the device. The device driver will go into Network Recovery Mode in an attempt to recover from this error. The device is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists.
ERRID_CSTOK_PIO_ERR: The driver has encountered a PIO operation error. The device driver will attempt to retry the operation 3 times before it will fail the command and return in the DEAD state to the user. User intervention is required.
ERRID_CSTOK_PERM_HW: The microcode on the device performs a series of diagnostic checks on initialization. These checks can find errors and they are reported as adapter checks. If the error occurs 4 times during adapter initialization this error log will be generated and the device considered inoperable. User intervention is required.
ERRID_CSTOK_ASB_ERR: The adapter has indicated that the processing of a TokenRing mac command failed.
ERRID_CSTOK_AUTO_FAIL: The ring speed of the adapter is set to autosense, and open has failed because this adapter is the only one on the ring. User intervention is required.
ERRID_CSTOK_EISR: If the adapter detects a PCI Master or Target Abort, the Error Interrupt Status Register (EISR) will be set.
ERRID_CSTOK_CMD_ERR: Adapter failed command due to a transient error and goes into limbo one time, if that fails the adapter goes into the dead state.
ERRID_CSTOK_EEH_ENTER: The adapter encountered a Bus I/O Error, and is attempting to recover by using the EEH recovery process.
ERRID_CSTOK_EEH_EXIT: The adapter sucessfully recovered from the I/O Error by using the EEH recovery process.
ERRID_CSTOK_EEH_HW_ERR: The adapter could not recover from the EEH error. The EEH error was the result of an adapter error, and not a bus error (logged by the kernel).