ESP Driver for Linux (Beta)

Release Notes: Linux ESP Driver

Release notes for version 3.16 of the Equinox ESP software for Linux.

Supported Linux Releases

This release provides the ESP driver and associated software for the following types of Linux systems:

• Systems based on Linux 2.2 kernels (with x86 hardware).
• Systems based on Linux 2.4 kernels (with x86 hardware).
• Systems based on Linux 2.6 kernels (with x86 hardware).
• Itanium (IA64) systems running Linux 2.4 kernels.
• Itanium (IA64) systems running Linux 2.6 kernels.
• X86_64 systems running Linux 2.4 kernels.
• X86_64 systems running Linux 2.6 kernels.

Installation

The product is shipped as a tar image containing a source RPM and a set of utilities to assist in the installation.

Installation can be done automatically using the script espx-cfg or can be done manually.

Generally, it is recommended that the installation be done automatically using espx-cfg. For more information, refer to provided installation notes.

To install with espx-cfg:

1. Optionally, remove existing espx product, if installed

2. Obtain and locate the source RPM product and espx-cfg. This may be obtained via ftp, cd-rom or floppy.

3. cd to the directory that contains the espx source RPM and espx-cfg.

4. ./espx-cfg [-U] [-v] [-o RPM options] [-d directory] [source RPM name]

5. The utility creates a log file - /var/tmp/espx-log. If the installation fails, please read this log file.

To install manually:

1. Install the source RPM:

2. Build the binary RPM:

3. Install the binary RPM:

4. Load the driver and create device files:

5. Modify the start-up scripts so that driver is loaded at boot time. This step varies between Linux distribution:

• Redhat, Mandrake, TurboLinux, etc:
  • chkconfig –add espx
• Suse with insserv:
  • /sbin/insserv /etc/rc.d/eqnx
• Suse (without insserv), Caldera, etc:
  • cp /usr/sbin/rc.espx /etc/rc.d/espx
  • ln –s /etc/rc.d/espx /etc/rc.d/rc{N}.d/S90espx (where N=2,3,4,5)
• Debian, etc:
  • cp /usr/sbin/rc.espx /etc/init.d/espx
  • ln –s /etc/init.d/espx /etc/rc{N}.d/S90espx (where N=2,3,4,5)
• Slackware, etc:
  • invoke /usr/sbin/rc.espx from /etc/rc.d/rc.local
• Gentoo:
  • Manual set-up required to invoke /usr/sbin/rc.espx at boot-time.
  • (note: the script /usr/local/espx/espx-installrc attempts to do this step correctly).
• Discover and configure ESPs:
  • /usr/bin/espcfg

Installation Problems

1. The ESP software is only distributed as a RPM. On some systems, it may be required to bypass the RPM dependency checks by adding the “—nodeps” option. This is generally required on systems that do not distributed packages using RPM (such as Debian and Slackware). This option can be specified to espx-cfg by using the option “-o –nodeps”.

2. Kernel source must be installed (typically this would be in the kernel-source RPM package). Curses and perhaps curses-development must be installed (typically these would be the ncurses and ncurses-devel RPM packages). The RPM utility must be installed and on some systems, rpm-devel and rpm-build must also be installed.

3. The version of the running kernel must match the version of the installed kernel source. For the running kernel, the version can be found by doing ‘uname –a’. The version of the kernel source can be found by looking in the file /usr/src/linux-$VERSION/include/linux/version.h.

Note that right after installation, the version.h file may not be properly installed and may need to be initialized from the file /usr/include/linux/version.h

4. The kernel configuration files must match the configuration of the currently running kernel. Otherwise, there may be build or install problems with the driver. The most critical kernel configuration items are:

5. An upgrade operation will fail if the existing driver is in use during the install-upgrade. After freeing the ports, issuing the following command:

Kernel Rebuild

The driver will be built using the include files for the current kernel. As a result, the correct source must be installed on the system or the build will fail. In addition, the kernel source must be configured to match the current kernel (particularly, CONFIG_SMP and CONFIG_MODVERSIONS).

NOTE: In order to reduce the possibility of installation or operational problems, it is highly recommended that the following procedure be followed:

1. Install appropriate kernel source.
2. Configure the kernel as required.
3. Re-build the entire kernel (and modules).
4. Install and re-boot using the new kernel.
5. If there are no problems, install the Equinox ESP driver.

The actual steps for configuring, building and installing a kernel will vary based on distribution.

Components

The following are provided on the installation diskette:

• version 3.16 of the espx device driver
• versions 3.16 of the diagnostic utilities (esp, espcfg, espdiag and esptty)
• system man pages.
• installation notes

Please note that the embedded images (espapp.img, espboot.img, espbootb.img and espbootc.img) are no longer provided with the driver installation package. The embedded images are in a separate product that can be downloaded from the Equinox website or obtained via the Equinox CD.

Removal

Product removal can be done in two ways:

• espx-cfg [-v] –r

this uninstalls the espx RPM and also (optionally) removes temporary files from the rpm and build directories (recommended).

• rpm –ev espx

this uninstalls the espx binary RPM only.

Validated Distributions

Installation testing and critical product checkout was done on the following:

• RedHat 7.2 (2.4.7 kernel)
• RedHat 7.3 (2.4.18 kernel)
• RedHat 8.0 (2.4.18 kernel)
• RedHat 9 (2.4.20 kernel)
• RedHat AS 3.0 (2.4.21 kernel)
• RedHat ES 4 (2.6.11 kernel)
• RedHat AS 2.1 IA-64 (2.4.18 kernel)
• Fedora Core 3 (2.6.9 kernel)
• Mandrake 10.0 (2.6.3 kernel)
• Mandrake 10.1 (2.6.8 kernel)
• Suse AS 9.1 (2.6.4 kernel)
• Suse Enterprise 8 (2.4.19 kernel)
• Slackware 10.0 (note 1) (2.4.26 kernel)
• Debian 3.0r2 (note 1) (2.4.18 kernel)
• Gentoo 2004.3 (notes 1,2) (2.4.26 kernel)

Note 1 = requires “—nodeps” option to RPM .

Note 2 = requires manual installation of the boot-time installation script.

SMP Systems

Kernel patches may be required to correctly run on a symmetric multi-processing (SMP) system. For more information refer to the installation notes provided with the package

(installed at /usr/share/doc/espx-3.16/INSTALL) or contact Equinox Technical Support.

Differences between release 3.16 and 3.16d:

• Fixes for for 2.6.18, 2.6.19 and 2.6.20 kernels.

Differences between release 3.15 and 3.16:

• Fix to espcfg so that both Equinox and Avocent MAC addresses may be specified to the manual installation menu.
• Fix to the espcfg model menu invoked when doing an ESP manual install. The menu would display improperly when scrolling through the selection items.
• Fix for 2.6 kernels to properly maintain module usage count.
• Fix for 2.2 kernels to to remove build error.
• Remove build warnings, primarily with 2.6.17+ kernels.
• Change to espdiag, to force hardware flow control off when running loopback test. Note that software flow control is forced on.
• Change on Suse systems to use insserv to install the startup script.

Differences between release 3.13 and 3.15:

• Added support for ESP-8 MI and ESP-16 MI models.
• Changes to support "Avocent" branding.
• Fix to espcfg to eliminate problem with clearing ARP cache after removing an ESP.
• Fix to license specification in espx.spec file.
• Added alternative kernel source path - /lib/modules/<version>/build
• Minor changes to espcfg help screens.
• Changed the package build/install process to:
  1. Determine kernel source and object locations (2.6 kernels).
  2. Accept the environment variables KERNELSRC and KERNELOBJ which are used to manually specified kernel source and object locations.
• Modified espcfg to check for and invoke cloneconfig, if avaiable.
• Changes to comply with tty sub-system changes in 2.6.16 kernels.

Differences between release 3.12 and 3.13:

• Added support for x86_64 platforms (Intel Xeon and AMD Athelon).

• Added support for RedHat ES 4, i.e. kernel source located in /usr/src/kernels.

• Added support for ESP-4 MI models.

• Made change to driver write routine to comply with linux 2.6.10+ changes.

• Various installation changes, primarily for Suse systems.

• Fix to prevent kernel panics when removing the driver on linux 2.6 systems.

Differences between release 3.10 and 3.12:

• Added support for ESP-4 models.

• Fix to the espcfg utility for configuring ESP-8 MI models. This utility would incorrectly build the esp_ports.conf file. This would primarily affect the “replace” function for ESP-8 MI units. NOTE: customers with ESP-8 MI models should check the integrity of the file /etc/eqnx/esp_ports.conf prior to doing a replace. Corruptions can be corrected by removing and rediscovering the units.

• Added remote datascope capability to the espdiag utility. This allows the datascope operation to monitor serial traffic to/from an ESP even if the data is not being sent to/from the local system. Specified by a new field in the “datascope menu”.

• Added the “-m” option to the espdiag utility. This provides an alternate mechanism for specifying an ESP port. When invoked with this option, all menu items that expect an ESP port will present two fields for ESP number (01-64) and ESP port number (1-16). When invoked without this option, the same menu items will expect a device file name (such as /dev/ttyQ01e0).

• Fix problem with CUPS printing causing large jobs to be truncated.

• Modified the ioctl interface used by diagnostic utilities so that the dependence on kernel structures is removed. Eliminates the need for building diagnostic utilities using kernel header files.

• Modifications to driver startup-up script.

• Modified close function to always lower control signals and wait 200 us. if HUPCL is enabled.

• Fix to logic that cleans up ports on lost connectivity to an ESP. Before, a process may hang in the close logic when this occurs.

Differences between release 3.09 and 3.10:

• Added support for linux 2.6 kernels.
• Added support for new ESP model – ESP2-opto.
• Fix for port recovery after an ESP has come back on-line. Sometimes, the recovery would fail, leaving the port in an unusable state.

Differences between release 3.08 and 3.09:

• Fixed the counters display in espdiag. The RX-ERRORS field contains the count of framing errors, parity errors and overruns. The RX-BREAKS field contains the count of line breaks.
• Minor changes to comply with RPM version 4.2
• Fixed build errors and warnings on IA64 systems.

Differences between release 3.07 and 3.08:

• Fixed problems with write operations using ppp. The driver was not consistently calling the line discipline “write_wakeup” routine indicating that more data could be written. This might result in hung ppp applications.

• Modified the esp utility so that it closes all files inherited from its parent process.

• Added the ability to configure the UDP timeout value using the espcfg utility. A timeout occurs if the amount of time since a UDP “heartbeat” message has been received exceeds the timeout value. When the timeout occurs, the connection between server and ESP is severed. By default, the timeout value is 60 seconds. On some WANs, it may be desirable to change (generally increase) this value.

• Fix to the espcfg utility so that the “one-port option” is provided when manually adding an ESP-2 MI that was not discovered.

• Fix to the espcfg utility so that the “one-port option” is preserved when replacing an ESP-2 MI.

• Fix to the espdiag utility so that framing errors do not occur when shutting down the loopback test.

• Fix to the espdiag utility so that software flow control is forced on when running the loopback test.

• Fix to the espdiag utility so that the display updates correctly when running loopback at very low baudrates.

• Fixed build problems for the utilities on Suse 8.0 – IA64.

Differences between release 3.06 and 3.07:

• Adds support for the ESP-2 MI.

• The embedded images (espapp.img, espboot.img, espbootb.img and espbootc.img) are no longer provided with the driver installation package. The embedded images are in a separate product that can be downloaded from the Equinox website or obtained via the Equinox CD.

• The installation script and kernel makefiles would print a warning if CONFIG_SMP not configured in the kernel source to match running kernel. This warning is now a fatal error.

• Fixed test for CONFIG_MODVERSIONS to ensure kernel source matches running kernel.

• Emphasize during installation that a kernel build from the same kernel source used to build the driver is recommended prior to installation.

• Changes made to comply with RedHat 8.0 and rpm version 4.02. These are all build and install issues.

• Clarified the operation of the espcfg utility when a “Replace” fails. Previously, this would display a screen with the “Finish” button. Clicking on finish would cause the failed operation to be redone. Now, the screen has an “Ok” button, which when selected, returns to the main menu.

• The espcfg utility only shows 6 esps at a time on most display screens. If there are more than 6, the screen provides a scroll mechanism. This scroll functionality did not work properly (for example, the discovery screen would scroll the MAC address column but not the IP address column). Furthermore, additional screens would have garbled displays after using the scroll mechanism. Corrected.

• The espdiag utility would sometimes leave extraneous characters on the display after running loopback.

• Fixed possible system panic condition when doing port hangup.

Differences between release 3.05 and 3.06:

• The RPM packaging was modified to conform to standard “good RPM practices”. As a result, the RPM is now distributed as a source RPM. The installation procedure is substantially different. Please see installation notes.

• The replace function in espcfg failed in the case where the ESP unit to be replaced had already been removed from the system and the replacement unit was installed at the same IP address as the previous ESP.

• The espcfg utility was incorrectly not validating the gateway address when an ESP being installed was on the local network.

• Fixed various retries that were not being done properly in espcfg.

• Fix to espcfg to handle long lines in esp.conf. Typical 10/100 ESPS, with a configured gateway, were not being parsed correctly – espcfg would report these as “Unknown” type. Various functions within espcfg would fail in this case.

• The espdiag utility would generally hang when the driver wasn’t loaded or there was a structure mismatch with the driver.

• When a network disconnection / reconnection occurs, ports that are open with CLOCAL do not have their state properly restored. This can lead to unexpected problems with those ports.

• Fixed build warnings in the driver and utilities.

• There were also several changes to the embedded application and BIOS/bootstrap images:

Changes in embedded application between releases 3.01 and 3.04:

• Corrected a problem that will cause the ESP 10/100 and ESP-MI to reboot when memory resources are low and an Ethernet packet cannot be read from the Ethernet chip. The error would cause the ESP firmware to watchdog timeout, forcing the reboot. The error can occur in either 10MB or 100MB mode. This problem does not affect the older 10MB model ESP.

• The ESP has been corrected to operate serial ports correctly at 2400 baud. The Baud rate was not correctly set causing framing errors when data was received on an ESP serial port at 2400 Baud.

Changes in BIOS/bootstrap between releases 3.50 and 3.61:

• Corrected a problem with switches that use the spanning tree algorithm. Customers report that these switches block transmission of Ethernet packets from devices that establish LINK with the switch. From the time that LINK is established, the switch will block transmission of Ethernet packets for up to 30 seconds. As such, BOOTP request for IP address and TFTP requests for flash update will fail. This is because these are tried for less than 30 seconds. Because Ethernet packets transmitted to the switch are discarded, the BOOTP and TFTP requests never reach the intended server. The correction is to BOOTP for up to 45 seconds and to TFTP up to 45 seconds before declaring a failure. This will elongate ESP and CPS initialization time, but is the only way to solve this problem.

Differences between release 3.03 and 3.05:

• System validation and check is done prior to the install/build on the target system. This is used to detect and report typical system scenarios that result in installation errors:

• Kernel source must be installed (if not, installation exits with an error)
• Kernel header files version.h and config.h must be present (if not, installation exits with an error)
• Kernel source version must match version of the running kernel (if not, a warning is displayed).
• SMP configuration from kernel source must match running kernel (if not, a warning is displayed).
• MODVERSIONS configuration from kernel source must match running kernel (if not, a warning is displayed).

• The driver will be installed in different places for linux 2.2 kernels vs. linux 2.4 kernels.

• /lib/modules/KERNEL-VERSION/char (2.2 kernels)
• /lib/modules/KERNEL-VERSION/kernel/drivers/char (2.4 kernels)

• The datascope facility has been added to espdiag. The functionality is similar to the datascope facility available with the equinox sst drivers. This allows all transmitted data, received data, or both for a specified port to be captured in a large circular buffer. The data is displayed as it is captured and can also be reviewed later.

• An option was added to esptty to force CLOCAL to be turned on or turned off for a specified port. This would be useful in cases where an attached device does not properly set the DCD control signal. In this case, the only way to open the device is if CLOCAL is set.

• Small fix to the inuse script used to determine if esps are in use prior to removing the package via rpm –e.

• Added module licensing which will be required with later linux kernels.

Differences between release 3.02 and 3.03:

• Provides version 3.50 of the ESP bootstrap images:

• The bootstrap images for ESP 10/100 and ESP MultiInterface have been enhanced to support compressed application image files.
• The bootstrap images have been enhanced to support more comprehensive DRAM testing.

• ESP source is now installed at /usr/src/espx.

Differences between release 3.01 and 3.02:

• The esp program has been modified to use select calls with timeouts instead of relying on SIGALRM signals. Signal processing within the esp program could result in relatively long periods when TCP messages are not being sent or received.

• Provides installation/build fixes for systems based on linux 2.4 kernels:
• The installation procedure was dependent on the kernel source being located under /usr/src/linux. With 2.4 kernels, this is not /usr/src/linux-2.4.
• Fixed build problem with espdiag and esptty.

• Installation of man page “whatis” database has been modified to work correctly with RedHat 7.1 (i.e. the “whatis” file has been relocated).

• Added control signal display to espdiag “ESP Port Stats” function.

• Enhanced several functions in the espdiag utility to gracefully exit when the ESP being monitored is no longer responding.

• Fixed driver to release all allocated memory when the driver is unloaded.

• Fixed driver so that parity errors and framing errors are displayed by the espdiag “Counters” function.

Differences between release 3.00 and 3.01:

• Provides full support for Linux systems based on 2.4 kernels (the i386 RPM package will install and run on 2.2 and 2.4 kernel based systems).

• Provides full support for Itanium (IA64) systems (using Linux 2.4 kernels).

• Several performance modifications were made to the device driver:
• The polling logic has been streamlined and is more selective, resulting in less system interrupt overhead.
• Modifications to internal locking, resulting in lower lock contention and less lock hold times.
• Critical routines have been streamlined.

• The cu devices (/dev/cuqNNeP) are no longer supported on 2.4 based systems. The only device files available are the standard tty devices (/dev/ttyQNNeP). The cu devices are still available on systems with 2.2 based kernels.

• Added several diagnostic routines to espdiag:
• Added “register dump” function. This is used to display the internal SSP4 registers.
• Added “ESP server stats” function. This is used to display internal information about a specific ESP. This includes uptime and interface, TCP and UDP transfer and error counts.
• Added “ESP port stats” function. This is used to display internal information about a specific ESP port. This includes connection information, transfer counts and transfer errors.

• Fixed a problem where espcfg would take down a network interface if ip aliasing was being used.

• Fixed problems with the espcfg utility when discovering and establishing the IP address on ESPs. Stray responses to the UDP broadcast messages sent by espcfg would cause these operations to fail.

• Provides version 3.41 of the bootstrap embedded images. The previous driver release contained version 3.32 of the bootstrap images. The following major fixes are provided by this version of the bootstrap image:
• Corrected a problem with the function that stored the gateway and subnet address. Unless a gateway address was defined, the subnet mask was not correctly stored and would incorrectly load after a power loss. This would fail with both static addresses and dynamic addresses assigned by BOOTP.
• Corrected a problem processing a BOOTP reply when no vendor area was provided.
• Changed the BOOTP request to specify the ‘magic cookie’ value. This complies with RFC1048 and is required to obtain vendor extension area from the dhcp server on some systems.

• Provides version 3.01 of the embedded application image. The previous driver release contained version 3.00 of the application image.. The following major fixes are provided by this version:
• The SST driver within the embedded application has been corrected to prevent output of characters during initialization after power up.
• The embedded application will no longer accept connections from hosts when memory resources are low. Previously, attempting to connect with more than 8 hosts could cause a memory allocation error resulting in a system reboot.
• The embedded application implements functions that support the Windows 32API calls for SETXOFF and SETXON.

Differences between release 1.07 and 3.00:

• Provides full support for Multi-Interface ESPs.

• Provides full support for 10/100MB ESPs.

• The auto-flash feature has been added. In this mode, the ESP will automatically update its flash if the download images are modified.

• Provides support for RPM upgrade feature.

• Modified esp process to print more understandable message when no esps are configured and esp is invoked (usually at boot time).

• Two fixes for espdiag:
• The “barber pole” function now works at baud rates > 38400.
• Limits the number of ports when performing loopback.