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