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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.