README.TXT DIGITAL UNIX Driver for the DIGITAL ATMworks 351 PCI ATM Adapter ====================================== Copyright (c) Digital Equipment Corporation, 1997. All Rights Reserved. Unpublished rights reserved under the copyright laws of the United States. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in Subparagraph (c)(1)(ii) of DFARS 252.227-7013, or in FAR 52.227-19, as applicable. Contents: 1. INTRODUCTION 2. FEATURES 3. LATEST SOFTWARE RELEASES AND INFORMATION 4. QUALIFICATION INFORMATION 5. INSTALLATION REQUIREMENTS 6. CONFIGURATION GUIDELINES 7. INSTALLATION 8. DISPLAYING NIC INFORMATION 9. SAMPLE CONFIGURATION FILE 10. CHANGING SWITCH PORTS 11. CUSTOMIZATION 12. TROUBLESHOOTING 13. INTERPRETING PRINTED MESSAGES **************** * INTRODUCTION * **************** This file describes the installation and the use of the DIGITAL UNIX driver for the ATMworks 351 PCI ATM adapter. This kit includes: * A readme.txt file describing the contents of this kit and its requirements. * A release.txt file describing known bugs, limitations, and bug fixes for the included driver. * The DIGITAL UNIX driver for the ATMworks 351 adapter. ************ * FEATURES * ************ The driver supports the following features: - Multiple ATMworks 351 cards running simultaneously - LAN Emulation Client - Classical IP Client and Server - IP switching - DIGITAL ATM sockets PVC API - PVCs only - UBR (unspecified bit rate) - Paced UBR (a UBR with a maximum bit rate) - CBR (constant bit rate) - FLOWmaster flow control (ALPHA WORKSTATIONS ONLY) - VPIs (0 - 7) ******************************************** * LATEST SOFTWARE RELEASES AND INFORMATION * ******************************************** The latest information (software releases, installation requirements, configuration guidelines, known bugs, etc) is available on the World Wide Web at the following addresses: North America: http://www.networks.digital.com Europe: http://www.networks.europe.digital.com Australia: http://www.digital.com.au/networks Japan: http://www.dec-j.co.jp/ic/network You can also use the Bulletin Board System to access software releases. Set your modem to 8 bits, no parity, 1 stop bit and dial 978-506-5777 (U.S.A.). For the latest in supported platforms and product information regarding your DIGITAL ATMworks product, call your local authorized DIGITAL reseller or dial 1-800-282-6672 in the U.S.A. ***************************** * QUALIFICATION INFORMATION * ***************************** The ATMworks 351 has been qualified on both workstations and servers. For information about particular systems, configuration restrictions and supported versions of Digital UNIX, refer to the following web pages: Servers: http://www.digital.com/alphaserver/products.html select a systems and then select "options list" Workstations: http://www.workstation.digital.com/products/alphstns.html select the hardware options button ***************************** * INSTALLATION REQUIREMENTS * ***************************** First, use the above mentioned web pages to ensure that your system is qualified with the ATMworks 351, and that it meets all of the qualification restrictions. To determine which DIGITAL UNIX version you are running, use the command "uname -a". Before installing the driver, make sure the following are available: - 1 bus-master capable PCI slot. - A minimum of 64 Mbytes of memory. - FLOWmaster REQUIRES THAT THE DRIVER IS INSTALLED ON A WORKSTATION. SERVERS DO NOT SUPPORT FLOWmaster. **************************** * CONFIGURATION GUIDELINES * **************************** 1) For best network throughput, install the ATMworks 351 adapter on the primary PCI bus. If this is not possible, then install the NIC on a lightly loaded PCI bus. 2) If the system's PCI bus is edge-triggered, do the following command at the UNIX prompt: sysconfig -r lpa edge_triggered=1 This command must be executed each time that the system boots. To determine if the system PCI bus is edge triggered, refer to the system's documentation, or to the PCI adapter's documention. Very few devices/systems require edge triggering. It is always okay to set the edge triggered parameter, although it will add a slight performance penalty. However, the system will hang if it requires the edge triggering and this parameter is not set. 3) If a KZPDA SCSI adapter is installed in the system, ensure that its FIFO threshold is set at 2, On older KZPDA SCSI adapters, it may have been set to 3. The release notes for the KZPDA describe how to do this. **************** * INSTALLATION * **************** The tar file kit is installed using the "setld" utility. To install the driver, perform the following steps: 1. Ensure that your system has all of the latest ATM patches installed. The latest patches can be obtained from: http://www.service.digital.com/html/patch_service.html 2. Power down the system and install the card into a bus-master capable PCI option slot. 3. Power up the system and use the console to verify that the ATMworks 351 adapter is recognized by the console: >>> show config For each ATMworks 351 adapter that you have inserted into the PCI bus, you should see one of the following two lines: Digital ATMworks 351 or, for older consoles that do not recognize the ATMworks 351 adapter: Vendor: 102F Device: 20 (or 21) If one of these lines is not displayed, then ensure that the card is installed in a PCI slot and that it is properly seated. 4. Boot the system and log in as root. 5. Uninstall any previous versions of the driver. You can determine if previous versions were installed by using the command: setld -i | grep LPADRV For example, to remove previous version 1.00, use the command: setld -d LPADRV100 6. Extract the tar file: tar xvf LPA101.tar 7. Install the setld kit: setld -l LPA101 This setld command performs the following actions: * Copies the driver to /usr/opt/LPA101, and sets up a soft link from /var/subsys to the driver in /usr/opt/LPA101. * Updates the sysconfigtab file. * Adds the driver to the list of dynamic subsystems. * Allows sysconfig to attempt a driver autoload if needed. 8. Remove the untar'd kit: rm -r LPA101 9. Reboot the system. 10. When the system reboots, be sure to to start up the ATM subsystem. Assuming that an atm.conf file exists (as described inthe "sample configuration" section, use the command "atmconfig source". By default, the driver does not enable FLOWmaster flow control. FOR SERVERS, DO NOT ENABLE FLOWMASTER. For workstations, enable FLOWmaster (before configuring either CLIP or LANE) by using the following command: atmconfig +vfc driver = where the driver_identifier would likely be lpa0, lpa1, etc. For information about the DIGITAL UNIX ATM infrastructure, refer to the DIGITAL UNIX book "Asynchronous Transfer Mode". You can also view the man pages for the topics "atmconfig" and "atmarp". These documentation resources provide information about setting up and configuring the LAN Emulation (LANE) and Classical IP (CLIP) convergence layers. The documentation also provides information about configuring and using PVCs and CBR under the "atmconfig" command. For information about the PVC API and to get sample applications, go to the previously mentioned Web site. ****************************** * DISPLAYING NIC INFORMATION * ****************************** When the operating system loads the ATMworks 351 device driver, it writes logging information to the file "/var/adm/messages". The written information includes MAC addresses, hardware revisions, PCI slot, etc. To find these messages, search the file for the text "lpa". For more detailed information, you can increase the logging level. This is described in the customization section. ***************************** * SAMPLE CONFIGURATION FILE * ***************************** # This file contains commands used to configure and start ATM networks # on DEC OSF/1. # # Each line in this file is a command to atmconfig. All atmconfig commands # can be used here. See the atmconfig manual page for a description of # atmconfig commands. # # When in batch mode, atmconfig permits the use of the following additional # commands: # # run prog_name arg1 arg2... # Execute the program prog_name with the arguments provided. # The PATH in the environment is used to search for prog_name. # # runb prog_name arg1 arg2... # Execute the program prog_name in the background with the # arguments provided. The PATH in the environment is used to # search for prog_name. # # print arg1 arg2... # Print the arguments to standard out. # # sleep [time] # Sleep for time seconds before executing the next command. # The default is 1 second. # # Commands are executed in the order in which the appear in this file. # Lines beginning with '#' are ignored. # # If any command results in a error being returned atmconfig will stop # executing and exit. # # The commands in this file are run by typing: # # atmconfig source # # print Starting ATM Network - configuring clIP # Enable FLOWmaster (DO NOT ENABLE FLOWMASTER ON ALPHA SERVERS) #run /sbin/atmconfig +vfc driver=lpa0 run /sbin/atmconfig up driver=lpa0 run /sbin/atmconfig wait state=up driver=lpa0 # Bring signaling up and wait till address registration is complete run /usr/sbin/atmsig up driver=lpa0 wait run /usr/sbin/atmarp -c lis=0 driver=lpa0 run /sbin/ifconfig lis0 pong.clip netmask 255.255.255.0 up # allow dynamic ESI time to register with switch sleep 3 # For setting a PVC, note PVC on a second NIC requires a # selector value. #+pvc driver=lpa0 converge=atmip vpi=0 vci=50 #+pvc driver=lpa1 selector=1 converge=atmip vpi=0 vci=200 run /usr/sbin/atmarp -h lis=0 client lane lane print Starting ATM Network - configuring ELAN run /usr/sbin/atmelan create driver=lpa0 run /usr/sbin/ifconfig elan0 pong.elan1 netmask 255.255.255.0 up run /usr/sbin/atmelan create driver=lpa0 name=ELAN1 mtu=4544 run /usr/sbin/ifconfig elan1 pong.elan2 netmask 255.255.255.0 up run /usr/sbin/atmelan create driver=lpa0 name=ELAN2 mtu=9234 run /usr/sbin/ifconfig elan2 pong.elan3 netmask 255.255.255.0 up print ATM network started ************************* * CHANGING SWITCH PORTS * ************************* When you connect an ATMworks 351 NIC to a new switch port, the NIC will have a new ATM address. If this NIC was acting as a Classical IP Server, then you must update all of the Classical IP clients with the Classical IP server's new ATM address. To determine the Classical IP server's new address, look at the console output when you execute the "atmarp -h lis=? server" command. Then, update the ATM address of the Classical IP ARP server in the client's atmhosts file. ***************** * CUSTOMIZATION * ***************** The driver contains the following features which you can customize: 1) vpi_bits The VPI bits can be set to a value from 0 to 3. The following table demonstrates the effect on the VPI and VCI values the NIC can use on the link. VPI_BITS VPI Values VCI Values 0 0 0-1023 1 0-1 0-511 2 0-3 0-255 3 0-7 0-127 2) logging_level The logging level can be set to the following values: 0 Display the important information (default). 1 Display information that is useful in resolving problems. 2 Display all possible information. If the logging level is increased from 0, then many more messages will be logged, which increases the size of the messages file. Therefore it is recommended that you do not leave the logging level at 1 or 2 after you have finished debugging a problem. 3) vc_max_xmt_slots This entry generally should not be changed by the user, unless they are doing performance tuning, and know what they are doing. The purpose of this parameter is to prevent VCs from using all of the transmit resources on the NIC. For instance, if this feature were not implemented, all VCs would tend to transmit at the rate of the slowest VC, which could be a problem if running a slow CBR circuit and a faster UBR circuit. Increasing the number can potentially increase your performance if the system seems to be running slow, but might cause less VCs to transmit concurrently. Decreasing the number can potentially decrease your performance, but might cause more VCs to transmit concurrently. 4) rcv_max_pkts_per_int This entry controls the number of receive packets that the driver can process per interrupt. Its purpose is to prevent the transmit path from being starved. It is unlikely that you should ever need to change this value. 5) rcv_holdoff_pkt_cnt This entry controls the number of packets that the NIC must receive before it generates a receive interrupt. However, if the receive holdoff timer expires, an interrupt is generated as long as the NIC has received at least one packet, even if the specified threshold has not been reached. It is unlikely that you should ever need to change this value. For more information, refer to the section "rcv_holdoff_time" below. 6) rcv_holdoff_time This entry controls the number of microseconds that the driver waits to generate an interrupt after it receives a packet. For low latency applications, use the value "0". If the NIC receives more than "rcv_holdoff_pkt_cnt" packets however, an interrupt is generated, even if the "rcv_holdoff_time" timer has not expired. It is unlikely that you should ever need to change this value. For more information, refer to the section "rcv_holdoff_pkt_cnt" above. 7) dump_vc_state This is a debug utility, do not use. 8) dump_csrs This is a debug utility, do not use. 9) dump_vc_state This is a debug utility, do not use. 10) dump_vc_abr_info This is a debug utility, do not use. 11) dump_csrs This is a debug utility, do not use. 12) dump_vc_ready_list This is a debug utility, do not use. 13) dump_xmt_slot_log This is a debug utility, do not use. Since this parameter controls both the logging and display of the transmit slots that the driver writes to the NIC, it must be set to the value 1 before an error occurs. Otherwise, the driver does not update the slot log. 14) dump_counters This is a debug utility, do not use. 15) dump_suni_counters This is a debug utility, do not use. 15) dump_drv_state This is a debug utility, do not use. 16) edge_triggered For most configurations, do not set this value. However, if you system is using an edge triggered PCI bus, then set this parameter to '1'. For more information, refer to the release notes. 12) dump_counters This is a debug utility, do not use. This parameter controls display of internal driver counters. ******************* * TROUBLESHOOTING * ******************* First, verify the following: - The system meets the installation requirements. - You have followed the configuration guidelines described in this document. - You have read the release notes for any known problems/restrictions. - The NIC is properly installed and fastened. Do not use the NIC without securely fastening it. - The ATM subsystem is installed. - You have executed the "atmconfig source" command. - Both LEDs are green on the NIC. If the NIC LED is not lit, then the driver has not yet been loaded, or it had a fatal error while loading. If the link LED is not green, verify that your switch is running, that the cable is good, and that the cable connections are not reversed. - The system's console is up to date. - The device driver is up to date. The console log is your best source of information. It displays information when the link goes up and down, and when VCs are set up and torn down. You can control the amount of information that is displayed by using the sysconfig -r command to change the logging level. For instance, to display the maximum amount of logging on device lpa0, use this command: sysconfig -r lpa logging_level=2 For more information on the logging levels and interpretation of the messages, refer to the section on "Customization". The "atmconfig" command is useful for viewing the current state of the driver. For example: atmconfig vclist For a list of all VCs currently opened. atmconfig drvlist For a list of all drivers currently configured. Appending a "long" to the end of each command provides extended detail. ********************************* * INTERPRETING PRINTED MESSAGES * ********************************* The section describes all of the printed messages that you might see, and how to interpret them. "Cannot create controller structure" The driver will not be able to run, a serious problem has occurred. Contact your support person. "Invalid unit number" You have attempted to install too many ATMworks 351 adapters into the system. Remove ATMworks 351 NICs until this message is no longer displayed. "Could not allocate memory for control structure" Install more memory in the system, and ensure that no applications have software leaks. "Invalid bus type" This message should never be seen, contact your support person. "ASIC Rev: %d, PHY type is MMF/UTP" This informational message is printed out each time the driver is loaded for a card. Higher numbered revisions are more recent. Cards are either multimode fiber (MMF) or unshielded twisted-pair (UTP). "This is not a Digital ATMworks 351, subsystem vendor id is" Verify that the installed card is really a DIGITAL ATMworks 351 adapter. If it is, contact your support person because you might have faulty hardware. "NICs ASIC not recognized, device id is 0x%x, vendor id is" Verify that the installed card is really a DIGITAL ATMworks 351 adapter. If it is, contact your support person because you might have faulty hardware. "Initialization failed" The NIC could not be initialized. Possible causes include insufficient memory in the system or faulty hardware. "Interrupt handler add failed" The NIC could not register its interrupt. It is likely that there is a conflict with another card, and that card is not functioning correctly. Remove non-vital cards from the system one-by-one until this error no longer occurs. "Couldn't start link check thread" This NIC could not start a thread, and will not run correctly. Contact your support person or upgrade your driver. "Total %d MAC addresses" This informational message displays the number of ESIs that the NIC has. "Digital DGLPA ATM Interface, hardware addresses" This informational message displays the NIC's ESIs. "Couldn't register with CMM" This is a serious error, the driver will not run correctly. Contact your support person or upgrade your driver. "atm_configure: Device already configured" This driver displays this message if you reconfigure a device that is already configured. The driver ignores the requested action. "cfgmgr_get_state failed" The driver could not perform a necessary action. Contact your support person or upgrade your driver. "lpa.mod: Cannot create controller structure" The driver could not perform a necessary action. Contact your support person or upgrade your driver. "Cannot configure driver" The driver could not perform a necessary action. Contact your support person or upgrade your driver. "Cannot register PRECONFIG callback" The driver could not perform a necessary action. Contact your support person or upgrade your driver. "atm_configure: unsupported operation" The user requested an unsupported operation, so the driver takes no action. "FAILED to create controller structs during init" There might be insufficient memory in the system. If you cannot resolve the problem, contact your support person. "ATM link is now down" This informational message is printed whenever the link transitions from up to down. Until the link comes up, no more packets can be sent or received. "ATM link is now up" This is an informational message that is printed whenever the link transitions from down to up. When the link comes up, the driver can send and receive packets. "Host access error" A serious error has occurred, the driver will no longer work. You might have faulty hardware or software, contact your support person. "Transmit underflow" A serious error has occurred, the driver will no longer work. You might have faulty hardware or software, contact your support person. "Receive FIFO overflow" A serious error has occurred, the driver will no longer work. You might have faulty hardware or software, contact your support person. "Receive data overflow" This is a normal occurrence during high traffic conditions. "No big receive buffers" This can happen during high traffic conditions. When traffic subsides, this message should not continue to be printed. "No small receive buffers" This can happen during high traffic conditions. When traffic subsides, this message should not continue to be printed. "No raw receive buffers" This can happen during high traffic conditions. When traffic subsides, this message should not continue to be printed. "CRC-32 error, packet(s) discarded" This message can be printed if there is cell loss in the network, cell loss traversing the PCI bus, or corrupted data on the network. "length error, packet(s) discarded" This message can be printed out on rare occasions, but if it occurs frequently, check your cabling. If you still cannot resolve the problem, contact your support person. "aborted packet, packet(s) discarded" This message can be printed out under normal circumstances, but if it occurs frequently, check your cabling. If you still cannot resolve the problem, contact your support person. "AAL5 packet reassembly timeout, packet(s) discarded" This can happen when part of the packet is lost. If this occurs frequently, contact your support person. "AAL5 packet too long, packet(s) discarded" If this happens frequently, there might be a misbehaving device on the network. "Unknown ack received" This can occur when FLOWmaster flow control is running. If it occurs very frequently, contact your support person and check your hardware. "Big receive buffers low" This can happen during high traffic conditions. When traffic subsides, this message should not continue to be printed. "Small receive buffers low" This can happen during high traffic conditions. When traffic subsides, this message should not continue to be printed. "Raw receive buffers low" This can happen during high traffic conditions. When traffic subsides, this message should not continue to be printed. "Data received on unopened VC" This can happen if the other end of the link sends a packet on a VC that the NIC has not opened. Typically, this happens just as VCs are being set up, but should not occur when VCs are stable. It can also occur when the NIC is configured to run IP switching only, and is connected to a switch that is running "ILMI". In this case, the switch sends cells on the ILMI VC (16) which the NIC did not open because it was only running IP switching (which does not require ILMI). "Data received on unknown VC" This can occur if the other end of the link transmits data on VCs outside of the range that can be supported by the ATMworks 351 adapter. "Lost the EOP of the PDU" This can happen during high traffic conditions. When traffic subsides, this message should not continue to be printed. "Xmt fatal error" There is either a hardware or software problem. The driver cannot continue operating. Contact your support person. "PCI fatal error" There is either a hardware or software problem. The driver cannot continue operating. Contact your support person. If your system doesn't generate PCI parity correctly, and you have an 01 version of the ATMworks 351 adapter, you need to upgrade your NIC. "PHY fatal error" There is either a hardware or software problem. The driver cannot continue operating. Contact your support person. "Peep Hole error" There is either a hardware or software problem. The driver cannot continue operating. Contact your support person. "Host Access error" There is either a hardware or software problem. The driver cannot continue operating. Contact your support person. "XMT Free Slot Underflow" There is either a hardware or software problem. The driver cannot continue operating. Contact your support person. "Rcv Free Slot FIFO Overflow" There is congestion on the PCI bus, some cells were possibly dropped. "Reclaiming Receive Buffers" This informational message can be seen on 01 revisions. A packet might subsequently be lost. "couldn't allocate big buffers" There is insufficient memory in the host system. Add more memory or use less NIC cards. "couldn't allocate small buffers" There is insufficient memory in the host system. Add more memory or use less NIC cards. "device is down" This informational message indicates that the device was brought down. It will not transmit or receive any more packets until it is brought back up. "LPA_VC_ENABLE failed" The driver could not perform a necessary action. Contact your support person or upgrade your driver. "VC for FM credit resync already open" Unless FM already had the VC open, the NIC will not work properly. Ensure that some application is not attempting to use the same VC. "VC for FM credit resync couldn't be opened" Unless FM already had the VC open, the NIC will not work properly. Ensure that some application is not attempting to use the same VC. "cannot set flow master credit" An error occurred running FLOWmaster flow control. Do not run FLOWmaster flow control until your support person rectifies the problem. "lpa_vc_xmt: can't get mbuf" A packet was dropped because the driver could not get an mbuf. Ensure that your system has sufficient memory. "FLOWmaster will be enabled on the next link up transition" This informational message indicates that the user has selected to run FLOWmaster flow control on the link. "FLOWmaster cannot be enabled when the sysconfigtab vpi_bits value is non-zero" The user is selecting an unsupported combination of features. "The value for vpi_bits is greater than the allowable maximum" This message should never be seen, contact your support person. "could not allocate memory for tx report buffer" There is insufficient memory in the host system. Add more memory or use less NIC cards. "could not allocate memory for rcv report buffer" There is insufficient memory in the host system. Add more memory or use less NIC cards. "could not allocate memory for aal5 trailers" There is insufficient memory in the host system. Add more memory or use less NIC cards. "Failed to create FLOWmaster" This message should never be seen, contact your support person. "Failed to create meteor data" This message should never be seen, contact your support person. "Failed to initialize meteor data" There might be a hardware or PCI configuration problem. Contact your support person. "Failed to create adapter data" This message should never be seen, contact your support person. "Failed to initialize adapter data" There might be a hardware or PCI configuration problem. Contact your support person. "Set vpi/vci mapping failed, using default" This message should never be seen, contact your support person. "Set big slot size failed, using default" This message should never be seen, contact your support person. "Set small slot size failed, using default" This message should never be seen, contact your support person. "couldn't allocate small buffers" There is insufficient memory in the host system. Add more memory or use less NIC cards. "couldn't allocate big buffers" There is insufficient memory in the host system. Add more memory or use less NIC cards. "Returning transmit slot 0!" This message should never be seen, contact your support person. ===================================================== TRADEMARKS ATMworks, DEC, DIGITAL, DECpc, and FLOWmaster are trademarks of Digital Equipment Corporation. All other trademarks and registered trademarks are the property of their respective holders.