[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Kernel Extensions and Device Support Programming Concepts

Ethernet Device Drivers

The following AIX Version 4 Ethernet device drivers are dynamically loadable device drivers that run on systems running AIX Version 4. The device drivers are automatically loaded into the system at device configuration time as part of the configuration process.

Note: The 10/100 MBps Ethernet TX MCA device driver is available on AIX Version 4.1.5 (and later) systems.

The following information is provided about each of the ethernet device drivers:

For each Ethernet device, the interface to the device driver is achieved by calling the entry points for opening, closing, transmitting data, and issuing device control commands. The Integrated Ethernet, 10/100 Mbps Ethernet TX MCA (AIX Version 4.1.5 and later), and PCI Ethernet Device Drivers also provide an interface for doing remote system dumps.

There are a number of Ethernet device drivers in use. The IBM ISA 16-bit Ethernet Adapter is the only existing ISA driver. The Ethernet High-Performance LAN Adapters (8ef5 and 8f95) and the Integrated Ethernet Device Drivers (8ef2, 8ef3, 8f98) all provide microchannel-based connections to an Ethernet network. The 10/100 Mbps Ethernet TX MCA Device Driver (8f62) provides a microchannel-based connection using a PCI adapter and bridge chip. The PCI Ethernet Device Driver (22100020) and the PCI 10/100 Mbps Ethernet Device Driver (23100020) provide PCI-based connections to an Ethernet network. All drivers support both Standard and IEEE 802.3 Ethernet Protocols, with support for a transmission rate of 10 megabits per second. The 10/100 Mbps Ethernet TX MCA Device Driver and PCI 10/100 Mbps Ethernet device driver (23100020) also support a transmission rate of 100 megabits per second. The Gigabit Ethernet-SX PCI Adapter (14100401) will not support either the transmission rate of 10 or 100 megabits per second.

The Ethernet High-Performance LAN Adapter (8ef5) device driver interfaces with a 3COM microchannel adapter card installed in one of the microchannel slots located on the system. This adapter supports thick (10BASE5 or DIX) and thin (10BASE2 or BNC) Ethernet connections.

The 10 Mbps Ethernet Low-Cost High-Performance Adapter (8f95) device driver interfaces with a microchannel adapter installed in one of the microchannel slots located on the system. This adapter supports AUI, 10BASE2 and 10BASE-T Ethernet connections.

The Integrated Ethernet Device Drivers (8ef2, 8ef3, 8f98) interface with an Intel 82596 Ethernet coprocessor located on the CPU planar, and is hardwired to microchannel slot 14 on the desktop systems. These devices support thick, thin, or twisted-pair (10BASE-T) Ethernet connections.

The 10/100 Mbps Ethernet TX MCA Adapter (8f62) interfaces with an Am79C971 Ethernet chip through an Adaptec AIC960 bridge chip. This device supports MII (Media Independent Interface).

The PCI Ethernet Device Driver (22100020) interfaces with an Am79C970 Ethernet chip located either on the planar or in an adapter card installed in one of the PCI slots on the system. This device supports twisted-pair (10BASE-T) and thin Ethernet connections. On the planar, only the twisted-pair connection is available for this PCI Ethernet device.

The PCI 10/100 Mbps Ethernet Device Driver (23100020) interfaces with an Am79C971 Ethernet chip located either on the planar or in an adapter card installed in one of the PCI slots on the system. This driver supports MII (Media Independent Interface).

The Gigabit Ethernet-SX PCI Adapter (14100401) device driver interfaces with a custom Application Specific Integrated Circuit (ASIC) in an adapter card installed in one of the PCI slots on the system. This device supports an SX fiber connection.

Configuration Parameters

The following is the configuration parameter that is supported by all Ethernet device drivers:

Alternate Ethernet Addresses
The device drivers support 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 least significant bit of an Individual Address must be set to zero. A multicast address can not be defined as a network address. Two configuration parameters are provided to provide the alternate Ethernet address and enable the alternate address.

The following are configuration parameters that are supported by the Ethernet High-Performance LAN Adapter (8ef5 and 8f95) and the Integrated Ethernet Device Drivers (8ef2, 8ef3, 8f98):

Software Transmit Queue
The device drivers support a user-configurable transmit queue that can be set to store between 20 to 150 transmit request pointers. Each transmit request pointer corresponds to a transmit request which may be for several buffers of data.

Adapter Connector Type
The device drivers support a user-configurable adapter connection for both BNC and DIX (AUI for adapter (8f95)) physical connector types. The Ethernet High-Performance LAN Adapter (8f95) device driver also supports user-configurable adapter connections TP (twisted-pair) and AUTO (auto sense).
Note: This option is not supported on some systems that implement the Integrated Ethernet and have DIX as the default.

The Ethernet High-Performance LAN Adapter (8ef5) device driver supports the following additional configuration parameter:

Receive Buffer Pool Size
The Ethernet High-Performance LAN Adapter (8ef5) device driver supports a user-configurable receive buffer pool. With this attribute, the user can configure between 16 to 64 receive buffers that will be used during the reception of incoming packets from the network. Increasing from a default value of 37 results in a smaller transmit buffer pool. Decreasing from the default value increases the number of transmit buffers in the pool.

The Ethernet High-Performance LAN Adapter (8f95) device driver supports the following additional configuration parameters:

Transmit Interrupt Mode
The Ethernet High-Performance LAN Adapter (8f95) can be configured to operate in one of three transmit modes.
Delay (0) Sends notification of transmit completion based on the number of packets transmitted.
Immediate (1) Sends notification of transmit completion immediately upon completion of transmit.
Poll (2) Queries the adapter for transmit status based on the number of packets transmitted. This parameter is used for performance tuning and should be set according to network usage.
Note: Under Delay and Poll modes, a timer is used to ensure timely process completion of transmit packets.

Receive Interrupt Mode
The Ethernet High-Performance LAN Adapter (8f95) can be configured to operate in one of two receive modes.
Delay (0) Sends notification of an incoming packet based on the number of packets currently in the receive queue.
Note: Under Delay mode, a timer is used to ensure that all received packets are processed efficiently.
Immediate (1) Sends notification of an incoming packet immediately upon receipt of the packet.

Transmit Interrupt Threshold
Under delayed transmit mode for the Ethernet High-Performance LAN Adapter (8f95), the frequency of transmit complete interrupts can be controlled based on the Transmit Interrupt Threshold parameter. The adapter issues an interrupt when the number of transmitted packets exceeds this threshold. For example, if the transmit interrupt threshold parameter is 0, the adapter issues an interrupt when 1 transmit packet is complete. If the transmit interrupt threshold parameter is 1, the adapter issues an interrupt when 2 transmit packets are complete. This pattern continues until the Transmit Interrupt Threshold parameter reaches its maximum value of 31.
Note: This parameter should be used for performance tuning only.
Receive Interrupt Threshold
Under delayed receive mode for the Ethernet High-Performance LAN Adapter (8f95), the frequency of receive complete interrupts can be controlled based on the Receive Interrupt Threshold parameter. The adapter issues an interrupt when the number of received packets exceeds this threshold. For example, if the Receive Interrupt Threshold parameter is 0, the adapter issues an interrupt when 1 receive packet is complete. If the Receive Interrupt Threshold parameter is 1, the adapter issues an interrupt when 2 receive packets are complete. This pattern continues until the Receive Interrupt Threshold parameter reaches its maximum value of 31.
Note: This parameter should be used for performance tuning only.
Transmit Poll Threshold
Under transmit poll mode for the Ethernet High-Performance LAN Adapter (8f95), the frequency in which the device driver polls the adapter for completed transmit packets can be controlled based on the Transmit Poll Threshold parameter. The device driver polls for completed transmit status when the number of outstanding transmitted packets exceeds this threshold. If the Transmit Poll Threshold parameter is 0, the device driver polls the adapter for status when 1 transmit packet status is pending. If the Transmit Poll Threshold parameter is 1, the device driver polls the adapter for status when status for 2 transmit packets is pending. This pattern continues until the Transmit Poll Threshold parameter reaches its maximum of 31.
Note: This parameter should be used for performance tuning only.
Receive Interval
Under receive delayed mode for the Ethernet High-Performance LAN Adapter (8f95), the maximum amount of time between receive interrupts can be controlled based on the Receive Interval parameter. The adapter guarantees that a receive interrupt is generated within 2** (receive Interval + 7)/10 microseconds after the last received packet, regardless of the value of the Receive Interrupt Threshold parameter. This timer is reset to zero by the adapter after each packet is received.

Duplex
The Ethernet High-Performance LAN Adapter (8f95) can be configured to operate in a full duplex 10BASET network. This mode of operation is only valid using the adapter's RJ-45 (10BASET) port. Duplex mode is not valid when using the AUI port or the BNC (10BASE2) port.

Beginning with AIX Version 4.1.5, the 10/100 Mbps Ethernet TX MCA device driver (8f62) supports the following additional configuration parameters:

Hardware Transmit Queue
The 10/100 Mbps Ethernet TX MCA device driver (8f62) supports a user-configurable transmit queue for the adapter. This is the actual queue the adapter uses to transmit packets. Each element corresponds to an Ethernet packet. It is configurable at 16, 32, 64, 128, and 256 elements. The default is 64.

Hardware Receive Queue
The 10/100 Mbps Ethernet TX MCA device driver (8f62) supports a user-configurable receive queue for the adapter. This is the actual queue the adapter uses to receive packets. Each element corresponds to an Ethernet packet. It is configurable at 16, 32, 64, 128, and 256 elements. The default is 64.

Media Speed
The 10/100 Mbps Ethernet TX MCA device driver (8f62) supports a user-configurable media speed for the adapter. The media speed attribute indicates the speed at which the adapter will attempt to operate. The available speeds are: 10 Mbps half-duplex, 10 Mbps full-duplex, 100 Mbps half-duplex, 100 Mbps full-duplex, and auto-negotiation. Select auto-negotiate when the adapter should use auto-negotiation across the network to determine the speed. When the network will not support auto-negotiation, the specific speed should be selected. The default is auto-negotiation.

Inter Packet Gap (IPG)
The 10/100 Mbps Ethernet TX MCA device driver (8f62) supports a user-configurable inter packet gap for the adapter. The inter packet gap attribute controls the aggressiveness of the adapter on the network. A small number increases the aggressiveness of the adapter, while a large number decreases the aggressiveness (and increases the fairness) of the adapter. A small number (more aggressive) could cause the adapter to capture the network by forcing other less aggressive nodes to defer. A larger number (less aggressive) could cause the adapter to defer more often than normal. If the statistics for other nodes on the network show a large number of collisions and deferrals, try increasing this number. The default is 96, which results in an IPG of 9.6 microseconds for 10 Mbps and 0.96 microseconds for 100 Mbps media speed. Each unit of bit rate introduces an IPG of 100 nsec at 10 Mbps and 10 nsec at 100 Mbps media speed.

The PCI Ethernet Device Driver (22100020) supports the following additional configuration parameters:

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 is half-duplex.
Note: Full duplex mode is valid for AIX Version 4.1.5 (and later).

Hardware Transmit Queue
Specifies the actual queue the adapter uses to transmit packets. Each element corresponds to an Ethernet packet. It is configurable at 16, 32, 64, 1 28, and 256 elements. The default is 64.

Hardware Receive Queue
Specifies the actual queue the adapter uses to receive packets. Each element corresponds to an Ethernet packet. It is configurable at 16, 32, 64, 128, and 256 elements. The default is 64.

The PCI 10/100 Mbps Ethernet Device Driver (23100020) supports the following additional configuration parameters:

Hardware Transmit Queue
The PCI 10/100 Mbps Ethernet Device Driver (23100020) supports a user-configurable transmit queue for the adapter. This is the actual queue the adapter uses to transmit packets. Each element corresponds to an Ethernet packet. It is configurable at 16, 32, 64, 128, and 256 elements, with a default of 64.

Hardware Receive Queue
The PCI 10/100 Mbps Ethernet Device Driver (23100020) supports a user-configurable receive queue for the adapter. This is the actual queue the adapter uses to receive packets. Each element corresponds to an Ethernet packet. It is configurable at 16, 32, 64, 128, and 256 elements, with a default of 32.

Media Speed
The PCI 10/100 Mbps Ethernet Device Driver (23100020) supports a user-configurable media speed for the adapter. The media speed attribute indicates the speed at which the adapter will attempt to operate. The available speeds are 10 Mbps half-duplex, 10 Mbps full-duplex, 100 Mbps half-duplex, 100 Mbps full-duplex and auto-negotiation, with a default of auto-negotiation. Select auto-negotiate when the adapter should use auto-negotiation across the network to determine the speed. When the network will not support auto-negotiation, the specific speed should be selected

Inter Packet Gap
The PCI 10/100 Mbps Ethernet Device Driver (23100020) supports a user-configurable inter packet gap for the adapter. The inter packet gap attribute controls the aggressiveness of the adapter on the network. A small number will increase the aggressiveness of the adapter, while a large number will decrease the aggressiveness (and increase the fairness) of the adapter. A small number (more aggressive) could cause the adapter to capture the network by forcing other less aggressive nodes to defer. A larger number (less aggressive) may cause the adapter to defer more often than normal. If the statistics for other nodes on the network show a large number of collisions and deferrals, then try increasing this number. The default is 96, which results in IPG of 9.6 micro seconds for 10 Mbps and 0.96 microseconds for 100 Mbps media speed. Each unit of bit rate introduces an IPG of 100 nsec at 10 Mbps, and 10 nsec at 100 Mbps media speed.

The Gigabit Ethernet-SX PCI Adapter (14100401) device driver supports the additional configuration parameters:

Software Transmit Queue Size
Indicates the number of transmit requests that can be queued for transmission by the device driver. Valid values range from 512 through 2048. The default value is 512.

Transmit Jumbo Frames
Setting this attribute to the yes value indicates that frames up to 9018 bytes in length may be transmitted on this adapter. If you specify the no value, the maximum size of frames transmitted is 1518 bytes. The default value is no. Frames up to 9018 bytes in length may always be received on this adapter.

Receive Buffer Pool Size
Indicates the number of mbufs to be used exclusively with this adapter. These mbufs will be used for receiving frames. They will be 4096 bytes long if yes is specified for the Transmit Jumbo Frames attribute. They will be 2048 bytes long otherwise. Valid values range from 256 through 2048. The default value is 768. The adapter has a receive queue of 512 entries. Each entry describes a mbuf where a frame (or part of a frame) will be received. The device driver will attempt to obtain a mbuf for the receive queue from this receive buffer pool. If the pool is empty the device driver will attempt to obtain a mbuf from the system buffer pool. After a frame is received the mbuf containing the frame will be passed to the user of that frame. A replacement mbuf will be obtained for the adapter receive queue. Thus more than 512 mbuf will be in use at any given time. The output of the ntstat -d ent0 program contains statistics concerning use of this buffer pool. Use of mbufs from this pool will improve the performance of the adapter with a possible increase in system network memory usage.

Enable Hardware Receive Checksum
Setting this attribute to the yes value indicates that the adapter should calculate the checksum for received TCP frames. If you specify the no value, the checksum will be calculated by the appropriate software. The default value is yes.
Note: The mbuf describing a frame to be transmitted contains a flag which says if the adapter should calculate the checksum for the frame.

Interface Entry Points

Device Driver Configuration and Unconfiguration

The configuration entry points of the device drivers conform to the guidelines for AIX Version 4 kernel object file entry points. The configuration entry points are en3com_config for the Ethernet High-Performance LAN Adapter (8ef5), ient_config for the Integrated Ethernet, kent_config for the PCI Ethernet Device Driver (22100020), and lce_config for the Ethernet High-Performance LAN Adapter (8f95). Beginning with AIX Version 4.1.5, the srent_config entry point is available for the 10/100 Mbps Ethernet TX MCA (8f62) device driver. Beginning with AIX Version 4.1.M, the phxent_config entry point is available for the PCI 10/100 Mbps Ethernet (23100020) Device Driver. The Gigabit Ethernet-SX PCI Adapter (14100401) entry point is gxent_config.

Device Driver Open

The open entry point for the device drivers perform a synchronous open of the specified network device.

The device driver issues commands to start the initialization of the device. The state of the device now is OPEN_PENDING. The device driver invokes the open process for the device. The open process involves a sequence of events that are necessary to initialize and configure the device. The device driver will do the sequence of events in an orderly fashion to make sure that one step is finished executing on the adapter before the next step is continued. Any error during these sequence of events will make the open fail. The device driver requires about 2 seconds to open the device. When the whole sequence of events is done, the device driver verifies the open status and then returns to the caller of the open with a return code to indicate open success or open failure.

Once the device has been successfully configured and connected to the network, the device driver will set the device state to OPENED, the NDD_RUNNING flag in the NDD flags field will be turned on. In the case of unsuccessful open, both the NDD_UP and NDD_RUNNING flags in the NDD flags field will be off and a non-zero error code will be returned to the caller.

The open entry points are en3com_open for the Ethernet High-Performance LAN Adapter (8ef5), ient_open for the Integrated Ethernet, kent_open for the PCI Ethernet Device Driver (22100020), and lce_open for the Ethernet High-Performance LAN Adapter (8f95). Beginning with AIX Version 4.1.5, the srent_open entry point is available for the 10/100 Mbps Ethernet TX MCA (8f62) device driver. Beginning with AIX Version 4.1.M, the phxent_open entry point is available for the PCI 10/100 Mbps Ethernet (23100020) Device Driver. The Gigabit Ethernet-SX PCI Adapter (14100401) entry point is gxent_open.

Device Driver Close

The close entry point for the device drivers 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. That is, the close entry point will not return until all packets have been transmitted or timed out. If the device is inoperable at the time of the close, the device's transmit queue does not have to be allowed to drain.

At the beginning of the close entry point, the device state will be set to be CLOSE_PENDING. The NDD_RUNNING flag in the ndd_flags will be turned off. After the outstanding transmit queue is all done, the device driver will start a sequence of operations to deactivate the adapter and to free up resources. Before the close entry point returns to the caller, the device state is set to CLOSED.

The close entry points are en3com_close for the Ethernet High-Performance LAN Adapter (8ef5), ient_close for the Integrated Ethernet, kent_close for the PCI Ethernet Device Driver (22100020), and lce_close for the Ethernet High-Performance LAN Adapter (8f95). Beginning with AIX Version 4.1.5, the srent_close entry point is available for the 10/100 Mbps Ethernet TX MCA (8f62) device driver. Beginning with AIX Version 4.1.M, the phxent_close entry point is available for the PCI 10/100 Mbps Ethernet (23100020) Device Driver. The Gigabit Ethernet-SX PCI Adapter (14100401) entry point is gxent_close.

Data Transmission

The output entry point transmits data using the specified network device.

The data to be transmitted is passed into the device driver by way of mbuf structures. The first mbuf in the chain must be of M_PKTHDR format. Multiple mbufs may be used to hold the frame. The mbufs should be linked using the m_next field of the mbuf structure.

Multiple packet transmits are allowed with the mbufs being chained using the m_nextpkt field of the mbuf structure. The m_pkthdr.len field must be set to the total length of the packet. The device driver does not support mbufs from user memory (which have the M_EXT flag set).

On successful transmit requests, the device driver is responsible for freeing all the mbufs associated with the transmit request. If the device driver returns an error, the caller is responsible for the mbufs. If any of the chained packets can be transmitted, the transmit is considered successful and the device driver is responsible for all of the mbufs in the chain.

If the destination address in the packet is a broadcast address the M_BCAST flag in the m_flags field should be set prior to entering this routine. A broadcast address is defined as 0xFFFF FFFF FFFF. If the destination address in the packet is a multicast address the M_MCAST flag in the 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.

For packets that are shorter than the Ethernet minimum MTU size (60 bytes), the device driver will pad them by adjusting the transmit length to the adapter so they can be transmitted as valid Ethernet packets.

Users will not be notified by the device driver about the status of the transmission. Various statistics about data transmission are kept by the driver in the ndd structure. These statistics will be part of the data returned by the NDD_GET_STATS control operation.

The output entry points are en3com_output for the Ethernet High-Performance LAN Adapter (8ef5), ient_output for the Integrated Ethernet, kent_output for the PCI Ethernet Device Driver (22100020), and lce_output for the Ethernet High-Performance LAN Adapter (8f95). Beginning with AIX Version 4.1.5, the srent_output entry point is available for the 10/100 Mbps Ethernet TX MCA (8f62) device driver. Beginning with AIX Version 4.1.M, the phxent_output entry point is available for the PCI 10/100 Mbps Ethernet (23100020) Device Driver. The Gigabit Ethernet-SX PCI Adapter (14100401) entry point is gxent_output.

Data Reception

When the Ethernet device drivers receive a valid packet from the network device, the device drivers call 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 the form of a mbuf.

The Ethernet device drivers may pass multiple packets to the nd_receive function by chaining the packets together using the m_nextpkt field of the mbuf structure. The m_pkthdr.len field must be set to the total length of the packet. If the source address in the packet is a broadcast address the M_BCAST flag in the m_flags field should be set. If the source address in the packet is a multicast address the M_MCAST flag in the m_flags field should be set.

When the device driver initially configures the device to discard all invalid frames. A frame is considered to be invalid for the following reasons:

If the asynchronous status for receiving invalid frames has been issued to the device driver, the device driver will configure the device to receive bad packets as well as good packets. Whenever a bad packet is received by the driver, an asynchronous status block NDD_BAD_PKTS is created and delivered to the appropriate user. The user must copy the contents of the mbuf to another memory area. The user must not modify the contents of the mbuf or free the mbuf. The device driver has the responsibility of releasing the mbuf upon returning from nd_status.

Various statistics about data reception on the device will be kept by the driver in the ndd structure. These statistics will be part of the data returned by the NDD_GET_STATS and NDD_GET_ALL_STATS control operations.

There is no specified entry point for this function. The device informs the device driver of a received packet via an interrupt. Upon determining that the interrupt was the result of a packet reception, the device driver's interrupt handler will invoke a completion routine to perform the tasks mentioned above. This is en3com_rv_intr for the Ethernet High-Performance LAN Adapter (8ef5), ient_RU_complete for the Integrated Ethernet, rx_handler for the 10/100 Mbps Ethernet TX MCA (8f62) device driver (AIX Version 4.1.5 and later) and the PCI Ethernet device driver (22100020), and lce_recv for the Ethernet High-Performance LAN Adapter (8f95). Beginning with AIX Version 4.1.M, the rx_handler entry point is available for the PCI 10/100 Mbps Ethernet (23100020) Device Driver. The Gigabit Ethernet-SX PCI Adapter (14100401) entry point is rx_handler.

Asynchronous Status

When a status event occurs on the device, the Ethernet device drivers build the appropriate status block and call 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 Ethernet device drivers.

Note: The PCI Ethernet Device Driver (22100020) and the Ethernet High-Performance LAN Adapter (8f95) only support the Bad Packets status block. The Gigabit Ethernet-SX PCI Adapter (14100401) does not support asynchronous status.
Hard Failure
When a hard failure has occurred on the Ethernet device, the following status blocks can be returned by the Ethernet device driver. These status blocks indicates that a fatal error occurred.
code Set to NDD_HARD_FAIL.
option[0] Set to one of the reason codes defined in <sys/ndd.h> and <sys/cdli_entuser.h>.

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.
code Set to NDD_LIMBO_ENTER.
option[0] Set to one of the reason codes defined in <sys/ndd.h> and <sys/cdli_entuser.h>.
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,

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.
Note: 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.
code Set to NDD_STATUS.
option[0] May be any of the common or interface type specific reason codes.
option[] The remainder of the status block may be used to return additional status information by the device driver.

Bad Packets
When the a bad packet has been received by a device driver (and a user has requested bad packets), the following status block is returned by the device driver.
code Set to NDD_BAD_PKTS.
option[0] Specifies the error status of the packet. These error numbers are defined in <sys/cdli_entuser.h>.
option[1] Pointer to the mbuf containing the bad packet.
option[] The remainder of the status block may be used to return additional status information by the device driver.
Note: The user will not own the mbuf containing the bad packet. The user must copy the mbuf (and the status block information if desired). The device driver will free the mbuf upon return from the nd_status function.

Device Connected
When the device is successfully connected to the network the following status block is returned by the device driver.
code Set to NDD_CONNECTED.
option[] The option fields are not used.
Note: Integrated Ethernet Only.

Device Control Operations

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

NDD_GET_STATS

The NDD_GET_STATS command returns statistics concerning the network device. General statistics are maintained by the device driver in the ndd_genstats field in the ndd_t structure. The ndd_specstats field in the ndd_t structure is a pointer to media-specific and device-specific statistics maintained by the device driver. Both sets of statistics are directly readable at any time by those users of the device that can access them. This command provides a way for any of the users of the device to access the general and media-specific statistics. The NDD_GET_ALL_STATS command provides a way to get the device-specific statistics also. Beginning with AIX Version 4.1, the phxent_all_stats_t structure is available for the PCI 10/100 Mbps Ethernet (23100020) Device Driver. This structure is defined in the device-specific include file cdli_entuser.phxent.h.

The arg and length parameters specify the address and length in bytes of the area where the statistics are to be written. The length specified must be the exact length of the general and media-specific statistics.

Note: The ndd_speclen field in the ndd_t structure plus the length of the ndd_genstats_t structure is the required length. The device-specific statistics may change with each new release of AIX, but the general and media-specific statistics are not expected to change.

The user should pass in the ent_ndd_stats_t structure as defined in <sys/cdli_entuser.h>. The driver fails 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 NDD_MIB_QUERY operation is used to determine which device-specific MIBs are supported on the network device. The arg and length parameters specify the address and length in bytes of a device-specific MIB structure. The device driver will fill every member of that structure with a flag indicating the level of support for that member. The individual MIB variables that are not supported on the network device will be set to MIB_NOT_SUPPORTED. The individual MIB variables that may only be read on the network device will be set to MIB_READ_ONLY. The individual MIB variables that may be read and set on the network device will be set to MIB_READ_WRITE. The individual MIB variables that may only be set (not read) on the network device will be set to MIB_WRITE_ONLY. These flags are defined in the /usr/include/sys/ndd.h file.

The arg parameter specifies the address of the ethernet_all_mib structure. This structure is defined in the /usr/include/sys/ethernet_mibs.h file.

NDD_MIB_GET

The NDD_MIB_GET operation is used to get all MIBs on the specified network device. The arg and length parameters specify the address and length in bytes of the device specific MIB structure. The device driver will set any unsupported variables to zero (nulls for strings).

If the device supports the RFC 1229 receive address object, the corresponding variable is set to the number of receive addresses currently active.

The arg parameter specifies the address of the ethernet_all_mib structure. This structure is defined in the /usr/include/sys/ethernet_mibs.h file.

NDD_ENABLE_ADDRESS

The NDD_ENABLE_ADDRESS command enables the receipt of packets with an alternate (for example, multicast) address. The arg and length parameters specify the address and length in bytes of the alternate address to be enabled. The NDD_ALTADDRS flag in the ndd_flags field is set.

The device driver verifies that if the address is a valid multicast address. If the address is not a valid multicast address, the operation will fail with an EINVAL error. If the address is valid, the driver will add it to its multicast table and enable the multicast filter on the adapter. The driver will keep a reference count for each individual address. Whenever a duplicate address is registered, the driver simply increments the reference count of that address in its multicast table, no update of the adapter's filter is needed. There is a hardware limitation on the number of multicast addresses in the filter.

NDD_DISABLE_ADDRESS

The NDD_DISABLE_ADDRESS command disables the receiving packets with a specified alternate (for example, multicast) address. The arg and length parameters specify the address and length in bytes of the alternate address to be disabled. The NDD_ALTADDRS flag in the ndd_flags field is reset if this is the last alternate address.

The device driver verifies that if the address is a valid multicast address. If the address is not a valid multicast address, the operation will fail with an EINVAL error. The device driver makes sure that the multicast address can be found in its multicast table. Whenever a match is found, the driver will decrement the reference count of that individual address in its multicast table. If the reference count becomes 0, the driver will delete the address from the table and update the multicast filter on the adapter.

NDD_MIB_ADDR

The NDD_MIB_ADDR operation is used to get all the addresses for which the specified device will accept packets or frames. The arg parameter specifies the address of the ndd_mib_addr_t structure. The length parameter specifies the length of the structure with the appropriate number of ndd_mib_addr_t.mib_addr elements. This structure is defined in the /usr/include/sys/ndd.h file. If the length is less than the length of the ndd_mib_addr_t structure, the device driver returns EINVAL. If the structure is not large enough to hold all the addresses, the addresses which fit will still be placed in the structure. The ndd_mib_addr_t.count field is set to the number of addresses returned and E2BIG is returned.

One of the following address types is returned:

NDD_CLEAR_STATS

The counters kept by the device will be zeroed.

NDD_GET_ALL_STATS

The NDD_GET_ALL_STATS operation is used to gather all the statistics for the specified device. The arg parameter specifies the address of the statistics structure for the particular device type. This structure is en3com_all_stats_t for the Ethernet High-Performance LAN Adapter (8ef5), ient_all_stats_t for the Integrated Ethernet Device, kent_all_stats_t for the PCI Ethernet Device Driver (22100020), and enlce_all_stats_t for the Ethernet High-Performance LAN Adapter (8f95). Beginning with AIX Version 4.1.5, the srent_all_stats_t structure is available for the 10/100 Mbps Ethernet TX MCA (8f62) device driver. These structures are defined in the /usr/include/sys/cdli_entuser.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.

NDD_ENABLE_MULTICAST

The NDD_ENABLE_MULTICAST command enables the receipt of packets with any multicast (or group) address. The arg and length parameters are not used. The NDD_MULTICAST flag in the ndd_flags field is set.

Note: Unlike the Integrated Ethernet and PCI Ethernet (22100020) Device Drivers, the Ethernet High-Performance LAN Adapter (8ef5) adapter does not support the "receive all multicast" function; this driver will enable the promiscuous mode on the adapter in order to bypass the multicast filtering existing on the adapter. The device driver performs additional packet filtering to discard packets which are not supposed to be received under this circumstance.

NDD_DISABLE_MULTICAST

The NDD_DISABLE_MULTICAST command disables the receipt of ALL packets with multicast addresses and only receives those packets whose multicast addresses were specified using the NDD_ENABLE_ADDRESS command. The arg and length parameters are not used. The NDD_MULTICAST flag in the ndd_flags field is reset only after the reference count for multicast addresses has reached zero.

NDD_PROMISCUOUS_ON

The NDD_PROMISCUOUS_ON command turns on promiscuous mode. The arg and length parameters are not used.

When the device driver is running in promiscuous mode, "all" network traffic is passed to the network demuxer. When the Ethernet device driver receives a valid packet from the network device, the Ethernet device driver calls the nd_receive function that is specified in the ndd_t structure of the network device. The NDD_PROMISC flag in the ndd_flags field is set. Promiscuous mode is considered to be valid packets only. See the NDD_ADD_STATUS command for information about how to request support for bad packets.

The device driver will maintain a reference count on this operation. The device driver increments the reference count for each operation. When this reference count is equal to one, the device driver issues commands to enable the promiscuous mode. If the reference count is greater than one, the device driver does not issue any commands to enable the promiscuous mode.

NDD_PROMISCUOUS_OFF

The NDD_PROMISCUOUS_OFF command terminates promiscuous mode. The arg and length parameters are not used. The NDD_PROMISC flag in the ndd_flags field is reset.

The device driver will maintain a reference count on this operation. The device driver decrements the reference count for each operation. When the reference count is not equal to zero, the device driver does not issue commands to disable the promiscuous mode. Once the reference count for this operation is equal to zero, the device driver issues commands to disable the promiscuous mode.

NDD_DUMP_ADDR

The NDD_DUMP_ADDR command returns the address of the device driver's remote dump routine. The arg parameter specifies the address where the dump routine's address is to be written. The length parameter is not used.

Note: The Ethernet High-Performance LAN Adapters (8ef5 and 8f95) Device Drivers do not support this.

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:

The existing Ethernet device drivers each have either three or four trace points. The Trace Hook IDs for most of the device types are defined in the sys/cdli_entuser.h file. Other drivers have defined local cdli_entuser.driver.h files with the Trace Hook definitions.

Following is a list of trace hooks (and location of definition file) for the existing Ethernet device drivers:

The device driver also has the following trace points to support the netpmon program:

WQUE An output packet has been queued for transmission
WEND The output of a packet is complete
RDAT An input packet has been received by the device driver
RNOT An input packet has been given to the demuxer
REND The demuxer has returned

For more information, see "Debug and Performance Tracing" .

Error Logging

The Error IDs for the Ethernet High-Performance LAN Adapter (8ef5) are as follows:

ERRID_EN3COM_TMOUT
The watchdog timer has expired while waiting on acknowledgement of either a control command or transmit command. 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_EN3COM_FAIL
The device driver has detected an error that prevents the device from functioning. This message is normally preceded by another error log which indicates the specific fatal error that has occurred. The device driver may have gone through the Network Recovery Mode and failed to recover from the error. This message indicates that the device will not be available due to some hard failure and user intervention is required.

ERRID_EN3COM_UCODE
The device driver detected an error in the microcode on the adapter. The device driver will log this error and indicate hardware failure. The device will not be available after this error is detected. User intervention is required in order to recover from this error.

ERRID_EN3COM_PARITY
The device detected a parity error. The device driver will log this error and 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_EN3COM_DMAFAIL
The device has detected a DMA channel error or a Micro Channel error has occurred. Normally, this error will be accompanied by another error that will indicate if this error is fatal or recoverable.

ERRID_EN3COM_NOBUFS
The device detected a memory shortage during the device initialization phase when the device driver attempted to allocate transmit and receive buffers from the host memory. The device driver will log this error and fail the device initialization. The device will not be available after this error is detected. User intervention is required in order to recover from this error.

ERRID_EN3COM_PIOFAIL
The device detected an I/O channel error or an error in a command the device driver issued, an error occurred during a PIO operation, or the device has detected an error in a packet given to the device. The device driver will retry the operation for three times. If they all failed, the device driver will log this error and indicate hardware failure. The device will not be available after this error is detected. User intervention is required in order to recover from this error.

The Error IDs for the Integrated Ethernet Device Driver are as follows:

ERRID_IENT_TMOUT
The watchdog timer has expired while waiting on acknowledgement of either a control command or transmit command. 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_IENT_PIOFAIL
The device detected an I/O channel error or an error in a command the device driver issued, an error occurred during a PIO operation, or the device has detected an error in a packet given to the device. 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_IENT_DMAFAIL
The device has detected an DMA channel error or a Micro Channel error has 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. User intervention is not required for this error unless the problem persists.

ERRID_IENT_FAIL
The device has detected an error that prevents the device from starting or restarting, such as pincode or i_init fails. If the device is restarting in Network Recovery Mode in an attempt to recover from an error, the device will be temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists.

Beginning with AIX Version 4.1.5, the Error IDs for the 10/100 Mbps Ethernet TX MCA (8f62) device driver are as follows:

ERRID_SRENT_ADAP_ERR
Indicates that the adapter is not responding to initialization commands. User intervention is necessary to fix the problem.

ERRID_SRENT_RCVRY
Indicates that the adapter hit a temporary error requiring that it enter network recovery mode. The adapter is reset in an attempt to fix the problem.

ERRID_SRENT_TX_ERR
Indicates that the device driver has detected a transmission error. User intervention is not required unless the problem persists.

ERRID_SRENT_PIO
Indicates that the device driver has detected a program IO error. User intervention is necessary to fix the problem.

ERRID_SRENT_DOWN
Indicates that the device driver has shutdown the adapter due to an unrecoverable error. The adapter is no longer functional. The error that caused the device to shutdown is logged immediately before this error log entry. User intervention is necessary to fix the problem.

ERRID_SRENT_EEPROM_ERR
Indicates that the device driver is in a defined state due to an invalid or bad EEPROM. The device driver will not become available. Contact your hardware support representative.

The Error IDs for the PCI Ethernet Device Driver (22100020) are as follows:

ERRID_KENT_ADAP_ERR
Indicates that the adapter is not responding to initialization commands. User intervention is necessary to fix the problem.

ERRID_KENT_RCVRY
Indicates that the adapter hit a temporary error requiring that it enter network recovery mode. It has reset the adapter in an attempt to fix the problem.

ERRID_KENT_TX_ERR
Indicates the the device driver has detected a transmission error. User intervention is not required unless the problem persists.

ERRID_KENT_PIO
Indicates that the device driver has detected a program IO error. The device driver was unable to fix the problem. User intervention is necessary to fix the problem.

ERRID_KENT_DOWN
Indicates that the device driver has shut down the adapter due to an unrecoverable error. The adapter is no longer functional due to the error. The error that caused the device to shut down is error logged immediately before this error log entry. User intervention is necessary to fix the problem.

Beginning with AIX Version 4.1.M, the Error IDs for the PCI 10/100 Mbps Ethernet Device Driver (23100020) are as follows:

ERRID_PHXENT_ADAP_ERR
Indicates that the adapter is not responding to initialization commands. User-intervention is necessary to fix the problem.

ERRID_PHXENT_TX_RCVRY
Indicates that the adapter hit a temporary error requiring that it enter network recovery mode. It has reset the adapter in an attempt to fix the problem.

ERRID_PHXENT_TX_ERR
Indicates that the device driver has detected a transmission error. User-intervention is not required unless the problem persists.

ERRID_PHXENT_PIO
Indicates that the device driver has detected a program IO error. The device driver was unable to fix the problem. User-intervention is necessary to fix the problem.

ERRID_PHXENT_DOWN
Indicates that the device driver has shutdown the adapter due to an unrecoverable error. The adapter is no longer functional due to the error. The error which caused the device shutdown is error logged immediately before this error log entry. User-intervention is necessary to fix the problem.

ERRID_PHXENT_EEPROM_ERR
Indicates that the device driver is in a defined state due to an invalid or bad EEPROM. The device driver will not become available. Hardware support should be contacted.

The Error IDs for the Ethernet High-Performance LAN Adapter (8f95) are as follows:

ERRID_ENLCE_TMOUT
Indicates status for a transmit packet was not received. The device will not be available during the error recovery process.

ERRID_ENLCE_FAIL
Indicates that the adapter has reported a hardware error. The device will not be available during the error recovery process.

ERRID_ENLCE_SWFAIL
Indicates the device driver has detected a software error. The current operation will not complete successfully.

ERRID_ENLCE_TXFAIL
Indicates a hardware/software transmit synchronization problem. The device will not be available during the error recovery process.

ERRID_ENLCE_RXFAIL
Indicates a hardware/software receive synchronization problem. The device will not be available during the error recovery process.

ERRID_ENLCE_MCFAIL
Indicates that the adapter has reported a Micro Channel error. The device will not be available during the error recovery process.

ERRID_ENLCE_VPDFAIL
Indicates that the device driver was unable to read the vital product data (VPD) from the adapter. The device will not be available after this error is detected.

ERRID_ENLCE_PARITY
Indicates that the adapter has reported a parity error.

ERRID_ENLCE_DMAFAIL
Indicates that the adapter has reported a DMA error.

ERRID_ENLCE_NOMEM
Indicates that not enough memory was available to complete the current operation.

ERRID_ENLCE_NOMBUFS
Indicates that no mbufs were available for a receive packet. The packet will be dropped.

ERRID_ENLCE_PIOFAIL
Indicates that the device driver has detected a PIO failure. The device will not be available after this error is detected.

The Error IDs for the Gigabit Ethernet-SX PCI Adapter (14100401) are as follows:

ERRID_GXENT_ADAP_ERR
Indicates that the adapter failed initialization commands. User intervention is necessary to fix the problem.

ERRID_GXENT_CMD_ERR
Indicates that the device driver has detected an error while issuing commands to the adapter. The device driver will enter an adapter recovery mode where it will attempt to recover from the error. If the device driver is successful, it will log ERRID_GXENT_RCVRY_EXIT. User intervention is not necessary for this error unless the problem persists.

ERRID_GXENT_DOWNLOAD_ERR
Indicates that an error occurred while downloading firmware to the adapter. User intervention is necessary to fix the problem.

ERRID_GXENT_EEPROM_ERR
Indicates that an error occurred while reading the adapter EEPROM. User intervention is necessary to fix the problem.

ERRID_GXENT_LINK_DOWN
Indicates that the link between the adapter and the network switch is down. The device driver will attempt to reestablish the connection once the physical link is reestablished. When the link is again established, the device driver will log ERRID_GXENT_RCVRY_EXIT. User intervention is necessary to fix the problem.

ERRID_GXENT_RCVRY_EXIT
Indicates that a temporary error (link down, command error, or transmission error) has been corrected.

ERRID_GXENT_TX_ERR
Indicates that the device driver has detected a transmission error. The device driver will enter an adapter recovery mode in an attempt to recover from the error. If the device driver is successful, it will log ERRID_GXENT_RCVRY_EXIT. User intervention is not necessary for this error unless the problem persists.

For more information, about error logging, see "Error Logging" .

Related Information

The following publications provide additional information about Ethernet:

[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]