2 Digi International driver package for the PC/Xe, PC/Xi, PC/Xr, PC/Xem as well
3 the EISA and PCI variants of these boards where applicable.
4 Copyright (C) 1996 Digi International. Written by Ronnie Sanford digilnux@dgii.com
6 This program is free software; you can redistribute it and/or modify it
7 under the terms of the GNU General Public License as published by the
8 Free Software Foundation; either version 2 of the License, or (At your
9 option) any later version.
11 This program is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
16 You should have received a copy of the GNU General Public License along
17 with this program; if not write to the Free Software Foundation, Inc.,
18 675 Mass Ave, Cambridge, MA 02139, USA.
21 This document describes the software used with the Digi/Linux driver package.
22 The four user programs listed below are described in this document:
24 1. digiConfig -> Application that configures the Digi driver.
26 2. digiDload -> Application which initializes the Digi hardware.
28 3. buildPCI -> Application which provides the user a method of
29 building device nodes for PCI devices.
31 4. ditty -> Application which provides the user a method of
32 configuring terminal options on Digi hardware.
36 --------------------------------------------------------------------------
37 1. Configuring driver/kernel for Digi products
38 --------------------------------------------------------------------------
40 The Digi driver must be configured each time Digi hardware is added
41 or removed. There are two supported methods of doing this. The
42 first method configures the driver dynamically at boot time but requires
43 the user to utilize the lilo loader. This method is the preffered method
44 as it does not require the rebuilding of the kernel. In order to use lilo
45 to configure Digi boards at boot time an appropriate append command should
46 be added to /etc/lilo.conf below the appropriate label decleration.
47 See footer 4. The append commands format is a string of comma separated
48 identifiers or integers used to configure supported boards. These six
51 Enable/Disable this card or Override,
52 Type of card: PC/Xe (AccelePort) (0), PC/Xeve (1), PC/Xem or PC/Xr (2),
53 EISA/Xem (3), PC/Xe (64K) (4), PC/Xi (5).
54 Enable/Disable alternate pin arrangement,
55 Number of ports on this card,
56 I/O Port where card is configured (in HEX if using string identifiers),
57 Base of memory window (in HEX if using string identifiers)
59 A sample append command is given below which if used would configure and
60 enable a PC/Xe with 8 ports, at i/o address 200, memory address 0xd0000
61 with alt pin turned off. The lilo.conf file should look like this:
66 append="digiepca=E,PC/Xe,D,8,200,D0000"
68 likewise the below will perform the same function:
73 append="digiepca=1,0,0,8,512,851968"
77 PCI boards are auto-detected and configured (Hence their codes are
78 not given here). Do not attempt to configure PCI boards with the lilo
81 If configuration data has been specified by using digiConfig (Described
82 below), and you wish to override this configuration using lilo without
83 specifying a specific card (Example if there are PCI cards in the system)
84 the following override command will accomplish this:
86 -> append="digiepca=2"
88 If lilo is not enabled, the second method of configuring Digi hardware
89 will have to be used. digiConfig is an application that can be used
90 to inform the system of any additions, deletions, or modifications
91 involving Digi hardware. To use this method the operator executes
92 digiConfig anytime an EISA or ISA card is added that he wishes to use.
93 This routine is also used to remove cards from the system, and to modify
94 parameters of those cards already present in the system. Upon being
95 executed digiConfig modifies files accessed by the Digi driver. To make
96 these changes permanent; the operating system must be recompiled. After
97 the operating system has been recompiled and booted, the changes made with
98 digiConfig will be introduced to the user. This program MUST be executed
99 every time Digi EISA/ISA hardware configuration changes. Note, it is not
100 necessary to execute digiConfig in order to configure the Digi PCI cards.
101 These cards are self-identifying and will be recognized by the driver.
102 They cannot be displayed using digiConfig nor will digiConfig build the
103 device nodes their device nodes. See footer 1.
105 To execute digiConfig; simply type: digiConfig
107 The application will query you for the type, memory address, port
108 address, number of ports, alt pin disposition and status of each board
109 that exist on the system. Note, currently this driver only supports
110 PC/Xe, PC/Xeve, PC/Xi, PC/Xr, and PC/Xem as well as their EISA and PCI
111 implementations if applicable. All supported cards (Other than PCI) that
112 are present should be registered via digiConfig. See footer 2.
114 After all cards have been configured select exit. The system will then
115 inform you if any changes have been made, and ask you if it is okay to
116 make these changes permanent. If the data entered is correct, select okay.
117 Selecting cancel will prevent the changes from becoming active. digiConfig
118 can then be re-executed to configure the system again.
120 --------------------------------------------------------------------------
121 2. Initializing Digi hardware with digiDload
122 --------------------------------------------------------------------------
124 digiDload is the application executed after the Digi driver has been
125 loaded. It is responsible for initializing the hardware and leaving
126 it in a state such that the Digi board may be operated by the user.
127 The application may be placed anywhere on the path, but its related
128 support files must be located in /etc/digi. The related files are:
135 The format for this command is "digiDload [v]". If given the "v"
136 option turns on verbosity. If not given the application runs in quite
137 mode. To execute the program simply type:
141 Upon completion digiDload will generate the below message:
143 "digiDload complete: Card initialized"
145 At this point the card is configured and ready for normal usage. See
146 technotes.doc for information on how how ports are determined and
149 --------------------------------------------------------------------------
150 3. Build PCI device nodes with buildPCI
151 --------------------------------------------------------------------------
153 buildPCI is an application useful for building the necessary device nodes
154 for Digi PCI cards. It is reccomended that this tool be used because the
155 current digiConfig application does not provide this function for PCI cards
156 (Though it does build device nodes for non-PCI cards). To use this program
157 execute the following:first install the driver, and execute digiDload (See above). After digiDload
158 has successfully loaded, execute the following:
160 buildPCI <arg1> <arg2>
162 Where arg1 is the number of ports connected to Digi cards that are not PCI
163 (As shown by the digiConfig utility), and arg2 is the number of ports
164 connected to Digi cards that are PCI.
166 Note, buildPCI only has to be ran once to build the necessary device
167 nodes. Though this program may be executed at anytime, we reccomend
168 delaying execution until the first time you install the package and after
169 digiDload has been executed.
171 --------------------------------------------------------------------------
172 4. Setting Terminal Options with ditty
173 --------------------------------------------------------------------------
175 ditty is a utility program that sets and displays the terminal options
176 for Digi intelligent serial products. See man ditty for detailed information.
181 1. The 1.2.x kernel does not provide a method of mapping the high
182 addresses (Normally higher than RAM) associated with PCI. For this
183 reason, this driver disables PCI support while running under the 1.2.x
186 2. PCI cards should not and cannot be registered with digiConfig. After
187 the driver has been loaded buildPCI may be executed to construct the
188 necessary device nodes. This step is not necessary for system not
189 having Digi PCI cards.
191 3. This is because we forsee a time when buildPCI may auto-detect the
192 available Digi PCI cards and this would only work if the program is
193 executed after digiDload.
195 4. A complete example is given in install.doc.
197 -------------CHANGES--------------------
199 All changes should be recorded here. All changes should be explained in
201 -----------------------------------------------------------------------
202 Programmer : Ronnie Sanford
204 Description (Verbose) : Initial release of driver package.
206 Release version : 1.0.0f (BETA)
207 -----------------------------------------------------------------------
208 -----------------------------------------------------------------------
209 Programmer : Ronnie Sanford
210 Date : August 7, 1996
211 Description (Verbose) : Made several modifications to provide PCI and EISA
214 1. We now allocate the termios structures based on
215 the maximum number of channels that COULD be
216 available to the system. We no longer use the
217 number of channels declared in epcaconfig.h
218 (NBDEVS) as the total channel number. This is
219 because this value does not represent channels
220 available to potential PCI cards. This new
221 larger value is also passed back to the os in
222 the num field of tty_driver.
224 2. Added code to copy the previous board structure
225 (Now called static_boards) into a new local
226 copy of the boards structure. This has been
227 done so that PCI cards may be added to this
228 board array and later referenced (And even
231 3. Added code to pc_init that checks for supported
232 PCI cards. If found this code initializes a new
233 entry into the drivers local board structure
234 with the PCI cards address, and type, etc.. It
235 also bumps the card count (num_cards).
237 4. Modified code in post_fep_init so that when this
238 routine is executed the number of ports supported
239 by a particular PCI card will be determined and
240 loaded into the board structure. It would be
241 much better if this code was placed in pc_init
242 (Because we could then report to the os the true
243 number of ports available; not just the max), but
244 since the card has to be booted to determine the
245 number of ports it supports, we are forced to do it
246 after DIGI_INIT has called post_fep_init. In the
247 future we may attempt to read the num ports
248 attached directly (address 0x1ac).
250 5. Added board types to epca.h in support of various
251 PCI boards (Some of which do not exist yet).
252 Added procedures for these boards throughout the
253 code. Note, windowing is not necessary for PCI
256 6. Added code supporting the EISA/XEM. This included
257 modifying epca.h with the new board type and
258 adding this type into the driver. The EISA/XEM
259 is basically identical to the PC/XEM, other than
260 it's base address does not have to be (And cannot
261 be configured directly).
263 7. Modified digiConfig to prompt for EISA/XEM cards.
265 Files affected : epca.c, epca.h, digi1.h, digiConfig
266 Release version : 1.0.0g (BETA)
267 -----------------------------------------------------------------------
268 -----------------------------------------------------------------------
269 Programmer : Ronnie Sanford
270 Date : August 21, 1996
271 Description (Verbose) : Made the following modifications:
273 1. A problem affecting hard flow control was found
274 in the termios2digi_h routine. Specifically,
275 when the user activated hard flow control using
276 the CRTSCTS specification, the values used to
277 program hard flow control on the board were
278 incorrect. The solution was to change a line
279 that read "res |= ((ch->m_dtr) | (ch->m_rts));"
280 to "res |= ((ch->m_cts) | (ch->m_rts));" This
281 line only applies if cflag & CRTSCTS. Special
282 thanks to Matt Robinson (matt@mania.com.au) who
283 found and fixed this problem.
285 2. In previous betas the cud device was set to CLOCAL
286 on driver boot up. Likewise the ttyD device was
287 set to ~CLOCAL. This has been fixed in this driver.
288 Now ttyD is CLOCAL and cud is ~CLOCAL. The fix
289 for this can be found in pc_init.
291 3. In ditty.c many changes were made to eliminate bugs
292 and warning messages. Two ioctl calls were eliminated
293 as well a problem involving using the returned baud
294 index to determine the drivers baud rate. Newer
295 Linux kernels support higher baud rates by using
296 0x1000 bit. When the returned value (ored with
297 0x1000) was used to reference our fbaud table a
298 serious memory problem occurred. This has been fixed.
300 4. Added a request_region call to post_fep_init. This
301 should cause the i/o ports being used to be
302 registered with proc.
304 5. Modified digiConfig to set all cud and ttyD devices
305 to read/write all permission.
307 6. Developed a new apps called buildPCI that provides
308 an easy way to build device nodes for PCI cards.
310 7. Modified user.doc and technotes.doc document the
313 Files affected : epca.c, ditty.c, digiConfig, user.doc, technotes.doc
314 Release version : 1.0.0 (Official release)
315 -----------------------------------------------------------------------
316 Programmer : Ronnie Sanford
317 Date : August 21, 1996
318 Description (Verbose) : Made the following modifications:
320 1. Removed code from pc_close which closes the
321 drivers line discipline and restores its original
322 line discipline. This is currently unnecessary,
323 though future fast cook enhancements may require
326 2. Removed code in block_til_ready that set the
327 asyncflags to either ASYNC_CALLOUT_ACTIVE, or
328 ASYNC_NORMAL_ACTIVE. This code was redundant
329 as it already existed in block_til_ready.
331 3. Added code in block_til_ready to cause a return
332 prior to schedule being called if the device
333 was a CALLOUT device. CALLOUT devices never
334 block on CD. (This was a serious bug that
335 prevented the CALLOUT devices (ttyD) from
336 functioning properly in some instances.
338 Make a change in the MODEMCHG_IND case of doevent
339 such that it does not require ASYNC_CALLOUT_ACTIVE
340 or ASYNC_NORMAL_ACTIVE to be set in order to
341 unblock an open (Using wait_interruptible).
343 Thanks to Mike McLagan (mike.mclagan@linux.org)
344 for diagnosing and fixing this problem.
346 4. Made changes to the disposition of CLOCAL on
347 both SERIAL NORMAL and CALLOUT devices. Both
348 device types now have CLOCAL active at default.
349 This may be changed with a stty command.
351 5. Made changes to digiConfig such that it checks
352 major.h (If valid) for the correct major
355 Files affected : epca.c, digiConfig
356 Release version : 1.0.1a
359 -----------------------------------------------------------------------
360 Programmer : Ronnie Sanford
361 Date : September 17, 1996
362 Description (Verbose) : Made the following modifications:
364 1. Modified pc_open such that it no longer checks
365 the cflag value returned by termios2digi_c for
366 CLOCAL. Digi hardware does not use this value
367 and thus termios2digi_c rightly screens this
368 value out. This driver checks for CLOCAL using
369 the drivers cflag value as known by the Linux OS.
370 (The value passed into termios2digi_c)
372 2. Modified termios2digi_c to screen out the
373 CBAUDEX in CBAUD. This error caused parity to
374 automaticaly be enabled on at higher baud rates.
377 3. Added the "disable_bh()" call to the shutdown
378 subroutine. Hopefully this will allow the driver
379 to correctly clean up after itself when used as a
382 4. Added support for the PC/XI and 64K PC/XE cards.
383 This involved primarily modifying digiDload to
384 initialize and boot the new cards; however
385 driver modifications were also required to
386 provide the proper windowing for the newly
387 supported cards. (Code was also added to
388 determine the memory segment of the XI card as
389 that card may have more than 64K. Currently
390 digiDload assumes a 64K XI card.)
392 5. Added subroutine called epca_setup that can be
393 called during LILO boot up. This provides the
394 user an easy way to change cards; without
395 running digiConfig and without recompiling the
396 kernel. Added code in pc_init and pc_open to
397 support the epca_setup routine. pc_init checks
398 the liloconfig flag (Which is set by epca_setup)
399 to determine if the driver is using the LILO
400 arguments. If not pc_init loads the board data
401 found in epcaconfig.h; if so it DOESN'T load
402 epcaconfig data depending on epca_setup to handle
403 board configuration. pc_open has been modified
404 such that it checks to ensure that no errors
405 occurred during the LILO boot process. If a
406 user attempts to boot the driver (via. LILO)
407 with incorrect data, the open will fail.
409 6. Modified the windowing routines pcxe_rxwinon
410 and pcxe_txwinon routines. A bug existed such
411 that those routines checked to see if the rxwin
412 and txwin flags were reset. If so they assumed
413 the board was an XI or 64K XE. Furthermore since
414 these flags were never initialized in our driver
415 sometimes they were 0 and therefore caused a
416 memory fault (Or at least a window overrun). This
417 code has been removed since the pcxe shares
418 nothing in common with the 64K XI and XE.
420 7. Added code in pc_init to set the memory_seg for
421 the various boards. This code was necessary to
422 correct a bug in the PCXE, PCXEVE code where
423 receive and transmit pointers were being calculated
424 from an uninitialized variable (memory_seg).
426 8. Modified digiConfig to allow 64K PC/XI and 64K
427 PC/XE cards to be configured.
429 9. Made changes to support the new 2.1.x development
430 kernel. In particular this required changing all
431 references to vremap to ioremap.
433 10. Modified digiConfig such that it now generates
434 node names corresponding to their internal
435 as opposed to the label on the port itself. Nodes
436 (ttyD?? and cud??) now start at 0. Example:
437 ttyD0 and cud0 represent port 1 on any supported
438 Digi product. A similar change has been made
441 12. At the early portion of post_fep_init if a PCI
442 card is detected a warning message could be given
443 incorrectly if 64 ports were attached to a PCI
444 card. The below line :
446 epcaassert(bd->numports > 64,"PCI returned a invalid number of ports");
450 epcaassert(bd->numports <= 64,"PCI returned a invalid number of ports");
452 Remember that epcaassert checks for NOT true.
453 Special thanks to Daniel Taylor for fixing this.
455 13. Modified the epcaparam routine. In version 100
456 and 101a there was a line that looked like the
459 if (ch->omodem != mval)
461 The problem with this line was that the first time
462 through omodem was not initialized. Secondly, since
463 many TIOC commands did not alter mval (They use
464 a different variable) changes made by these commands
465 could be lost. This line was changed to:
467 mval ^= ch->modemfake & (mval ^ ch->modem);
469 if (ch->omodem ^ mval)
471 14. Modified digiConfig in such a way that it checks
472 the version number of the kernel and if it finds
473 a 2.x.x kernel or higher it reads the necessary
474 major numbers for cud and ttyD devices from major.h.
475 This was also done in prior versions but these
476 versions required a #define which identified the
477 kernel as a version which did not have major numbers
478 assigned to Digi systems. This #define is no
479 longer required allowing the same source tree for
480 multiple kernel releases.
482 15. Used macros to replace kernel specific calls such
483 as put_fs_long, get_fs_long, put_user, and get_user
484 the kernel version is now detected and the macro
485 is defined as to correspond with the kernel it
486 is being compiled into. Again this was done to
487 allow one source tree for multiple kernel releases.
489 16. Added support for the new 2.1.x development kernels
492 Files affected : epca.c, digiConfig
493 Release version : 1.1.0
494 -----------------------------------------------------------------------
495 Programmer : Daniel Taylor
496 Date : April 25, 1997
497 Description (Verbose) : Updated driver:
498 1. Fixed DCD bug. (&tq scheduler)
499 2. Removed BH handler code, as it was only handling
500 hangups, and not being called for that.
501 3. Namespace cleanup (DIGI_TIMER2 => DIGI_TIMER)
502 4. Updated to 2.1.36, removed #ifdefs for earlier
504 Files affected : epca.c
505 Release version : 1.1.1 (BETA)
506 -----------------------------------------------------------------------
507 Programmer : Daniel Taylor
508 Date : March 11, 1999
509 Description (Verbose) : Updated driver:
510 1. Simultaneous data and modem change events were
511 resulting in the modem change events not being
513 2. Modified pc_info device name to work better
515 Files affected : epca.c
516 Release version : 1.3.0-K
517 -----------------------------------------------------------------------
518 Programmer : Jeff Garzik
519 Date : February 26, 2000
520 Description (Verbose) : Updated driver:
521 1. Use new kernel PCI interfaces.
522 2. Updated list of includes.
523 Files affected : epca.c
524 Release version : 1.3.0.1-LK
525 -----------------------------------------------------------------------
526 Programmer : Arjan van de Ven <adve@oce.nl>
527 Date : March 10, 2000
528 Description (Verbose) : Fixed includes to make it actually compile
530 Files affected : epca.c
531 Release version : 1.3.0.2-LK
532 -----------------------------------------------------------------------