code:
.. SPDX-License-Identifier: GPL-2.0

=========================
3Com Vortex device driver
=========================

Andrew Morton

30 April 2000

This document describes the usage and errata of the 3Com "Vortex" device
driver for Linux, 3c59x.c.

The driver was written by Donald Becker <becker@scyld.com>

Don is no longer the prime maintainer of this version of the driver.
Please report problems to one or more of:

- Andrew Morton
- Netdev mailing list <netdev@vger.kernel.org>
- Linux kernel mailing list <linux-kernel@vger.kernel.org>

Please note the 'Reporting and Diagnosing Problems' section at the end
of this file.

Since kernel 2.3.99-pre6, this driver incorporates the support for the
3c575-series Cardbus cards which used to be handled by 3c575_cb.c.

This driver supports the following hardware:

	- 3c590 Vortex 10Mbps
	- 3c592 EISA 10Mbps Demon/Vortex
	- 3c597 EISA Fast Demon/Vortex
	- 3c595 Vortex 100baseTx
	- 3c595 Vortex 100baseT4
	- 3c595 Vortex 100base-MII
	- 3c900 Boomerang 10baseT
	- 3c900 Boomerang 10Mbps Combo
	- 3c900 Cyclone 10Mbps TPO
	- 3c900 Cyclone 10Mbps Combo
	- 3c900 Cyclone 10Mbps TPC
	- 3c900B-FL Cyclone 10base-FL
	- 3c905 Boomerang 100baseTx
	- 3c905 Boomerang 100baseT4
	- 3c905B Cyclone 100baseTx
	- 3c905B Cyclone 10/100/BNC
	- 3c905B-FX Cyclone 100baseFx
	- 3c905C Tornado
	- 3c920B-EMB-WNM (ATI Radeon 9100 IGP)
	- 3c980 Cyclone
	- 3c980C Python-T
	- 3cSOHO100-TX Hurricane
	- 3c555 Laptop Hurricane
	- 3c556 Laptop Tornado
	- 3c556B Laptop Hurricane
	- 3c575 [Megahertz] 10/100 LAN  CardBus
	- 3c575 Boomerang CardBus
	- 3CCFE575BT Cyclone CardBus
	- 3CCFE575CT Tornado CardBus
	- 3CCFE656 Cyclone CardBus
	- 3CCFEM656B Cyclone+Winmodem CardBus
	- 3CXFEM656C Tornado+Winmodem CardBus
	- 3c450 HomePNA Tornado
	- 3c920 Tornado
	- 3c982 Hydra Dual Port A
	- 3c982 Hydra Dual Port B
	- 3c905B-T4
	- 3c920B-EMB-WNM Tornado

Module parameters
=================

There are several parameters which may be provided to the driver when
its module is loaded.  These are usually placed in ``/etc/modprobe.d/*.conf``
configuration files.  Example::

    options 3c59x debug=3 rx_copybreak=300

If you are using the PCMCIA tools (cardmgr) then the options may be
placed in /etc/pcmcia/config.opts::

    module "3c59x" opts "debug=3 rx_copybreak=300"

The supported parameters are:

debug=N

  Where N is a number from 0 to 7.  Anything above 3 produces a lot
  of output in your system logs.  debug=1 is default.

options=N1,N2,N3,...

  Each number in the list provides an option to the corresponding
  network card.  So if you have two 3c905's and you wish to provide
  them with option 0x204 you would use::

    options=0x204,0x204

  The individual options are composed of a number of bitfields which
  have the following meanings:

  Possible media type settings

	==	=================================
	0	10baseT
	1	10Mbs AUI
	2	undefined
	3	10base2 (BNC)
	4	100base-TX
	5	100base-FX
	6	MII (Media Independent Interface)
	7	Use default setting from EEPROM
	8       Autonegotiate
	9       External MII
	10      Use default setting from EEPROM
	==	=================================

  When generating a value for the 'options' setting, the above media
  selection values may be OR'ed (or added to) the following:

  ======  =============================================
  0x8000  Set driver debugging level to 7
  0x4000  Set driver debugging level to 2
  0x0400  Enable Wake-on-LAN
  0x0200  Force full duplex mode.
  0x0010  Bus-master enable bit (Old Vortex cards only)
  ======  =============================================

  For example::

    insmod 3c59x options=0x204

  will force full-duplex 100base-TX, rather than allowing the usual
  autonegotiation.

global_options=N

  Sets the ``options`` parameter for all 3c59x NICs in the machine.
  Entries in the ``options`` array above will override any setting of
  this.

full_duplex=N1,N2,N3...

  Similar to bit 9 of 'options'.  Forces the corresponding card into
  full-duplex mode.  Please use this in preference to the ``options``
  parameter.

  In fact, please don't use this at all! You're better off getting
  autonegotiation working properly.

global_full_duplex=N1

  Sets full duplex mode for all 3c59x NICs in the machine.  Entries
  in the ``full_duplex`` array above will override any setting of this.

flow_ctrl=N1,N2,N3...

  Use 802.3x MAC-layer flow control.  The 3com cards only support the
  PAUSE command, which means that they will stop sending packets for a
  short period if they receive a PAUSE frame from the link partner.

  The driver only allows flow control on a link which is operating in
  full duplex mode.

  This feature does not appear to work on the 3c905 - only 3c905B and
  3c905C have been tested.

  The 3com cards appear to only respond to PAUSE frames which are
  sent to the reserved destination address of 01:80:c2:00:00:01.  They
  do not honour PAUSE frames which are sent to the station MAC address.

rx_copybreak=M

  The driver preallocates 32 full-sized (1536 byte) network buffers
  for receiving.  When a packet arrives, the driver has to decide
  whether to leave the packet in its full-sized buffer, or to allocate
  a smaller buffer and copy the packet across into it.

  This is a speed/space tradeoff.

  The value of rx_copybreak is used to decide when to make the copy.
  If the packet size is less than rx_copybreak, the packet is copied.
  The default value for rx_copybreak is 200 bytes.

max_interrupt_work=N

  The driver's interrupt service routine can handle many receive and
  transmit packets in a single invocation.  It does this in a loop.
  The value of max_interrupt_work governs how many times the interrupt
  service routine will loop.  The default value is 32 loops.  If this
  is exceeded the interrupt service routine gives up and generates a
  warning message "eth0: Too much work in interrupt".

hw_checksums=N1,N2,N3,...

  Recent 3com NICs are able to generate IPv4, TCP and UDP checksums
  in hardware.  Linux has used the Rx checksumming for a long time.
  The "zero copy" patch which is planned for the 2.4 kernel series
  allows you to make use of the NIC's DMA scatter/gather and transmit
  checksumming as well.

  The driver is set up so that, when the zerocopy patch is applied,
  all Tornado and Cyclone devices will use S/G and Tx checksums.

  This module parameter has been provided so you can override this
  decision.  If you think that Tx checksums are causing a problem, you
  may disable the feature with ``hw_checksums=0``.

  If you think your NIC should be performing Tx checksumming and the
  driver isn't enabling it, you can force the use of hardware Tx
  checksumming with ``hw_checksums=1``.

  The driver drops a message in the logfiles to indicate whether or
  not it is using hardware scatter/gather and hardware Tx checksums.

  Scatter/gather and hardware checksums provide considerable
  performance improvement for the sendfile() system call, but a small
  decrease in throughput for send().  There is no effect upon receive
  efficiency.

compaq_ioaddr=N,
compaq_irq=N,
compaq_device_id=N

  "Variables to work-around the Compaq PCI BIOS32 problem"....

watchdog=N

  Sets the time duration (in milliseconds) after which the kernel
  decides that the transmitter has become stuck and needs to be reset.
  This is mainly for debugging purposes, although it may be advantageous
  to increase this value on LANs which have very high collision rates.
  The default value is 5000 (5.0 seconds).

enable_wol=N1,N2,N3,...

  Enable Wake-on-LAN support for the relevant interface.  Donald
  Becker's ``ether-wake`` application may be used to wake suspended
  machines.

  Also enables the NIC's power management support.

global_enable_wol=N

  Sets enable_wol mode for all 3c59x NICs in the machine.  Entries in
  the ``enable_wol`` array above will override any setting of this.

Media selection
---------------

A number of the older NICs such as the 3c590 and 3c900 series have
10base2 and AUI interfaces.

Prior to January, 2001 this driver would autoeselect the 10base2 or AUI
port if it didn't detect activity on the 10baseT port.  It would then
get stuck on the 10base2 port and a driver reload was necessary to
switch back to 10baseT.  This behaviour could not be prevented with a
module option override.

Later (current) versions of the driver _do_ support locking of the
media type.  So if you load the driver module with

	modprobe 3c59x options=0

it will permanently select the 10baseT port.  Automatic selection of
other media types does not occur.

Transmit error, Tx status register 82
-------------------------------------

This is a common error which is almost always caused by another host on
the same network being in full-duplex mode, while this host is in
half-duplex mode.  You need to find that other host and make it run in
half-duplex mode or fix this host to run in full-duplex mode.

As a last resort, you can force the 3c59x driver into full-duplex mode
with

	options 3c59x full_duplex=1

but this has to be viewed as a workaround for broken network gear and
should only really be used for equipment which cannot autonegotiate.

Additional resources
--------------------

Details of the device driver implementation are at the top of the source file.

Additional documentation is available at Don Becker's Linux Drivers site:

     http://www.scyld.com/vortex.html

Donald Becker's driver development site:

     http://www.scyld.com/network.html

Donald's vortex-diag program is useful for inspecting the NIC's state:

     http://www.scyld.com/ethercard_diag.html

Donald's mii-diag program may be used for inspecting and manipulating
the NIC's Media Independent Interface subsystem:

     http://www.scyld.com/ethercard_diag.html#mii-diag

Donald's wake-on-LAN page:

     http://www.scyld.com/wakeonlan.html

3Com's DOS-based application for setting up the NICs EEPROMs:

	ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe

Autonegotiation notes
---------------------

  The driver uses a one-minute heartbeat for adapting to changes in
  the external LAN environment if link is up and 5 seconds if link is down.
  This means that when, for example, a machine is unplugged from a hubbed
  10baseT LAN plugged into a  switched 100baseT LAN, the throughput
  will be quite dreadful for up to sixty seconds.  Be patient.

  Cisco interoperability note from Walter Wong <wcw+@CMU.EDU>:

  On a side note, adding HAS_NWAY seems to share a problem with the
  Cisco 6509 switch.  Specifically, you need to change the spanning
  tree parameter for the port the machine is plugged into to 'portfast'
  mode.  Otherwise, the negotiation fails.  This has been an issue
  we've noticed for a while but haven't had the time to track down.

  Cisco switches    (Jeff Busch <jbusch@deja.com>)

    My "standard config" for ports to which PC's/servers connect directly::

	interface FastEthernet0/N
	description machinename
	load-interval 30
	spanning-tree portfast

    If autonegotiation is a problem, you may need to specify "speed
    100" and "duplex full" as well (or "speed 10" and "duplex half").

    WARNING: DO NOT hook up hubs/switches/bridges to these
    specially-configured ports! The switch will become very confused.

Reporting and diagnosing problems
---------------------------------

Maintainers find that accurate and complete problem reports are
invaluable in resolving driver problems.  We are frequently not able to
reproduce problems and must rely on your patience and efforts to get to
the bottom of the problem.

If you believe you have a driver problem here are some of the
steps you should take:

- Is it really a driver problem?

   Eliminate some variables: try different cards, different
   computers, different cables, different ports on the switch/hub,
   different versions of the kernel or of the driver, etc.

- OK, it's a driver problem.

   You need to generate a report.  Typically this is an email to the
   maintainer and/or netdev@vger.kernel.org.  The maintainer's
   email address will be in the driver source or in the MAINTAINERS file.

- The contents of your report will vary a lot depending upon the
  problem.  If it's a kernel crash then you should refer to
  'Documentation/admin-guide/reporting-issues.rst'.

  But for most problems it is useful to provide the following:

   - Kernel version, driver version

   - A copy of the banner message which the driver generates when
     it is initialised.  For example:

     eth0: 3Com PCI 3c905C Tornado at 0xa400,  00:50:da:6a:88:f0, IRQ 19
     8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate interface.
     MII transceiver found at address 24, status 782d.
     Enabling bus-master transmits and whole-frame receives.

     NOTE: You must provide the ``debug=2`` modprobe option to generate
     a full detection message.  Please do this::

	modprobe 3c59x debug=2

   - If it is a PCI device, the relevant output from 'lspci -vx', eg::

       00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast Etherlink] (rev 74)
	       Subsystem: 3Com Corporation: Unknown device 9200
	       Flags: bus master, medium devsel, latency 32, IRQ 19
	       I/O ports at a400 [size=128]
	       Memory at db000000 (32-bit, non-prefetchable) [size=128]
	       Expansion ROM at <unassigned> [disabled] [size=128K]
	       Capabilities: [dc] Power Management version 2
       00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00
       10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00
       20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10
       30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a

   - A description of the environment: 10baseT? 100baseT?
     full/half duplex? switched or hubbed?

   - Any additional module parameters which you may be providing to the driver.

   - Any kernel logs which are produced.  The more the merrier.
     If this is a large file and you are sending your report to a
     mailing list, mention that you have the logfile, but don't send
     it.  If you're reporting direct to the maintainer then just send
     it.

     To ensure that all kernel logs are available, add the
     following line to /etc/syslog.conf::

	 kern.* /var/log/messages

     Then restart syslogd with::

	 /etc/rc.d/init.d/syslog restart

     (The above may vary, depending upon which Linux distribution you use).

    - If your problem is reproducible then that's great.  Try the
      following:

      1) Increase the debug level.  Usually this is done via:

	 a) modprobe driver debug=7
	 b) In /etc/modprobe.d/driver.conf:
	    options driver debug=7

      2) Recreate the problem with the higher debug level,
	 send all logs to the maintainer.

      3) Download you card's diagnostic tool from Donald
	 Becker's website <http://www.scyld.com/ethercard_diag.html>.
	 Download mii-diag.c as well.  Build these.

	 a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is
	    working correctly.  Save the output.

	 b) Run the above commands when the card is malfunctioning.  Send
	    both sets of output.

Finally, please be patient and be prepared to do some work.  You may
end up working on this problem for a week or more as the maintainer
asks more questions, asks for more tests, asks for patches to be
applied, etc.  At the end of it all, the problem may even remain
unresolved.


code:
.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.txt>

=======================================
Altera Triple-Speed Ethernet MAC driver
=======================================

Copyright |copy| 2008-2014 Altera Corporation

This is the driver for the Altera Triple-Speed Ethernet (TSE) controllers
using the SGDMA and MSGDMA soft DMA IP components. The driver uses the
platform bus to obtain component resources. The designs used to test this
driver were built for a Cyclone(R) V SOC FPGA board, a Cyclone(R) V FPGA board,
and tested with ARM and NIOS processor hosts separately. The anticipated use
cases are simple communications between an embedded system and an external peer
for status and simple configuration of the embedded system.

For more information visit www.altera.com and www.rocketboards.org. Support
forums for the driver may be found on www.rocketboards.org, and a design used
to test this driver may be found there as well. Support is also available from
the maintainer of this driver, found in MAINTAINERS.

The Triple-Speed Ethernet, SGDMA, and MSGDMA components are all soft IP
components that can be assembled and built into an FPGA using the Altera
Quartus toolchain. Quartus 13.1 and 14.0 were used to build the design that
this driver was tested against. The sopc2dts tool is used to create the
device tree for the driver, and may be found at rocketboards.org.

The driver probe function examines the device tree and determines if the
Triple-Speed Ethernet instance is using an SGDMA or MSGDMA component. The
probe function then installs the appropriate set of DMA routines to
initialize, setup transmits, receives, and interrupt handling primitives for
the respective configurations.

The SGDMA component is to be deprecated in the near future (over the next 1-2
years as of this writing in early 2014) in favor of the MSGDMA component.
SGDMA support is included for existing designs and reference in case a
developer wishes to support their own soft DMA logic and driver support. Any
new designs should not use the SGDMA.

The SGDMA supports only a single transmit or receive operation at a time, and
therefore will not perform as well compared to the MSGDMA soft IP. Please
visit www.altera.com for known, documented SGDMA errata.

Scatter-gather DMA is not supported by the SGDMA or MSGDMA at this time.
Scatter-gather DMA will be added to a future maintenance update to this
driver.

Jumbo frames are not supported at this time.

The driver limits PHY operations to 10/100Mbps, and has not yet been fully
tested for 1Gbps. This support will be added in a future maintenance update.

1. Kernel Configuration
=======================

The kernel configuration option is ALTERA_TSE:

 Device Drivers ---> Network device support ---> Ethernet driver support --->
 Altera Triple-Speed Ethernet MAC support (ALTERA_TSE)

2. Driver parameters list
=========================

	- debug: message level (0: no output, 16: all);
	- dma_rx_num: Number of descriptors in the RX list (default is 64);
	- dma_tx_num: Number of descriptors in the TX list (default is 64).

3. Command line options
=======================

Driver parameters can be also passed in command line by using::

	altera_tse=dma_rx_num:128,dma_tx_num:512

4. Driver information and notes
===============================

4.1. Transmit process
---------------------
When the driver's transmit routine is called by the kernel, it sets up a
transmit descriptor by calling the underlying DMA transmit routine (SGDMA or
MSGDMA), and initiates a transmit operation. Once the transmit is complete, an
interrupt is driven by the transmit DMA logic. The driver handles the transmit
completion in the context of the interrupt handling chain by recycling
resource required to send and track the requested transmit operation.

4.2. Receive process
--------------------
The driver will post receive buffers to the receive DMA logic during driver
initialization. Receive buffers may or may not be queued depending upon the
underlying DMA logic (MSGDMA is able queue receive buffers, SGDMA is not able
to queue receive buffers to the SGDMA receive logic). When a packet is
received, the DMA logic generates an interrupt. The driver handles a receive
interrupt by obtaining the DMA receive logic status, reaping receive
completions until no more receive completions are available.

4.3. Interrupt Mitigation
-------------------------
The driver is able to mitigate the number of its DMA interrupts
using NAPI for receive operations. Interrupt mitigation is not yet supported
for transmit operations, but will be added in a future maintenance release.

4.4) Ethtool support
--------------------
Ethtool is supported. Driver statistics and internal errors can be taken using:
ethtool -S ethX command. It is possible to dump registers etc.

4.5) PHY Support
----------------
The driver is compatible with PAL to work with PHY and GPHY devices.

4.7) List of source files:
--------------------------
 - Kconfig
 - Makefile
 - altera_tse_main.c: main network device driver
 - altera_tse_ethtool.c: ethtool support
 - altera_tse.h: private driver structure and common definitions
 - altera_msgdma.h: MSGDMA implementation function definitions
 - altera_sgdma.h: SGDMA implementation function definitions
 - altera_msgdma.c: MSGDMA implementation
 - altera_sgdma.c: SGDMA implementation
 - altera_sgdmahw.h: SGDMA register and descriptor definitions
 - altera_msgdmahw.h: MSGDMA register and descriptor definitions
 - altera_utils.c: Driver utility functions
 - altera_utils.h: Driver utility function definitions

5. Debug Information
====================

The driver exports debug information such as internal statistics,
debug information, MAC and DMA registers etc.

A user may use the ethtool support to get statistics:
e.g. using: ethtool -S ethX (that shows the statistics counters)
or sees the MAC registers: e.g. using: ethtool -d ethX

The developer can also use the "debug" module parameter to get
further debug information.

6. Statistics Support
=====================

The controller and driver support a mix of IEEE standard defined statistics,
RFC defined statistics, and driver or Altera defined statistics. The four
specifications containing the standard definitions for these statistics are
as follows:

 - IEEE 802.3-2012 - IEEE Standard for Ethernet.
 - RFC 2863 found at http://www.rfc-editor.org/rfc/rfc2863.txt.
 - RFC 2819 found at http://www.rfc-editor.org/rfc/rfc2819.txt.
 - Altera Triple Speed Ethernet User Guide, found at http://www.altera.com

The statistics supported by the TSE and the device driver are as follows:

"tx_packets" is equivalent to aFramesTransmittedOK defined in IEEE 802.3-2012,
Section 5.2.2.1.2. This statistics is the count of frames that are successfully
transmitted.

"rx_packets" is equivalent to aFramesReceivedOK defined in IEEE 802.3-2012,
Section 5.2.2.1.5. This statistic is the count of frames that are successfully
received. This count does not include any error packets such as CRC errors,
length errors, or alignment errors.

"rx_crc_errors" is equivalent to aFrameCheckSequenceErrors defined in IEEE
802.3-2012, Section 5.2.2.1.6. This statistic is the count of frames that are
an integral number of bytes in length and do not pass the CRC test as the frame
is received.

"rx_align_errors" is equivalent to aAlignmentErrors defined in IEEE 802.3-2012,
Section 5.2.2.1.7. This statistic is the count of frames that are not an
integral number of bytes in length and do not pass the CRC test as the frame is
received.

"tx_bytes" is equivalent to aOctetsTransmittedOK defined in IEEE 802.3-2012,
Section 5.2.2.1.8. This statistic is the count of data and pad bytes
successfully transmitted from the interface.

"rx_bytes" is equivalent to aOctetsReceivedOK defined in IEEE 802.3-2012,
Section 5.2.2.1.14. This statistic is the count of data and pad bytes
successfully received by the controller.

"tx_pause" is equivalent to aPAUSEMACCtrlFramesTransmitted defined in IEEE
802.3-2012, Section 30.3.4.2. This statistic is a count of PAUSE frames
transmitted from the network controller.

"rx_pause" is equivalent to aPAUSEMACCtrlFramesReceived defined in IEEE
802.3-2012, Section 30.3.4.3. This statistic is a count of PAUSE frames
received by the network controller.

"rx_errors" is equivalent to ifInErrors defined in RFC 2863. This statistic is
a count of the number of packets received containing errors that prevented the
packet from being delivered to a higher level protocol.

"tx_errors" is equivalent to ifOutErrors defined in RFC 2863. This statistic
is a count of the number of packets that could not be transmitted due to errors.

"rx_unicast" is equivalent to ifInUcastPkts defined in RFC 2863. This
statistic is a count of the number of packets received that were not addressed
to the broadcast address or a multicast group.

"rx_multicast" is equivalent to ifInMulticastPkts defined in RFC 2863. This
statistic is a count of the number of packets received that were addressed to
a multicast address group.

"rx_broadcast" is equivalent to ifInBroadcastPkts defined in RFC 2863. This
statistic is a count of the number of packets received that were addressed to
the broadcast address.

"tx_discards" is equivalent to ifOutDiscards defined in RFC 2863. This
statistic is the number of outbound packets not transmitted even though an
error was not detected. An example of a reason this might occur is to free up
internal buffer space.

"tx_unicast" is equivalent to ifOutUcastPkts defined in RFC 2863. This
statistic counts the number of packets transmitted that were not addressed to
a multicast group or broadcast address.

"tx_multicast" is equivalent to ifOutMulticastPkts defined in RFC 2863. This
statistic counts the number of packets transmitted that were addressed to a
multicast group.

"tx_broadcast" is equivalent to ifOutBroadcastPkts defined in RFC 2863. This
statistic counts the number of packets transmitted that were addressed to a
broadcast address.

"ether_drops" is equivalent to etherStatsDropEvents defined in RFC 2819.
This statistic counts the number of packets dropped due to lack of internal
controller resources.

"rx_total_bytes" is equivalent to etherStatsOctets defined in RFC 2819.
This statistic counts the total number of bytes received by the controller,
including error and discarded packets.

"rx_total_packets" is equivalent to etherStatsPkts defined in RFC 2819.
This statistic counts the total number of packets received by the controller,
including error, discarded, unicast, multicast, and broadcast packets.

"rx_undersize" is equivalent to etherStatsUndersizePkts defined in RFC 2819.
This statistic counts the number of correctly formed packets received less
than 64 bytes long.

"rx_oversize" is equivalent to etherStatsOversizePkts defined in RFC 2819.
This statistic counts the number of correctly formed packets greater than 1518
bytes long.

"rx_64_bytes" is equivalent to etherStatsPkts64Octets defined in RFC 2819.
This statistic counts the total number of packets received that were 64 octets
in length.

"rx_65_127_bytes" is equivalent to etherStatsPkts65to127Octets defined in RFC
2819. This statistic counts the total number of packets received that were
between 65 and 127 octets in length inclusive.

"rx_128_255_bytes" is equivalent to etherStatsPkts128to255Octets defined in
RFC 2819. This statistic is the total number of packets received that were
between 128 and 255 octets in length inclusive.

"rx_256_511_bytes" is equivalent to etherStatsPkts256to511Octets defined in
RFC 2819. This statistic is the total number of packets received that were
between 256 and 511 octets in length inclusive.

"rx_512_1023_bytes" is equivalent to etherStatsPkts512to1023Octets defined in
RFC 2819. This statistic is the total number of packets received that were
between 512 and 1023 octets in length inclusive.

"rx_1024_1518_bytes" is equivalent to etherStatsPkts1024to1518Octets define
in RFC 2819. This statistic is the total number of packets received that were
between 1024 and 1518 octets in length inclusive.

"rx_gte_1519_bytes" is a statistic defined specific to the behavior of the
Altera TSE. This statistics counts the number of received good and errored
frames between the length of 1519 and the maximum frame length configured
in the frm_length register. See the Altera TSE User Guide for More details.

"rx_jabbers" is equivalent to etherStatsJabbers defined in RFC 2819. This
statistic is the total number of packets received that were longer than 1518
octets, and had either a bad CRC with an integral number of octets (CRC Error)
or a bad CRC with a non-integral number of octets (Alignment Error).

"rx_runts" is equivalent to etherStatsFragments defined in RFC 2819. This
statistic is the total number of packets received that were less than 64 octets
in length and had either a bad CRC with an integral number of octets (CRC
error) or a bad CRC with a non-integral number of octets (Alignment Error).

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GPL-2.0

============================================================
Linux kernel driver for Elastic Network Adapter (ENA) family
============================================================

Overview
========

ENA is a networking interface designed to make good use of modern CPU
features and system architectures.

The ENA device exposes a lightweight management interface with a
minimal set of memory mapped registers and extendible command set
through an Admin Queue.

The driver supports a range of ENA devices, is link-speed independent
(i.e., the same driver is used for 10GbE, 25GbE, 40GbE, etc), and has
a negotiated and extendible feature set.

Some ENA devices support SR-IOV. This driver is used for both the
SR-IOV Physical Function (PF) and Virtual Function (VF) devices.

ENA devices enable high speed and low overhead network traffic
processing by providing multiple Tx/Rx queue pairs (the maximum number
is advertised by the device via the Admin Queue), a dedicated MSI-X
interrupt vector per Tx/Rx queue pair, adaptive interrupt moderation,
and CPU cacheline optimized data placement.

The ENA driver supports industry standard TCP/IP offload features such as
checksum offload. Receive-side scaling (RSS) is supported for multi-core
scaling.

The ENA driver and its corresponding devices implement health
monitoring mechanisms such as watchdog, enabling the device and driver
to recover in a manner transparent to the application, as well as
debug logs.

Some of the ENA devices support a working mode called Low-latency
Queue (LLQ), which saves several more microseconds.
ENA Source Code Directory Structure
===================================

=================   ======================================================
ena_com.[ch]        Management communication layer. This layer is
                    responsible for the handling all the management
                    (admin) communication between the device and the
                    driver.
ena_eth_com.[ch]    Tx/Rx data path.
ena_admin_defs.h    Definition of ENA management interface.
ena_eth_io_defs.h   Definition of ENA data path interface.
ena_common_defs.h   Common definitions for ena_com layer.
ena_regs_defs.h     Definition of ENA PCI memory-mapped (MMIO) registers.
ena_netdev.[ch]     Main Linux kernel driver.
ena_ethtool.c       ethtool callbacks.
ena_pci_id_tbl.h    Supported device IDs.
=================   ======================================================

Management Interface:
=====================

ENA management interface is exposed by means of:

- PCIe Configuration Space
- Device Registers
- Admin Queue (AQ) and Admin Completion Queue (ACQ)
- Asynchronous Event Notification Queue (AENQ)

ENA device MMIO Registers are accessed only during driver
initialization and are not used during further normal device
operation.

AQ is used for submitting management commands, and the
results/responses are reported asynchronously through ACQ.

ENA introduces a small set of management commands with room for
vendor-specific extensions. Most of the management operations are
framed in a generic Get/Set feature command.

The following admin queue commands are supported:

- Create I/O submission queue
- Create I/O completion queue
- Destroy I/O submission queue
- Destroy I/O completion queue
- Get feature
- Set feature
- Configure AENQ
- Get statistics

Refer to ena_admin_defs.h for the list of supported Get/Set Feature
properties.

The Asynchronous Event Notification Queue (AENQ) is a uni-directional
queue used by the ENA device to send to the driver events that cannot
be reported using ACQ. AENQ events are subdivided into groups. Each
group may have multiple syndromes, as shown below

The events are:

====================    ===============
Group                   Syndrome
====================    ===============
Link state change       **X**
Fatal error             **X**
Notification            Suspend traffic
Notification            Resume traffic
Keep-Alive              **X**
====================    ===============

ACQ and AENQ share the same MSI-X vector.

Keep-Alive is a special mechanism that allows monitoring the device's health.
A Keep-Alive event is delivered by the device every second.
The driver maintains a watchdog (WD) handler which logs the current state and
statistics. If the keep-alive events aren't delivered as expected the WD resets
the device and the driver.

Data Path Interface
===================

I/O operations are based on Tx and Rx Submission Queues (Tx SQ and Rx
SQ correspondingly). Each SQ has a completion queue (CQ) associated
with it.

The SQs and CQs are implemented as descriptor rings in contiguous
physical memory.

The ENA driver supports two Queue Operation modes for Tx SQs:

- **Regular mode:**
  In this mode the Tx SQs reside in the host's memory. The ENA
  device fetches the ENA Tx descriptors and packet data from host
  memory.

- **Low Latency Queue (LLQ) mode or "push-mode":**
  In this mode the driver pushes the transmit descriptors and the
  first 96 bytes of the packet directly to the ENA device memory
  space. The rest of the packet payload is fetched by the
  device. For this operation mode, the driver uses a dedicated PCI
  device memory BAR, which is mapped with write-combine capability.

  **Note that** not all ENA devices support LLQ, and this feature is negotiated
  with the device upon initialization. If the ENA device does not
  support LLQ mode, the driver falls back to the regular mode.

The Rx SQs support only the regular mode.

The driver supports multi-queue for both Tx and Rx. This has various
benefits:

- Reduced CPU/thread/process contention on a given Ethernet interface.
- Cache miss rate on completion is reduced, particularly for data
  cache lines that hold the sk_buff structures.
- Increased process-level parallelism when handling received packets.
- Increased data cache hit rate, by steering kernel processing of
  packets to the CPU, where the application thread consuming the
  packet is running.
- In hardware interrupt re-direction.

Interrupt Modes
===============

The driver assigns a single MSI-X vector per queue pair (for both Tx
and Rx directions). The driver assigns an additional dedicated MSI-X vector
for management (for ACQ and AENQ).

Management interrupt registration is performed when the Linux kernel
probes the adapter, and it is de-registered when the adapter is
removed. I/O queue interrupt registration is performed when the Linux
interface of the adapter is opened, and it is de-registered when the
interface is closed.

The management interrupt is named::

   ena-mgmnt@pci:<PCI domain:bus:slot.function>

and for each queue pair, an interrupt is named::

   <interface name>-Tx-Rx-<queue index>

The ENA device operates in auto-mask and auto-clear interrupt
modes. That is, once MSI-X is delivered to the host, its Cause bit is
automatically cleared and the interrupt is masked. The interrupt is
unmasked by the driver after NAPI processing is complete.

Interrupt Moderation
====================

ENA driver and device can operate in conventional or adaptive interrupt
moderation mode.

**In conventional mode** the driver instructs device to postpone interrupt
posting according to static interrupt delay value. The interrupt delay
value can be configured through `ethtool(8)`. The following `ethtool`
parameters are supported by the driver: ``tx-usecs``, ``rx-usecs``

**In adaptive interrupt** moderation mode the interrupt delay value is
updated by the driver dynamically and adjusted every NAPI cycle
according to the traffic nature.

Adaptive coalescing can be switched on/off through `ethtool(8)`'s
:code:`adaptive_rx on|off` parameter.

More information about Adaptive Interrupt Moderation (DIM) can be found in
Documentation/networking/net_dim.rst

RX copybreak
============
The rx_copybreak is initialized by default to ENA_DEFAULT_RX_COPYBREAK
and can be configured by the ETHTOOL_STUNABLE command of the
SIOCETHTOOL ioctl.

Statistics
==========

The user can obtain ENA device and driver statistics using `ethtool`.
The driver can collect regular or extended statistics (including
per-queue stats) from the device.

In addition the driver logs the stats to syslog upon device reset.

MTU
===

The driver supports an arbitrarily large MTU with a maximum that is
negotiated with the device. The driver configures MTU using the
SetFeature command (ENA_ADMIN_MTU property). The user can change MTU
via `ip(8)` and similar legacy tools.

Stateless Offloads
==================

The ENA driver supports:

- IPv4 header checksum offload
- TCP/UDP over IPv4/IPv6 checksum offloads

RSS
===

- The ENA device supports RSS that allows flexible Rx traffic
  steering.
- Toeplitz and CRC32 hash functions are supported.
- Different combinations of L2/L3/L4 fields can be configured as
  inputs for hash functions.
- The driver configures RSS settings using the AQ SetFeature command
  (ENA_ADMIN_RSS_HASH_FUNCTION, ENA_ADMIN_RSS_HASH_INPUT and
  ENA_ADMIN_RSS_INDIRECTION_TABLE_CONFIG properties).
- If the NETIF_F_RXHASH flag is set, the 32-bit result of the hash
  function delivered in the Rx CQ descriptor is set in the received
  SKB.
- The user can provide a hash key, hash function, and configure the
  indirection table through `ethtool(8)`.

DATA PATH
=========

Tx
--

:code:`ena_start_xmit()` is called by the stack. This function does the following:

- Maps data buffers (``skb->data`` and frags).
- Populates ``ena_buf`` for the push buffer (if the driver and device are
  in push mode).
- Prepares ENA bufs for the remaining frags.
- Allocates a new request ID from the empty ``req_id`` ring. The request
  ID is the index of the packet in the Tx info. This is used for
  out-of-order Tx completions.
- Adds the packet to the proper place in the Tx ring.
- Calls :code:`ena_com_prepare_tx()`, an ENA communication layer that converts
  the ``ena_bufs`` to ENA descriptors (and adds meta ENA descriptors as
  needed).

  * This function also copies the ENA descriptors and the push buffer
    to the Device memory space (if in push mode).

- Writes a doorbell to the ENA device.
- When the ENA device finishes sending the packet, a completion
  interrupt is raised.
- The interrupt handler schedules NAPI.
- The :code:`ena_clean_tx_irq()` function is called. This function handles the
  completion descriptors generated by the ENA, with a single
  completion descriptor per completed packet.

  * ``req_id`` is retrieved from the completion descriptor. The ``tx_info`` of
    the packet is retrieved via the ``req_id``. The data buffers are
    unmapped and ``req_id`` is returned to the empty ``req_id`` ring.
  * The function stops when the completion descriptors are completed or
    the budget is reached.

Rx
--

- When a packet is received from the ENA device.
- The interrupt handler schedules NAPI.
- The :code:`ena_clean_rx_irq()` function is called. This function calls
  :code:`ena_com_rx_pkt()`, an ENA communication layer function, which returns the
  number of descriptors used for a new packet, and zero if
  no new packet is found.
- :code:`ena_rx_skb()` checks packet length:

  * If the packet is small (len < rx_copybreak), the driver allocates
    a SKB for the new packet, and copies the packet payload into the
    SKB data buffer.

    - In this way the original data buffer is not passed to the stack
      and is reused for future Rx packets.

  * Otherwise the function unmaps the Rx buffer, sets the first
    descriptor as `skb`'s linear part and the other descriptors as the
    `skb`'s frags.

- The new SKB is updated with the necessary information (protocol,
  checksum hw verify result, etc), and then passed to the network
  stack, using the NAPI interface function :code:`napi_gro_receive()`.


code:
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

===============================
Marvell(Aquantia) AQtion Driver
===============================

For the aQuantia Multi-Gigabit PCI Express Family of Ethernet Adapters

.. Contents

    - Identifying Your Adapter
    - Configuration
    - Supported ethtool options
    - Command Line Parameters
    - Config file parameters
    - Support
    - License

Identifying Your Adapter
========================

The driver in this release is compatible with AQC-100, AQC-107, AQC-108
based ethernet adapters.

SFP+ Devices (for AQC-100 based adapters)
-----------------------------------------

This release tested with passive Direct Attach Cables (DAC) and SFP+/LC
Optical Transceiver.

Configuration
=============

Viewing Link Messages
---------------------
  Link messages will not be displayed to the console if the distribution is
  restricting system messages. In order to see network driver link messages on
  your console, set dmesg to eight by entering the following::

       dmesg -n 8

  .. note::

     This setting is not saved across reboots.

Jumbo Frames
------------
  The driver supports Jumbo Frames for all adapters. Jumbo Frames support is
  enabled by changing the MTU to a value larger than the default of 1500.
  The maximum value for the MTU is 16000.  Use the `ip` command to
  increase the MTU size.  For example::

	ip link set mtu 16000 dev enp1s0

ethtool
-------
  The driver utilizes the ethtool interface for driver configuration and
  diagnostics, as well as displaying statistical information. The latest
  ethtool version is required for this functionality.

NAPI
----
  NAPI (Rx polling mode) is supported in the atlantic driver.

Supported ethtool options
=========================

Viewing adapter settings
------------------------

 ::

    ethtool <ethX>

 Output example::

  Settings for enp1s0:
    Supported ports: [ TP ]
    Supported link modes:   100baseT/Full
			    1000baseT/Full
			    10000baseT/Full
			    2500baseT/Full
			    5000baseT/Full
    Supported pause frame use: Symmetric
    Supports auto-negotiation: Yes
    Supported FEC modes: Not reported
    Advertised link modes:  100baseT/Full
			    1000baseT/Full
			    10000baseT/Full
			    2500baseT/Full
			    5000baseT/Full
    Advertised pause frame use: Symmetric
    Advertised auto-negotiation: Yes
    Advertised FEC modes: Not reported
    Speed: 10000Mb/s
    Duplex: Full
    Port: Twisted Pair
    PHYAD: 0
    Transceiver: internal
    Auto-negotiation: on
    MDI-X: Unknown
    Supports Wake-on: g
    Wake-on: d
    Link detected: yes

 .. note::

    AQrate speeds (2.5/5 Gb/s) will be displayed only with linux kernels > 4.10.
    But you can still use these speeds::

	ethtool -s eth0 autoneg off speed 2500

Viewing adapter information
---------------------------

 ::

  ethtool -i <ethX>

 Output example::

  driver: atlantic
  version: 5.2.0-050200rc5-generic-kern
  firmware-version: 3.1.78
  expansion-rom-version:
  bus-info: 0000:01:00.0
  supports-statistics: yes
  supports-test: no
  supports-eeprom-access: no
  supports-register-dump: yes
  supports-priv-flags: no

Viewing Ethernet adapter statistics
-----------------------------------

 ::

    ethtool -S <ethX>

 Output example::

  NIC statistics:
     InPackets: 13238607
     InUCast: 13293852
     InMCast: 52
     InBCast: 3
     InErrors: 0
     OutPackets: 23703019
     OutUCast: 23704941
     OutMCast: 67
     OutBCast: 11
     InUCastOctects: 213182760
     OutUCastOctects: 22698443
     InMCastOctects: 6600
     OutMCastOctects: 8776
     InBCastOctects: 192
     OutBCastOctects: 704
     InOctects: 2131839552
     OutOctects: 226938073
     InPacketsDma: 95532300
     OutPacketsDma: 59503397
     InOctetsDma: 1137102462
     OutOctetsDma: 2394339518
     InDroppedDma: 0
     Queue[0] InPackets: 23567131
     Queue[0] OutPackets: 20070028
     Queue[0] InJumboPackets: 0
     Queue[0] InLroPackets: 0
     Queue[0] InErrors: 0
     Queue[1] InPackets: 45428967
     Queue[1] OutPackets: 11306178
     Queue[1] InJumboPackets: 0
     Queue[1] InLroPackets: 0
     Queue[1] InErrors: 0
     Queue[2] InPackets: 3187011
     Queue[2] OutPackets: 13080381
     Queue[2] InJumboPackets: 0
     Queue[2] InLroPackets: 0
     Queue[2] InErrors: 0
     Queue[3] InPackets: 23349136
     Queue[3] OutPackets: 15046810
     Queue[3] InJumboPackets: 0
     Queue[3] InLroPackets: 0
     Queue[3] InErrors: 0

Interrupt coalescing support
----------------------------

 ITR mode, TX/RX coalescing timings could be viewed with::

    ethtool -c <ethX>

 and changed with::

    ethtool -C <ethX> tx-usecs <usecs> rx-usecs <usecs>

 To disable coalescing::

    ethtool -C <ethX> tx-usecs 0 rx-usecs 0 tx-max-frames 1 tx-max-frames 1

Wake on LAN support
-------------------

 WOL support by magic packet::

    ethtool -s <ethX> wol g

 To disable WOL::

    ethtool -s <ethX> wol d

Set and check the driver message level
--------------------------------------

 Set message level

 ::

    ethtool -s <ethX> msglvl <level>

 Level values:

 ======   =============================
 0x0001   general driver status.
 0x0002   hardware probing.
 0x0004   link state.
 0x0008   periodic status check.
 0x0010   interface being brought down.
 0x0020   interface being brought up.
 0x0040   receive error.
 0x0080   transmit error.
 0x0200   interrupt handling.
 0x0400   transmit completion.
 0x0800   receive completion.
 0x1000   packet contents.
 0x2000   hardware status.
 0x4000   Wake-on-LAN status.
 ======   =============================

 By default, the level of debugging messages is set 0x0001(general driver status).

 Check message level

 ::

    ethtool <ethX> | grep "Current message level"

 If you want to disable the output of messages::

    ethtool -s <ethX> msglvl 0

RX flow rules (ntuple filters)
------------------------------

 There are separate rules supported, that applies in that order:

 1. 16 VLAN ID rules
 2. 16 L2 EtherType rules
 3. 8 L3/L4 5-Tuple rules

 The driver utilizes the ethtool interface for configuring ntuple filters,
 via ``ethtool -N <device> <filter>``.

 To enable or disable the RX flow rules::

    ethtool -K ethX ntuple <on|off>

 When disabling ntuple filters, all the user programed filters are
 flushed from the driver cache and hardware. All needed filters must
 be re-added when ntuple is re-enabled.

 Because of the fixed order of the rules, the location of filters is also fixed:

 - Locations 0 - 15 for VLAN ID filters
 - Locations 16 - 31 for L2 EtherType filters
 - Locations 32 - 39 for L3/L4 5-tuple filters (locations 32, 36 for IPv6)

 The L3/L4 5-tuple (protocol, source and destination IP address, source and
 destination TCP/UDP/SCTP port) is compared against 8 filters. For IPv4, up to
 8 source and destination addresses can be matched. For IPv6, up to 2 pairs of
 addresses can be supported. Source and destination ports are only compared for
 TCP/UDP/SCTP packets.

 To add a filter that directs packet to queue 5, use
 ``<-N|-U|--config-nfc|--config-ntuple>`` switch::

    ethtool -N <ethX> flow-type udp4 src-ip 10.0.0.1 dst-ip 10.0.0.2 src-port 2000 dst-port 2001 action 5 <loc 32>

 - action is the queue number.
 - loc is the rule number.

 For ``flow-type ip4|udp4|tcp4|sctp4|ip6|udp6|tcp6|sctp6`` you must set the loc
 number within 32 - 39.
 For ``flow-type ip4|udp4|tcp4|sctp4|ip6|udp6|tcp6|sctp6`` you can set 8 rules
 for traffic IPv4 or you can set 2 rules for traffic IPv6. Loc number traffic
 IPv6 is 32 and 36.
 At the moment you can not use IPv4 and IPv6 filters at the same time.

 Example filter for IPv6 filter traffic::

    sudo ethtool -N <ethX> flow-type tcp6 src-ip 2001:db8:0:f101::1 dst-ip 2001:db8:0:f101::2 action 1 loc 32
    sudo ethtool -N <ethX> flow-type ip6 src-ip 2001:db8:0:f101::2 dst-ip 2001:db8:0:f101::5 action -1 loc 36

 Example filter for IPv4 filter traffic::

    sudo ethtool -N <ethX> flow-type udp4 src-ip 10.0.0.4 dst-ip 10.0.0.7 src-port 2000 dst-port 2001 loc 32
    sudo ethtool -N <ethX> flow-type tcp4 src-ip 10.0.0.3 dst-ip 10.0.0.9 src-port 2000 dst-port 2001 loc 33
    sudo ethtool -N <ethX> flow-type ip4 src-ip 10.0.0.6 dst-ip 10.0.0.4 loc 34

 If you set action -1, then all traffic corresponding to the filter will be discarded.

 The maximum value action is 31.

 The VLAN filter (VLAN id) is compared against 16 filters.
 VLAN id must be accompanied by mask 0xF000. That is to distinguish VLAN filter
 from L2 Ethertype filter with UserPriority since both User Priority and VLAN ID
 are passed in the same 'vlan' parameter.

 To add a filter that directs packets from VLAN 2001 to queue 5::

    ethtool -N <ethX> flow-type ip4 vlan 2001 m 0xF000 action 1 loc 0

 L2 EtherType filters allows filter packet by EtherType field or both EtherType
 and User Priority (PCP) field of 802.1Q.
 UserPriority (vlan) parameter must be accompanied by mask 0x1FFF. That is to
 distinguish VLAN filter from L2 Ethertype filter with UserPriority since both
 User Priority and VLAN ID are passed in the same 'vlan' parameter.

 To add a filter that directs IP4 packess of priority 3 to queue 3::

    ethtool -N <ethX> flow-type ether proto 0x800 vlan 0x600 m 0x1FFF action 3 loc 16

 To see the list of filters currently present::

    ethtool <-u|-n|--show-nfc|--show-ntuple> <ethX>

 Rules may be deleted from the table itself. This is done using::

    sudo ethtool <-N|-U|--config-nfc|--config-ntuple> <ethX> delete <loc>

 - loc is the rule number to be deleted.

 Rx filters is an interface to load the filter table that funnels all flow
 into queue 0 unless an alternative queue is specified using "action". In that
 case, any flow that matches the filter criteria will be directed to the
 appropriate queue. RX filters is supported on all kernels 2.6.30 and later.

RSS for UDP
-----------

 Currently, NIC does not support RSS for fragmented IP packets, which leads to
 incorrect working of RSS for fragmented UDP traffic. To disable RSS for UDP the
 RX Flow L3/L4 rule may be used.

 Example::

    ethtool -N eth0 flow-type udp4 action 0 loc 32

UDP GSO hardware offload
------------------------

 UDP GSO allows to boost UDP tx rates by offloading UDP headers allocation
 into hardware. A special userspace socket option is required for this,
 could be validated with /kernel/tools/testing/selftests/net/::

    udpgso_bench_tx -u -4 -D 10.0.1.1 -s 6300 -S 100

 Will cause sending out of 100 byte sized UDP packets formed from single
 6300 bytes user buffer.

 UDP GSO is configured by::

    ethtool -K eth0 tx-udp-segmentation on

Private flags (testing)
-----------------------

 Atlantic driver supports private flags for hardware custom features::

	$ ethtool --show-priv-flags ethX

	Private flags for ethX:
	DMASystemLoopback  : off
	PKTSystemLoopback  : off
	DMANetworkLoopback : off
	PHYInternalLoopback: off
	PHYExternalLoopback: off

 Example::

	$ ethtool --set-priv-flags ethX DMASystemLoopback on

 DMASystemLoopback:   DMA Host loopback.
 PKTSystemLoopback:   Packet buffer host loopback.
 DMANetworkLoopback:  Network side loopback on DMA block.
 PHYInternalLoopback: Internal loopback on Phy.
 PHYExternalLoopback: External loopback on Phy (with loopback ethernet cable).

Command Line Parameters
=======================
The following command line parameters are available on atlantic driver:

aq_itr -Interrupt throttling mode
---------------------------------
Accepted values: 0, 1, 0xFFFF

Default value: 0xFFFF

======   ==============================================================
0        Disable interrupt throttling.
1        Enable interrupt throttling and use specified tx and rx rates.
0xFFFF   Auto throttling mode. Driver will choose the best RX and TX
	 interrupt throtting settings based on link speed.
======   ==============================================================

aq_itr_tx - TX interrupt throttle rate
--------------------------------------

Accepted values: 0 - 0x1FF

Default value: 0

TX side throttling in microseconds. Adapter will setup maximum interrupt delay
to this value. Minimum interrupt delay will be a half of this value

aq_itr_rx - RX interrupt throttle rate
--------------------------------------

Accepted values: 0 - 0x1FF

Default value: 0

RX side throttling in microseconds. Adapter will setup maximum interrupt delay
to this value. Minimum interrupt delay will be a half of this value

.. note::

   ITR settings could be changed in runtime by ethtool -c means (see below)

Config file parameters
======================

For some fine tuning and performance optimizations,
some parameters can be changed in the {source_dir}/aq_cfg.h file.

AQ_CFG_RX_PAGEORDER
-------------------

Default value: 0

RX page order override. Thats a power of 2 number of RX pages allocated for
each descriptor. Received descriptor size is still limited by
AQ_CFG_RX_FRAME_MAX.

Increasing pageorder makes page reuse better (actual on iommu enabled systems).

AQ_CFG_RX_REFILL_THRES
----------------------

Default value: 32

RX refill threshold. RX path will not refill freed descriptors until the
specified number of free descriptors is observed. Larger values may help
better page reuse but may lead to packet drops as well.

AQ_CFG_VECS_DEF
---------------

Number of queues

Valid Range: 0 - 8 (up to AQ_CFG_VECS_MAX)

Default value: 8

Notice this value will be capped by the number of cores available on the system.

AQ_CFG_IS_RSS_DEF
-----------------

Enable/disable Receive Side Scaling

This feature allows the adapter to distribute receive processing
across multiple CPU-cores and to prevent from overloading a single CPU core.

Valid values

==  ========
0   disabled
1   enabled
==  ========

Default value: 1

AQ_CFG_NUM_RSS_QUEUES_DEF
-------------------------

Number of queues for Receive Side Scaling

Valid Range: 0 - 8 (up to AQ_CFG_VECS_DEF)

Default value: AQ_CFG_VECS_DEF

AQ_CFG_IS_LRO_DEF
-----------------

Enable/disable Large Receive Offload

This offload enables the adapter to coalesce multiple TCP segments and indicate
them as a single coalesced unit to the OS networking subsystem.

The system consumes less energy but it also introduces more latency in packets
processing.

Valid values

==  ========
0   disabled
1   enabled
==  ========

Default value: 1

AQ_CFG_TX_CLEAN_BUDGET
----------------------

Maximum descriptors to cleanup on TX at once.

Default value: 256

After the aq_cfg.h file changed the driver must be rebuilt to take effect.

Support
=======

If an issue is identified with the released source code on the supported
kernel with a supported adapter, email the specific information related
to the issue to aqn_support@marvell.com

License
=======

aQuantia Corporation Network Driver

Copyright |copy| 2014 - 2019 aQuantia Corporation.

This program is free software; you can redistribute it and/or modify it
under the terms and conditions of the GNU General Public License,
version 2, as published by the Free Software Foundation.


code:
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

=============================================
Chelsio N210 10Gb Ethernet Network Controller
=============================================

Driver Release Notes for Linux

Version 2.1.1

June 20, 2005

.. Contents

 INTRODUCTION
 FEATURES
 PERFORMANCE
 DRIVER MESSAGES
 KNOWN ISSUES
 SUPPORT

Introduction
============

 This document describes the Linux driver for Chelsio 10Gb Ethernet Network
 Controller. This driver supports the Chelsio N210 NIC and is backward
 compatible with the Chelsio N110 model 10Gb NICs.

Features
========

Adaptive Interrupts (adaptive-rx)
---------------------------------

  This feature provides an adaptive algorithm that adjusts the interrupt
  coalescing parameters, allowing the driver to dynamically adapt the latency
  settings to achieve the highest performance during various types of network
  load.

  The interface used to control this feature is ethtool. Please see the
  ethtool manpage for additional usage information.

  By default, adaptive-rx is disabled.
  To enable adaptive-rx::

      ethtool -C <interface> adaptive-rx on

  To disable adaptive-rx, use ethtool::

      ethtool -C <interface> adaptive-rx off

  After disabling adaptive-rx, the timer latency value will be set to 50us.
  You may set the timer latency after disabling adaptive-rx::

      ethtool -C <interface> rx-usecs <microseconds>

  An example to set the timer latency value to 100us on eth0::

      ethtool -C eth0 rx-usecs 100

  You may also provide a timer latency value while disabling adaptive-rx::

      ethtool -C <interface> adaptive-rx off rx-usecs <microseconds>

  If adaptive-rx is disabled and a timer latency value is specified, the timer
  will be set to the specified value until changed by the user or until
  adaptive-rx is enabled.

  To view the status of the adaptive-rx and timer latency values::

      ethtool -c <interface>

TCP Segmentation Offloading (TSO) Support
-----------------------------------------

  This feature, also known as "large send", enables a system's protocol stack
  to offload portions of outbound TCP processing to a network interface card
  thereby reducing system CPU utilization and enhancing performance.

  The interface used to control this feature is ethtool version 1.8 or higher.
  Please see the ethtool manpage for additional usage information.

  By default, TSO is enabled.
  To disable TSO::

      ethtool -K <interface> tso off

  To enable TSO::

      ethtool -K <interface> tso on

  To view the status of TSO::

      ethtool -k <interface>

Performance
===========

 The following information is provided as an example of how to change system
 parameters for "performance tuning" an what value to use. You may or may not
 want to change these system parameters, depending on your server/workstation
 application. Doing so is not warranted in any way by Chelsio Communications,
 and is done at "YOUR OWN RISK". Chelsio will not be held responsible for loss
 of data or damage to equipment.

 Your distribution may have a different way of doing things, or you may prefer
 a different method. These commands are shown only to provide an example of
 what to do and are by no means definitive.

 Making any of the following system changes will only last until you reboot
 your system. You may want to write a script that runs at boot-up which
 includes the optimal settings for your system.

  Setting PCI Latency Timer::

      setpci -d 1425::

* 0x0c.l=0x0000F800

  Disabling TCP timestamp::

      sysctl -w net.ipv4.tcp_timestamps=0

  Disabling SACK::

      sysctl -w net.ipv4.tcp_sack=0

  Setting large number of incoming connection requests::

      sysctl -w net.ipv4.tcp_max_syn_backlog=3000

  Setting maximum receive socket buffer size::

      sysctl -w net.core.rmem_max=1024000

  Setting maximum send socket buffer size::

      sysctl -w net.core.wmem_max=1024000

  Set smp_affinity (on a multiprocessor system) to a single CPU::

      echo 1 > /proc/irq/<interrupt_number>/smp_affinity

  Setting default receive socket buffer size::

      sysctl -w net.core.rmem_default=524287

  Setting default send socket buffer size::

      sysctl -w net.core.wmem_default=524287

  Setting maximum option memory buffers::

      sysctl -w net.core.optmem_max=524287

  Setting maximum backlog (# of unprocessed packets before kernel drops)::

      sysctl -w net.core.netdev_max_backlog=300000

  Setting TCP read buffers (min/default/max)::

      sysctl -w net.ipv4.tcp_rmem="10000000 10000000 10000000"

  Setting TCP write buffers (min/pressure/max)::

      sysctl -w net.ipv4.tcp_wmem="10000000 10000000 10000000"

  Setting TCP buffer space (min/pressure/max)::

      sysctl -w net.ipv4.tcp_mem="10000000 10000000 10000000"

  TCP window size for single connections:

   The receive buffer (RX_WINDOW) size must be at least as large as the
   Bandwidth-Delay Product of the communication link between the sender and
   receiver. Due to the variations of RTT, you may want to increase the buffer
   size up to 2 times the Bandwidth-Delay Product. Reference page 289 of
   "TCP/IP Illustrated, Volume 1, The Protocols" by W. Richard Stevens.

   At 10Gb speeds, use the following formula::

       RX_WINDOW >= 1.25MBytes * RTT(in milliseconds)
       Example for RTT with 100us: RX_WINDOW = (1,250,000 * 0.1) = 125,000

   RX_WINDOW sizes of 256KB - 512KB should be sufficient.

   Setting the min, max, and default receive buffer (RX_WINDOW) size::

       sysctl -w net.ipv4.tcp_rmem="<min> <default> <max>"

  TCP window size for multiple connections:
   The receive buffer (RX_WINDOW) size may be calculated the same as single
   connections, but should be divided by the number of connections. The
   smaller window prevents congestion and facilitates better pacing,
   especially if/when MAC level flow control does not work well or when it is
   not supported on the machine. Experimentation may be necessary to attain
   the correct value. This method is provided as a starting point for the
   correct receive buffer size.

   Setting the min, max, and default receive buffer (RX_WINDOW) size is
   performed in the same manner as single connection.

Driver Messages
===============

 The following messages are the most common messages logged by syslog. These
 may be found in /var/log/messages.

  Driver up::

     Chelsio Network Driver - version 2.1.1

  NIC detected::

     eth#: Chelsio N210 1x10GBaseX NIC (rev #), PCIX 133MHz/64-bit

  Link up::

     eth#: link is up at 10 Gbps, full duplex

  Link down::

     eth#: link is down

Known Issues
============

 These issues have been identified during testing. The following information
 is provided as a workaround to the problem. In some cases, this problem is
 inherent to Linux or to a particular Linux Distribution and/or hardware
 platform.

  1. Large number of TCP retransmits on a multiprocessor (SMP) system.

      On a system with multiple CPUs, the interrupt (IRQ) for the network
      controller may be bound to more than one CPU. This will cause TCP
      retransmits if the packet data were to be split across different CPUs
      and re-assembled in a different order than expected.

      To eliminate the TCP retransmits, set smp_affinity on the particular
      interrupt to a single CPU. You can locate the interrupt (IRQ) used on
      the N110/N210 by using ifconfig::

	  ifconfig <dev_name> | grep Interrupt

      Set the smp_affinity to a single CPU::

	  echo 1 > /proc/irq/<interrupt_number>/smp_affinity

      It is highly suggested that you do not run the irqbalance daemon on your
      system, as this will change any smp_affinity setting you have applied.
      The irqbalance daemon runs on a 10 second interval and binds interrupts
      to the least loaded CPU determined by the daemon. To disable this daemon::

	  chkconfig --level 2345 irqbalance off

      By default, some Linux distributions enable the kernel feature,
      irqbalance, which performs the same function as the daemon. To disable
      this feature, add the following line to your bootloader::

	  noirqbalance

	  Example using the Grub bootloader::

	      title Red Hat Enterprise Linux AS (2.4.21-27.ELsmp)
	      root (hd0,0)
	      kernel /vmlinuz-2.4.21-27.ELsmp ro root=/dev/hda3 noirqbalance
	      initrd /initrd-2.4.21-27.ELsmp.img

  2. After running insmod, the driver is loaded and the incorrect network
     interface is brought up without running ifup.

      When using 2.4.x kernels, including RHEL kernels, the Linux kernel
      invokes a script named "hotplug". This script is primarily used to
      automatically bring up USB devices when they are plugged in, however,
      the script also attempts to automatically bring up a network interface
      after loading the kernel module. The hotplug script does this by scanning
      the ifcfg-eth# config files in /etc/sysconfig/network-scripts, looking
      for HWADDR=<mac_address>.

      If the hotplug script does not find the HWADDRR within any of the
      ifcfg-eth# files, it will bring up the device with the next available
      interface name. If this interface is already configured for a different
      network card, your new interface will have incorrect IP address and
      network settings.

      To solve this issue, you can add the HWADDR=<mac_address> key to the
      interface config file of your network controller.

      To disable this "hotplug" feature, you may add the driver (module name)
      to the "blacklist" file located in /etc/hotplug. It has been noted that
      this does not work for network devices because the net.agent script
      does not use the blacklist file. Simply remove, or rename, the net.agent
      script located in /etc/hotplug to disable this feature.

  3. Transport Protocol (TP) hangs when running heavy multi-connection traffic
     on an AMD Opteron system with HyperTransport PCI-X Tunnel chipset.

      If your AMD Opteron system uses the AMD-8131 HyperTransport PCI-X Tunnel
      chipset, you may experience the "133-Mhz Mode Split Completion Data
      Corruption" bug identified by AMD while using a 133Mhz PCI-X card on the
      bus PCI-X bus.

      AMD states, "Under highly specific conditions, the AMD-8131 PCI-X Tunnel
      can provide stale data via split completion cycles to a PCI-X card that
      is operating at 133 Mhz", causing data corruption.

      AMD's provides three workarounds for this problem, however, Chelsio
      recommends the first option for best performance with this bug:

	For 133Mhz secondary bus operation, limit the transaction length and
	the number of outstanding transactions, via BIOS configuration
	programming of the PCI-X card, to the following:

	   Data Length (bytes): 1k

	   Total allowed outstanding transactions: 2

      Please refer to AMD 8131-HT/PCI-X Errata 26310 Rev 3.08 August 2004,
      section 56, "133-MHz Mode Split Completion Data Corruption" for more
      details with this bug and workarounds suggested by AMD.

      It may be possible to work outside AMD's recommended PCI-X settings, try
      increasing the Data Length to 2k bytes for increased performance. If you
      have issues with these settings, please revert to the "safe" settings
      and duplicate the problem before submitting a bug or asking for support.

      .. note::

	    The default setting on most systems is 8 outstanding transactions
	    and 2k bytes data length.

  4. On multiprocessor systems, it has been noted that an application which
     is handling 10Gb networking can switch between CPUs causing degraded
     and/or unstable performance.

      If running on an SMP system and taking performance measurements, it
      is suggested you either run the latest netperf-2.4.0+ or use a binding
      tool such as Tim Hockin's procstate utilities (runon)
      <http://www.hockin.org/~thockin/procstate/>.

      Binding netserver and netperf (or other applications) to particular
      CPUs will have a significant difference in performance measurements.
      You may need to experiment which CPU to bind the application to in
      order to achieve the best performance for your system.

      If you are developing an application designed for 10Gb networking,
      please keep in mind you may want to look at kernel functions
      sched_setaffinity & sched_getaffinity to bind your application.

      If you are just running user-space applications such as ftp, telnet,
      etc., you may want to try the runon tool provided by Tim Hockin's
      procstate utility. You could also try binding the interface to a
      particular CPU: runon 0 ifup eth0

Support
=======

 If you have problems with the software or hardware, please contact our
 customer support team via email at support@chelsio.com or check our website
 at http://www.chelsio.com

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

::

 Chelsio Communications
 370 San Aleso Ave.
 Suite 100
 Sunnyvale, CA 94085
 http://www.chelsio.com

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License, version 2, as
published by the Free Software Foundation.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

THIS SOFTWARE IS PROVIDED ``AS IS`` AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Copyright |copy| 2003-2005 Chelsio Communications. All rights reserved.


code:
.. SPDX-License-Identifier: GPL-2.0

================================================
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.

Linux Network Interface Driver ver. 2.00 <kernel 2.3.48>

.. TABLE OF CONTENTS

   1.0 CIRRUS LOGIC LAN CS8900/CS8920 ETHERNET ADAPTERS
	1.1 Product Overview
	1.2 Driver Description
	    1.2.1 Driver Name
	    1.2.2 File in the Driver Package
	1.3 System Requirements
	1.4 Licensing Information

   2.0 ADAPTER INSTALLATION and CONFIGURATION
	2.1 CS8900-based Adapter Configuration
	2.2 CS8920-based Adapter Configuration

   3.0 LOADING THE DRIVER AS A MODULE

   4.0 COMPILING THE DRIVER
	4.1 Compiling the Driver as a Loadable Module
	4.2 Compiling the driver to support memory mode
	4.3 Compiling the driver to support Rx DMA

   5.0 TESTING AND TROUBLESHOOTING
	5.1 Known Defects and Limitations
	5.2 Testing the Adapter
	    5.2.1 Diagnostic Self-Test
	    5.2.2 Diagnostic Network Test
	5.3 Using the Adapter's LEDs
	5.4 Resolving I/O Conflicts

   6.0 TECHNICAL SUPPORT
	6.1 Contacting Cirrus Logic's Technical Support
	6.2 Information Required Before Contacting Technical Support
	6.3 Obtaining the Latest Driver Version
	6.4 Current maintainer
	6.5 Kernel boot parameters

1. Cirrus Logic LAN CS8900/CS8920 Ethernet Adapters
===================================================

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
computers on 10 Mbps Ethernet networks.  The adapters are designed for operation
in 16-bit ISA or EISA bus expansion slots and are available in
10BaseT-only or 3-media configurations (10BaseT, 10Base2, and AUI for 10Base-5
or fiber networks).

CS8920-based adapters are similar to the CS8900-based adapter with additional
features for Plug and Play (PnP) support and Wakeup Frame recognition.  As
such, the configuration procedures differ somewhat between the two types of
adapters.  Refer to the "Adapter Configuration" section for details on
configuring both types of adapters.

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
or loaded at run-time as a device driver module.

1.2.1 Driver Name: cs89x0

1.2.2 Files in the Driver Archive:

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.
  ===================  ====================================================

1.3. System Requirements
------------------------

The following hardware is required:

   * Cirrus Logic LAN (CS8900/20-based) Ethernet ISA Adapter

   * IBM or IBM-compatible PC with:
     * An 80386 or higher processor
     * 16 bytes of contiguous IO space available between 210h - 370h
     * One available IRQ (5,10,11,or 12 for the CS8900, 3-7,9-15 for CS8920).

   * Appropriate cable (and connector for AUI, 10BASE-2) for your network
     topology.

The following software is required:

* LINUX kernel version 2.3.48 or higher

   * CS8900/20 Setup Utility (DOS-based)

   * LINUX kernel sources for your kernel (if compiling into kernel)

   * GNU Toolkit (gcc and make) v2.6 or above (if compiling into kernel
     or a module)

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
Foundation, version 1.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

For a full copy of the GNU General Public License, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

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
Utility if you want to change the adapter's configuration in EEPROM.

When loading the driver as a module, you can specify many of the adapter's
configuration parameters on the command-line to override the EEPROM's settings
or for interface configuration when an EEPROM is not used. (CS8920-based
adapters must use an EEPROM.) See Section 3.0 LOADING THE DRIVER AS A MODULE.

Since the CS8900/20 Setup Utility is a DOS-based application, you must install
and configure the adapter in a DOS-based system using the CS8900/20 Setup
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
---------------------------------------

CS8900-based adapters shipped from Cirrus Logic have been configured
with the following "default" settings::

  Operation Mode:      Memory Mode
  IRQ:                 10
  Base I/O Address:    300
  Memory Base Address: D0000
  Optimization:	       DOS Client
  Transmission Mode:   Half-duplex
  BootProm:            None
  Media Type:	       Autodetect (3-media cards) or
		       10BASE-T (10BASE-T only adapter)

You should only change the default configuration settings if conflicts with
another adapter exists. To change the adapter's configuration, run the
CS8900/20 Setup Utility.

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
support PnP, you must install the CS8920 adapter in a DOS-based PC and
run the CS8900/20 Setup Utility to disable PnP and configure the
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:                    *
	*                                                              *
	* CS8920-BASED ADAPTERS ARE PLUG and PLAY ENABLED BY DEFAULT.  *
	* THE CS89X0 DRIVER DOES NOT SUPPORT PnP. THEREFORE, YOU MUST  *
	* RUN THE CS8900/20 SETUP UTILITY TO DISABLE PnP SUPPORT AND   *
	* TO ACTIVATE THE ADAPTER.                                     *
	****************************************************************

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
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::

    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::

  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
   or media=bnc
   or media=aui
   or media=auto
  duplex=full          - specify forced half/full/autonegotiate duplex
   or duplex=half
   or duplex=auto
  debug=#              - debug level (only available if the driver was compiled
			 for debugging)

**Notes:**

a) If an EEPROM is present, any specified command-line parameter
   will override the corresponding configuration value stored in
   EEPROM.

b) The "io" parameter must be specified on the command-line.

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
   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
   not sure that there is a cs89x0 card at the provided address.

   For example, to scan for an adapter located at IO base 0x300,
   specify an IO address of 0x301.

d) The "duplex=auto" parameter is only supported for the CS8920.

e) The minimum command-line configuration required if an EEPROM is
   not present is:

   io
   irq
   media type (no autodetect)

f) The following additional parameters are CS89XX defaults (values
   used with no EEPROM or command-line argument).

   * DMA Burst = enabled
   * IOCHRDY Enabled = enabled
   * UseSA = enabled
   * CS8900 defaults to half-duplex if not specified on command-line
   * CS8920 defaults to autoneg if not specified on command-line
   * Use reset defaults for other config parameters
   * dma_mode = 0

g) You can use ifconfig to set the adapter's Ethernet address.

h) Many Linux distributions use the 'modprobe' command to load
   modules.  This program uses the '/etc/conf.modules' file to
   determine configuration information which is passed to a driver
   module when it is loaded.  All the configuration options which are
   described above may be placed within /etc/conf.modules.

   For example::

     > cat /etc/conf.modules
     ...
     alias eth0 cs89x0
     options cs89x0 io=0x0200 dma=5 use_dma=1
     ...

   In this example we are telling the module system that the
   ethernet driver for this machine should use the cs89x0 driver.  We
   are asking 'modprobe' to pass the 'io', 'dma' and 'use_dma'
   arguments to the driver when it is loaded.

i) Cirrus recommend that the cs89x0 use the ISA DMA channels 5, 6 or
   7.  You will probably find that other DMA channels will not work.

j) The cs89x0 supports DMA for receiving only.  DMA mode is
   significantly more efficient.  Flooding a 400 MHz Celeron machine
   with large ping packets consumes 82% of its CPU capacity in non-DMA
   mode.  With DMA this is reduced to 45%.

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::

     cat /proc/isapnp

l) If during DMA operation you find erratic behavior or network data
   corruption you should use your PC's BIOS to slow the EISA bus clock.

m) If the cs89x0 driver is compiled directly into the kernel
   (non-modular) then its I/O address is automatically determined by
   ISA bus probing.  The IRQ number, media options, etc are determined
   from the card's EEPROM.

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::

	LILO boot: linux cs89x0_dma=5

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

	image=/boot/bzImage-2.3.48
	  append="cs89x0_dma=5"
	  label=linux
	  root=/dev/hda5
	  read-only

   The DMA Rx buffer size is hardwired to 16 kbytes in this mode.
   (64k mode is not available).

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 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. Testing and Troubleshooting
==============================

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
------------------------

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
adapter and its network connection.  Use the diagnostics 'Self Test' option to
test the functionality of the adapter with the hardware configuration you have
assigned. You can use the diagnostics 'Network Test' to test the ability of the
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
	 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.

   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.
       * 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
     assignment. (Test only applies if the adapter is configured to use the
     Boot PROM option.)

Failure of a test item indicates a possible system resource conflict with
another device on the ISA bus.  In this case, you should use the Manual Setup
option to reconfigure the adapter by selecting a different value for the system
resource that failed.

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
on the same network. (Note: the diagnostic network test should not be run
between two nodes across a router.)

This test requires that each of the two PCs have a CS8900/20-based adapter
installed and have the CS8900/20 Setup Utility running.  The first PC is
configured as a Responder and the other PC is configured as an Initiator.
Once the Initiator is started, it sends data frames to the Responder which
returns the frames to the Initiator.

The total number of frames received and transmitted are displayed on the
Initiator's display, along with a count of the number of frames received and
transmitted OK or in error.  The test can be terminated anytime by the user at
either PC.

To setup the Diagnostic Network Test:

    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
	start the CS8900/20 Setup Utility.

    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
to continue running.  In this manner, you can move to additional PCs and test
them by starting the Initiator on another PC without having to stop/start the
Responder.

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.

Link Integrity LED: A "steady" ON of the green LED indicates a valid 10Base-T
connection.  (Only applies to 10Base-T.  The green LED has no significance for
a 10Base-2 or AUI connection.)

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
----------------------------

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).

    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.

    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.

If an IO conflict occurs, run the CS8900/20 Setup Utility and perform a
diagnostic self-test.  Normally, the ISA resource in conflict will fail the
self-test.  If so, reconfigure the adapter selecting another choice for the
resource in conflict.  Run the diagnostics again to check for further IO
conflicts.

In some cases, such as when the PC will not boot, it may be necessary to remove
the adapter and reconfigure it by installing it in another PC to run the
CS8900/20 Setup Utility.  Once reinstalled in the target system, run the
diagnostics self-test to ensure the new configuration is free of conflicts
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
     230-23F       	Bus Mouse                      4       COM1
     270-27F       	LPT3: third parallel port      5       LPT2
     2F0-2FF       	COM2: second serial port       6       Floppy Disk controller
     320-32F       	Fixed disk controller          7       LPT1
							 8       Real-time Clock
						     9       EGA/VGA display adapter
						    12       Mouse (PS/2)
  Memory Address  Device                          13       Math Coprocessor
  --------------  ---------------------           14       Hard Disk controller
  A000-BFFF	EGA Graphics Adapter
  A000-C7FF	VGA Graphics Adapter
  B000-BFFF	Mono Graphics Adapter
  B800-BFFF	Color Graphics Adapter
  E000-FFFF	AT BIOS

6. Technical Support
====================

6.1. Contacting Cirrus Logic's Technical Support
------------------------------------------------

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)
  Fax        :(512) 912-3871
  Email      :ethernet@crystal.cirrus.com
  WWW        :http://www.cirrus.com

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.

1.) Adapter type (CRD8900, CDB8900, CDB8920, etc.)

2.) Adapter configuration

    * IO Base, Memory Base, IO or memory mode enabled, IRQ, DMA channel
    * Plug and Play enabled/disabled (CS8920-based adapters only)
    * Configured for media auto-detect or specific media type (which type).

3.) PC System's Configuration

    * Plug and Play system (yes/no)
    * BIOS (make and version)
    * System make and model
    * CPU (type and speed)
    * System RAM
    * SCSI Adapter

4.) Software

    * CS89XX driver and version
    * Your network operating system and version
    * Your system's OS version
    * Version of all protocol support files

5.) Any Error Message displayed.

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:
ethernet@crystal.cirrus.com) and request that you be registered for automatic
software-update notification.

Cirrus Logic maintains a web page at http://www.cirrus.com with the
latest drivers and technical publications.

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::

	cs89x0_media=rj45    or
	cs89x0_media=aui     or
	cs89x0_media=bnc


code:
.. SPDX-License-Identifier: GPL-2.0

=====================
DM9000 Network driver
=====================

Copyright 2008 Simtec Electronics,

	  Ben Dooks <ben@simtec.co.uk> <ben-linux@fluff.org>

Introduction
------------

This file describes how to use the DM9000 platform-device based network driver
that is contained in the files drivers/net/dm9000.c and drivers/net/dm9000.h.

The driver supports three DM9000 variants, the DM9000E which is the first chip
supported as well as the newer DM9000A and DM9000B devices. It is currently
maintained and tested by Ben Dooks, who should be CC: to any patches for this
driver.

Defining the platform device
----------------------------

The minimum set of resources attached to the platform device are as follows:

    1) The physical address of the address register
    2) The physical address of the data register
    3) The IRQ line the device's interrupt pin is connected to.

These resources should be specified in that order, as the ordering of the
two address regions is important (the driver expects these to be address
and then data).

An example from arch/arm/mach-s3c/mach-bast.c is::

  static struct resource bast_dm9k_resource[] = {
	[0] = {
		.start = S3C2410_CS5 + BAST_PA_DM9000,
		.end   = S3C2410_CS5 + BAST_PA_DM9000 + 3,
		.flags = IORESOURCE_MEM,
	},
	[1] = {
		.start = S3C2410_CS5 + BAST_PA_DM9000 + 0x40,
		.end   = S3C2410_CS5 + BAST_PA_DM9000 + 0x40 + 0x3f,
		.flags = IORESOURCE_MEM,
	},
	[2] = {
		.start = IRQ_DM9000,
		.end   = IRQ_DM9000,
		.flags = IORESOURCE_IRQ | IORESOURCE_IRQ_HIGHLEVEL,
	}
  };

  static struct platform_device bast_device_dm9k = {
	.name		= "dm9000",
	.id		= 0,
	.num_resources	= ARRAY_SIZE(bast_dm9k_resource),
	.resource	= bast_dm9k_resource,
  };

Note the setting of the IRQ trigger flag in bast_dm9k_resource[2].flags,
as this will generate a warning if it is not present. The trigger from
the flags field will be passed to request_irq() when registering the IRQ
handler to ensure that the IRQ is setup correctly.

This shows a typical platform device, without the optional configuration
platform data supplied. The next example uses the same resources, but adds
the optional platform data to pass extra configuration data::

  static struct dm9000_plat_data bast_dm9k_platdata = {
	.flags		= DM9000_PLATF_16BITONLY,
  };

  static struct platform_device bast_device_dm9k = {
	.name		= "dm9000",
	.id		= 0,
	.num_resources	= ARRAY_SIZE(bast_dm9k_resource),
	.resource	= bast_dm9k_resource,
	.dev		= {
		.platform_data = &bast_dm9k_platdata,
	}
  };

The platform data is defined in include/linux/dm9000.h and described below.

Platform data
-------------

Extra platform data for the DM9000 can describe the IO bus width to the
device, whether or not an external PHY is attached to the device and
the availability of an external configuration EEPROM.

The flags for the platform data .flags field are as follows:

DM9000_PLATF_8BITONLY

	The IO should be done with 8bit operations.

DM9000_PLATF_16BITONLY

	The IO should be done with 16bit operations.

DM9000_PLATF_32BITONLY

	The IO should be done with 32bit operations.

DM9000_PLATF_EXT_PHY

	The chip is connected to an external PHY.

DM9000_PLATF_NO_EEPROM

	This can be used to signify that the board does not have an
	EEPROM, or that the EEPROM should be hidden from the user.

DM9000_PLATF_SIMPLE_PHY

	Switch to using the simpler PHY polling method which does not
	try and read the MII PHY state regularly. This is only available
	when using the internal PHY. See the section on link state polling
	for more information.

	The config symbol DM9000_FORCE_SIMPLE_PHY_POLL, Kconfig entry
	"Force simple NSR based PHY polling" allows this flag to be
	forced on at build time.

PHY Link state polling
----------------------

The driver keeps track of the link state and informs the network core
about link (carrier) availability. This is managed by several methods
depending on the version of the chip and on which PHY is being used.

For the internal PHY, the original (and currently default) method is
to read the MII state, either when the status changes if we have the
necessary interrupt support in the chip or every two seconds via a
periodic timer.

To reduce the overhead for the internal PHY, there is now the option
of using the DM9000_FORCE_SIMPLE_PHY_POLL config, or DM9000_PLATF_SIMPLE_PHY
platform data option to read the summary information without the
expensive MII accesses. This method is faster, but does not print
as much information.

When using an external PHY, the driver currently has to poll the MII
link status as there is no method for getting an interrupt on link change.

DM9000A / DM9000B
-----------------

These chips are functionally similar to the DM9000E and are supported easily
by the same driver. The features are:

   1) Interrupt on internal PHY state change. This means that the periodic
      polling of the PHY status may be disabled on these devices when using
      the internal PHY.

   2) TCP/UDP checksum offloading, which the driver does not currently support.

ethtool
-------

The driver supports the ethtool interface for access to the driver
state information, the PHY state and the EEPROM.


code:
.. SPDX-License-Identifier: GPL-2.0

==============================================================
Davicom DM9102(A)/DM9132/DM9801 fast ethernet driver for Linux
==============================================================

Note: This driver doesn't have a maintainer.

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 Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

This driver provides kernel support for Davicom DM9102(A)/DM9132/DM9801 ethernet cards ( CNET
10/100 ethernet cards uses Davicom chipset too, so this driver supports CNET cards too ).If you
didn't compile this driver as a module, it will automatically load itself on boot and print a
line similar to::

	dmfe: Davicom DM9xxx net driver, version 1.36.4 (2002-01-17)

If you compiled this driver as a module, you have to load it on boot.You can load it with command::

	insmod dmfe

This way it will autodetect the device mode.This is the suggested way to load the module.Or you can pass
a mode= setting to module while loading, like::

	insmod dmfe mode=0 # Force 10M Half Duplex
	insmod dmfe mode=1 # Force 100M Half Duplex
	insmod dmfe mode=4 # Force 10M Full Duplex
	insmod dmfe mode=5 # Force 100M Full Duplex

Next you should configure your network interface with a command similar to::

	ifconfig eth0 172.22.3.18
		      ^^^^^^^^^^^
		     Your IP Address

Then you may have to modify the default routing table with command::

	route add default eth0

Now your ethernet card should be up and running.

TODO:

- Implement pci_driver::suspend() and pci_driver::resume() power management methods.
- Check on 64 bit boxes.
- Check and fix on big endian boxes.
- Test and make sure PCI latency is now correct for all cases.

Authors:

Sten Wang <sten_wang@davicom.com.tw >   : Original Author

Contributors:

- Marcelo Tosatti <marcelo@conectiva.com.br>
- Alan Cox <alan@lxorguk.ukuu.org.uk>
- Jeff Garzik <jgarzik@pobox.com>
- Vojtech Pavlik <vojtech@suse.cz>