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