Note: The ATM LAN Emulation device driver is available for systems running AIX Version 4.1.5 (or later).
The Forum-Compliant ATM LAN Emulation (LANE) device driver allows communications applications and access methods that would normally operate over local area network (LAN) attachments to operate over high-speed ATM networks. This ATM LANE function supports LAN Emulation Client (LEC) as specified in The ATM Forum Technical Committee LAN Emulation Over ATM Version 1.0.
The ATM LANE device driver emulates the operation of Standard Ethernet, IEEE 802.3 Ethernet, and IEEE 802.5 Token Ring LANs. It encapsulates each LAN packet and transfers its LAN data over an ATM network at up to 155 megabits per second. This data can also be bridged transparently to a traditional LAN with ATM/LAN bridges such as the IBM 8281. (See the System Environment illustration.)
Each LEC participates in an emulated LAN containing additional functions such as:
There is always at least one ATM switch and a possibility of additional switches, bridges, or concentrators. An example of a typical network topology is shown in the following illustration.
The ATM LANE device driver is a dynamically loadable device driver that operates on a system running AIX Version 4.1.5 (or later). Each LE Client is configurable by the operator, and the LANE driver is loaded into the system as part of that configuration process. If an LE Client has already been configured, the LANE driver is automatically reloaded at reboot time as part of the system configuration process.
The interface to the ATM LANE device driver is through kernel services known as Network Services.
Interfacing to the ATM LANE device driver is achieved by calling the device driver's entry points for opening the device, closing the device, transmitting data, and issuing device control commands, just as you would interface to any of the AIX Common Data Link Interface (CDLI) LAN device drivers.
The ATM LANE device driver interfaces with all hardware-level ATM device drivers that support AIX CDLI, AIX ATM Call Management, and AIX ATM Signaling.
At least one ATM LAN Emulation client must be added to the system to communicate over an ATM network using the ATM Forum LANE protocol. A user with root authority can add Ethernet or Token-Ring clients using the smit atmle_panel fast path.
Entries are required for the Local LE Client's LAN MAC Address field and possibly the LES ATM Address or LECS ATM Address fields, depending on the support provided at the server. If the server accepts the "well-known ATM address" for LECS, the value of the Automatic Configuration via LECS field can be set to Yes, and the LES and LECS ATM Address fields can be left blank. If the server does not support the "well-known ATM address" for LECS, an ATM address must be entered for either LES (manual configuration) or LECS (automatic configuration). All other configuration attribute values are optional. If used, you can accept the defaults for ease-of-use.
Configuration help text is also available within the SMIT LE Client add and change menus.
The ATM LANE device driver supports the following configuration parameters for each LE Client:
The atmle_config entry point performs configuration functions for the ATM LANE device driver.
The atmle_open function is called to open the specified network device.
The LANE 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 network 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 or the NDD_LIMBO flag is set in the ndd_flags field or 15 seconds have passed.
If the connection is successful, the NDD_RUNNING flag will be set in the ndd_flags field, and an 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 an 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 sent.
The atmle_close function is called by the Network Services ns_free routine 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.
The atmle_output function transmits data using the network device.
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 FF.FF.FF.FF.FF.FF (hex) for both Ethernet and Token Ring and C0.00.FF.FF.FF.FF (hex) for Token Ring.
If the destination address in the packet is a multicast or group address, the M_MCAST flag in the p_mbuf->m_flags field should be set prior to entering this routine. A multicast or group address is defined as any nonindividual address other than a broadcast address.
The device driver will keep statistics based on the M_BCAST and M_MCAST flags.
AIX Token Ring LANE emulates a duplex device. If a Token Ring packet is transmitted with a destination address that matches the LAN MAC address of the local LE Client, the packet is received. This is also true for Token Ring packets transmitted to a broadcast address, enabled functional address, or an enabled group address. AIX Ethernet LANE, on the other hand, emulates a simplex device and does not receive its own broadcast or multicast transmit packets.
When the LANE device driver receives a valid packet from a network ATM device driver, the LANE 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 LANE 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 destination address. This address value is defined as FF.FF.FF.FF.FF.FF (hex) for both Token Ring and Ethernet and is defined as C0.00.FF.FF.FF.FF (hex) for Token Ring.
The device driver sets the M_MCAST flag in the p_mbuf->m_flags field when a packet is received which has a nonindividual address that is different than an all-stations broadcast address.
Any packets received from the network are discarded if they do not fit the currently emulated LAN protocol and frame format are discarded.
When a status event occurs on the device, the LANE 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 LANE device driver:
When an error occurs within the internal operation of the ATM LANE device driver, it is considered unrecoverable. If the device was operational at the time of the error, the NDD_LIMBO and NDD_RUNNING flags are turned off, and the NDD_DEAD flag is set in the ndd_flags field, and a hard failure status block is generated.
| code | Set to NDD_HARD_FAIL |
| option[0] | Set to NDD_UCODE_FAIL |
When the device driver detects an error which requires initiating recovery logic to 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 NDD_UCODE_FAIL |
Note: While the device driver is in this recovery logic, the network connections 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.
When a general error occurs during operation of the device, this status block is generated.
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.
| code | Set to NDD_LIMBO_EXIT |
| option[0] | The option field is not used. |
The atmle_ctl function is used to provide device control functions.
This control requests the LANE device driver's current ATM LAN Emulation MIB statistics.
The user should pass in the address of an atmle_mibs_t structure as defined in usr/include/sys/atmle_mibs.h. The driver will return EINVAL if the buffer area is smaller than the required structure.
The ndd_flags field can be checked to determine the current state of the LANE device.
This control requests the LANE device driver's ATM LAN Emulation MIB support structure.
The user should pass in the address of an atmle_mibs_t structure as defined in usr/include/sys/atmle_mibs.h. The driver will return EINVAL if the buffer area is smaller than the required structure.
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.
This control requests all the statistics counters kept by the LANE device driver to be zeroed.
This command disables the receipt of packets destined for a multicast/group address; and for Token Ring, it disables the receipt of packets destined for a functional address. For Token Ring, 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).
In all cases, the length field value is required to be 6. Any other value will cause the LANE device driver to return EINVAL.
The reference counts are decremented for those bits in the functional address that are enabled (set to 1). If the reference count for a bit goes to zero, the bit will be "turned off" in the functional address mask for this LE Client.
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 multicast/group addresses are active after receipt of this command, the NDD_ALTADDRS flag in the ndd_flags field is reset.
If a multicast/group address which is currently enabled is specified, receipt of packets destined for that group address is disabled. If an address is specified that is not currently enabled, EINVAL is returned.
If no functional or multicast/group addresses are active after receipt of this command, the NDD_ALTADDRS flag in the ndd_flags field is reset. Additionally for Token Ring, if no multicast/group address is active after receipt of this command, the TOK_RECEIVE_GROUP flag in the ndd_flags field is reset.
The NDD_DISABLE_MULTICAST command disables the receipt of all packets with unregistered multicast addresses, and only receives those packets whose multicast addresses were registered 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.
This command enables the receipt of packets destined for a multicast/group address; and additionally for Token Ring, it enables the receipt of packets destined for a functional address. For Ethernet, the address is entered in canonical format which is left-to-right byte order with the I/G (Individual/Group) indicator as the least significant bit of the first byte. For Token Ring, the address format is entered in noncanonical format which is left-to-right bit and byte order and has a functional address indicator. The functional address indicator (the most significant bit of byte 2) indicates whether the address is a functional address (the bit value is 0) or a group address (the bit value is 1).
In all cases, the length field value is required to be 6. Any other length value will cause the LANE device driver to return EINVAL.
The Token-Ring network architecture provides bit-specific functional addresses for widely used functions, such as Ring Parameter Server or Configuration Report Server. Ring stations use functional address "masks" to identify these functions. 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.
For example, if function G is assigned a functional address of C0.00.00.08.00.00 (hex), and function M is assigned a functional address of C0.00.00.00.00.40 (hex), then ring station Y, whose node contains function G and M, would have a mask of C0.00.00.08.00.40 (hex). Ring station Y would receive packets addressed to either function G or M or to an address like C0.00.00.08.00.48 (hex) since that address contains bits specified in the "mask."
Note: The LANE device driver forces the first 2 bytes of the functional address to be C0.00 (hex). In addition, bits 6 and 7 of byte 5 of the functional address are forced to 0.
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 C0.00 (hex) of the functional address and the functional address indicator bit).
A multicast/group address table is used by the LANE device driver to store address filters for incoming multicast/group packets. If the LANE device driver is unable to allocate kernel memory when attempting to add a multicast/group address to the table, the address is not added and ENOMEM is returned.
If the LANE device driver is successful in adding a multicast/group address, the NDD_ALTADDRS flag in the ndd_flags field is set. Additionally for Token Ring, the TOK_RECEIVE_GROUP flag is set, and the first 2 bytes of the group address are forced to be C0.00 (hex).
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.
This control requests all current LANE statistics, based on both the generic LAN statistics and the ATM LANE protocol in progress.
For Ethernet, you should pass in the address of an ent_ndd_stats_t structure as defined in file /usr/include/sys/cdli_entuser.h.
For Token Ring, you should pass in the address of a tok_ndd_stats_t structure as defined in file /usr/include/sys/cdli_tokuser.h.
The driver will return EINVAL if the buffer area is smaller than the required structure.
The ndd_flags field can be checked to determine the current state of the LANE device.
This control requests the current generic LAN statistics based on the LAN protocol being emulated.
For Ethernet, you should pass in the address of an ent_ndd_stats_t structure as defined in file /usr/include/sys/cdli_entuser.h.
For Token Ring, you should pass in the address of a tok_ndd_stats_t structure as defined in file /usr/include/sys/cdli_tokuser.h.
The ndd_flags field can be checked to determine the current state of the LANE device.
This control requests the current receive addresses that are enabled on the LANE device driver. The following address types are returned, up to the amount of memory specified to accept the address list:
Each address is 6-bytes in length.
This control requests the current MIB statistics based on whether the LAN being emulated is Ethernet or Token Ring.
If Ethernet, you should pass in the address of an ethernet_all_mib_t structure as defined in file /usr/include/sys/ethernet_mibs.h.
If Token Ring, you should pass in the address of a token_ring_all_mib_t structure as defined in file /usr/include/sys/tokenring_mibs.h.
The driver will return EINVAL if the buffer area is smaller than the required structure.
The ndd_flags field can be checked to determine the current state of the LANE device.
This control requests LANE device driver's MIB support structure based on whether the LAN being emulated is Ethernet or Token Ring.
If Ethernet, you should pass in the address of an ethernet_all_mib_t structure as defined in file /usr/include/sys/ethernet_mibs.h.
If Token Ring, you should pass in the address of a token_ring_all_mib_t structure as defined in file /usr/include/sys/tokenring_mibs.h.
The driver will return EINVAL if the buffer area is smaller than the required structure.
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.
The LANE device driver has two trace points:
Tracing can be enabled through SMIT or with the trace command.
trace -a -j 3a1,3a2
Tracing can be disabled through SMIT or with the trcstop command. Once trace is stopped, the results can be formatted into readable text with the trcrpt command.
trcrpt > /tmp/trc.out
The LANE error log templates are:
| ERRID_ATMLE_MEM_ERR | An error occurred while attempting to allocate memory or pin the code. This error log entry accompanies return code ENOMEM on an open or control operation. |
| ERRID_ATMLE_LOST_SW | The LANE device driver lost contact with the ATM switch. The device driver will enter Network Recovery Mode in an attempt to recover from the error and will be temporarily unavailable during the recovery procedure. This generally occurs when the cable is unplugged from the switch or ATM adapter. |
| ERRID_ATMLE_REGAIN_SW | Contact with the ATM switch has been re-established (for example, the cable has been plugged back in). |
| ERRID_ATMLE_NET_FAIL | The device driver has gone into Network Recovery Mode in an attempt to recover from a network error and is temporarily unavailable during the recovery procedure. User intervention is not required for this error unless the problem persists. |
| ERRID_ATMLE_RCVRY_CMPLETE | The network error which caused the LANE device driver to go into error recovery mode has been corrected. |
