user.doc Digi International driver package for the PC/Xe, PC/Xi, PC/Xr, PC/Xem as well the EISA and PCI variants of these boards where applicable. Copyright (C) 1996 Digi International. Written by Ronnie Sanford digilnux@dgii.com This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (At your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. This document describes the software used with the Digi/Linux driver package. The four user programs listed below are described in this document: 1. digiConfig -> Application that configures the Digi driver. 2. digiDload -> Application which initializes the Digi hardware. 3. buildPCI -> Application which provides the user a method of building device nodes for PCI devices. 4. ditty -> Application which provides the user a method of configuring terminal options on Digi hardware. -------------------------------------------------------------------------- 1. Configuring driver/kernel for Digi products -------------------------------------------------------------------------- The Digi driver must be configured each time Digi hardware is added or removed. There are two supported methods of doing this. The first method configures the driver dynamically at boot time but requires the user to utilize the lilo loader. This method is the preffered method as it does not require the rebuilding of the kernel. In order to use lilo to configure Digi boards at boot time an appropriate append command should be added to /etc/lilo.conf below the appropriate label decleration. See footer 4. The append commands format is a string of comma separated identifiers or integers used to configure supported boards. These six values in order are: Enable/Disable this card or Override, Type of card: PC/Xe (AccelePort) (0), PC/Xeve (1), PC/Xem or PC/Xr (2), EISA/Xem (3), PC/Xe (64K) (4), PC/Xi (5). Enable/Disable alternate pin arrangement, Number of ports on this card, I/O Port where card is configured (in HEX if using string identifiers), Base of memory window (in HEX if using string identifiers) A sample append command is given below which if used would configure and enable a PC/Xe with 8 ports, at i/o address 200, memory address 0xd0000 with alt pin turned off. The lilo.conf file should look like this: image = /vmlinuz root = /dev/hda2 label = vmlinuz append="digiepca=E,PC/Xe,D,8,200,D0000" likewise the below will perform the same function: image = /vmlinuz root = /dev/hda2 label = vmlinuz append="digiepca=1,0,0,8,512,851968" Note: PCI boards are auto-detected and configured (Hence their codes are not given here). Do not attempt to configure PCI boards with the lilo append command. If configuration data has been specified by using digiConfig (Described below), and you wish to override this configuration using lilo without specifying a specific card (Example if there are PCI cards in the system) the following override command will accomplish this: -> append="digiepca=2" If lilo is not enabled, the second method of configuring Digi hardware will have to be used. digiConfig is an application that can be used to inform the system of any additions, deletions, or modifications involving Digi hardware. To use this method the operator executes digiConfig anytime an EISA or ISA card is added that he wishes to use. This routine is also used to remove cards from the system, and to modify parameters of those cards already present in the system. Upon being executed digiConfig modifies files accessed by the Digi driver. To make these changes permanent; the operating system must be recompiled. After the operating system has been recompiled and booted, the changes made with digiConfig will be introduced to the user. This program MUST be executed every time Digi EISA/ISA hardware configuration changes. Note, it is not necessary to execute digiConfig in order to configure the Digi PCI cards. These cards are self-identifying and will be recognized by the driver. They cannot be displayed using digiConfig nor will digiConfig build the device nodes their device nodes. See footer 1. To execute digiConfig; simply type: digiConfig The application will query you for the type, memory address, port address, number of ports, alt pin disposition and status of each board that exist on the system. Note, currently this driver only supports PC/Xe, PC/Xeve, PC/Xi, PC/Xr, and PC/Xem as well as their EISA and PCI implementations if applicable. All supported cards (Other than PCI) that are present should be registered via digiConfig. See footer 2. After all cards have been configured select exit. The system will then inform you if any changes have been made, and ask you if it is okay to make these changes permanent. If the data entered is correct, select okay. Selecting cancel will prevent the changes from becoming active. digiConfig can then be re-executed to configure the system again. -------------------------------------------------------------------------- 2. Initializing Digi hardware with digiDload -------------------------------------------------------------------------- digiDload is the application executed after the Digi driver has been loaded. It is responsible for initializing the hardware and leaving it in a state such that the Digi board may be operated by the user. The application may be placed anywhere on the path, but its related support files must be located in /etc/digi. The related files are: sxfep.bin sxbios.bin xxfep.bin xxbios.bin The format for this command is "digiDload [v]". If given the "v" option turns on verbosity. If not given the application runs in quite mode. To execute the program simply type: digiDload Upon completion digiDload will generate the below message: "digiDload complete: Card initialized" At this point the card is configured and ready for normal usage. See technotes.doc for information on how how ports are determined and assigned. -------------------------------------------------------------------------- 3. Build PCI device nodes with buildPCI -------------------------------------------------------------------------- buildPCI is an application useful for building the necessary device nodes for Digi PCI cards. It is reccomended that this tool be used because the current digiConfig application does not provide this function for PCI cards (Though it does build device nodes for non-PCI cards). To use this program execute the following:first install the driver, and execute digiDload (See above). After digiDload has successfully loaded, execute the following: buildPCI Where arg1 is the number of ports connected to Digi cards that are not PCI (As shown by the digiConfig utility), and arg2 is the number of ports connected to Digi cards that are PCI. Note, buildPCI only has to be ran once to build the necessary device nodes. Though this program may be executed at anytime, we reccomend delaying execution until the first time you install the package and after digiDload has been executed. -------------------------------------------------------------------------- 4. Setting Terminal Options with ditty -------------------------------------------------------------------------- ditty is a utility program that sets and displays the terminal options for Digi intelligent serial products. See man ditty for detailed information. Footnotes: 1. The 1.2.x kernel does not provide a method of mapping the high addresses (Normally higher than RAM) associated with PCI. For this reason, this driver disables PCI support while running under the 1.2.x kernels. 2. PCI cards should not and cannot be registered with digiConfig. After the driver has been loaded buildPCI may be executed to construct the necessary device nodes. This step is not necessary for system not having Digi PCI cards. 3. This is because we forsee a time when buildPCI may auto-detect the available Digi PCI cards and this would only work if the program is executed after digiDload. 4. A complete example is given in install.doc. -------------CHANGES-------------------- All changes should be recorded here. All changes should be explained in verbose detail. ----------------------------------------------------------------------- Programmer : Ronnie Sanford Date : June 1, 1996 Description (Verbose) : Initial release of driver package. Files affected : all Release version : 1.0.0f (BETA) ----------------------------------------------------------------------- ----------------------------------------------------------------------- Programmer : Ronnie Sanford Date : August 7, 1996 Description (Verbose) : Made several modifications to provide PCI and EISA support: 1. We now allocate the termios structures based on the maximum number of channels that COULD be available to the system. We no longer use the number of channels declared in epcaconfig.h (NBDEVS) as the total channel number. This is because this value does not represent channels available to potential PCI cards. This new larger value is also passed back to the os in the num field of tty_driver. 2. Added code to copy the previous board structure (Now called static_boards) into a new local copy of the boards structure. This has been done so that PCI cards may be added to this board array and later referenced (And even queried.). 3. Added code to pc_init that checks for supported PCI cards. If found this code initializes a new entry into the drivers local board structure with the PCI cards address, and type, etc.. It also bumps the card count (num_cards). 4. Modified code in post_fep_init so that when this routine is executed the number of ports supported by a particular PCI card will be determined and loaded into the board structure. It would be much better if this code was placed in pc_init (Because we could then report to the os the true number of ports available; not just the max), but since the card has to be booted to determine the number of ports it supports, we are forced to do it after DIGI_INIT has called post_fep_init. In the future we may attempt to read the num ports attached directly (address 0x1ac). 5. Added board types to epca.h in support of various PCI boards (Some of which do not exist yet). Added procedures for these boards throughout the code. Note, windowing is not necessary for PCI boards. 6. Added code supporting the EISA/XEM. This included modifying epca.h with the new board type and adding this type into the driver. The EISA/XEM is basically identical to the PC/XEM, other than it's base address does not have to be (And cannot be configured directly). 7. Modified digiConfig to prompt for EISA/XEM cards. Files affected : epca.c, epca.h, digi1.h, digiConfig Release version : 1.0.0g (BETA) ----------------------------------------------------------------------- ----------------------------------------------------------------------- Programmer : Ronnie Sanford Date : August 21, 1996 Description (Verbose) : Made the following modifications: 1. A problem affecting hard flow control was found in the termios2digi_h routine. Specifically, when the user activated hard flow control using the CRTSCTS specification, the values used to program hard flow control on the board were incorrect. The solution was to change a line that read "res |= ((ch->m_dtr) | (ch->m_rts));" to "res |= ((ch->m_cts) | (ch->m_rts));" This line only applies if cflag & CRTSCTS. Special thanks to Matt Robinson (matt@mania.com.au) who found and fixed this problem. 2. In previous betas the cud device was set to CLOCAL on driver boot up. Likewise the ttyD device was set to ~CLOCAL. This has been fixed in this driver. Now ttyD is CLOCAL and cud is ~CLOCAL. The fix for this can be found in pc_init. 3. In ditty.c many changes were made to eliminate bugs and warning messages. Two ioctl calls were eliminated as well a problem involving using the returned baud index to determine the drivers baud rate. Newer Linux kernels support higher baud rates by using 0x1000 bit. When the returned value (ored with 0x1000) was used to reference our fbaud table a serious memory problem occurred. This has been fixed. 4. Added a request_region call to post_fep_init. This should cause the i/o ports being used to be registered with proc. 5. Modified digiConfig to set all cud and ttyD devices to read/write all permission. 6. Developed a new apps called buildPCI that provides an easy way to build device nodes for PCI cards. 7. Modified user.doc and technotes.doc document the use of buildPCI. Files affected : epca.c, ditty.c, digiConfig, user.doc, technotes.doc Release version : 1.0.0 (Official release) ----------------------------------------------------------------------- Programmer : Ronnie Sanford Date : August 21, 1996 Description (Verbose) : Made the following modifications: 1. Removed code from pc_close which closes the drivers line discipline and restores its original line discipline. This is currently unnecessary, though future fast cook enhancements may require this. 2. Removed code in block_til_ready that set the asyncflags to either ASYNC_CALLOUT_ACTIVE, or ASYNC_NORMAL_ACTIVE. This code was redundant as it already existed in block_til_ready. 3. Added code in block_til_ready to cause a return prior to schedule being called if the device was a CALLOUT device. CALLOUT devices never block on CD. (This was a serious bug that prevented the CALLOUT devices (ttyD) from functioning properly in some instances. Make a change in the MODEMCHG_IND case of doevent such that it does not require ASYNC_CALLOUT_ACTIVE or ASYNC_NORMAL_ACTIVE to be set in order to unblock an open (Using wait_interruptible). Thanks to Mike McLagan (mike.mclagan@linux.org) for diagnosing and fixing this problem. 4. Made changes to the disposition of CLOCAL on both SERIAL NORMAL and CALLOUT devices. Both device types now have CLOCAL active at default. This may be changed with a stty command. 5. Made changes to digiConfig such that it checks major.h (If valid) for the correct major numbers to use. Files affected : epca.c, digiConfig Release version : 1.0.1a ----------------------------------------------------------------------- Programmer : Ronnie Sanford Date : September 17, 1996 Description (Verbose) : Made the following modifications: 1. Modified pc_open such that it no longer checks the cflag value returned by termios2digi_c for CLOCAL. Digi hardware does not use this value and thus termios2digi_c rightly screens this value out. This driver checks for CLOCAL using the drivers cflag value as known by the Linux OS. (The value passed into termios2digi_c) 2. Modified termios2digi_c to screen out the CBAUDEX in CBAUD. This error caused parity to automaticaly be enabled on at higher baud rates. 3. Added the "disable_bh()" call to the shutdown subroutine. Hopefully this will allow the driver to correctly clean up after itself when used as a module. 4. Added support for the PC/XI and 64K PC/XE cards. This involved primarily modifying digiDload to initialize and boot the new cards; however driver modifications were also required to provide the proper windowing for the newly supported cards. (Code was also added to determine the memory segment of the XI card as that card may have more than 64K. Currently digiDload assumes a 64K XI card.) 5. Added subroutine called epca_setup that can be called during LILO boot up. This provides the user an easy way to change cards; without running digiConfig and without recompiling the kernel. Added code in pc_init and pc_open to support the epca_setup routine. pc_init checks the liloconfig flag (Which is set by epca_setup) to determine if the driver is using the LILO arguments. If not pc_init loads the board data found in epcaconfig.h; if so it DOESN'T load epcaconfig data depending on epca_setup to handle board configuration. pc_open has been modified such that it checks to ensure that no errors occurred during the LILO boot process. If a user attempts to boot the driver (via. LILO) with incorrect data, the open will fail. 6. Modified the windowing routines pcxe_rxwinon and pcxe_txwinon routines. A bug existed such that those routines checked to see if the rxwin and txwin flags were reset. If so they assumed the board was an XI or 64K XE. Furthermore since these flags were never initialized in our driver sometimes they were 0 and therefore caused a memory fault (Or at least a window overrun). This code has been removed since the pcxe shares nothing in common with the 64K XI and XE. 7. Added code in pc_init to set the memory_seg for the various boards. This code was necessary to correct a bug in the PCXE, PCXEVE code where receive and transmit pointers were being calculated from an uninitialized variable (memory_seg). 8. Modified digiConfig to allow 64K PC/XI and 64K PC/XE cards to be configured. 9. Made changes to support the new 2.1.x development kernel. In particular this required changing all references to vremap to ioremap. 10. Modified digiConfig such that it now generates node names corresponding to their internal as opposed to the label on the port itself. Nodes (ttyD?? and cud??) now start at 0. Example: ttyD0 and cud0 represent port 1 on any supported Digi product. A similar change has been made in buildPCI.c. 12. At the early portion of post_fep_init if a PCI card is detected a warning message could be given incorrectly if 64 ports were attached to a PCI card. The below line : epcaassert(bd->numports > 64,"PCI returned a invalid number of ports"); was changed to : epcaassert(bd->numports <= 64,"PCI returned a invalid number of ports"); Remember that epcaassert checks for NOT true. Special thanks to Daniel Taylor for fixing this. 13. Modified the epcaparam routine. In version 100 and 101a there was a line that looked like the below: if (ch->omodem != mval) The problem with this line was that the first time through omodem was not initialized. Secondly, since many TIOC commands did not alter mval (They use a different variable) changes made by these commands could be lost. This line was changed to: mval ^= ch->modemfake & (mval ^ ch->modem); if (ch->omodem ^ mval) 14. Modified digiConfig in such a way that it checks the version number of the kernel and if it finds a 2.x.x kernel or higher it reads the necessary major numbers for cud and ttyD devices from major.h. This was also done in prior versions but these versions required a #define which identified the kernel as a version which did not have major numbers assigned to Digi systems. This #define is no longer required allowing the same source tree for multiple kernel releases. 15. Used macros to replace kernel specific calls such as put_fs_long, get_fs_long, put_user, and get_user the kernel version is now detected and the macro is defined as to correspond with the kernel it is being compiled into. Again this was done to allow one source tree for multiple kernel releases. 16. Added support for the new 2.1.x development kernels to digiInstall. Files affected : epca.c, digiConfig Release version : 1.1.0 ----------------------------------------------------------------------- Programmer : Daniel Taylor Date : April 25, 1997 Description (Verbose) : Updated driver: 1. Fixed DCD bug. (&tq scheduler) 2. Removed BH handler code, as it was only handling hangups, and not being called for that. 3. Namespace cleanup (DIGI_TIMER2 => DIGI_TIMER) 4. Updated to 2.1.36, removed #ifdefs for earlier kernel revisions. Files affected : epca.c Release version : 1.1.1 (BETA) ----------------------------------------------------------------------- Programmer : Daniel Taylor Date : March 11, 1999 Description (Verbose) : Updated driver: 1. Simultaneous data and modem change events were resulting in the modem change events not being recognized. Fixed. 2. Modified pc_info device name to work better with devfs. Files affected : epca.c Release version : 1.3.0-K ----------------------------------------------------------------------- Programmer : Jeff Garzik Date : February 26, 2000 Description (Verbose) : Updated driver: 1. Use new kernel PCI interfaces. 2. Updated list of includes. Files affected : epca.c Release version : 1.3.0.1-LK ----------------------------------------------------------------------- Programmer : Arjan van de Ven Date : March 10, 2000 Description (Verbose) : Fixed includes to make it actually compile for kernel 2.3.51 Files affected : epca.c Release version : 1.3.0.2-LK -----------------------------------------------------------------------