Commit 714a4da4 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by David S. Miller
Browse files

docs: networking: device drivers: convert cirrus/cs89x0.txt to ReST 



- add SPDX header;
- adjust title markup;
- mark code blocks and literals as such;
- adjust identation, whitespaces and blank lines where needed;
- add to networking/index.rst.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent c839ce55

Documentation/networking/device_drivers/cirrus/cs89x0.txt→Documentation/networking/device_drivers/cirrus/cs89x0.rst

+291 −268
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



NOTE

----

================================================

Cirrus Logic LAN CS8900/CS8920 Ethernet Adapters

================================================



.. note::



   This document was contributed by Cirrus Logic for kernel 2.2.5.  This version

   has been updated for 2.3.48 by Andrew Morton.



   Still, this is too outdated! A major cleanup is needed here.



Cirrus make a copy of this driver available at their website, as

described below.  In general, you should use the driver version which

comes with your Linux distribution.







CIRRUS LOGIC LAN CS8900/CS8920 ETHERNET ADAPTERS

Linux Network Interface Driver ver. 2.00 <kernel 2.3.48>

===============================================================================





TABLE OF CONTENTS

.. TABLE OF CONTENTS



   1.0 CIRRUS LOGIC LAN CS8900/CS8920 ETHERNET ADAPTERS

	1.1 Product Overview
@@ -53,11 +56,12 @@ TABLE OF CONTENTS 
	6.5 Kernel boot parameters





1.0 CIRRUS LOGIC LAN CS8900/CS8920 ETHERNET ADAPTERS

===============================================================================

1. Cirrus Logic LAN CS8900/CS8920 Ethernet Adapters

===================================================





1.1 PRODUCT OVERVIEW

1.1. Product Overview

=====================



The CS8900-based ISA Ethernet Adapters from Cirrus Logic follow

IEEE 802.3 standards and support half or full-duplex operation in ISA bus
@@ -73,7 +77,8 @@ adapters. Refer to the "Adapter Configuration" section for details on 
configuring both types of adapters.





1.2 DRIVER DESCRIPTION

1.2. Driver Description

=======================



The CS8900/CS8920 Ethernet Adapter driver for Linux supports the Linux

v2.3.48 or greater kernel.  It can be compiled directly into the kernel
@@ -85,18 +90,21 @@ or loaded at run-time as a device driver module. 


The files in the driver at Cirrus' website include:



  readme.txt         - this file

  build              - batch file to compile cs89x0.c.

  cs89x0.c           - driver C code

  cs89x0.h           - driver header file

  cs89x0.o           - pre-compiled module (for v2.2.5 kernel)

  config/Config.in   - sample file to include cs89x0 driver in the kernel.

  config/Makefile    - sample file to include cs89x0 driver in the kernel.

  config/Space.c     - sample file to include cs89x0 driver in the kernel.

  ===================  ====================================================

  readme.txt           this file

  build                batch file to compile cs89x0.c.

  cs89x0.c             driver C code

  cs89x0.h             driver header file

  cs89x0.o             pre-compiled module (for v2.2.5 kernel)

  config/Config.in     sample file to include cs89x0 driver in the kernel.

  config/Makefile      sample file to include cs89x0 driver in the kernel.

  config/Space.c       sample file to include cs89x0 driver in the kernel.

  ===================  ====================================================







1.3 SYSTEM REQUIREMENTS

1.3. System Requirements

------------------------



The following hardware is required:
@@ -123,7 +131,8 @@ The following software is required: 






1.4 LICENSING INFORMATION

1.4. Licensing Information

--------------------------



This program is free software; you can redistribute it and/or modify it under

the terms of the GNU General Public License as published by the Free Software
@@ -139,8 +148,8 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 






2.0 ADAPTER INSTALLATION and CONFIGURATION

===============================================================================

2. Adapter Installation and Configuration

=========================================



Both the CS8900 and CS8920-based adapters can be configured using parameters

stored in an on-board EEPROM. You must use the DOS-based CS8900/20 Setup
@@ -157,10 +166,11 @@ Utility before installation in the target LINUX system. (Not required if 
installing a CS8900-based adapter and the default configuration is acceptable.)





2.1 CS8900-BASED ADAPTER CONFIGURATION

2.1. CS8900-based Adapter Configuration

---------------------------------------



CS8900-based adapters shipped from Cirrus Logic have been configured

with the following "default" settings:

with the following "default" settings::



  Operation Mode:      Memory Mode

  IRQ:                 10
@@ -177,7 +187,8 @@ another adapter exists. To change the adapter's configuration, run the 
CS8900/20 Setup Utility.





2.2 CS8920-BASED ADAPTER CONFIGURATION

2.2. CS8920-based Adapter Configuration

---------------------------------------



CS8920-based adapters are shipped from Cirrus Logic configured as Plug

and Play (PnP) enabled.  However, since the cs89x0 driver does NOT
@@ -187,6 +198,7 @@ adapter before installation in the target Linux system. Failure to do 
this will leave the adapter inactive and the driver will be unable to

communicate with the adapter.



::



	****************************************************************

	*                    CS8920-BASED ADAPTERS:                    *
@@ -200,8 +212,8 @@ communicate with the adapter. 






3.0 LOADING THE DRIVER AS A MODULE

===============================================================================

3. Loading the Driver as a Module

=================================



If the driver is compiled as a loadable module, you can load the driver module

with the 'modprobe' command.  Many of the adapter's configuration parameters can
@@ -209,31 +221,31 @@ be specified as command-line arguments to the load command. This facility 
provides a means to override the EEPROM's settings or for interface

configuration when an EEPROM is not used.



Example:

Example::



    insmod cs89x0.o io=0x200 irq=0xA media=aui



This example loads the module and configures the adapter to use an IO port base

address of 200h, interrupt 10, and use the AUI media connection.  The following

configuration options are available on the command line:

configuration options are available on the command line::



* io=###               - specify IO address (200h-360h)

* irq=##               - specify interrupt level

* use_dma=1            - Enable DMA

* dma=#                - specify dma channel (Driver is compiled to support

  io=###               - specify IO address (200h-360h)

  irq=##               - specify interrupt level

  use_dma=1            - Enable DMA

  dma=#                - specify dma channel (Driver is compiled to support

			 Rx DMA only)

* dmasize=# (16 or 64) - DMA size 16K or 64K.  Default value is set to 16.

* media=rj45           - specify media type

  dmasize=# (16 or 64) - DMA size 16K or 64K.  Default value is set to 16.

  media=rj45           - specify media type

   or media=bnc

   or media=aui

   or media=auto

* duplex=full          - specify forced half/full/autonegotiate duplex

  duplex=full          - specify forced half/full/autonegotiate duplex

   or duplex=half

   or duplex=auto

* debug=#              - debug level (only available if the driver was compiled

  debug=#              - debug level (only available if the driver was compiled

			 for debugging)



NOTES:

**Notes:**



a) If an EEPROM is present, any specified command-line parameter

   will override the corresponding configuration value stored in
@@ -245,7 +257,7 @@ c) The driver's hardware probe routine is designed to avoid 
   writing to I/O space until it knows that there is a cs89x0

   card at the written addresses.  This could cause problems

   with device probing.  To avoid this behaviour, add one

   to the `io=' module parameter.  This doesn't actually change

   to the ``io=`` module parameter.  This doesn't actually change

   the I/O address, but it is a flag to tell the driver

   to partially initialise the hardware before trying to

   identify the card.  This could be dangerous if you are
@@ -282,7 +294,7 @@ h) Many Linux distributions use the 'modprobe' command to load 
   module when it is loaded.  All the configuration options which are

   described above may be placed within /etc/conf.modules.



   For example:

   For example::



     > cat /etc/conf.modules

     ...
@@ -305,7 +317,7 @@ j) The cs89x0 supports DMA for receiving only. DMA mode is 


k) If your Linux kernel was compiled with inbuilt plug-and-play

   support you will be able to find information about the cs89x0 card

   with the command

   with the command::



     cat /proc/isapnp
@@ -321,11 +333,11 @@ n) If the cs89x0 driver is compiled directly into the kernel, DMA 
   mode may be selected by providing the kernel with a boot option

   'cs89x0_dma=N' where 'N' is the desired DMA channel number (5, 6 or 7).



   Kernel boot options may be provided on the LILO command line:

   Kernel boot options may be provided on the LILO command line::



	LILO boot: linux cs89x0_dma=5



   or they may be placed in /etc/lilo.conf:

   or they may be placed in /etc/lilo.conf::



	image=/boot/bzImage-2.3.48

	  append="cs89x0_dma=5"
@@ -337,43 +349,35 @@ n) If the cs89x0 driver is compiled directly into the kernel, DMA 
   (64k mode is not available).





4.0 COMPILING THE DRIVER

===============================================================================

4. Compiling the Driver

=======================



The cs89x0 driver can be compiled directly into the kernel or compiled into

a loadable device driver module.



Just use the standard way to configure the driver and compile the Kernel.



4.1 COMPILING THE DRIVER AS A LOADABLE MODULE



To compile the driver into a loadable module, use the following command 

(single command line, without quotes):



"gcc -D__KERNEL__ -I/usr/src/linux/include -I/usr/src/linux/net/inet -Wall 

-Wstrict-prototypes -O2 -fomit-frame-pointer -DMODULE -DCONFIG_MODVERSIONS 

-c cs89x0.c"



4.2 COMPILING THE DRIVER TO SUPPORT MEMORY MODE



Support for memory mode was not carried over into the 2.3 series kernels.



4.3 COMPILING THE DRIVER TO SUPPORT Rx DMA

4.1. Compiling the Driver to Support Rx DMA

-------------------------------------------



The compile-time optionality for DMA was removed in the 2.3 kernel

series.  DMA support is now unconditionally part of the driver.  It is

enabled by the 'use_dma=1' module option.





5.0 TESTING AND TROUBLESHOOTING

===============================================================================

5. Testing and Troubleshooting

==============================



5.1 KNOWN DEFECTS and LIMITATIONS

5.1. Known Defects and Limitations

----------------------------------



Refer to the RELEASE.TXT file distributed as part of this archive for a list of

known defects, driver limitations, and work arounds.





5.2 TESTING THE ADAPTER

5.2. Testing the Adapter

------------------------



Once the adapter has been installed and configured, the diagnostic option of

the CS8900/20 Setup Utility can be used to test the functionality of the
@@ -384,56 +388,66 @@ adapter to communicate across the Ethernet with another PC equipped with a 
CS8900/20-based adapter card (it must also be running the CS8900/20 Setup

Utility).



         NOTE: The Setup Utility's diagnostics are designed to run in a

.. note::



	 The Setup Utility's diagnostics are designed to run in a

	 DOS-only operating system environment.  DO NOT run the diagnostics

	 from a DOS or command prompt session under Windows 95, Windows NT,

	 OS/2, or other operating system.



To run the diagnostics tests on the CS8900/20 adapter:



   1.) Boot DOS on the PC and start the CS8900/20 Setup Utility.

   1.  Boot DOS on the PC and start the CS8900/20 Setup Utility.



   2.) The adapter's current configuration is displayed.  Hit the ENTER key to

   2.  The adapter's current configuration is displayed.  Hit the ENTER key to

       get to the main menu.



   4.) Select 'Diagnostics' (ALT-G) from the main menu.  

   4.  Select 'Diagnostics' (ALT-G) from the main menu.

       * Select 'Self-Test' to test the adapter's basic functionality.

       * Select 'Network Test' to test the network connection and cabling.





5.2.1 DIAGNOSTIC SELF-TEST

5.2.1. Diagnostic Self-test

^^^^^^^^^^^^^^^^^^^^^^^^^^^



The diagnostic self-test checks the adapter's basic functionality as well as

its ability to communicate across the ISA bus based on the system resources

assigned during hardware configuration.  The following tests are performed:



   * IO Register Read/Write Test



     The IO Register Read/Write test insures that the CS8900/20 can be

     accessed in IO mode, and that the IO base address is correct.



   * Shared Memory Test



     The Shared Memory test insures the CS8900/20 can be accessed in memory

     mode and that the range of memory addresses assigned does not conflict

     with other devices in the system.



   * Interrupt Test



     The Interrupt test insures there are no conflicts with the assigned IRQ

     signal.



   * EEPROM Test



     The EEPROM test insures the EEPROM can be read.



   * Chip RAM Test



     The Chip RAM test insures the 4K of memory internal to the CS8900/20 is

     working properly.



   * Internal Loop-back Test



     The Internal Loop Back test insures the adapter's transmitter and

     receiver are operating properly.  If this test fails, make sure the

     adapter's cable is connected to the network (check for LED activity for

     example).



   * Boot PROM Test



     The Boot PROM  test insures the Boot PROM is present, and can be read.

     Failure indicates the Boot PROM  was not successfully read due to a

     hardware problem or due to a conflicts on the Boot PROM address
@@ -446,7 +460,8 @@ option to reconfigure the adapter by selecting a different value for the system 
resource that failed.





5.2.2 DIAGNOSTIC NETWORK TEST

5.2.2. Diagnostic Network Test

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



The Diagnostic Network Test verifies a working network connection by

transferring data between two CS8900/20 adapters installed in different PCs
@@ -466,15 +481,15 @@ either PC. 


To setup the Diagnostic Network Test:



    1.) Select a PC with a CS8900/20-based adapter and a known working network

    1.  Select a PC with a CS8900/20-based adapter and a known working network

	connection to act as the Responder.  Run the CS8900/20 Setup Utility

	and select 'Diagnostics -> Network Test -> Responder' from the main

	menu.  Hit ENTER to start the Responder.



    2.) Return to the PC with the CS8900/20-based adapter you want to test and

    2.  Return to the PC with the CS8900/20-based adapter you want to test and

	start the CS8900/20 Setup Utility.



    3.) From the main menu, Select 'Diagnostic -> Network Test -> Initiator'.

    3.  From the main menu, Select 'Diagnostic -> Network Test -> Initiator'.

	Hit ENTER to start the test.



You may stop the test on the Initiator at any time while allowing the Responder
@@ -484,7 +499,8 @@ Responder. 






5.3 USING THE ADAPTER'S LEDs

5.3. Using the Adapter's LEDs

-----------------------------



The 2 and 3-media adapters have two LEDs visible on the back end of the board

located near the 10Base-T connector.
@@ -497,20 +513,21 @@ TX/RX LED: The yellow LED lights briefly each time the adapter transmits or 
receives data. (The yellow LED will appear to "flicker" on a typical network.)





5.4 RESOLVING I/O CONFLICTS

5.4. Resolving I/O Conflicts

----------------------------



An IO conflict occurs when two or more adapter use the same ISA resource (IO

address, memory address or IRQ).  You can usually detect an IO conflict in one

of four ways after installing and or configuring the CS8900/20-based adapter:



    1.) The system does not boot properly (or at all).

    1.  The system does not boot properly (or at all).



    2.) The driver cannot communicate with the adapter, reporting an "Adapter

    2.  The driver cannot communicate with the adapter, reporting an "Adapter

	not found" error message.



    3.) You cannot connect to the network or the driver will not load.

    3.  You cannot connect to the network or the driver will not load.



    4.) If you have configured the adapter to run in memory mode but the driver

    4.  If you have configured the adapter to run in memory mode but the driver

	reports it is using IO mode when loading, this is an indication of a

	memory address conflict.
@@ -529,6 +546,8 @@ before loading the driver again. 
When manually configuring the adapter, keep in mind the typical ISA system

resource usage as indicated in the tables below.



::



  I/O Address    	Device                        IRQ      Device

  -----------    	--------                      ---      --------

     200-20F       	Game I/O adapter               3       COM2, Bus Mouse
@@ -550,12 +569,13 @@ E000-FFFF AT BIOS 






6.0 TECHNICAL SUPPORT

===============================================================================

6. Technical Support

====================



6.1 CONTACTING CIRRUS LOGIC'S TECHNICAL SUPPORT

6.1. Contacting Cirrus Logic's Technical Support

------------------------------------------------



Cirrus Logic's CS89XX Technical Application Support can be reached at:

Cirrus Logic's CS89XX Technical Application Support can be reached at::



  Telephone  :(800) 888-5016 (from inside U.S. and Canada)

	     :(512) 442-7555 (from outside the U.S. and Canada)
@@ -564,7 +584,8 @@ Email :ethernet@crystal.cirrus.com 
  WWW        :http://www.cirrus.com





6.2 INFORMATION REQUIRED BEFORE CONTACTING TECHNICAL SUPPORT

6.2. Information Required before Contacting Technical Support

-------------------------------------------------------------



Before contacting Cirrus Logic for technical support, be prepared to provide as

Much of the following information as possible.
@@ -597,7 +618,8 @@ Much of the following information as possible. 






6.3 OBTAINING THE LATEST DRIVER VERSION

6.3 Obtaining the Latest Driver Version

---------------------------------------



You can obtain the latest CS89XX drivers and support software from Cirrus Logic's

Web site.  You can also contact Cirrus Logic's Technical Support (email:
@@ -608,17 +630,18 @@ Cirrus Logic maintains a web page at http://www.cirrus.com with the 
latest drivers and technical publications.





6.4 Current maintainer

6.4. Current maintainer

-----------------------



In February 2000 the maintenance of this driver was assumed by Andrew

Morton.



6.5 Kernel module parameters

----------------------------



For use in embedded environments with no cs89x0 EEPROM, the kernel boot

parameter `cs89x0_media=' has been implemented.  Usage is:

parameter ``cs89x0_media=`` has been implemented.  Usage is::



	cs89x0_media=rj45    or

	cs89x0_media=aui     or

	cs89x0_media=bnc

Documentation/networking/device_drivers/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -32,6 +32,7 @@ Contents: 
   amazon/ena

   aquantia/atlantic

   chelsio/cxgb

   cirrus/cs89x0



.. only::  subproject and html

drivers/net/ethernet/cirrus/Kconfig

+1 −1
Original line number Diff line number Diff line
@@ -24,7 +24,7 @@ config CS89x0 
	---help---

	  Support for CS89x0 chipset based Ethernet cards. If you have a

	  network (Ethernet) card of this type, say Y and read the file

	  <file:Documentation/networking/device_drivers/cirrus/cs89x0.txt>.

	  <file:Documentation/networking/device_drivers/cirrus/cs89x0.rst>.



	  To compile this driver as a module, choose M here. The module

	  will be called cs89x0.

CRA Git | Maintained and supported by SUSTech CRA and CCSE