1 .. SPDX-License-Identifier: GPL-2.0 2 3 ================================================ 4 Cirrus Logic LAN CS8900/CS8920 Ethernet Adapters 5 ================================================ 6 7 .. note:: 8 9 This document was contributed by Cirrus Logic for kernel 2.2.5. This version 10 has been updated for 2.3.48 by Andrew Morton. 11 12 Still, this is too outdated! A major cleanup is needed here. 13 14 Cirrus make a copy of this driver available at their website, as 15 described below. In general, you should use the driver version which 16 comes with your Linux distribution. 17 18 19 Linux Network Interface Driver ver. 2.00 <kernel 2.3.48> 20 21 22 .. TABLE OF CONTENTS 23 24 1.0 CIRRUS LOGIC LAN CS8900/CS8920 ETHERNET ADAPTERS 25 1.1 Product Overview 26 1.2 Driver Description 27 1.2.1 Driver Name 28 1.2.2 File in the Driver Package 29 1.3 System Requirements 30 1.4 Licensing Information 31 32 2.0 ADAPTER INSTALLATION and CONFIGURATION 33 2.1 CS8900-based Adapter Configuration 34 2.2 CS8920-based Adapter Configuration 35 36 3.0 LOADING THE DRIVER AS A MODULE 37 38 4.0 COMPILING THE DRIVER 39 4.1 Compiling the Driver as a Loadable Module 40 4.2 Compiling the driver to support memory mode 41 4.3 Compiling the driver to support Rx DMA 42 43 5.0 TESTING AND TROUBLESHOOTING 44 5.1 Known Defects and Limitations 45 5.2 Testing the Adapter 46 5.2.1 Diagnostic Self-Test 47 5.2.2 Diagnostic Network Test 48 5.3 Using the Adapter's LEDs 49 5.4 Resolving I/O Conflicts 50 51 6.0 TECHNICAL SUPPORT 52 6.1 Contacting Cirrus Logic's Technical Support 53 6.2 Information Required Before Contacting Technical Support 54 6.3 Obtaining the Latest Driver Version 55 6.4 Current maintainer 56 6.5 Kernel boot parameters 57 58 59 1. Cirrus Logic LAN CS8900/CS8920 Ethernet Adapters 60 =================================================== 61 62 63 1.1. Product Overview 64 ===================== 65 66 The CS8900-based ISA Ethernet Adapters from Cirrus Logic follow 67 IEEE 802.3 standards and support half or full-duplex operation in ISA bus 68 computers on 10 Mbps Ethernet networks. The adapters are designed for operation 69 in 16-bit ISA or EISA bus expansion slots and are available in 70 10BaseT-only or 3-media configurations (10BaseT, 10Base2, and AUI for 10Base-5 71 or fiber networks). 72 73 CS8920-based adapters are similar to the CS8900-based adapter with additional 74 features for Plug and Play (PnP) support and Wakeup Frame recognition. As 75 such, the configuration procedures differ somewhat between the two types of 76 adapters. Refer to the "Adapter Configuration" section for details on 77 configuring both types of adapters. 78 79 80 1.2. Driver Description 81 ======================= 82 83 The CS8900/CS8920 Ethernet Adapter driver for Linux supports the Linux 84 v2.3.48 or greater kernel. It can be compiled directly into the kernel 85 or loaded at run-time as a device driver module. 86 87 1.2.1 Driver Name: cs89x0 88 89 1.2.2 Files in the Driver Archive: 90 91 The files in the driver at Cirrus' website include: 92 93 =================== ==================================================== 94 readme.txt this file 95 build batch file to compile cs89x0.c. 96 cs89x0.c driver C code 97 cs89x0.h driver header file 98 cs89x0.o pre-compiled module (for v2.2.5 kernel) 99 config/Config.in sample file to include cs89x0 driver in the kernel. 100 config/Makefile sample file to include cs89x0 driver in the kernel. 101 config/Space.c sample file to include cs89x0 driver in the kernel. 102 =================== ==================================================== 103 104 105 106 1.3. System Requirements 107 ------------------------ 108 109 The following hardware is required: 110 111 * Cirrus Logic LAN (CS8900/20-based) Ethernet ISA Adapter 112 113 * IBM or IBM-compatible PC with: 114 * An 80386 or higher processor 115 * 16 bytes of contiguous IO space available between 210h - 370h 116 * One available IRQ (5,10,11,or 12 for the CS8900, 3-7,9-15 for CS8920). 117 118 * Appropriate cable (and connector for AUI, 10BASE-2) for your network 119 topology. 120 121 The following software is required: 122 123 * LINUX kernel version 2.3.48 or higher 124 125 * CS8900/20 Setup Utility (DOS-based) 126 127 * LINUX kernel sources for your kernel (if compiling into kernel) 128 129 * GNU Toolkit (gcc and make) v2.6 or above (if compiling into kernel 130 or a module) 131 132 133 134 1.4. Licensing Information 135 -------------------------- 136 137 This program is free software; you can redistribute it and/or modify it under 138 the terms of the GNU General Public License as published by the Free Software 139 Foundation, version 1. 140 141 This program is distributed in the hope that it will be useful, but WITHOUT 142 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 143 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for 144 more details. 145 146 For a full copy of the GNU General Public License, write to the Free Software 147 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 148 149 150 151 2. Adapter Installation and Configuration 152 ========================================= 153 154 Both the CS8900 and CS8920-based adapters can be configured using parameters 155 stored in an on-board EEPROM. You must use the DOS-based CS8900/20 Setup 156 Utility if you want to change the adapter's configuration in EEPROM. 157 158 When loading the driver as a module, you can specify many of the adapter's 159 configuration parameters on the command-line to override the EEPROM's settings 160 or for interface configuration when an EEPROM is not used. (CS8920-based 161 adapters must use an EEPROM.) See Section 3.0 LOADING THE DRIVER AS A MODULE. 162 163 Since the CS8900/20 Setup Utility is a DOS-based application, you must install 164 and configure the adapter in a DOS-based system using the CS8900/20 Setup 165 Utility before installation in the target LINUX system. (Not required if 166 installing a CS8900-based adapter and the default configuration is acceptable.) 167 168 169 2.1. CS8900-based Adapter Configuration 170 --------------------------------------- 171 172 CS8900-based adapters shipped from Cirrus Logic have been configured 173 with the following "default" settings:: 174 175 Operation Mode: Memory Mode 176 IRQ: 10 177 Base I/O Address: 300 178 Memory Base Address: D0000 179 Optimization: DOS Client 180 Transmission Mode: Half-duplex 181 BootProm: None 182 Media Type: Autodetect (3-media cards) or 183 10BASE-T (10BASE-T only adapter) 184 185 You should only change the default configuration settings if conflicts with 186 another adapter exists. To change the adapter's configuration, run the 187 CS8900/20 Setup Utility. 188 189 190 2.2. CS8920-based Adapter Configuration 191 --------------------------------------- 192 193 CS8920-based adapters are shipped from Cirrus Logic configured as Plug 194 and Play (PnP) enabled. However, since the cs89x0 driver does NOT 195 support PnP, you must install the CS8920 adapter in a DOS-based PC and 196 run the CS8900/20 Setup Utility to disable PnP and configure the 197 adapter before installation in the target Linux system. Failure to do 198 this will leave the adapter inactive and the driver will be unable to 199 communicate with the adapter. 200 201 :: 202 203 **************************************************************** 204 * CS8920-BASED ADAPTERS: * 205 * * 206 * CS8920-BASED ADAPTERS ARE PLUG and PLAY ENABLED BY DEFAULT. * 207 * THE CS89X0 DRIVER DOES NOT SUPPORT PnP. THEREFORE, YOU MUST * 208 * RUN THE CS8900/20 SETUP UTILITY TO DISABLE PnP SUPPORT AND * 209 * TO ACTIVATE THE ADAPTER. * 210 **************************************************************** 211 212 213 214 215 3. Loading the Driver as a Module 216 ================================= 217 218 If the driver is compiled as a loadable module, you can load the driver module 219 with the 'modprobe' command. Many of the adapter's configuration parameters can 220 be specified as command-line arguments to the load command. This facility 221 provides a means to override the EEPROM's settings or for interface 222 configuration when an EEPROM is not used. 223 224 Example:: 225 226 insmod cs89x0.o io=0x200 irq=0xA media=aui 227 228 This example loads the module and configures the adapter to use an IO port base 229 address of 200h, interrupt 10, and use the AUI media connection. The following 230 configuration options are available on the command line:: 231 232 io=### - specify IO address (200h-360h) 233 irq=## - specify interrupt level 234 use_dma=1 - Enable DMA 235 dma=# - specify dma channel (Driver is compiled to support 236 Rx DMA only) 237 dmasize=# (16 or 64) - DMA size 16K or 64K. Default value is set to 16. 238 media=rj45 - specify media type 239 or media=bnc 240 or media=aui 241 or media=auto 242 duplex=full - specify forced half/full/autonegotiate duplex 243 or duplex=half 244 or duplex=auto 245 debug=# - debug level (only available if the driver was compiled 246 for debugging) 247 248 **Notes:** 249 250 a) If an EEPROM is present, any specified command-line parameter 251 will override the corresponding configuration value stored in 252 EEPROM. 253 254 b) The "io" parameter must be specified on the command-line. 255 256 c) The driver's hardware probe routine is designed to avoid 257 writing to I/O space until it knows that there is a cs89x0 258 card at the written addresses. This could cause problems 259 with device probing. To avoid this behaviour, add one 260 to the ``io=`` module parameter. This doesn't actually change 261 the I/O address, but it is a flag to tell the driver 262 to partially initialise the hardware before trying to 263 identify the card. This could be dangerous if you are 264 not sure that there is a cs89x0 card at the provided address. 265 266 For example, to scan for an adapter located at IO base 0x300, 267 specify an IO address of 0x301. 268 269 d) The "duplex=auto" parameter is only supported for the CS8920. 270 271 e) The minimum command-line configuration required if an EEPROM is 272 not present is: 273 274 io 275 irq 276 media type (no autodetect) 277 278 f) The following additional parameters are CS89XX defaults (values 279 used with no EEPROM or command-line argument). 280 281 * DMA Burst = enabled 282 * IOCHRDY Enabled = enabled 283 * UseSA = enabled 284 * CS8900 defaults to half-duplex if not specified on command-line 285 * CS8920 defaults to autoneg if not specified on command-line 286 * Use reset defaults for other config parameters 287 * dma_mode = 0 288 289 g) You can use ifconfig to set the adapter's Ethernet address. 290 291 h) Many Linux distributions use the 'modprobe' command to load 292 modules. This program uses the '/etc/conf.modules' file to 293 determine configuration information which is passed to a driver 294 module when it is loaded. All the configuration options which are 295 described above may be placed within /etc/conf.modules. 296 297 For example:: 298 299 > cat /etc/conf.modules 300 ... 301 alias eth0 cs89x0 302 options cs89x0 io=0x0200 dma=5 use_dma=1 303 ... 304 305 In this example we are telling the module system that the 306 ethernet driver for this machine should use the cs89x0 driver. We 307 are asking 'modprobe' to pass the 'io', 'dma' and 'use_dma' 308 arguments to the driver when it is loaded. 309 310 i) Cirrus recommend that the cs89x0 use the ISA DMA channels 5, 6 or 311 7. You will probably find that other DMA channels will not work. 312 313 j) The cs89x0 supports DMA for receiving only. DMA mode is 314 significantly more efficient. Flooding a 400 MHz Celeron machine 315 with large ping packets consumes 82% of its CPU capacity in non-DMA 316 mode. With DMA this is reduced to 45%. 317 318 k) If your Linux kernel was compiled with inbuilt plug-and-play 319 support you will be able to find information about the cs89x0 card 320 with the command:: 321 322 cat /proc/isapnp 323 324 l) If during DMA operation you find erratic behavior or network data 325 corruption you should use your PC's BIOS to slow the EISA bus clock. 326 327 m) If the cs89x0 driver is compiled directly into the kernel 328 (non-modular) then its I/O address is automatically determined by 329 ISA bus probing. The IRQ number, media options, etc are determined 330 from the card's EEPROM. 331 332 n) If the cs89x0 driver is compiled directly into the kernel, DMA 333 mode may be selected by providing the kernel with a boot option 334 'cs89x0_dma=N' where 'N' is the desired DMA channel number (5, 6 or 7). 335 336 Kernel boot options may be provided on the LILO command line:: 337 338 LILO boot: linux cs89x0_dma=5 339 340 or they may be placed in /etc/lilo.conf:: 341 342 image=/boot/bzImage-2.3.48 343 append="cs89x0_dma=5" 344 label=linux 345 root=/dev/hda5 346 read-only 347 348 The DMA Rx buffer size is hardwired to 16 kbytes in this mode. 349 (64k mode is not available). 350 351 352 4. Compiling the Driver 353 ======================= 354 355 The cs89x0 driver can be compiled directly into the kernel or compiled into 356 a loadable device driver module. 357 358 Just use the standard way to configure the driver and compile the Kernel. 359 360 361 4.1. Compiling the Driver to Support Rx DMA 362 ------------------------------------------- 363 364 The compile-time optionality for DMA was removed in the 2.3 kernel 365 series. DMA support is now unconditionally part of the driver. It is 366 enabled by the 'use_dma=1' module option. 367 368 369 5. Testing and Troubleshooting 370 ============================== 371 372 5.1. Known Defects and Limitations 373 ---------------------------------- 374 375 Refer to the RELEASE.TXT file distributed as part of this archive for a list of 376 known defects, driver limitations, and work arounds. 377 378 379 5.2. Testing the Adapter 380 ------------------------ 381 382 Once the adapter has been installed and configured, the diagnostic option of 383 the CS8900/20 Setup Utility can be used to test the functionality of the 384 adapter and its network connection. Use the diagnostics 'Self Test' option to 385 test the functionality of the adapter with the hardware configuration you have 386 assigned. You can use the diagnostics 'Network Test' to test the ability of the 387 adapter to communicate across the Ethernet with another PC equipped with a 388 CS8900/20-based adapter card (it must also be running the CS8900/20 Setup 389 Utility). 390 391 .. note:: 392 393 The Setup Utility's diagnostics are designed to run in a 394 DOS-only operating system environment. DO NOT run the diagnostics 395 from a DOS or command prompt session under Windows 95, Windows NT, 396 OS/2, or other operating system. 397 398 To run the diagnostics tests on the CS8900/20 adapter: 399 400 1. Boot DOS on the PC and start the CS8900/20 Setup Utility. 401 402 2. The adapter's current configuration is displayed. Hit the ENTER key to 403 get to the main menu. 404 405 4. Select 'Diagnostics' (ALT-G) from the main menu. 406 * Select 'Self-Test' to test the adapter's basic functionality. 407 * Select 'Network Test' to test the network connection and cabling. 408 409 410 5.2.1. Diagnostic Self-test 411 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 412 413 The diagnostic self-test checks the adapter's basic functionality as well as 414 its ability to communicate across the ISA bus based on the system resources 415 assigned during hardware configuration. The following tests are performed: 416 417 * IO Register Read/Write Test 418 419 The IO Register Read/Write test insures that the CS8900/20 can be 420 accessed in IO mode, and that the IO base address is correct. 421 422 * Shared Memory Test 423 424 The Shared Memory test insures the CS8900/20 can be accessed in memory 425 mode and that the range of memory addresses assigned does not conflict 426 with other devices in the system. 427 428 * Interrupt Test 429 430 The Interrupt test insures there are no conflicts with the assigned IRQ 431 signal. 432 433 * EEPROM Test 434 435 The EEPROM test insures the EEPROM can be read. 436 437 * Chip RAM Test 438 439 The Chip RAM test insures the 4K of memory internal to the CS8900/20 is 440 working properly. 441 442 * Internal Loop-back Test 443 444 The Internal Loop Back test insures the adapter's transmitter and 445 receiver are operating properly. If this test fails, make sure the 446 adapter's cable is connected to the network (check for LED activity for 447 example). 448 449 * Boot PROM Test 450 451 The Boot PROM test insures the Boot PROM is present, and can be read. 452 Failure indicates the Boot PROM was not successfully read due to a 453 hardware problem or due to a conflicts on the Boot PROM address 454 assignment. (Test only applies if the adapter is configured to use the 455 Boot PROM option.) 456 457 Failure of a test item indicates a possible system resource conflict with 458 another device on the ISA bus. In this case, you should use the Manual Setup 459 option to reconfigure the adapter by selecting a different value for the system 460 resource that failed. 461 462 463 5.2.2. Diagnostic Network Test 464 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 465 466 The Diagnostic Network Test verifies a working network connection by 467 transferring data between two CS8900/20 adapters installed in different PCs 468 on the same network. (Note: the diagnostic network test should not be run 469 between two nodes across a router.) 470 471 This test requires that each of the two PCs have a CS8900/20-based adapter 472 installed and have the CS8900/20 Setup Utility running. The first PC is 473 configured as a Responder and the other PC is configured as an Initiator. 474 Once the Initiator is started, it sends data frames to the Responder which 475 returns the frames to the Initiator. 476 477 The total number of frames received and transmitted are displayed on the 478 Initiator's display, along with a count of the number of frames received and 479 transmitted OK or in error. The test can be terminated anytime by the user at 480 either PC. 481 482 To setup the Diagnostic Network Test: 483 484 1. Select a PC with a CS8900/20-based adapter and a known working network 485 connection to act as the Responder. Run the CS8900/20 Setup Utility 486 and select 'Diagnostics -> Network Test -> Responder' from the main 487 menu. Hit ENTER to start the Responder. 488 489 2. Return to the PC with the CS8900/20-based adapter you want to test and 490 start the CS8900/20 Setup Utility. 491 492 3. From the main menu, Select 'Diagnostic -> Network Test -> Initiator'. 493 Hit ENTER to start the test. 494 495 You may stop the test on the Initiator at any time while allowing the Responder 496 to continue running. In this manner, you can move to additional PCs and test 497 them by starting the Initiator on another PC without having to stop/start the 498 Responder. 499 500 501 502 5.3. Using the Adapter's LEDs 503 ----------------------------- 504 505 The 2 and 3-media adapters have two LEDs visible on the back end of the board 506 located near the 10Base-T connector. 507 508 Link Integrity LED: A "steady" ON of the green LED indicates a valid 10Base-T 509 connection. (Only applies to 10Base-T. The green LED has no significance for 510 a 10Base-2 or AUI connection.) 511 512 TX/RX LED: The yellow LED lights briefly each time the adapter transmits or 513 receives data. (The yellow LED will appear to "flicker" on a typical network.) 514 515 516 5.4. Resolving I/O Conflicts 517 ---------------------------- 518 519 An IO conflict occurs when two or more adapter use the same ISA resource (IO 520 address, memory address or IRQ). You can usually detect an IO conflict in one 521 of four ways after installing and or configuring the CS8900/20-based adapter: 522 523 1. The system does not boot properly (or at all). 524 525 2. The driver cannot communicate with the adapter, reporting an "Adapter 526 not found" error message. 527 528 3. You cannot connect to the network or the driver will not load. 529 530 4. If you have configured the adapter to run in memory mode but the driver 531 reports it is using IO mode when loading, this is an indication of a 532 memory address conflict. 533 534 If an IO conflict occurs, run the CS8900/20 Setup Utility and perform a 535 diagnostic self-test. Normally, the ISA resource in conflict will fail the 536 self-test. If so, reconfigure the adapter selecting another choice for the 537 resource in conflict. Run the diagnostics again to check for further IO 538 conflicts. 539 540 In some cases, such as when the PC will not boot, it may be necessary to remove 541 the adapter and reconfigure it by installing it in another PC to run the 542 CS8900/20 Setup Utility. Once reinstalled in the target system, run the 543 diagnostics self-test to ensure the new configuration is free of conflicts 544 before loading the driver again. 545 546 When manually configuring the adapter, keep in mind the typical ISA system 547 resource usage as indicated in the tables below. 548 549 :: 550 551 I/O Address Device IRQ Device 552 ----------- -------- --- -------- 553 200-20F Game I/O adapter 3 COM2, Bus Mouse 554 230-23F Bus Mouse 4 COM1 555 270-27F LPT3: third parallel port 5 LPT2 556 2F0-2FF COM2: second serial port 6 Floppy Disk controller 557 320-32F Fixed disk controller 7 LPT1 558 8 Real-time Clock 559 9 EGA/VGA display adapter 560 12 Mouse (PS/2) 561 Memory Address Device 13 Math Coprocessor 562 -------------- --------------------- 14 Hard Disk controller 563 A000-BFFF EGA Graphics Adapter 564 A000-C7FF VGA Graphics Adapter 565 B000-BFFF Mono Graphics Adapter 566 B800-BFFF Color Graphics Adapter 567 E000-FFFF AT BIOS 568 569 570 571 572 6. Technical Support 573 ==================== 574 575 6.1. Contacting Cirrus Logic's Technical Support 576 ------------------------------------------------ 577 578 Cirrus Logic's CS89XX Technical Application Support can be reached at:: 579 580 Telephone :(800) 888-5016 (from inside U.S. and Canada) 581 :(512) 442-7555 (from outside the U.S. and Canada) 582 Fax :(512) 912-3871 583 Email :ethernet@crystal.cirrus.com 584 WWW :http://www.cirrus.com 585 586 587 6.2. Information Required before Contacting Technical Support 588 ------------------------------------------------------------- 589 590 Before contacting Cirrus Logic for technical support, be prepared to provide as 591 Much of the following information as possible. 592 593 1.) Adapter type (CRD8900, CDB8900, CDB8920, etc.) 594 595 2.) Adapter configuration 596 597 * IO Base, Memory Base, IO or memory mode enabled, IRQ, DMA channel 598 * Plug and Play enabled/disabled (CS8920-based adapters only) 599 * Configured for media auto-detect or specific media type (which type). 600 601 3.) PC System's Configuration 602 603 * Plug and Play system (yes/no) 604 * BIOS (make and version) 605 * System make and model 606 * CPU (type and speed) 607 * System RAM 608 * SCSI Adapter 609 610 4.) Software 611 612 * CS89XX driver and version 613 * Your network operating system and version 614 * Your system's OS version 615 * Version of all protocol support files 616 617 5.) Any Error Message displayed. 618 619 620 621 6.3 Obtaining the Latest Driver Version 622 --------------------------------------- 623 624 You can obtain the latest CS89XX drivers and support software from Cirrus Logic's 625 Web site. You can also contact Cirrus Logic's Technical Support (email: 626 ethernet@crystal.cirrus.com) and request that you be registered for automatic 627 software-update notification. 628 629 Cirrus Logic maintains a web page at http://www.cirrus.com with the 630 latest drivers and technical publications. 631 632 633 6.4. Current maintainer 634 ----------------------- 635 636 In February 2000 the maintenance of this driver was assumed by Andrew 637 Morton. 638 639 6.5 Kernel module parameters 640 ---------------------------- 641 642 For use in embedded environments with no cs89x0 EEPROM, the kernel boot 643 parameter ``cs89x0_media=`` has been implemented. Usage is:: 644 645 cs89x0_media=rj45 or 646 cs89x0_media=aui or 647 cs89x0_media=bnc
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.