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