1user.doc 2Digi International driver package for the PC/Xe, PC/Xi, PC/Xr, PC/Xem as well 3the EISA and PCI variants of these boards where applicable. 4Copyright (C) 1996 Digi International. Written by Ronnie Sanford digilnux@dgii.com 5 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. 10 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 14 for more details. 15 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. 19 20 21This document describes the software used with the Digi/Linux driver package. 22The four user programs listed below are described in this document: 23 24 1. digiConfig -> Application that configures the Digi driver. 25 26 2. digiDload -> Application which initializes the Digi hardware. 27 28 3. buildPCI -> Application which provides the user a method of 29 building device nodes for PCI devices. 30 31 4. ditty -> Application which provides the user a method of 32 configuring terminal options on Digi hardware. 33 34 35 36-------------------------------------------------------------------------- 371. Configuring driver/kernel for Digi products 38-------------------------------------------------------------------------- 39 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 49 values in order are: 50 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) 58 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: 62 63 image = /vmlinuz 64 root = /dev/hda2 65 label = vmlinuz 66 append="digiepca=E,PC/Xe,D,8,200,D0000" 67 68 likewise the below will perform the same function: 69 70 image = /vmlinuz 71 root = /dev/hda2 72 label = vmlinuz 73 append="digiepca=1,0,0,8,512,851968" 74 75 Note: 76 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 79 append command. 80 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: 85 86 -> append="digiepca=2" 87 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. 104 105 To execute digiConfig; simply type: digiConfig 106 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. 113 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. 119 120-------------------------------------------------------------------------- 1212. Initializing Digi hardware with digiDload 122-------------------------------------------------------------------------- 123 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: 129 130 sxfep.bin 131 sxbios.bin 132 xxfep.bin 133 xxbios.bin 134 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: 138 139 digiDload 140 141 Upon completion digiDload will generate the below message: 142 143 "digiDload complete: Card initialized" 144 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 147 assigned. 148 149-------------------------------------------------------------------------- 1503. Build PCI device nodes with buildPCI 151-------------------------------------------------------------------------- 152 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: 159 160 buildPCI <arg1> <arg2> 161 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. 165 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. 170 171-------------------------------------------------------------------------- 1724. Setting Terminal Options with ditty 173-------------------------------------------------------------------------- 174 175ditty is a utility program that sets and displays the terminal options 176for Digi intelligent serial products. See man ditty for detailed information. 177 178 179Footnotes: 180 1811. 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 184 kernels. 185 1862. 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. 190 1913. 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. 194 1954. A complete example is given in install.doc. 196 197-------------CHANGES-------------------- 198 199All changes should be recorded here. All changes should be explained in 200verbose detail. 201----------------------------------------------------------------------- 202Programmer : Ronnie Sanford 203Date : June 1, 1996 204Description (Verbose) : Initial release of driver package. 205Files affected : all 206Release version : 1.0.0f (BETA) 207----------------------------------------------------------------------- 208----------------------------------------------------------------------- 209Programmer : Ronnie Sanford 210Date : August 7, 1996 211Description (Verbose) : Made several modifications to provide PCI and EISA 212 support: 213 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. 223 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 229 queried.). 230 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). 236 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). 249 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 254 boards. 255 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). 262 263 7. Modified digiConfig to prompt for EISA/XEM cards. 264 265Files affected : epca.c, epca.h, digi1.h, digiConfig 266Release version : 1.0.0g (BETA) 267----------------------------------------------------------------------- 268----------------------------------------------------------------------- 269Programmer : Ronnie Sanford 270Date : August 21, 1996 271Description (Verbose) : Made the following modifications: 272 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. 284 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. 290 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. 299 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. 303 304 5. Modified digiConfig to set all cud and ttyD devices 305 to read/write all permission. 306 307 6. Developed a new apps called buildPCI that provides 308 an easy way to build device nodes for PCI cards. 309 310 7. Modified user.doc and technotes.doc document the 311 use of buildPCI. 312 313Files affected : epca.c, ditty.c, digiConfig, user.doc, technotes.doc 314Release version : 1.0.0 (Official release) 315----------------------------------------------------------------------- 316Programmer : Ronnie Sanford 317Date : August 21, 1996 318Description (Verbose) : Made the following modifications: 319 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 324 this. 325 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. 330 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. 337 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). 342 343 Thanks to Mike McLagan (mike.mclagan@linux.org) 344 for diagnosing and fixing this problem. 345 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. 350 351 5. Made changes to digiConfig such that it checks 352 major.h (If valid) for the correct major 353 numbers to use. 354 355Files affected : epca.c, digiConfig 356Release version : 1.0.1a 357 358 359----------------------------------------------------------------------- 360Programmer : Ronnie Sanford 361Date : September 17, 1996 362Description (Verbose) : Made the following modifications: 363 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) 371 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. 375 376 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 380 module. 381 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.) 391 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. 408 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. 419 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). 425 426 8. Modified digiConfig to allow 64K PC/XI and 64K 427 PC/XE cards to be configured. 428 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. 432 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 439 in buildPCI.c. 440 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 : 445 446 epcaassert(bd->numports > 64,"PCI returned a invalid number of ports"); 447 448 was changed to : 449 450 epcaassert(bd->numports <= 64,"PCI returned a invalid number of ports"); 451 452 Remember that epcaassert checks for NOT true. 453 Special thanks to Daniel Taylor for fixing this. 454 455 13. Modified the epcaparam routine. In version 100 456 and 101a there was a line that looked like the 457 below: 458 459 if (ch->omodem != mval) 460 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: 466 467 mval ^= ch->modemfake & (mval ^ ch->modem); 468 469 if (ch->omodem ^ mval) 470 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. 481 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. 488 489 16. Added support for the new 2.1.x development kernels 490 to digiInstall. 491 492Files affected : epca.c, digiConfig 493Release version : 1.1.0 494----------------------------------------------------------------------- 495Programmer : Daniel Taylor 496Date : April 25, 1997 497Description (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 503 kernel revisions. 504Files affected : epca.c 505Release version : 1.1.1 (BETA) 506----------------------------------------------------------------------- 507Programmer : Daniel Taylor 508Date : March 11, 1999 509Description (Verbose) : Updated driver: 510 1. Simultaneous data and modem change events were 511 resulting in the modem change events not being 512 recognized. Fixed. 513 2. Modified pc_info device name to work better 514 with devfs. 515Files affected : epca.c 516Release version : 1.3.0-K 517----------------------------------------------------------------------- 518Programmer : Jeff Garzik 519Date : February 26, 2000 520Description (Verbose) : Updated driver: 521 1. Use new kernel PCI interfaces. 522 2. Updated list of includes. 523Files affected : epca.c 524Release version : 1.3.0.1-LK 525----------------------------------------------------------------------- 526Programmer : Arjan van de Ven <adve@oce.nl> 527Date : March 10, 2000 528Description (Verbose) : Fixed includes to make it actually compile 529 for kernel 2.3.51 530Files affected : epca.c 531Release version : 1.3.0.2-LK 532----------------------------------------------------------------------- 533