drivers/staging/fsl-dpaa2/ethernet/ethernet-driver.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2 .. include:: <isonum.txt>
   3
   4 ===============================
   5 DPAA2 Ethernet driver
   6 ===============================
   7
   8 :Copyright: |copy| 2017-2018 NXP
   9
  10 This file provides documentation for the Freescale DPAA2 Ethernet driver.
  11
  12 Supported Platforms
  13 ===================
  14 This driver provides networking support for Freescale DPAA2 SoCs, e.g.
  15 LS2080A, LS2088A, LS1088A.
  16
  17
  18 Architecture Overview
  19 =====================
  20 Unlike regular NICs, in the DPAA2 architecture there is no single hardware block
  21 representing network interfaces; instead, several separate hardware resources
  22 concur to provide the networking functionality:
  23
  24 - network interfaces
  25 - queues, channels
  26 - buffer pools
  27 - MAC/PHY
  28
  29 All hardware resources are allocated and configured through the Management
  30 Complex (MC) portals. MC abstracts most of these resources as DPAA2 objects
  31 and exposes ABIs through which they can be configured and controlled. A few
  32 hardware resources, like queues, do not have a corresponding MC object and
  33 are treated as internal resources of other objects.
  34
  35 For a more detailed description of the DPAA2 architecture and its object
  36 abstractions see *Documentation/networking/dpaa2/overview.rst*.
  37
  38 Each Linux net device is built on top of a Datapath Network Interface (DPNI)
  39 object and uses Buffer Pools (DPBPs), I/O Portals (DPIOs) and Concentrators
  40 (DPCONs).
  41
  42 Configuration interface::
  43
  44                  -----------------------
  45                 | DPAA2 Ethernet Driver |
  46                  -----------------------
  47                      .      .      .
  48                      .      .      .
  49              . . . . .      .      . . . . . .
  50              .              .                .
  51              .              .                .
  52          ----------     ----------      -----------
  53         | DPBP API |   | DPNI API |    | DPCON API |
  54          ----------     ----------      -----------
  55              .              .                .             software
  56     =======  .  ==========  .  ============  .  ===================
  57              .              .                .             hardware
  58          ------------------------------------------
  59         |            MC hardware portals           |
  60          ------------------------------------------
  61              .              .                .
  62              .              .                .
  63           ------         ------            -------
  64          | DPBP |       | DPNI |          | DPCON |
  65           ------         ------            -------
  66
  67 The DPNIs are network interfaces without a direct one-on-one mapping to PHYs.
  68 DPBPs represent hardware buffer pools. Packet I/O is performed in the context
  69 of DPCON objects, using DPIO portals for managing and communicating with the
  70 hardware resources.
  71
  72 Datapath (I/O) interface::
  73
  74          -----------------------------------------------
  75         |           DPAA2 Ethernet Driver               |
  76          -----------------------------------------------
  77           |          ^        ^         |            |
  78           |          |        |         |            |
  79    enqueue|   dequeue|   data |  dequeue|       seed |
  80     (Tx)  | (Rx, TxC)|  avail.|  request|     buffers|
  81           |          |  notify|         |            |
  82           |          |        |         |            |
  83           V          |        |         V            V
  84          -----------------------------------------------
  85         |                 DPIO Driver                   |
  86          -----------------------------------------------
  87           |          |        |         |            |          software
  88           |          |        |         |            |  ================
  89           |          |        |         |            |          hardware
  90          -----------------------------------------------
  91         |               I/O hardware portals            |
  92          -----------------------------------------------
  93           |          ^        ^         |            |
  94           |          |        |         |            |
  95           |          |        |         V            |
  96           V          |    ================           V
  97         ----------------------           |      -------------
  98  queues  ----------------------          |     | Buffer pool |
  99           ----------------------         |      -------------
 100                    =======================
 101                                 Channel
 102
 103 Datapath I/O (DPIO) portals provide enqueue and dequeue services, data
 104 availability notifications and buffer pool management. DPIOs are shared between
 105 all DPAA2 objects (and implicitly all DPAA2 kernel drivers) that work with data
 106 frames, but must be affine to the CPUs for the purpose of traffic distribution.
 107
 108 Frames are transmitted and received through hardware frame queues, which can be
 109 grouped in channels for the purpose of hardware scheduling. The Ethernet driver
 110 enqueues TX frames on egress queues and after transmission is complete a TX
 111 confirmation frame is sent back to the CPU.
 112
 113 When frames are available on ingress queues, a data availability notification
 114 is sent to the CPU; notifications are raised per channel, so even if multiple
 115 queues in the same channel have available frames, only one notification is sent.
 116 After a channel fires a notification, is must be explicitly rearmed.
 117
 118 Each network interface can have multiple Rx, Tx and confirmation queues affined
 119 to CPUs, and one channel (DPCON) for each CPU that services at least one queue.
 120 DPCONs are used to distribute ingress traffic to different CPUs via the cores'
 121 affine DPIOs.
 122
 123 The role of hardware buffer pools is storage of ingress frame data. Each network
 124 interface has a privately owned buffer pool which it seeds with kernel allocated
 125 buffers.
 126
 127
 128 DPNIs are decoupled from PHYs; a DPNI can be connected to a PHY through a DPMAC
 129 object or to another DPNI through an internal link, but the connection is
 130 managed by MC and completely transparent to the Ethernet driver.
 131
 132 ::
 133
 134      ---------     ---------     ---------
 135     | eth if1 |   | eth if2 |   | eth ifn |
 136      ---------     ---------     ---------
 137           .           .          .
 138           .           .          .
 139           .           .          .
 140          ---------------------------
 141         |   DPAA2 Ethernet Driver   |
 142          ---------------------------
 143           .           .          .
 144           .           .          .
 145           .           .          .
 146        ------      ------      ------            -------
 147       | DPNI |    | DPNI |    | DPNI |          | DPMAC |----+
 148        ------      ------      ------            -------     |
 149          |           |           |                  |        |
 150          |           |           |                  |      -----
 151           ===========             ==================      | PHY |
 152                                                            -----
 153
 154 Creating a Network Interface
 155 ============================
 156 A net device is created for each DPNI object probed on the MC bus. Each DPNI has
 157 a number of properties which determine the network interface configuration
 158 options and associated hardware resources.
 159
 160 DPNI objects (and the other DPAA2 objects needed for a network interface) can be
 161 added to a container on the MC bus in one of two ways: statically, through a
 162 Datapath Layout Binary file (DPL) that is parsed by MC at boot time; or created
 163 dynamically at runtime, via the DPAA2 objects APIs.
 164
 165
 166 Features & Offloads
 167 ===================
 168 Hardware checksum offloading is supported for TCP and UDP over IPv4/6 frames.
 169 The checksum offloads can be independently configured on RX and TX through
 170 ethtool.
 171
 172 Hardware offload of unicast and multicast MAC filtering is supported on the
 173 ingress path and permanently enabled.
 174
 175 Scatter-gather frames are supported on both RX and TX paths. On TX, SG support
 176 is configurable via ethtool; on RX it is always enabled.
 177
 178 The DPAA2 hardware can process jumbo Ethernet frames of up to 10K bytes.
 179
 180 The Ethernet driver defines a static flow hashing scheme that distributes
 181 traffic based on a 5-tuple key: src IP, dst IP, IP proto, L4 src port,
 182 L4 dst port. No user configuration is supported for now.
 183
 184 Hardware specific statistics for the network interface as well as some
 185 non-standard driver stats can be consulted through ethtool -S option.