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