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

=========================================================
D-Link DL2000-based Gigabit Ethernet Adapter Installation
=========================================================

May 23, 2002

.. Contents

 - Compatibility List
 - Quick Install
 - Compiling the Driver
 - Installing the Driver
 - Option parameter
 - Configuration Script Sample
 - Troubleshooting

Compatibility List
==================

Adapter Support:

- D-Link DGE-550T Gigabit Ethernet Adapter.
- D-Link DGE-550SX Gigabit Ethernet Adapter.
- D-Link DL2000-based Gigabit Ethernet Adapter.

The driver support Linux kernel 2.4.7 later. We had tested it
on the environments below.

 . Red Hat v6.2 (update kernel to 2.4.7)
 . Red Hat v7.0 (update kernel to 2.4.7)
 . Red Hat v7.1 (kernel 2.4.7)
 . Red Hat v7.2 (kernel 2.4.7-10)

Quick Install
=============
Install linux driver as following command::

    1. make all
    2. insmod dl2k.ko
    3. ifconfig eth0 up 10.xxx.xxx.xxx netmask 255.0.0.0
			^^^^^^^^^^^^^^^\	    ^^^^^^^^\
					IP		     NETMASK

Now eth0 should active, you can test it by "ping" or get more information by
"ifconfig". If tested ok, continue the next step.

4. ``cp dl2k.ko /lib/modules/`uname -r`/kernel/drivers/net``
5. Add the following line to /etc/modprobe.d/dl2k.conf::

	alias eth0 dl2k

6. Run ``depmod`` to updated module indexes.
7. Run ``netconfig`` or ``netconf`` to create configuration script ifcfg-eth0
   located at /etc/sysconfig/network-scripts or create it manually.

   [see - Configuration Script Sample]
8. Driver will automatically load and configure at next boot time.

Compiling the Driver
====================
In Linux, NIC drivers are most commonly configured as loadable modules.
The approach of building a monolithic kernel has become obsolete. The driver
can be compiled as part of a monolithic kernel, but is strongly discouraged.
The remainder of this section assumes the driver is built as a loadable module.
In the Linux environment, it is a good idea to rebuild the driver from the
source instead of relying on a precompiled version. This approach provides
better reliability since a precompiled driver might depend on libraries or
kernel features that are not present in a given Linux installation.

The 3 files necessary to build Linux device driver are dl2k.c, dl2k.h and
Makefile. To compile, the Linux installation must include the gcc compiler,
the kernel source, and the kernel headers. The Linux driver supports Linux
Kernels 2.4.7. Copy the files to a directory and enter the following command
to compile and link the driver:

CD-ROM drive
------------

::

    [root@XXX /] mkdir cdrom
    [root@XXX /] mount -r -t iso9660 -o conv=auto /dev/cdrom /cdrom
    [root@XXX /] cd root
    [root@XXX /root] mkdir dl2k
    [root@XXX /root] cd dl2k
    [root@XXX dl2k] cp /cdrom/linux/dl2k.tgz /root/dl2k
    [root@XXX dl2k] tar xfvz dl2k.tgz
    [root@XXX dl2k] make all

Floppy disc drive
-----------------

::

    [root@XXX /] cd root
    [root@XXX /root] mkdir dl2k
    [root@XXX /root] cd dl2k
    [root@XXX dl2k] mcopy a:/linux/dl2k.tgz /root/dl2k
    [root@XXX dl2k] tar xfvz dl2k.tgz
    [root@XXX dl2k] make all

Installing the Driver
=====================

Manual Installation
-------------------

  Once the driver has been compiled, it must be loaded, enabled, and bound
  to a protocol stack in order to establish network connectivity. To load a
  module enter the command::

    insmod dl2k.o

  or::

    insmod dl2k.o <optional parameter>	; add parameter

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

  example::

    insmod dl2k.o media=100mbps_hd

   or::

    insmod dl2k.o media=3

   or::

    insmod dl2k.o media=3,2	; for 2 cards

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

  Please reference the list of the command line parameters supported by
  the Linux device driver below.

  The insmod command only loads the driver and gives it a name of the form
  eth0, eth1, etc. To bring the NIC into an operational state,
  it is necessary to issue the following command::

    ifconfig eth0 up

  Finally, to bind the driver to the active protocol (e.g., TCP/IP with
  Linux), enter the following command::

    ifup eth0

  Note that this is meaningful only if the system can find a configuration
  script that contains the necessary network information. A sample will be
  given in the next paragraph.

  The commands to unload a driver are as follows::

    ifdown eth0
    ifconfig eth0 down
    rmmod dl2k.o

  The following are the commands to list the currently loaded modules and
  to see the current network configuration::

    lsmod
    ifconfig

Automated Installation
----------------------
  This section describes how to install the driver such that it is
  automatically loaded and configured at boot time. The following description
  is based on a Red Hat 6.0/7.0 distribution, but it can easily be ported to
  other distributions as well.

Red Hat v6.x/v7.x
-----------------
  1. Copy dl2k.o to the network modules directory, typically
     /lib/modules/2.x.x-xx/net or /lib/modules/2.x.x/kernel/drivers/net.
  2. Locate the boot module configuration file, most commonly in the
     /etc/modprobe.d/ directory. Add the following lines::

	alias ethx dl2k
	options dl2k <optional parameters>

     where ethx will be eth0 if the NIC is the only ethernet adapter, eth1 if
     one other ethernet adapter is installed, etc. Refer to the table in the
     previous section for the list of optional parameters.
  3. Locate the network configuration scripts, normally the
     /etc/sysconfig/network-scripts directory, and create a configuration
     script named ifcfg-ethx that contains network information.
  4. Note that for most Linux distributions, Red Hat included, a configuration
     utility with a graphical user interface is provided to perform steps 2
     and 3 above.

Parameter Description
=====================
You can install this driver without any additional parameter. However, if you
are going to have extensive functions then it is necessary to set extra
parameter. Below is a list of the command line parameters supported by the
Linux device
driver.

===============================   ==============================================
mtu=packet_size			  Specifies the maximum packet size. default
				  is 1500.

media=media_type		  Specifies the media type the NIC operates at.
				  autosense	Autosensing active media.

				  ===========	=========================
				  10mbps_hd	10Mbps half duplex.
				  10mbps_fd	10Mbps full duplex.
				  100mbps_hd	100Mbps half duplex.
				  100mbps_fd	100Mbps full duplex.
				  1000mbps_fd	1000Mbps full duplex.
				  1000mbps_hd	1000Mbps half duplex.
				  0		Autosensing active media.
				  1		10Mbps half duplex.
				  2		10Mbps full duplex.
				  3		100Mbps half duplex.
				  4		100Mbps full duplex.
				  5          	1000Mbps half duplex.
				  6          	1000Mbps full duplex.
				  ===========	=========================

				  By default, the NIC operates at autosense.
				  1000mbps_fd and 1000mbps_hd types are only
				  available for fiber adapter.

vlan=n				  Specifies the VLAN ID. If vlan=0, the
				  Virtual Local Area Network (VLAN) function is
				  disable.

jumbo=[0|1]			  Specifies the jumbo frame support. If jumbo=1,
				  the NIC accept jumbo frames. By default, this
				  function is disabled.
				  Jumbo frame usually improve the performance
				  int gigabit.
				  This feature need jumbo frame compatible
				  remote.

rx_coalesce=m			  Number of rx frame handled each interrupt.
rx_timeout=n			  Rx DMA wait time for an interrupt.
				  If set rx_coalesce > 0, hardware only assert
				  an interrupt for m frames. Hardware won't
				  assert rx interrupt until m frames received or
				  reach timeout of n * 640 nano seconds.
				  Set proper rx_coalesce and rx_timeout can
				  reduce congestion collapse and overload which
				  has been a bottleneck for high speed network.

				  For example, rx_coalesce=10 rx_timeout=800.
				  that is, hardware assert only 1 interrupt
				  for 10 frames received or timeout of 512 us.

tx_coalesce=n			  Number of tx frame handled each interrupt.
				  Set n > 1 can reduce the interrupts
				  congestion usually lower performance of
				  high speed network card. Default is 16.

tx_flow=[1|0]			  Specifies the Tx flow control. If tx_flow=0,
				  the Tx flow control disable else driver
				  autodetect.
rx_flow=[1|0]			  Specifies the Rx flow control. If rx_flow=0,
				  the Rx flow control enable else driver
				  autodetect.
===============================   ==============================================

Configuration Script Sample
===========================
Here is a sample of a simple configuration script::

    DEVICE=eth0
    USERCTL=no
    ONBOOT=yes
    POOTPROTO=none
    BROADCAST=207.200.5.255
    NETWORK=207.200.5.0
    NETMASK=255.255.255.0
    IPADDR=207.200.5.2

Troubleshooting
===============
Q1. Source files contain ^ M behind every line.

    Make sure all files are Unix file format (no LF). Try the following
    shell command to convert files::

	cat dl2k.c | col -b > dl2k.tmp
	mv dl2k.tmp dl2k.c

    OR::

	cat dl2k.c | tr -d "\r" > dl2k.tmp
	mv dl2k.tmp dl2k.c

Q2: Could not find header files (``*.h``)?

    To compile the driver, you need kernel header files. After
    installing the kernel source, the header files are usually located in
    /usr/src/linux/include, which is the default include directory configured
    in Makefile. For some distributions, there is a copy of header files in
    /usr/src/include/linux and /usr/src/include/asm, that you can change the
    INCLUDEDIR in Makefile to /usr/include without installing kernel source.

    Note that RH 7.0 didn't provide correct header files in /usr/include,
    including those files will make a wrong version driver.


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

==============================
The QorIQ DPAA Ethernet Driver
==============================

Authors:
- Madalin Bucur <madalin.bucur@nxp.com>
- Camelia Groza <camelia.groza@nxp.com>

.. Contents

	- DPAA Ethernet Overview
	- DPAA Ethernet Supported SoCs
	- Configuring DPAA Ethernet in your kernel
	- DPAA Ethernet Frame Processing
	- DPAA Ethernet Features
	- DPAA IRQ Affinity and Receive Side Scaling
	- Debugging

DPAA Ethernet Overview
======================

DPAA stands for Data Path Acceleration Architecture and it is a
set of networking acceleration IPs that are available on several
generations of SoCs, both on PowerPC and ARM64.

The Freescale DPAA architecture consists of a series of hardware blocks
that support Ethernet connectivity. The Ethernet driver depends upon the
following drivers in the Linux kernel:

 - Peripheral Access Memory Unit (PAMU) (* needed only for PPC platforms)
    drivers/iommu/fsl_*
 - Frame Manager (FMan)
    drivers/net/ethernet/freescale/fman
 - Queue Manager (QMan), Buffer Manager (BMan)
    drivers/soc/fsl/qbman

A simplified view of the dpaa_eth interfaces mapped to FMan MACs::

  dpaa_eth       /eth0\     ...       /ethN\
  driver        |      |             |      |
  -------------   ----   -----------   ----   -------------
       -Ports  / Tx  Rx \    ...    / Tx  Rx \
  FMan        |          |         |          |
       -MACs  |   MAC0   |         |   MACN   |
	     /   dtsec0   \  ...  /   dtsecN   \ (or tgec)
	    /              \     /              \(or memac)
  ---------  --------------  ---  --------------  ---------
      FMan, FMan Port, FMan SP, FMan MURAM drivers
  ---------------------------------------------------------
      FMan HW blocks: MURAM, MACs, Ports, SP
  ---------------------------------------------------------

The dpaa_eth relation to the QMan, BMan and FMan::

	      ________________________________
  dpaa_eth   /            eth0                \
  driver    /                                  \
  ---------   -^-   -^-   -^-   ---    ---------
  QMan driver / \   / \   / \  \   /  | BMan    |
	     |Rx | |Rx | |Tx | |Tx |  | driver  |
  ---------  |Dfl| |Err| |Cnf| |FQs|  |         |
  QMan HW    |FQ | |FQ | |FQs| |   |  |         |
	     /   \ /   \ /   \  \ /   |         |
  ---------   ---   ---   ---   -v-    ---------
	    |        FMan QMI         |         |
	    | FMan HW       FMan BMI  | BMan HW |
	      -----------------------   --------

where the acronyms used above (and in the code) are:

=============== ===========================================================
DPAA 		Data Path Acceleration Architecture
FMan 		DPAA Frame Manager
QMan 		DPAA Queue Manager
BMan 		DPAA Buffers Manager
QMI 		QMan interface in FMan
BMI 		BMan interface in FMan
FMan SP 	FMan Storage Profiles
MURAM 		Multi-user RAM in FMan
FQ 		QMan Frame Queue
Rx Dfl FQ 	default reception FQ
Rx Err FQ 	Rx error frames FQ
Tx Cnf FQ 	Tx confirmation FQs
Tx FQs 		transmission frame queues
dtsec 		datapath three speed Ethernet controller (10/100/1000 Mbps)
tgec 		ten gigabit Ethernet controller (10 Gbps)
memac 		multirate Ethernet MAC (10/100/1000/10000)
=============== ===========================================================

DPAA Ethernet Supported SoCs
============================

The DPAA drivers enable the Ethernet controllers present on the following SoCs:

PPC
- P1023
- P2041
- P3041
- P4080
- P5020
- P5040
- T1023
- T1024
- T1040
- T1042
- T2080
- T4240
- B4860

ARM
- LS1043A
- LS1046A

Configuring DPAA Ethernet in your kernel
========================================

To enable the DPAA Ethernet driver, the following Kconfig options are required::

  # common for arch/arm64 and arch/powerpc platforms
  CONFIG_FSL_DPAA=y
  CONFIG_FSL_FMAN=y
  CONFIG_FSL_DPAA_ETH=y
  CONFIG_FSL_XGMAC_MDIO=y

  # for arch/powerpc only
  CONFIG_FSL_PAMU=y

  # common options needed for the PHYs used on the RDBs
  CONFIG_VITESSE_PHY=y
  CONFIG_REALTEK_PHY=y
  CONFIG_AQUANTIA_PHY=y

DPAA Ethernet Frame Processing
==============================

On Rx, buffers for the incoming frames are retrieved from the buffers found
in the dedicated interface buffer pool. The driver initializes and seeds these
with one page buffers.

On Tx, all transmitted frames are returned to the driver through Tx
confirmation frame queues. The driver is then responsible for freeing the
buffers. In order to do this properly, a backpointer is added to the buffer
before transmission that points to the skb. When the buffer returns to the
driver on a confirmation FQ, the skb can be correctly consumed.

DPAA Ethernet Features
======================

Currently the DPAA Ethernet driver enables the basic features required for
a Linux Ethernet driver. The support for advanced features will be added
gradually.

The driver has Rx and Tx checksum offloading for UDP and TCP. Currently the Rx
checksum offload feature is enabled by default and cannot be controlled through
ethtool. Also, rx-flow-hash and rx-hashing was added. The addition of RSS
provides a big performance boost for the forwarding scenarios, allowing
different traffic flows received by one interface to be processed by different
CPUs in parallel.

The driver has support for multiple prioritized Tx traffic classes. Priorities
range from 0 (lowest) to 3 (highest). These are mapped to HW workqueues with
strict priority levels. Each traffic class contains NR_CPU TX queues. By
default, only one traffic class is enabled and the lowest priority Tx queues
are used. Higher priority traffic classes can be enabled with the mqprio
qdisc. For example, all four traffic classes are enabled on an interface with
the following command. Furthermore, skb priority levels are mapped to traffic
classes as follows:

	* priorities 0 to 3 - traffic class 0 (low priority)
	* priorities 4 to 7 - traffic class 1 (medium-low priority)
	* priorities 8 to 11 - traffic class 2 (medium-high priority)
	* priorities 12 to 15 - traffic class 3 (high priority)

::

  tc qdisc add dev <int> root handle 1: \
	 mqprio num_tc 4 map 0 0 0 0 1 1 1 1 2 2 2 2 3 3 3 3 hw 1

DPAA IRQ Affinity and Receive Side Scaling
==========================================

Traffic coming on the DPAA Rx queues or on the DPAA Tx confirmation
queues is seen by the CPU as ingress traffic on a certain portal.
The DPAA QMan portal interrupts are affined each to a certain CPU.
The same portal interrupt services all the QMan portal consumers.

By default the DPAA Ethernet driver enables RSS, making use of the
DPAA FMan Parser and Keygen blocks to distribute traffic on 128
hardware frame queues using a hash on IP v4/v6 source and destination
and L4 source and destination ports, in present in the received frame.
When RSS is disabled, all traffic received by a certain interface is
received on the default Rx frame queue. The default DPAA Rx frame
queues are configured to put the received traffic into a pool channel
that allows any available CPU portal to dequeue the ingress traffic.
The default frame queues have the HOLDACTIVE option set, ensuring that
traffic bursts from a certain queue are serviced by the same CPU.
This ensures a very low rate of frame reordering. A drawback of this
is that only one CPU at a time can service the traffic received by a
certain interface when RSS is not enabled.

To implement RSS, the DPAA Ethernet driver allocates an extra set of
128 Rx frame queues that are configured to dedicated channels, in a
round-robin manner. The mapping of the frame queues to CPUs is now
hardcoded, there is no indirection table to move traffic for a certain
FQ (hash result) to another CPU. The ingress traffic arriving on one
of these frame queues will arrive at the same portal and will always
be processed by the same CPU. This ensures intra-flow order preservation
and workload distribution for multiple traffic flows.

RSS can be turned off for a certain interface using ethtool, i.e.::

	# ethtool -N fm1-mac9 rx-flow-hash tcp4 ""

To turn it back on, one needs to set rx-flow-hash for tcp4/6 or udp4/6::

	# ethtool -N fm1-mac9 rx-flow-hash udp4 sfdn

There is no independent control for individual protocols, any command
run for one of tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6 is
going to control the rx-flow-hashing for all protocols on that interface.

Besides using the FMan Keygen computed hash for spreading traffic on the
128 Rx FQs, the DPAA Ethernet driver also sets the skb hash value when
the NETIF_F_RXHASH feature is on (active by default). This can be turned
on or off through ethtool, i.e.::

	# ethtool -K fm1-mac9 rx-hashing off
	# ethtool -k fm1-mac9 | grep hash
	receive-hashing: off
	# ethtool -K fm1-mac9 rx-hashing on
	Actual changes:
	receive-hashing: on
	# ethtool -k fm1-mac9 | grep hash
	receive-hashing: on

Please note that Rx hashing depends upon the rx-flow-hashing being on
for that interface - turning off rx-flow-hashing will also disable the
rx-hashing (without ethtool reporting it as off as that depends on the
NETIF_F_RXHASH feature flag).

Debugging
=========

The following statistics are exported for each interface through ethtool:

	- interrupt count per CPU
	- Rx packets count per CPU
	- Tx packets count per CPU
	- Tx confirmed packets count per CPU
	- Tx S/G frames count per CPU
	- Tx error count per CPU
	- Rx error count per CPU
	- Rx error count per type
	- congestion related statistics:

		- congestion status
		- time spent in congestion
		- number of time the device entered congestion
		- dropped packets count per cause

The driver also exports the following information in sysfs:

	- the FQ IDs for each FQ type
	  /sys/devices/platform/soc/<addr>.fman/<addr>.ethernet/dpaa-ethernet.<id>/net/fm<nr>-mac<nr>/fqids

	- the ID of the buffer pool in use
	  /sys/devices/platform/soc/<addr>.fman/<addr>.ethernet/dpaa-ethernet.<id>/net/fm<nr>-mac<nr>/bpids

repo_name: angery/linux


code:
.. include:: <isonum.txt>

===================================
DPAA2 DPIO (Data Path I/O) Overview
===================================

:Copyright: |copy| 2016-2018 NXP

This document provides an overview of the Freescale DPAA2 DPIO
drivers

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

A DPAA2 DPIO (Data Path I/O) is a hardware object that provides
interfaces to enqueue and dequeue frames to/from network interfaces
and other accelerators.  A DPIO also provides hardware buffer
pool management for network interfaces.

This document provides an overview the Linux DPIO driver, its
subcomponents, and its APIs.

See
Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst
for a general overview of DPAA2 and the general DPAA2 driver architecture
in Linux.

Driver Overview
---------------

The DPIO driver is bound to DPIO objects discovered on the fsl-mc bus and
provides services that:

  A. allow other drivers, such as the Ethernet driver, to enqueue and dequeue
     frames for their respective objects
  B. allow drivers to register callbacks for data availability notifications
     when data becomes available on a queue or channel
  C. allow drivers to manage hardware buffer pools

The Linux DPIO driver consists of 3 primary components--
   DPIO object driver-- fsl-mc driver that manages the DPIO object

   DPIO service-- provides APIs to other Linux drivers for services

   QBman portal interface-- sends portal commands, gets responses::

          fsl-mc          other
           bus           drivers
            |               |
        +---+----+   +------+-----+
        |DPIO obj|   |DPIO service|
        | driver |---|  (DPIO)    |
        +--------+   +------+-----+
                            |
                     +------+-----+
                     |    QBman   |
                     | portal i/f |
                     +------------+
                            |
                         hardware

The diagram below shows how the DPIO driver components fit with the other
DPAA2 Linux driver components::

                                                   +------------+
                                                   | OS Network |
                                                   |   Stack    |
                 +------------+                    +------------+
                 | Allocator  |. . . . . . .       |  Ethernet  |
                 |(DPMCP,DPBP)|                    |   (DPNI)   |
                 +-.----------+                    +---+---+----+
                  .          .                         ^   |
                 .            .           <data avail, |   |<enqueue,
                .              .           tx confirm> |   | dequeue>
    +-------------+             .                      |   |
    | DPRC driver |              .    +--------+ +------------+
    |   (DPRC)    |               . . |DPIO obj| |DPIO service|
    +----------+--+                   | driver |-|  (DPIO)    |
               |                      +--------+ +------+-----+
               |<dev add/remove>                 +------|-----+
               |                                 |   QBman    |
          +----+--------------+                  | portal i/f |
          |   MC-bus driver   |                  +------------+
          |                   |                     |
          | /soc/fsl-mc       |                     |
          +-------------------+                     |
                                                    |
 =========================================|=========|========================
                                        +-+--DPIO---|-----------+
                                        |           |           |
                                        |        QBman Portal   |
                                        +-----------------------+

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

DPIO Object Driver (dpio-driver.c)
----------------------------------

   The dpio-driver component registers with the fsl-mc bus to handle objects of
   type "dpio".  The implementation of probe() handles basic initialization
   of the DPIO including mapping of the DPIO regions (the QBman SW portal)
   and initializing interrupts and registering irq handlers.  The dpio-driver
   registers the probed DPIO with dpio-service.

DPIO service  (dpio-service.c, dpaa2-io.h)
------------------------------------------

   The dpio service component provides queuing, notification, and buffers
   management services to DPAA2 drivers, such as the Ethernet driver.  A system
   will typically allocate 1 DPIO object per CPU to allow queuing operations
   to happen simultaneously across all CPUs.

   Notification handling
      dpaa2_io_service_register()

      dpaa2_io_service_deregister()

      dpaa2_io_service_rearm()

   Queuing
      dpaa2_io_service_pull_fq()

      dpaa2_io_service_pull_channel()

      dpaa2_io_service_enqueue_fq()

      dpaa2_io_service_enqueue_qd()

      dpaa2_io_store_create()

      dpaa2_io_store_destroy()

      dpaa2_io_store_next()

   Buffer pool management
      dpaa2_io_service_release()

      dpaa2_io_service_acquire()

QBman portal interface (qbman-portal.c)
---------------------------------------

   The qbman-portal component provides APIs to do the low level hardware
   bit twiddling for operations such as:

      - initializing Qman software portals
      - building and sending portal commands
      - portal interrupt configuration and processing

   The qbman-portal APIs are not public to other drivers, and are
   only used by dpio-service.

Other (dpaa2-fd.h, dpaa2-global.h)
----------------------------------

   Frame descriptor and scatter-gather definitions and the APIs used to
   manipulate them are defined in dpaa2-fd.h.

   Dequeue result struct and parsing APIs are defined in dpaa2-global.h.


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

===============================
DPAA2 Ethernet driver
===============================

:Copyright: |copy| 2017-2018 NXP

This file provides documentation for the Freescale DPAA2 Ethernet driver.

Supported Platforms
===================
This driver provides networking support for Freescale DPAA2 SoCs, e.g.
LS2080A, LS2088A, LS1088A.

Architecture Overview
=====================
Unlike regular NICs, in the DPAA2 architecture there is no single hardware block
representing network interfaces; instead, several separate hardware resources
concur to provide the networking functionality:

- network interfaces
- queues, channels
- buffer pools
- MAC/PHY

All hardware resources are allocated and configured through the Management
Complex (MC) portals. MC abstracts most of these resources as DPAA2 objects
and exposes ABIs through which they can be configured and controlled. A few
hardware resources, like queues, do not have a corresponding MC object and
are treated as internal resources of other objects.

For a more detailed description of the DPAA2 architecture and its object
abstractions see
*Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst*.

Each Linux net device is built on top of a Datapath Network Interface (DPNI)
object and uses Buffer Pools (DPBPs), I/O Portals (DPIOs) and Concentrators
(DPCONs).

Configuration interface::

                 -----------------------
                | DPAA2 Ethernet Driver |
                 -----------------------
                     .      .      .
                     .      .      .
             . . . . .      .      . . . . . .
             .              .                .
             .              .                .
         ----------     ----------      -----------
        | DPBP API |   | DPNI API |    | DPCON API |
         ----------     ----------      -----------
             .              .                .             software
    =======  .  ==========  .  ============  .  ===================
             .              .                .             hardware
         ------------------------------------------
        |            MC hardware portals           |
         ------------------------------------------
             .              .                .
             .              .                .
          ------         ------            -------
         | DPBP |       | DPNI |          | DPCON |
          ------         ------            -------

The DPNIs are network interfaces without a direct one-on-one mapping to PHYs.
DPBPs represent hardware buffer pools. Packet I/O is performed in the context
of DPCON objects, using DPIO portals for managing and communicating with the
hardware resources.

Datapath (I/O) interface::

         -----------------------------------------------
        |           DPAA2 Ethernet Driver               |
         -----------------------------------------------
          |          ^        ^         |            |
          |          |        |         |            |
   enqueue|   dequeue|   data |  dequeue|       seed |
    (Tx)  | (Rx, TxC)|  avail.|  request|     buffers|
          |          |  notify|         |            |
          |          |        |         |            |
          V          |        |         V            V
         -----------------------------------------------
        |                 DPIO Driver                   |
         -----------------------------------------------
          |          |        |         |            |          software
          |          |        |         |            |  ================
          |          |        |         |            |          hardware
         -----------------------------------------------
        |               I/O hardware portals            |
         -----------------------------------------------
          |          ^        ^         |            |
          |          |        |         |            |
          |          |        |         V            |
          V          |    ================           V
        ----------------------           |      -------------
 queues  ----------------------          |     | Buffer pool |
          ----------------------         |      -------------
                   =======================
                                Channel

Datapath I/O (DPIO) portals provide enqueue and dequeue services, data
availability notifications and buffer pool management. DPIOs are shared between
all DPAA2 objects (and implicitly all DPAA2 kernel drivers) that work with data
frames, but must be affine to the CPUs for the purpose of traffic distribution.

Frames are transmitted and received through hardware frame queues, which can be
grouped in channels for the purpose of hardware scheduling. The Ethernet driver
enqueues TX frames on egress queues and after transmission is complete a TX
confirmation frame is sent back to the CPU.

When frames are available on ingress queues, a data availability notification
is sent to the CPU; notifications are raised per channel, so even if multiple
queues in the same channel have available frames, only one notification is sent.
After a channel fires a notification, is must be explicitly rearmed.

Each network interface can have multiple Rx, Tx and confirmation queues affined
to CPUs, and one channel (DPCON) for each CPU that services at least one queue.
DPCONs are used to distribute ingress traffic to different CPUs via the cores'
affine DPIOs.

The role of hardware buffer pools is storage of ingress frame data. Each network
interface has a privately owned buffer pool which it seeds with kernel allocated
buffers.

DPNIs are decoupled from PHYs; a DPNI can be connected to a PHY through a DPMAC
object or to another DPNI through an internal link, but the connection is
managed by MC and completely transparent to the Ethernet driver.

::

     ---------     ---------     ---------
    | eth if1 |   | eth if2 |   | eth ifn |
     ---------     ---------     ---------
          .           .          .
          .           .          .
          .           .          .
         ---------------------------
        |   DPAA2 Ethernet Driver   |
         ---------------------------
          .           .          .
          .           .          .
          .           .          .
       ------      ------      ------            -------
      | DPNI |    | DPNI |    | DPNI |          | DPMAC |----+
       ------      ------      ------            -------     |
         |           |           |                  |        |
         |           |           |                  |      -----
          ===========             ==================      | PHY |
                                                           -----

Creating a Network Interface
============================
A net device is created for each DPNI object probed on the MC bus. Each DPNI has
a number of properties which determine the network interface configuration
options and associated hardware resources.

DPNI objects (and the other DPAA2 objects needed for a network interface) can be
added to a container on the MC bus in one of two ways: statically, through a
Datapath Layout Binary file (DPL) that is parsed by MC at boot time; or created
dynamically at runtime, via the DPAA2 objects APIs.

Features & Offloads
===================
Hardware checksum offloading is supported for TCP and UDP over IPv4/6 frames.
The checksum offloads can be independently configured on RX and TX through
ethtool.

Hardware offload of unicast and multicast MAC filtering is supported on the
ingress path and permanently enabled.

Scatter-gather frames are supported on both RX and TX paths. On TX, SG support
is configurable via ethtool; on RX it is always enabled.

The DPAA2 hardware can process jumbo Ethernet frames of up to 10K bytes.

The Ethernet driver defines a static flow hashing scheme that distributes
traffic based on a 5-tuple key: src IP, dst IP, IP proto, L4 src port,
L4 dst port. No user configuration is supported for now.

Hardware specific statistics for the network interface as well as some
non-standard driver stats can be consulted through ethtool -S option.


code:
===================
DPAA2 Documentation
===================

.. toctree::
   :maxdepth: 1

   overview
   dpio-driver
   ethernet-driver
   mac-phy-support
   switch-driver


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

=======================
DPAA2 MAC / PHY support
=======================

:Copyright: |copy| 2019 NXP

Overview
--------

The DPAA2 MAC / PHY support consists of a set of APIs that help DPAA2 network
drivers (dpaa2-eth, dpaa2-ethsw) interract with the PHY library.

DPAA2 Software Architecture
---------------------------

Among other DPAA2 objects, the fsl-mc bus exports DPNI objects (abstracting a
network interface) and DPMAC objects (abstracting a MAC). The dpaa2-eth driver
probes on the DPNI object and connects to and configures a DPMAC object with
the help of phylink.

Data connections may be established between a DPNI and a DPMAC, or between two
DPNIs. Depending on the connection type, the netif_carrier_[on/off] is handled
directly by the dpaa2-eth driver or by phylink.

.. code-block:: none

  Sources of abstracted link state information presented by the MC firmware

                                               +--------------------------------------+
  +------------+                  +---------+  |                           xgmac_mdio |
  | net_device |                  | phylink |--|  +-----+  +-----+  +-----+  +-----+  |
  +------------+                  +---------+  |  | PHY |  | PHY |  | PHY |  | PHY |  |
        |                             |        |  +-----+  +-----+  +-----+  +-----+  |
      +------------------------------------+   |                    External MDIO bus |
      |            dpaa2-eth               |   +--------------------------------------+
      +------------------------------------+
        |                             |                                           Linux
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        |                             |                                     MC firmware
        |              /|             V
  +----------+        / |       +----------+
  |          |       /  |       |          |
  |          |       |  |       |          |
  |   DPNI   |<------|  |<------|   DPMAC  |
  |          |       |  |       |          |
  |          |       \  |<---+  |          |
  +----------+        \ |    |  +----------+
                       \|    |
                             |
           +--------------------------------------+
           | MC firmware polling MAC PCS for link |
           |  +-----+  +-----+  +-----+  +-----+  |
           |  | PCS |  | PCS |  | PCS |  | PCS |  |
           |  +-----+  +-----+  +-----+  +-----+  |
           |                    Internal MDIO bus |
           +--------------------------------------+

Depending on an MC firmware configuration setting, each MAC may be in one of two modes:

- DPMAC_LINK_TYPE_FIXED: the link state management is handled exclusively by
  the MC firmware by polling the MAC PCS. Without the need to register a
  phylink instance, the dpaa2-eth driver will not bind to the connected dpmac
  object at all.

- DPMAC_LINK_TYPE_PHY: The MC firmware is left waiting for link state update
  events, but those are in fact passed strictly between the dpaa2-mac (based on
  phylink) and its attached net_device driver (dpaa2-eth, dpaa2-ethsw),
  effectively bypassing the firmware.

Implementation
--------------

At probe time or when a DPNI's endpoint is dynamically changed, the dpaa2-eth
is responsible to find out if the peer object is a DPMAC and if this is the
case, to integrate it with PHYLINK using the dpaa2_mac_connect() API, which
will do the following:

 - look up the device tree for PHYLINK-compatible of binding (phy-handle)
 - will create a PHYLINK instance associated with the received net_device
 - connect to the PHY using phylink_of_phy_connect()

The following phylink_mac_ops callback are implemented:

 - .validate() will populate the supported linkmodes with the MAC capabilities
   only when the phy_interface_t is RGMII_* (at the moment, this is the only
   link type supported by the driver).

 - .mac_config() will configure the MAC in the new configuration using the
   dpmac_set_link_state() MC firmware API.

 - .mac_link_up() / .mac_link_down() will update the MAC link using the same
   API described above.

At driver unbind() or when the DPNI object is disconnected from the DPMAC, the
dpaa2-eth driver calls dpaa2_mac_disconnect() which will, in turn, disconnect
from the PHY and destroy the PHYLINK instance.

In case of a DPNI-DPMAC connection, an 'ip link set dev eth0 up' would start
the following sequence of operations:

(1) phylink_start() called from .dev_open().
(2) The .mac_config() and .mac_link_up() callbacks are called by PHYLINK.
(3) In order to configure the HW MAC, the MC Firmware API
    dpmac_set_link_state() is called.
(4) The firmware will eventually setup the HW MAC in the new configuration.
(5) A netif_carrier_on() call is made directly from PHYLINK on the associated
    net_device.
(6) The dpaa2-eth driver handles the LINK_STATE_CHANGE irq in order to
    enable/disable Rx taildrop based on the pause frame settings.

.. code-block:: none

  +---------+               +---------+
  | PHYLINK |-------------->|  eth0   |
  +---------+           (5) +---------+
  (1) ^  |
      |  |
      |  v (2)
  +-----------------------------------+
  |             dpaa2-eth             |
  +-----------------------------------+
         |                    ^ (6)
         |                    |
         v (3)                |
  +---------+---------------+---------+
  |  DPMAC  |               |  DPNI   |
  +---------+               +---------+
  |            MC Firmware            |
  +-----------------------------------+
         |
         |
         v (4)
  +-----------------------------------+
  |             HW MAC                |
  +-----------------------------------+

In case of a DPNI-DPNI connection, a usual sequence of operations looks like
the following:

(1) ip link set dev eth0 up
(2) The dpni_enable() MC API called on the associated fsl_mc_device.
(3) ip link set dev eth1 up
(4) The dpni_enable() MC API called on the associated fsl_mc_device.
(5) The LINK_STATE_CHANGED irq is received by both instances of the dpaa2-eth
    driver because now the operational link state is up.
(6) The netif_carrier_on() is called on the exported net_device from
    link_state_update().

.. code-block:: none

  +---------+               +---------+
  |  eth0   |               |  eth1   |
  +---------+               +---------+
      |  ^                     ^  |
      |  |                     |  |
  (1) v  | (6)             (6) |  v (3)
  +---------+               +---------+
  |dpaa2-eth|               |dpaa2-eth|
  +---------+               +---------+
      |  ^                     ^  |
      |  |                     |  |
  (2) v  | (5)             (5) |  v (4)
  +---------+---------------+---------+
  |  DPNI   |               |  DPNI   |
  +---------+               +---------+
  |            MC Firmware            |
  +-----------------------------------+

Exported API
------------

Any DPAA2 driver that drivers endpoints of DPMAC objects should service its
_EVENT_ENDPOINT_CHANGED irq and connect/disconnect from the associated DPMAC
when necessary using the below listed API::

 - int dpaa2_mac_connect(struct dpaa2_mac *mac);
 - void dpaa2_mac_disconnect(struct dpaa2_mac *mac);

A phylink integration is necessary only when the partner DPMAC is not of
``TYPE_FIXED``. This means it is either of ``TYPE_PHY``, or of
``TYPE_BACKPLANE`` (the difference being the two that in the ``TYPE_BACKPLANE``
mode, the MC firmware does not access the PCS registers). One can check for
this condition using the following helper::

 - static inline bool dpaa2_mac_is_type_phy(struct dpaa2_mac *mac);

Before connection to a MAC, the caller must allocate and populate the
dpaa2_mac structure with the associated net_device, a pointer to the MC portal
to be used and the actual fsl_mc_device structure of the DPMAC.


code:
.. include:: <isonum.txt>

=========================================================
DPAA2 (Data Path Acceleration Architecture Gen2) Overview
=========================================================

:Copyright: |copy| 2015 Freescale Semiconductor Inc.
:Copyright: |copy| 2018 NXP

This document provides an overview of the Freescale DPAA2 architecture
and how it is integrated into the Linux kernel.

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

DPAA2 is a hardware architecture designed for high-speeed network
packet processing.  DPAA2 consists of sophisticated mechanisms for
processing Ethernet packets, queue management, buffer management,
autonomous L2 switching, virtual Ethernet bridging, and accelerator
(e.g. crypto) sharing.

A DPAA2 hardware component called the Management Complex (or MC) manages the
DPAA2 hardware resources.  The MC provides an object-based abstraction for
software drivers to use the DPAA2 hardware.
The MC uses DPAA2 hardware resources such as queues, buffer pools, and
network ports to create functional objects/devices such as network
interfaces, an L2 switch, or accelerator instances.
The MC provides memory-mapped I/O command interfaces (MC portals)
which DPAA2 software drivers use to operate on DPAA2 objects.

The diagram below shows an overview of the DPAA2 resource management
architecture::

	+--------------------------------------+
	|                  OS                  |
	|                        DPAA2 drivers |
	|                             |        |
	+-----------------------------|--------+
	                              |
	                              | (create,discover,connect
	                              |  config,use,destroy)
	                              |
	                 DPAA2        |
	+------------------------| mc portal |-+
	|                             |        |
	|   +- - - - - - - - - - - - -V- - -+  |
	|   |                               |  |
	|   |   Management Complex (MC)     |  |
	|   |                               |  |
	|   +- - - - - - - - - - - - - - - -+  |
	|                                      |
	| Hardware                  Hardware   |
	| Resources                 Objects    |
	| ---------                 -------    |
	| -queues                   -DPRC      |
	| -buffer pools             -DPMCP     |
	| -Eth MACs/ports           -DPIO      |
	| -network interface        -DPNI      |
	|  profiles                 -DPMAC     |
	| -queue portals            -DPBP      |
	| -MC portals                ...       |
	|  ...                                 |
	|                                      |
	+--------------------------------------+

The MC mediates operations such as create, discover,
connect, configuration, and destroy.  Fast-path operations
on data, such as packet transmit/receive, are not mediated by
the MC and are done directly using memory mapped regions in
DPIO objects.

Overview of DPAA2 Objects
=========================

The section provides a brief overview of some key DPAA2 objects.
A simple scenario is described illustrating the objects involved
in creating a network interfaces.

DPRC (Datapath Resource Container)
----------------------------------

A DPRC is a container object that holds all the other
types of DPAA2 objects.  In the example diagram below there
are 8 objects of 5 types (DPMCP, DPIO, DPBP, DPNI, and DPMAC)
in the container.

::

	+---------------------------------------------------------+
	| DPRC                                                    |
	|                                                         |
	|  +-------+  +-------+  +-------+  +-------+  +-------+  |
	|  | DPMCP |  | DPIO  |  | DPBP  |  | DPNI  |  | DPMAC |  |
	|  +-------+  +-------+  +-------+  +---+---+  +---+---+  |
	|  | DPMCP |  | DPIO  |                                   |
	|  +-------+  +-------+                                   |
	|  | DPMCP |                                              |
	|  +-------+                                              |
	|                                                         |
	+---------------------------------------------------------+

From the point of view of an OS, a DPRC behaves similar to a plug and
play bus, like PCI.  DPRC commands can be used to enumerate the contents
of the DPRC, discover the hardware objects present (including mappable
regions and interrupts).

::

	DPRC.1 (bus)
	   |
	   +--+--------+-------+-------+-------+
	      |        |       |       |       |
	    DPMCP.1  DPIO.1  DPBP.1  DPNI.1  DPMAC.1
	    DPMCP.2  DPIO.2
	    DPMCP.3

Hardware objects can be created and destroyed dynamically, providing
the ability to hot plug/unplug objects in and out of the DPRC.

A DPRC has a mappable MMIO region (an MC portal) that can be used
to send MC commands.  It has an interrupt for status events (like
hotplug).
All objects in a container share the same hardware "isolation context".
This means that with respect to an IOMMU the isolation granularity
is at the DPRC (container) level, not at the individual object
level.

DPRCs can be defined statically and populated with objects
via a config file passed to the MC when firmware starts it.

DPAA2 Objects for an Ethernet Network Interface
-----------------------------------------------

A typical Ethernet NIC is monolithic-- the NIC device contains TX/RX
queuing mechanisms, configuration mechanisms, buffer management,
physical ports, and interrupts.  DPAA2 uses a more granular approach
utilizing multiple hardware objects.  Each object provides specialized
functions. Groups of these objects are used by software to provide
Ethernet network interface functionality.  This approach provides
efficient use of finite hardware resources, flexibility, and
performance advantages.

The diagram below shows the objects needed for a simple
network interface configuration on a system with 2 CPUs.

::

	+---+---+ +---+---+
	   CPU0     CPU1
	+---+---+ +---+---+
	    |         |
	+---+---+ +---+---+
	   DPIO     DPIO
	+---+---+ +---+---+
	    \     /
	     \   /
	      \ /
	   +---+---+
	      DPNI  --- DPBP,DPMCP
	   +---+---+
	       |
	       |
	   +---+---+
	     DPMAC
	   +---+---+
	       |
	   port/PHY

Below the objects are described.  For each object a brief description
is provided along with a summary of the kinds of operations the object
supports and a summary of key resources of the object (MMIO regions
and IRQs).

DPMAC (Datapath Ethernet MAC)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Represents an Ethernet MAC, a hardware device that connects to an Ethernet
PHY and allows physical transmission and reception of Ethernet frames.

- MMIO regions: none
- IRQs: DPNI link change
- commands: set link up/down, link config, get stats,
  IRQ config, enable, reset

DPNI (Datapath Network Interface)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Contains TX/RX queues, network interface configuration, and RX buffer pool
configuration mechanisms.  The TX/RX queues are in memory and are identified
by queue number.

- MMIO regions: none
- IRQs: link state
- commands: port config, offload config, queue config,
  parse/classify config, IRQ config, enable, reset

DPIO (Datapath I/O)
~~~~~~~~~~~~~~~~~~~
Provides interfaces to enqueue and dequeue
packets and do hardware buffer pool management operations.  The DPAA2
architecture separates the mechanism to access queues (the DPIO object)
from the queues themselves.  The DPIO provides an MMIO interface to
enqueue/dequeue packets.  To enqueue something a descriptor is written
to the DPIO MMIO region, which includes the target queue number.
There will typically be one DPIO assigned to each CPU.  This allows all
CPUs to simultaneously perform enqueue/dequeued operations.  DPIOs are
expected to be shared by different DPAA2 drivers.

- MMIO regions: queue operations, buffer management
- IRQs: data availability, congestion notification, buffer
  pool depletion
- commands: IRQ config, enable, reset

DPBP (Datapath Buffer Pool)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Represents a hardware buffer pool.

- MMIO regions: none
- IRQs: none
- commands: enable, reset

DPMCP (Datapath MC Portal)
~~~~~~~~~~~~~~~~~~~~~~~~~~
Provides an MC command portal.
Used by drivers to send commands to the MC to manage
objects.

- MMIO regions: MC command portal
- IRQs: command completion
- commands: IRQ config, enable, reset

Object Connections
==================
Some objects have explicit relationships that must
be configured:

- DPNI <--> DPMAC
- DPNI <--> DPNI
- DPNI <--> L2-switch-port

    A DPNI must be connected to something such as a DPMAC,
    another DPNI, or L2 switch port.  The DPNI connection
    is made via a DPRC command.

::

              +-------+  +-------+
              | DPNI  |  | DPMAC |
              +---+---+  +---+---+
                  |          |
                  +==========+

- DPNI <--> DPBP

    A network interface requires a 'buffer pool' (DPBP
    object) which provides a list of pointers to memory
    where received Ethernet data is to be copied.  The
    Ethernet driver configures the DPBPs associated with
    the network interface.

Interrupts
==========
All interrupts generated by DPAA2 objects are message
interrupts.  At the hardware level message interrupts
generated by devices will normally have 3 components--
1) a non-spoofable 'device-id' expressed on the hardware
bus, 2) an address, 3) a data value.

In the case of DPAA2 devices/objects, all objects in the
same container/DPRC share the same 'device-id'.
For ARM-based SoC this is the same as the stream ID.

DPAA2 Linux Drivers Overview
============================

This section provides an overview of the Linux kernel drivers for
DPAA2-- 1) the bus driver and associated "DPAA2 infrastructure"
drivers and 2) functional object drivers (such as Ethernet).

As described previously, a DPRC is a container that holds the other
types of DPAA2 objects.  It is functionally similar to a plug-and-play
bus controller.
Each object in the DPRC is a Linux "device" and is bound to a driver.
The diagram below shows the Linux drivers involved in a networking
scenario and the objects bound to each driver.  A brief description
of each driver follows.

::

	                                     +------------+
	                                     | OS Network |
	                                     |   Stack    |
	         +------------+              +------------+
	         | Allocator  |. . . . . . . |  Ethernet  |
	         |(DPMCP,DPBP)|              |   (DPNI)   |
	         +-.----------+              +---+---+----+
	          .          .                   ^   |
	         .            .     <data avail, |   | <enqueue,
	        .              .     tx confirm> |   | dequeue>
	+-------------+         .                |   |
	| DPRC driver |          .           +---+---V----+     +---------+
	|   (DPRC)    |           . . . . . .| DPIO driver|     |   MAC   |
	+----------+--+                      |  (DPIO)    |     | (DPMAC) |
	           |                         +------+-----+     +-----+---+
	           |<dev add/remove>                |                 |
	           |                                |                 |
	  +--------+----------+                     |              +--+---+
	  |   MC-bus driver   |                     |              | PHY  |
	  |                   |                     |              |driver|
	  |   /bus/fsl-mc     |                     |              +--+---+
	  +-------------------+                     |                 |
	                                            |                 |
	========================= HARDWARE =========|=================|======
	                                          DPIO                |
	                                            |                 |
	                                          DPNI---DPBP         |
	                                            |                 |
	                                          DPMAC               |
	                                            |                 |
	                                           PHY ---------------+
	============================================|========================

A brief description of each driver is provided below.

MC-bus driver
-------------
The MC-bus driver is a platform driver and is probed from a
node in the device tree (compatible "fsl,qoriq-mc") passed in by boot
firmware.  It is responsible for bootstrapping the DPAA2 kernel
infrastructure.
Key functions include:

- registering a new bus type named "fsl-mc" with the kernel,
  and implementing bus call-backs (e.g. match/uevent/dev_groups)
- implementing APIs for DPAA2 driver registration and for device
  add/remove
- creates an MSI IRQ domain
- doing a 'device add' to expose the 'root' DPRC, in turn triggering
  a bind of the root DPRC to the DPRC driver

The binding for the MC-bus device-tree node can be consulted at
*Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt*.
The sysfs bind/unbind interfaces for the MC-bus can be consulted at
*Documentation/ABI/testing/sysfs-bus-fsl-mc*.

DPRC driver
-----------
The DPRC driver is bound to DPRC objects and does runtime management
of a bus instance.  It performs the initial bus scan of the DPRC
and handles interrupts for container events such as hot plug by
re-scanning the DPRC.

Allocator
---------
Certain objects such as DPMCP and DPBP are generic and fungible,
and are intended to be used by other drivers.  For example,
the DPAA2 Ethernet driver needs:

- DPMCPs to send MC commands, to configure network interfaces
- DPBPs for network buffer pools

The allocator driver registers for these allocatable object types
and those objects are bound to the allocator when the bus is probed.
The allocator maintains a pool of objects that are available for
allocation by other DPAA2 drivers.

DPIO driver
-----------
The DPIO driver is bound to DPIO objects and provides services that allow
other drivers such as the Ethernet driver to enqueue and dequeue data for
their respective objects.
Key services include:

- data availability notifications
- hardware queuing operations (enqueue and dequeue of data)
- hardware buffer pool management

To transmit a packet the Ethernet driver puts data on a queue and
invokes a DPIO API.  For receive, the Ethernet driver registers
a data availability notification callback.  To dequeue a packet
a DPIO API is used.
There is typically one DPIO object per physical CPU for optimum
performance, allowing different CPUs to simultaneously enqueue
and dequeue data.

The DPIO driver operates on behalf of all DPAA2 drivers
active in the kernel--  Ethernet, crypto, compression,
etc.

Ethernet driver
---------------
The Ethernet driver is bound to a DPNI and implements the kernel
interfaces needed to connect the DPAA2 network interface to
the network stack.
Each DPNI corresponds to a Linux network interface.

MAC driver
----------
An Ethernet PHY is an off-chip, board specific component and is managed
by the appropriate PHY driver via an mdio bus.  The MAC driver
plays a role of being a proxy between the PHY driver and the
MC.  It does this proxy via the MC commands to a DPMAC object.
If the PHY driver signals a link change, the MAC driver notifies
the MC via a DPMAC command.  If a network interface is brought
up or down, the MC notifies the DPMAC driver via an interrupt and
the driver can take appropriate action.


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

===================
DPAA2 Switch driver
===================

:Copyright: |copy| 2021 NXP

The DPAA2 Switch driver probes on the Datapath Switch (DPSW) object which can
be instantiated on the following DPAA2 SoCs and their variants: LS2088A and
LX2160A.

The driver uses the switch device driver model and exposes each switch port as
a network interface, which can be included in a bridge or used as a standalone
interface. Traffic switched between ports is offloaded into the hardware.

The DPSW can have ports connected to DPNIs or to DPMACs for external access.
::

         [ethA]     [ethB]      [ethC]     [ethD]     [ethE]     [ethF]
            :          :          :          :          :          :
            :          :          :          :          :          :
       [dpaa2-eth]  [dpaa2-eth]  [              dpaa2-switch              ]
            :          :          :          :          :          :        kernel
       =============================================================================
            :          :          :          :          :          :        hardware
         [DPNI]      [DPNI]     [============= DPSW =================]
            |          |          |          |          |          |
            |           ----------           |       [DPMAC]    [DPMAC]
             -------------------------------            |          |
                                                        |          |
                                                      [PHY]      [PHY]

Creating an Ethernet Switch
===========================

The dpaa2-switch driver probes on DPSW devices found on the fsl-mc bus. These
devices can be either created statically through the boot time configuration
file - DataPath Layout (DPL) - or at runtime using the DPAA2 object APIs
(incorporated already into the restool userspace tool).

At the moment, the dpaa2-switch driver imposes the following restrictions on
the DPSW object that it will probe:

 * The minimum number of FDBs should be at least equal to the number of switch
   interfaces. This is necessary so that separation of switch ports can be
   done, ie when not under a bridge, each switch port will have its own FDB.
   ::

        fsl_dpaa2_switch dpsw.0: The number of FDBs is lower than the number of ports, cannot probe

 * Both the broadcast and flooding configuration should be per FDB. This
   enables the driver to restrict the broadcast and flooding domains of each
   FDB depending on the switch ports that are sharing it (aka are under the
   same bridge).
   ::

        fsl_dpaa2_switch dpsw.0: Flooding domain is not per FDB, cannot probe
        fsl_dpaa2_switch dpsw.0: Broadcast domain is not per FDB, cannot probe

 * The control interface of the switch should not be disabled
   (DPSW_OPT_CTRL_IF_DIS not passed as a create time option). Without the
   control interface, the driver is not capable to provide proper Rx/Tx traffic
   support on the switch port netdevices.
   ::

        fsl_dpaa2_switch dpsw.0: Control Interface is disabled, cannot probe

Besides the configuration of the actual DPSW object, the dpaa2-switch driver
will need the following DPAA2 objects:

 * 1 DPMCP - A Management Command Portal object is needed for any interraction
   with the MC firmware.

 * 1 DPBP - A Buffer Pool is used for seeding buffers intended for the Rx path
   on the control interface.

 * Access to at least one DPIO object (Software Portal) is needed for any
   enqueue/dequeue operation to be performed on the control interface queues.
   The DPIO object will be shared, no need for a private one.

Switching features
==================

The driver supports the configuration of L2 forwarding rules in hardware for
port bridging as well as standalone usage of the independent switch interfaces.

The hardware is not configurable with respect to VLAN awareness, thus any DPAA2
switch port should be used only in usecases with a VLAN aware bridge::

        $ ip link add dev br0 type bridge vlan_filtering 1

        $ ip link add dev br1 type bridge
        $ ip link set dev ethX master br1
        Error: fsl_dpaa2_switch: Cannot join a VLAN-unaware bridge

Topology and loop detection through STP is supported when ``stp_state 1`` is
used at bridge create ::

        $ ip link add dev br0 type bridge vlan_filtering 1 stp_state 1

L2 FDB manipulation (add/delete/dump) is supported.

HW FDB learning can be configured on each switch port independently through
bridge commands. When the HW learning is disabled, a fast age procedure will be
run and any previously learnt addresses will be removed.
::

        $ bridge link set dev ethX learning off
        $ bridge link set dev ethX learning on

Restricting the unknown unicast and multicast flooding domain is supported, but
not independently of each other::

        $ ip link set dev ethX type bridge_slave flood off mcast_flood off
        $ ip link set dev ethX type bridge_slave flood off mcast_flood on
        Error: fsl_dpaa2_switch: Cannot configure multicast flooding independently of unicast.

Broadcast flooding on a switch port can be disabled/enabled through the brport sysfs::

        $ echo 0 > /sys/bus/fsl-mc/devices/dpsw.Y/net/ethX/brport/broadcast_flood

Offloads
========

Routing actions (redirect, trap, drop)
--------------------------------------

The DPAA2 switch is able to offload flow-based redirection of packets making
use of ACL tables. Shared filter blocks are supported by sharing a single ACL
table between multiple ports.

The following flow keys are supported:

 * Ethernet: dst_mac/src_mac
 * IPv4: dst_ip/src_ip/ip_proto/tos
 * VLAN: vlan_id/vlan_prio/vlan_tpid/vlan_dei
 * L4: dst_port/src_port

Also, the matchall filter can be used to redirect the entire traffic received
on a port.

As per flow actions, the following are supported:

 * drop
 * mirred egress redirect
 * trap

Each ACL entry (filter) can be setup with only one of the listed
actions.

Example 1: send frames received on eth4 with a SA of 00:01:02:03:04:05 to the
CPU::

        $ tc qdisc add dev eth4 clsact
        $ tc filter add dev eth4 ingress flower src_mac 00:01:02:03:04:05 skip_sw action trap

Example 2: drop frames received on eth4 with VID 100 and PCP of 3::

        $ tc filter add dev eth4 ingress protocol 802.1q flower skip_sw vlan_id 100 vlan_prio 3 action drop

Example 3: redirect all frames received on eth4 to eth1::

        $ tc filter add dev eth4 ingress matchall action mirred egress redirect dev eth1

Example 4: Use a single shared filter block on both eth5 and eth6::

        $ tc qdisc add dev eth5 ingress_block 1 clsact
        $ tc qdisc add dev eth6 ingress_block 1 clsact
        $ tc filter add block 1 ingress flower dst_mac 00:01:02:03:04:04 skip_sw \
                action trap
        $ tc filter add block 1 ingress protocol ipv4 flower src_ip 192.168.1.1 skip_sw \
                action mirred egress redirect dev eth3

Mirroring
~~~~~~~~~

The DPAA2 switch supports only per port mirroring and per VLAN mirroring.
Adding mirroring filters in shared blocks is also supported.

When using the tc-flower classifier with the 802.1q protocol, only the
''vlan_id'' key will be accepted. Mirroring based on any other fields from the
802.1q protocol will be rejected::

        $ tc qdisc add dev eth8 ingress_block 1 clsact
        $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_prio 3 action mirred egress mirror dev eth6
        Error: fsl_dpaa2_switch: Only matching on VLAN ID supported.
        We have an error talking to the kernel

If a mirroring VLAN filter is requested on a port, the VLAN must to be
installed on the switch port in question either using ''bridge'' or by creating
a VLAN upper device if the switch port is used as a standalone interface::

        $ tc qdisc add dev eth8 ingress_block 1 clsact
        $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 200 action mirred egress mirror dev eth6
        Error: VLAN must be installed on the switch port.
        We have an error talking to the kernel

        $ bridge vlan add vid 200 dev eth8
        $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 200 action mirred egress mirror dev eth6

        $ ip link add link eth8 name eth8.200 type vlan id 200
        $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 200 action mirred egress mirror dev eth6

Also, it should be noted that the mirrored traffic will be subject to the same
egress restrictions as any other traffic. This means that when a mirrored
packet will reach the mirror port, if the VLAN found in the packet is not
installed on the port it will get dropped.

The DPAA2 switch supports only a single mirroring destination, thus multiple
mirror rules can be installed but their ''to'' port has to be the same::

        $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 200 action mirred egress mirror dev eth6
        $ tc filter add block 1 ingress protocol 802.1q flower skip_sw vlan_id 100 action mirred egress mirror dev eth7
        Error: fsl_dpaa2_switch: Multiple mirror ports not supported.
        We have an error talking to the kernel


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

===========================
The Gianfar Ethernet Driver
===========================

:Author: Andy Fleming <afleming@freescale.com>
:Updated: 2005-07-28

Checksum Offloading
===================

The eTSEC controller (first included in parts from late 2005 like
the 8548) has the ability to perform TCP, UDP, and IP checksums
in hardware.  The Linux kernel only offloads the TCP and UDP
checksums (and always performs the pseudo header checksums), so
the driver only supports checksumming for TCP/IP and UDP/IP
packets.  Use ethtool to enable or disable this feature for RX
and TX.

VLAN
====

In order to use VLAN, please consult Linux documentation on
configuring VLANs.  The gianfar driver supports hardware insertion and
extraction of VLAN headers, but not filtering.  Filtering will be
done by the kernel.

Multicasting
============

The gianfar driver supports using the group hash table on the
TSEC (and the extended hash table on the eTSEC) for multicast
filtering.  On the eTSEC, the exact-match MAC registers are used
before the hash tables.  See Linux documentation on how to join
multicast groups.

Padding
=======

The gianfar driver supports padding received frames with 2 bytes
to align the IP header to a 16-byte boundary, when supported by
hardware.

Ethtool
=======

The gianfar driver supports the use of ethtool for many
configuration options.  You must run ethtool only on currently
open interfaces.  See ethtool documentation for details.


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

==============================================================
Linux kernel driver for Compute Engine Virtual Ethernet (gve):
==============================================================

Supported Hardware
===================
The GVE driver binds to a single PCI device id used by the virtual
Ethernet device found in some Compute Engine VMs.

+--------------+----------+---------+
|Field         | Value    | Comments|
+==============+==========+=========+
|Vendor ID     | `0x1AE0` | Google  |
+--------------+----------+---------+
|Device ID     | `0x0042` |         |
+--------------+----------+---------+
|Sub-vendor ID | `0x1AE0` | Google  |
+--------------+----------+---------+
|Sub-device ID | `0x0058` |         |
+--------------+----------+---------+
|Revision ID   | `0x0`    |         |
+--------------+----------+---------+
|Device Class  | `0x200`  | Ethernet|
+--------------+----------+---------+

PCI Bars
========
The gVNIC PCI device exposes three 32-bit memory BARS:
- Bar0 - Device configuration and status registers.
- Bar1 - MSI-X vector table
- Bar2 - IRQ, RX and TX doorbells

Device Interactions
===================
The driver interacts with the device in the following ways:
 - Registers
    - A block of MMIO registers
    - See gve_register.h for more detail
 - Admin Queue
    - See description below
 - Reset
    - At any time the device can be reset
 - Interrupts
    - See supported interrupts below
 - Transmit and Receive Queues
    - See description below

Descriptor Formats
------------------
GVE supports two descriptor formats: GQI and DQO. These two formats have
entirely different descriptors, which will be described below.

Registers
---------
All registers are MMIO.

The registers are used for initializing and configuring the device as well as
querying device status in response to management interrupts.

Endianness
----------
- Admin Queue messages and registers are all Big Endian.
- GQI descriptors and datapath registers are Big Endian.
- DQO descriptors and datapath registers are Little Endian.

Admin Queue (AQ)
----------------
The Admin Queue is a PAGE_SIZE memory block, treated as an array of AQ
commands, used by the driver to issue commands to the device and set up
resources.The driver and the device maintain a count of how many commands
have been submitted and executed. To issue AQ commands, the driver must do
the following (with proper locking):

1)  Copy new commands into next available slots in the AQ array
2)  Increment its counter by he number of new commands
3)  Write the counter into the GVE_ADMIN_QUEUE_DOORBELL register
4)  Poll the ADMIN_QUEUE_EVENT_COUNTER register until it equals
    the value written to the doorbell, or until a timeout.

The device will update the status field in each AQ command reported as
executed through the ADMIN_QUEUE_EVENT_COUNTER register.

Device Resets
-------------
A device reset is triggered by writing 0x0 to the AQ PFN register.
This causes the device to release all resources allocated by the
driver, including the AQ itself.

Interrupts
----------
The following interrupts are supported by the driver:

Management Interrupt
~~~~~~~~~~~~~~~~~~~~
The management interrupt is used by the device to tell the driver to
look at the GVE_DEVICE_STATUS register.

The handler for the management irq simply queues the service task in
the workqueue to check the register and acks the irq.

Notification Block Interrupts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The notification block interrupts are used to tell the driver to poll
the queues associated with that interrupt.

The handler for these irqs schedule the napi for that block to run
and poll the queues.

GQI Traffic Queues
------------------
GQI queues are composed of a descriptor ring and a buffer and are assigned to a
notification block.

The descriptor rings are power-of-two-sized ring buffers consisting of
fixed-size descriptors. They advance their head pointer using a __be32
doorbell located in Bar2. The tail pointers are advanced by consuming
descriptors in-order and updating a __be32 counter. Both the doorbell
and the counter overflow to zero.

Each queue's buffers must be registered in advance with the device as a
queue page list, and packet data can only be put in those pages.

Transmit
~~~~~~~~
gve maps the buffers for transmit rings into a FIFO and copies the packets
into the FIFO before sending them to the NIC.

Receive
~~~~~~~
The buffers for receive rings are put into a data ring that is the same
length as the descriptor ring and the head and tail pointers advance over
the rings together.

DQO Traffic Queues
------------------
- Every TX and RX queue is assigned a notification block.

- TX and RX buffers queues, which send descriptors to the device, use MMIO
  doorbells to notify the device of new descriptors.

- RX and TX completion queues, which receive descriptors from the device, use a
  "generation bit" to know when a descriptor was populated by the device. The
  driver initializes all bits with the "current generation". The device will
  populate received descriptors with the "next generation" which is inverted
  from the current generation. When the ring wraps, the current/next generation
  are swapped.

- It's the driver's responsibility to ensure that the RX and TX completion
  queues are not overrun. This can be accomplished by limiting the number of
  descriptors posted to HW.

- TX packets have a 16 bit completion_tag and RX buffers have a 16 bit
  buffer_id. These will be returned on the TX completion and RX queues
  respectively to let the driver know which packet/buffer was completed.

Transmit
~~~~~~~~
A packet's buffers are DMA mapped for the device to access before transmission.
After the packet was successfully transmitted, the buffers are unmapped.

Receive
~~~~~~~
The driver posts fixed sized buffers to HW on the RX buffer queue. The packet
received on the associated RX queue may span multiple descriptors.


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

============================================================
Linux Kernel Driver for Huawei Intelligent NIC(HiNIC) family
============================================================

Overview:
=========
HiNIC is a network interface card for the Data Center Area.

The driver supports a range of link-speed devices (10GbE, 25GbE, 40GbE, etc.).
The driver supports also a negotiated and extendable feature set.

Some HiNIC devices support SR-IOV. This driver is used for Physical Function
(PF).

HiNIC devices support MSI-X interrupt vector for each Tx/Rx queue and
adaptive interrupt moderation.

HiNIC devices support also various offload features such as checksum offload,
TCP Transmit Segmentation Offload(TSO), Receive-Side Scaling(RSS) and
LRO(Large Receive Offload).

Supported PCI vendor ID/device IDs:
===================================

19e5:1822 - HiNIC PF

Driver Architecture and Source Code:
====================================

hinic_dev - Implement a Logical Network device that is independent from
specific HW details about HW data structure formats.

hinic_hwdev - Implement the HW details of the device and include the components
for accessing the PCI NIC.

hinic_hwdev contains the following components:
===============================================

HW Interface:
=============

The interface for accessing the pci device (DMA memory and PCI BARs).
(hinic_hw_if.c, hinic_hw_if.h)

Configuration Status Registers Area that describes the HW Registers on the
configuration and status BAR0. (hinic_hw_csr.h)

MGMT components:
================

Asynchronous Event Queues(AEQs) - The event queues for receiving messages from
the MGMT modules on the cards. (hinic_hw_eqs.c, hinic_hw_eqs.h)

Application Programmable Interface commands(API CMD) - Interface for sending
MGMT commands to the card. (hinic_hw_api_cmd.c, hinic_hw_api_cmd.h)

Management (MGMT) - the PF to MGMT channel that uses API CMD for sending MGMT
commands to the card and receives notifications from the MGMT modules on the
card by AEQs. Also set the addresses of the IO CMDQs in HW.
(hinic_hw_mgmt.c, hinic_hw_mgmt.h)

IO components:
==============

Completion Event Queues(CEQs) - The completion Event Queues that describe IO
tasks that are finished. (hinic_hw_eqs.c, hinic_hw_eqs.h)

Work Queues(WQ) - Contain the memory and operations for use by CMD queues and
the Queue Pairs. The WQ is a Memory Block in a Page. The Block contains
pointers to Memory Areas that are the Memory for the Work Queue Elements(WQEs).
(hinic_hw_wq.c, hinic_hw_wq.h)

Command Queues(CMDQ) - The queues for sending commands for IO management and is
used to set the QPs addresses in HW. The commands completion events are
accumulated on the CEQ that is configured to receive the CMDQ completion events.
(hinic_hw_cmdq.c, hinic_hw_cmdq.h)

Queue Pairs(QPs) - The HW Receive and Send queues for Receiving and Transmitting
Data. (hinic_hw_qp.c, hinic_hw_qp.h, hinic_hw_qp_ctxt.h)

IO - de/constructs all the IO components. (hinic_hw_io.c, hinic_hw_io.h)

HW device:
==========

HW device - de/constructs the HW Interface, the MGMT components on the
initialization of the driver and the IO components on the case of Interface
UP/DOWN Events. (hinic_hw_dev.c, hinic_hw_dev.h)

hinic_dev contains the following components:
===============================================

PCI ID table - Contains the supported PCI Vendor/Device IDs.
(hinic_pci_tbl.h)

Port Commands - Send commands to the HW device for port management
(MAC, Vlan, MTU, ...). (hinic_port.c, hinic_port.h)

Tx Queues - Logical Tx Queues that use the HW Send Queues for transmit.
The Logical Tx queue is not dependent on the format of the HW Send Queue.
(hinic_tx.c, hinic_tx.h)

Rx Queues - Logical Rx Queues that use the HW Receive Queues for receive.
The Logical Rx queue is not dependent on the format of the HW Receive Queue.
(hinic_rx.c, hinic_rx.h)

hinic_dev - de/constructs the Logical Tx and Rx Queues.
(hinic_main.c, hinic_dev.h)

Miscellaneous
=============

Common functions that are used by HW and Logical Device.
(hinic_common.c, hinic_common.h)

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
aviad.krawczyk@huawei.com.


code:
.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

Ethernet Device Drivers
=======================

Device drivers for Ethernet and Ethernet-based virtual function devices.

Contents:

.. toctree::
   :maxdepth: 2

   3com/3c509
   3com/vortex
   amazon/ena
   altera/altera_tse
   aquantia/atlantic
   chelsio/cxgb
   cirrus/cs89x0
   dlink/dl2k
   davicom/dm9000
   dec/dmfe
   freescale/dpaa
   freescale/dpaa2/index
   freescale/gianfar
   google/gve
   huawei/hinic
   intel/e100
   intel/e1000
   intel/e1000e
   intel/fm10k
   intel/igb
   intel/igbvf
   intel/ixgb
   intel/ixgbe
   intel/ixgbevf
   intel/i40e
   intel/iavf
   intel/ice
   marvell/octeontx2
   marvell/octeon_ep
   mellanox/mlx5
   microsoft/netvsc
   neterion/s2io
   netronome/nfp
   pensando/ionic
   smsc/smc9
   stmicro/stmmac
   ti/cpsw
   ti/cpsw_switchdev
   ti/am65_nuss_cpsw_switchdev
   ti/tlan
   toshiba/spider_net
   wangxun/txgbe
   wangxun/ngbe

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


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

=============================================================
Linux Base Driver for the Intel(R) PRO/100 Family of Adapters
=============================================================

June 1, 2018

Contents
========

- In This Release
- Identifying Your Adapter
- Building and Installation
- Driver Configuration Parameters
- Additional Configurations
- Known Issues
- Support

In This Release
===============

This file describes the Linux Base Driver for the Intel(R) PRO/100 Family of
Adapters. This driver includes support for Itanium(R)2-based systems.

For questions related to hardware requirements, refer to the documentation
supplied with your Intel PRO/100 adapter.

The following features are now available in supported kernels:
 - Native VLANs
 - Channel Bonding (teaming)
 - SNMP

Channel Bonding documentation can be found in the Linux kernel source:
/Documentation/networking/bonding.rst

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

For information on how to identify your adapter, and for the latest Intel
network drivers, refer to the Intel Support website:
https://www.intel.com/support

Driver Configuration Parameters
===============================

The default value for each parameter is generally the recommended setting,
unless otherwise noted.

Rx Descriptors:
   Number of receive descriptors. A receive descriptor is a data
   structure that describes a receive buffer and its attributes to the network
   controller. The data in the descriptor is used by the controller to write
   data from the controller to host memory. In the 3.x.x driver the valid range
   for this parameter is 64-256. The default value is 256. This parameter can be
   changed using the command::

     ethtool -G eth? rx n

   Where n is the number of desired Rx descriptors.

Tx Descriptors:
   Number of transmit descriptors. A transmit descriptor is a data
   structure that describes a transmit buffer and its attributes to the network
   controller. The data in the descriptor is used by the controller to read
   data from the host memory to the controller. In the 3.x.x driver the valid
   range for this parameter is 64-256. The default value is 128. This parameter
   can be changed using the command::

     ethtool -G eth? tx n

   Where n is the number of desired Tx descriptors.

Speed/Duplex:
   The driver auto-negotiates the link speed and duplex settings by
   default. The ethtool utility can be used as follows to force speed/duplex.::

     ethtool -s eth?  autoneg off speed {10|100} duplex {full|half}

   NOTE: setting the speed/duplex to incorrect values will cause the link to
   fail.

Event Log Message Level:
   The driver uses the message level flag to log events
   to syslog. The message level can be set at driver load time. It can also be
   set using the command::

     ethtool -s eth? msglvl n

Additional Configurations
=========================

Configuring the Driver on Different Distributions
-------------------------------------------------

Configuring a network driver to load properly when the system is started
is distribution dependent.  Typically, the configuration process involves
adding an alias line to `/etc/modprobe.d/*.conf` as well as editing other
system startup scripts and/or configuration files.  Many popular Linux
distributions ship with tools to make these changes for you.  To learn
the proper way to configure a network device for your system, refer to
your distribution documentation.  If during this process you are asked
for the driver or module name, the name for the Linux Base Driver for
the Intel PRO/100 Family of Adapters is e100.

As an example, if you install the e100 driver for two PRO/100 adapters
(eth0 and eth1), add the following to a configuration file in
/etc/modprobe.d/::

       alias eth0 e100
       alias eth1 e100

Viewing Link Messages
---------------------

In order to see link messages and other Intel driver information on your
console, you must set the dmesg level up to six.  This can be done by
entering the following on the command line before loading the e100
driver::

       dmesg -n 6

If you wish to see all messages issued by the driver, including debug
messages, set the dmesg level to eight.

NOTE: This setting is not saved across reboots.

ethtool
-------

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

The latest release of ethtool can be found from
https://www.kernel.org/pub/software/network/ethtool/

Enabling Wake on LAN (WoL)
--------------------------
WoL is provided through the ethtool utility.  For instructions on
enabling WoL with ethtool, refer to the ethtool man page.  WoL will be
enabled on the system during the next shut down or reboot.  For this
driver version, in order to enable WoL, the e100 driver must be loaded
when shutting down or rebooting the system.

NAPI
----

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

See https://wiki.linuxfoundation.org/networking/napi for more
information on NAPI.

Multiple Interfaces on Same Ethernet Broadcast Network
------------------------------------------------------

Due to the default ARP behavior on Linux, it is not possible to have one
system on two IP networks in the same Ethernet broadcast domain
(non-partitioned switch) behave as expected.  All Ethernet interfaces
will respond to IP traffic for any IP address assigned to the system.
This results in unbalanced receive traffic.

If you have multiple interfaces in a server, either turn on ARP
filtering by

(1) entering::

	echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter

    (this only works if your kernel's version is higher than 2.4.5), or

(2) installing the interfaces in separate broadcast domains (either
    in different switches or in a switch partitioned to VLANs).

Support
=======
For general information, go to the Intel support website at:
https://www.intel.com/support/

or the Intel Wired Networking project hosted by Sourceforge at:
http://sourceforge.net/projects/e1000
If an issue is identified with the released source code on a supported kernel
with a supported adapter, email the specific information related to the issue
to e1000-devel@lists.sf.net.