Release Notes PN 93000236R Digi RealPort Device Driver Version 3.8.0.0 AIX 4.2.1 and AIX 4.3.x 32bit ONLY Device Driver PN 40001427R 08/18/2003 CONTENTS Section Description ------- ---------------------------------------------------- 1 Introduction 2 Supported Products 3 Enhancements 4 Bug Fixes 5 Known Limitations 6 Upgrading from Release 2.X to Release 3.X 7 Device Configuration 8 stty-ncxa program 9 Transparent Printing 10 Error Logging 11 AIX 4.3.1 Patches 12 History 1. INTRODUCTION The Digi AIX RealPort (ncxa) driver makes the ports on Digi Ethernet-based Serial Products appear as though they are local AIX tty devices directly attached to the computer. When the AIX system boots, one ncxd daemon is spawned for each serial unit. Each daemon makes a single TCP/IP connection to its associated unit and sends all asynchronous serial data on this single connection. The daemon accesses the RealPort driver a through special parent adapter device set up by "smit". On most systems, smit will assign /dev/sa2 for the first unit, /dev/sa3 for the second unit and so on. This is a privileged, exclusive access device used only by the daemon. The ports on Ethernet-based Serial Products can be accessed any time they are configured for RealPort operations and are not otherwise in use. The RealPort Service requires AIX TCP/IP services to be installed and properly configured. This RealPort package includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). 2. SUPPORTED PRODUCTS Digi One EM Digi One IA Digi One IA RealPort Digi One RealPort Digi One SP Digi One TS Digi Flex Digi PortServer Digi PortServer II Digi PortServer II Rack Digi PortServer TS 2 Digi PortServer TS 4 Digi PortServer TS 8 Digi PortServer TS 16 Digi PortServer TS 16 Rack Digi EtherLite 2 Digi EtherLite 8 Digi EtherLite 16 Digi EtherLite 32 Digi EtherLite 80 Digi EtherLite 160 Digi EtherLite 162 3. ENHANCEMENTS Added support for RealPort with encryption. Removed AIX 5.x support from the driver. AIX 5.x support now has its own separate package. Removed AIX 4.1.x support from the driver. Daemons are no longer started in /etc/inittab. They are now started automatically during system boot by cfgmgr. 4. BUG FIXES None. 5. KNOWN LIMITATIONS If a unit loses power it may be necessary to wait for up to 2 minutes before communication is re-established with that unit. This Driver requires AIX Version 4.2.1 or higher, and is not recommended with AIX 4.3.0. AIX 4.3.1 requires two patches to fix several bugs in the "xtiso" driver. (see below under "AIX 4.3.1 Patches") Power Management does NOT work with RealPort. If running RealPort, AIX's Power Management must be unconfigured. If not unconfigured, the RealPort driver will disable Power Management. You cannot define an EtherLite unit as both an EtherLite (stsdd) device and a PortServer (ncxadd) device. The EtherLite devices may require a firmware change to work with this driver. EtherLite RS-422 and RS-485 ports should always add CLOCAL to the run and login modes when defining ports. Specify RS-422 for EL2 RS-485 ports. The driver should not be used under AIX 5.x anymore. There is a new 5.x package that supports 32bit and 64bit AIX kernels. Please visit http://support.digi.com/ for more information. The OpenSSL software requires an external Random Number Generator. IBM has this package prepared for AIX 4.3.x and above on their ftp site. 1) Install the "RPM" package manager first from: ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/INSTALLP/ppc/rpm.rte 2) Install the "PRNGD" RPM package from: ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/prngd/prngd-0.9.23-3.aix4.3.ppc.rpm NOTE: Both of these package links were correct at time of driver release. In case they are changed at some time in the future, you can find any updated links from this web page: http://www-1.ibm.com/servers/aix/products/aixos/linux/download.html Driver support for RealPort with encryption is only supported for Digi products that also include support for RealPort with encryption. Not all Digi products support encryption. Please check your Digi product's firmware documentation for more information. 6. UPGRADING FROM RELEASE 2.X TO RELEASE 3.X **This is NOT necessary for first time installation or if **migrating from Version 3.1.0 (Version 3.X) or any later **revisions of the driver. One of the differences between existing AIX RealPort device drivers (version 2.x.x.x, also referred to as v2) and the new AIX RealPort driver package (version 3.x.x.x, also referred to as v3) is the minor device numbering scheme. As a result of this difference, existing configuration information (such as defined tty devices) will not directly be supported by the new driver. Without external tools, the only option for a system manager is to delete the existing configuration, replace the v2 driver with a v3 driver, and then reconfigure all devices. This manual process is the safest means available but will be cumbersome as the number of devices grows. To minimize the impact of the minor numbering change, Digi has created tools to automate much of the migration process. These tools may be referred to as the "RealPort Migration Tools". Using these tools, most system administrators will be able to smoothly transition from the v2 drivers to the v3 drivers because the names and configuration of existing devices will be preserved. The migration tools are ONLY useful for those customers moving an existing install-base from the version 2 to the version 3 driver. They are available from the Digi FTP site (ftp.dgii.com) in the same location as the RealPort device driver. The part number is "80006838", and release notes (which serve as a user guide) for the migration tools are available in the same location. If you have any questions about whether the migration procedure is required in your situation, contact Digi technical support. 7. DEVICE CONFIGURATION Before you can use the devices on your unit, you must first configure each remote device and then configure each port on the unit. This is easiest to do with smit. Configure each unit as follows: Select "Devices" Select "Digi Device and Terminal Servers" Select "Add a Digi Device or Terminal Server" Select the type of unit you have. Enter the "INTERNET ADDRESS" of your unit. If the network connection between your AIX system and the unit includes a WAN Link that is slower than 1 MBit, enter the bits-per-second "WAN Link Speed" in the field provided. This parameter is not needed if your AIX system connects to the unit over a high-speed LAN. If your Digi RealPort product supports RealPort with encryption, and you would like the session to be encrypted, change the default of "Encrypt RealPort session" from "never" to "always". Hit Enter to complete configuration. Configure each TTY as follows: Select "Devices" Select "TTY" Select "Add a TTY" Select "tty rs232 Asynchronous Terminals" Select a Digi Parent Adapter. Enter the desired "Port number". Modify other TTY parameters as desired. Hit Enter to complete configuration. Configure each printer as follows: Select "Printer/Plotter" Select "Printer/Plotter Devices" Select "Add a Printer/Plotter" Select "osp Other serial printer" Select "rs232" Select a Digi Parent Adapter. Enter the desired "Port number". Modify other printer/plotter parameters as desired. Hit Enter to complete configuration. 8. STTY-NCXA PROGRAM The stty-ncxa program is a Digi-special version of stty that allows you to access Digi extensions to standard AIX ports. This program is installed as: /usr/lbin/tty/stty-ncxa The RealPort driver differs from the documentation as follows: altpin The altpin option is set in the unit and may not be changed from AIX. Altpin settings are configured on the unit. See "PORTSERVER SETUP" for more details. hupcl This option is ineffective because carrier is always dropped by the unit when a port is closed. The /usr/lbin/tty/stty-ncxa program's fastbaud option changes the baud rate table to a higher range of baud rates for users that need baud rates above termios's limit of 38400. The fastbaud table of substitute baud rates are: 0 - 0 50 - 57600 75 - 76800 110 - 115200 134 - 131657 150 - 153600 200 - 230400 300 - 460800 600 - 921600 1200 - N/A 1800 - N/A 2400 - 2400 4800 - 4800 9600 - 9600 19200 - 19200 38400 - 38400 9. TRANSPARENT PRINT If you configure a unit's port as a tty and you ask for an associated transparent print port, the following two devices will be created: /dev/ttyN - Login Port /dev/ttyNp - Transparent Print port Where "N" is the tty port number assigned by "smit". If you configure a port as a printer, only one device will be created: /dev/lpN - Printer Port The Login ports and Transparent Print ports will not operate unless carrier (DCD) is present. The stty-ncxa command may be used to change this with the "forcedcd" option. Printer Ports normally require both DCD and Clear To Send (CTS). The Login and Transparent Print ports may be open at the same time. Data sent to the Login port goes out the port without modification, while data sent to the transparent print port is bracketed with printer-on and printer-off sequences before output. The stty-ncxa command can set the on-off sequences and adjust the print speed. The Login port receives all input data. Reads to the print device always fail. 10. ERROR LOGGING Driver detected errors are logged to the error log and displayed with the AIX command "errpt". A limit of 100 messages is imposed. Daemon messages are written to the System Log. To direct these errors to a file, insert the following line in your /etc/syslog.conf file. *.info /var/adm/messages As ROOT, then run: touch /var/adm/messages chmod 0644 /var/adm/messages kill -1 `cat /etc/syslog.pid` The /var/adm/messages file can grow very large over a period of weeks or months and should be periodically truncated to avoid wasting disk space. 11. AIX 4.3.1 PATCHES In AIX 4.3.0, IBM introduced a number of problems in the "xti" interface to the TCP protocol stack. According to the IBM APAR database (and our own experience), these may cause lost data and system crashes. The patch list to make 4.3.0 is very long and Digi has not verified that the patch list solves the problems. Fortunately 4.3.1 requires only two patches to fix most of the problems in the "xti" interface. Currently these patches are available directly from IBM: http://service.boulder.ibm.com/aix/fixes/v4/os/bos.mp.4.3.1.1.bff http://service.boulder.ibm.com/aix/fixes/v4/os/bos.up.4.3.1.1.bff For help on installing fixes: http://service.software.ibm.com/rs6k/fixhelp.html 12. HISTORY Version 3.8.0 Added support for RealPort with encryption. Removed AIX 5.x support from the driver. AIX 5.x support now has its own separate package. Removed AIX 4.1.x support. Daemons are no longer started in /etc/inittab. They are now started automatically during system boot by cfgmgr. Version 3.7.0 Added support for EtherLite 32, Digi Flex, and a "catch-all" designed to give customers an opportunity to operate with Digi RealPort based units that are not explicitly supported by the device driver: "Other". Under certain circumstances, if the driver detected a loss of the carrier signal, it would make the serial port unusable until it was closed, which was not consistent with other AIX serial device drivers. Now the driver simply signals the condition and continues. Various message catalog errors were corrected, including incorrect SMIT screen headings, incorrect attribute names, and incorrect product names. The driver used to ignore the AIX port-specific default parameters assigned in the ODM (usually by SMIT). The driver now correctly reverts to the defaults stored in the ODM after the last close of the serial port. Version 3.6.0 Added support for EtherLite 80. Added support for custom baud rates. A custom baud rate overrides all other baud rate control for a port until the custom baud rate is set to zero or the system is reset. To set a custom baud rate, use stty-ncxa cspeed {custom-rate} ttyname. The new ioctls to get and set custom baud rates are defined here: #define DIGI_SETCUSTOMBAUD (('d'<<8) | 106) /* Set custom baud */ #define DIGI_GETCUSTOMBAUD (('d'<<8) | 107) /* Get custom baud */ NOTE: The ioctls do not know the valid range of baud rates supported by each unit and will let you set the baud rate to values that are unsupported by that port. In the examples below, the variable fd is the file descriptor of a RealPort tty device that is currently open by the calling process. { int speed, check; if (ioctl(fd, DIGI_SETCUSTOMBAUD, &speed) < 0) fprintf (stderr,"ioctl DIGI_SETCUSTOMBAUD fails: %s\n",strerror(errno)); if (ioctl(fd, DIGI_GETCUSTOMBAUD, &check) < 0) fprintf (stderr,"ioctl DIGI_SETCUSTOMBAUD fails: %s\n",strerror(errno)); } Version 3.5.0 Added support for PortServer TS, EtherLite and Digi One products. Streamlined the configuration process for the purpose of speeding up the boot cycle. This avoids the previously long boot process that was seen on machines with a high RealPort device count. Updated the fastbaud table to include baud rates up to 921600. Fixed a problem where the driver was not properly displaying the correct device number for devices of sa100 and higher. Increased device initialization speed at boot time. Devices entries to the /etc/inittab file now precede the tty entries so gettys do not error out with respawning too radidly messages. Version 3.3.0 Bug Fixes A problem with the driver removing all transparent print nodes (not just the associated nodes for that particular PortServer) has been resolved. The symptom of this error was the removal of all /dev/ttyXp nodes upon removal or unconfiguration of any configured PortServer device node. Version 3.2.0 Bug Fixes Fixed a problem where the driver incorrectly sends a break while waiting for output data to drain. Fixed a system crash which occurs when a modem hangup signal is received. Fixed a problem where data was lost at the end of a printout. Removed incorrect assert() message that triggered occasionally at some sites. Enhancements Increased the size of transparent print packets sent from the host system to the Portserver. Version 3.1.0 Enhancements Redesigned the driver to improve stability and add new features.