patch-2.1.37 linux/drivers/char/README.epca
Next file: linux/drivers/char/busmouse.c
Previous file: linux/drivers/char/Makefile
Back to the patch index
Back to the overall index
- Lines: 507
- Date:
Mon May 12 10:35:39 1997
- Orig file:
v2.1.36/linux/drivers/char/README.epca
- Orig date:
Wed Dec 31 16:00:00 1969
diff -u --recursive --new-file v2.1.36/linux/drivers/char/README.epca linux/drivers/char/README.epca
@@ -0,0 +1,506 @@
+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 seperated
+ 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 sucessfully loaded, execute the following:
+
+ buildPCI <arg1> <arg2>
+
+ 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 occured. 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 unecessary,
+ 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 insure that no errors
+ occured 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)
+-----------------------------------------------------------------------
FUNET's LINUX-ADM group, linux-adm@nic.funet.fi
TCL-scripts by Sam Shen, slshen@lbl.gov