1132db935SJakub Kicinski.. SPDX-License-Identifier: GPL-2.0 2132db935SJakub Kicinski.. include:: <isonum.txt> 3132db935SJakub Kicinski 4132db935SJakub Kicinski=============================== 5132db935SJakub KicinskiDPAA2 Ethernet driver 6132db935SJakub Kicinski=============================== 7132db935SJakub Kicinski 8132db935SJakub Kicinski:Copyright: |copy| 2017-2018 NXP 9132db935SJakub Kicinski 10132db935SJakub KicinskiThis file provides documentation for the Freescale DPAA2 Ethernet driver. 11132db935SJakub Kicinski 12132db935SJakub KicinskiSupported Platforms 13132db935SJakub Kicinski=================== 14132db935SJakub KicinskiThis driver provides networking support for Freescale DPAA2 SoCs, e.g. 15132db935SJakub KicinskiLS2080A, LS2088A, LS1088A. 16132db935SJakub Kicinski 17132db935SJakub Kicinski 18132db935SJakub KicinskiArchitecture Overview 19132db935SJakub Kicinski===================== 20132db935SJakub KicinskiUnlike regular NICs, in the DPAA2 architecture there is no single hardware block 21132db935SJakub Kicinskirepresenting network interfaces; instead, several separate hardware resources 22132db935SJakub Kicinskiconcur to provide the networking functionality: 23132db935SJakub Kicinski 24132db935SJakub Kicinski- network interfaces 25132db935SJakub Kicinski- queues, channels 26132db935SJakub Kicinski- buffer pools 27132db935SJakub Kicinski- MAC/PHY 28132db935SJakub Kicinski 29132db935SJakub KicinskiAll hardware resources are allocated and configured through the Management 30132db935SJakub KicinskiComplex (MC) portals. MC abstracts most of these resources as DPAA2 objects 31132db935SJakub Kicinskiand exposes ABIs through which they can be configured and controlled. A few 32132db935SJakub Kicinskihardware resources, like queues, do not have a corresponding MC object and 33132db935SJakub Kicinskiare treated as internal resources of other objects. 34132db935SJakub Kicinski 35132db935SJakub KicinskiFor a more detailed description of the DPAA2 architecture and its object 36132db935SJakub Kicinskiabstractions see 37132db935SJakub Kicinski*Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst*. 38132db935SJakub Kicinski 39132db935SJakub KicinskiEach Linux net device is built on top of a Datapath Network Interface (DPNI) 40132db935SJakub Kicinskiobject and uses Buffer Pools (DPBPs), I/O Portals (DPIOs) and Concentrators 41132db935SJakub Kicinski(DPCONs). 42132db935SJakub Kicinski 43132db935SJakub KicinskiConfiguration interface:: 44132db935SJakub Kicinski 45132db935SJakub Kicinski ----------------------- 46132db935SJakub Kicinski | DPAA2 Ethernet Driver | 47132db935SJakub Kicinski ----------------------- 48132db935SJakub Kicinski . . . 49132db935SJakub Kicinski . . . 50132db935SJakub Kicinski . . . . . . . . . . . . 51132db935SJakub Kicinski . . . 52132db935SJakub Kicinski . . . 53132db935SJakub Kicinski ---------- ---------- ----------- 54132db935SJakub Kicinski | DPBP API | | DPNI API | | DPCON API | 55132db935SJakub Kicinski ---------- ---------- ----------- 56132db935SJakub Kicinski . . . software 57132db935SJakub Kicinski ======= . ========== . ============ . =================== 58132db935SJakub Kicinski . . . hardware 59132db935SJakub Kicinski ------------------------------------------ 60132db935SJakub Kicinski | MC hardware portals | 61132db935SJakub Kicinski ------------------------------------------ 62132db935SJakub Kicinski . . . 63132db935SJakub Kicinski . . . 64132db935SJakub Kicinski ------ ------ ------- 65132db935SJakub Kicinski | DPBP | | DPNI | | DPCON | 66132db935SJakub Kicinski ------ ------ ------- 67132db935SJakub Kicinski 68132db935SJakub KicinskiThe DPNIs are network interfaces without a direct one-on-one mapping to PHYs. 69132db935SJakub KicinskiDPBPs represent hardware buffer pools. Packet I/O is performed in the context 70132db935SJakub Kicinskiof DPCON objects, using DPIO portals for managing and communicating with the 71132db935SJakub Kicinskihardware resources. 72132db935SJakub Kicinski 73132db935SJakub KicinskiDatapath (I/O) interface:: 74132db935SJakub Kicinski 75132db935SJakub Kicinski ----------------------------------------------- 76132db935SJakub Kicinski | DPAA2 Ethernet Driver | 77132db935SJakub Kicinski ----------------------------------------------- 78132db935SJakub Kicinski | ^ ^ | | 79132db935SJakub Kicinski | | | | | 80132db935SJakub Kicinski enqueue| dequeue| data | dequeue| seed | 81132db935SJakub Kicinski (Tx) | (Rx, TxC)| avail.| request| buffers| 82132db935SJakub Kicinski | | notify| | | 83132db935SJakub Kicinski | | | | | 84132db935SJakub Kicinski V | | V V 85132db935SJakub Kicinski ----------------------------------------------- 86132db935SJakub Kicinski | DPIO Driver | 87132db935SJakub Kicinski ----------------------------------------------- 88132db935SJakub Kicinski | | | | | software 89132db935SJakub Kicinski | | | | | ================ 90132db935SJakub Kicinski | | | | | hardware 91132db935SJakub Kicinski ----------------------------------------------- 92132db935SJakub Kicinski | I/O hardware portals | 93132db935SJakub Kicinski ----------------------------------------------- 94132db935SJakub Kicinski | ^ ^ | | 95132db935SJakub Kicinski | | | | | 96132db935SJakub Kicinski | | | V | 97132db935SJakub Kicinski V | ================ V 98132db935SJakub Kicinski ---------------------- | ------------- 99132db935SJakub Kicinski queues ---------------------- | | Buffer pool | 100132db935SJakub Kicinski ---------------------- | ------------- 101132db935SJakub Kicinski ======================= 102132db935SJakub Kicinski Channel 103132db935SJakub Kicinski 104132db935SJakub KicinskiDatapath I/O (DPIO) portals provide enqueue and dequeue services, data 105132db935SJakub Kicinskiavailability notifications and buffer pool management. DPIOs are shared between 106132db935SJakub Kicinskiall DPAA2 objects (and implicitly all DPAA2 kernel drivers) that work with data 107132db935SJakub Kicinskiframes, but must be affine to the CPUs for the purpose of traffic distribution. 108132db935SJakub Kicinski 109132db935SJakub KicinskiFrames are transmitted and received through hardware frame queues, which can be 110132db935SJakub Kicinskigrouped in channels for the purpose of hardware scheduling. The Ethernet driver 111132db935SJakub Kicinskienqueues TX frames on egress queues and after transmission is complete a TX 112132db935SJakub Kicinskiconfirmation frame is sent back to the CPU. 113132db935SJakub Kicinski 114132db935SJakub KicinskiWhen frames are available on ingress queues, a data availability notification 115132db935SJakub Kicinskiis sent to the CPU; notifications are raised per channel, so even if multiple 116132db935SJakub Kicinskiqueues in the same channel have available frames, only one notification is sent. 117132db935SJakub KicinskiAfter a channel fires a notification, is must be explicitly rearmed. 118132db935SJakub Kicinski 119132db935SJakub KicinskiEach network interface can have multiple Rx, Tx and confirmation queues affined 120132db935SJakub Kicinskito CPUs, and one channel (DPCON) for each CPU that services at least one queue. 121132db935SJakub KicinskiDPCONs are used to distribute ingress traffic to different CPUs via the cores' 122132db935SJakub Kicinskiaffine DPIOs. 123132db935SJakub Kicinski 124132db935SJakub KicinskiThe role of hardware buffer pools is storage of ingress frame data. Each network 125132db935SJakub Kicinskiinterface has a privately owned buffer pool which it seeds with kernel allocated 126132db935SJakub Kicinskibuffers. 127132db935SJakub Kicinski 128132db935SJakub Kicinski 129132db935SJakub KicinskiDPNIs are decoupled from PHYs; a DPNI can be connected to a PHY through a DPMAC 130132db935SJakub Kicinskiobject or to another DPNI through an internal link, but the connection is 131132db935SJakub Kicinskimanaged by MC and completely transparent to the Ethernet driver. 132132db935SJakub Kicinski 133132db935SJakub Kicinski:: 134132db935SJakub Kicinski 135132db935SJakub Kicinski --------- --------- --------- 136132db935SJakub Kicinski | eth if1 | | eth if2 | | eth ifn | 137132db935SJakub Kicinski --------- --------- --------- 138132db935SJakub Kicinski . . . 139132db935SJakub Kicinski . . . 140132db935SJakub Kicinski . . . 141132db935SJakub Kicinski --------------------------- 142132db935SJakub Kicinski | DPAA2 Ethernet Driver | 143132db935SJakub Kicinski --------------------------- 144132db935SJakub Kicinski . . . 145132db935SJakub Kicinski . . . 146132db935SJakub Kicinski . . . 147132db935SJakub Kicinski ------ ------ ------ ------- 148132db935SJakub Kicinski | DPNI | | DPNI | | DPNI | | DPMAC |----+ 149132db935SJakub Kicinski ------ ------ ------ ------- | 150132db935SJakub Kicinski | | | | | 151132db935SJakub Kicinski | | | | ----- 152132db935SJakub Kicinski =========== ================== | PHY | 153132db935SJakub Kicinski ----- 154132db935SJakub Kicinski 155132db935SJakub KicinskiCreating a Network Interface 156132db935SJakub Kicinski============================ 157132db935SJakub KicinskiA net device is created for each DPNI object probed on the MC bus. Each DPNI has 158132db935SJakub Kicinskia number of properties which determine the network interface configuration 159132db935SJakub Kicinskioptions and associated hardware resources. 160132db935SJakub Kicinski 161132db935SJakub KicinskiDPNI objects (and the other DPAA2 objects needed for a network interface) can be 162132db935SJakub Kicinskiadded to a container on the MC bus in one of two ways: statically, through a 163132db935SJakub KicinskiDatapath Layout Binary file (DPL) that is parsed by MC at boot time; or created 164132db935SJakub Kicinskidynamically at runtime, via the DPAA2 objects APIs. 165132db935SJakub Kicinski 166132db935SJakub Kicinski 167132db935SJakub KicinskiFeatures & Offloads 168132db935SJakub Kicinski=================== 169132db935SJakub KicinskiHardware checksum offloading is supported for TCP and UDP over IPv4/6 frames. 170132db935SJakub KicinskiThe checksum offloads can be independently configured on RX and TX through 171132db935SJakub Kicinskiethtool. 172132db935SJakub Kicinski 173132db935SJakub KicinskiHardware offload of unicast and multicast MAC filtering is supported on the 174132db935SJakub Kicinskiingress path and permanently enabled. 175132db935SJakub Kicinski 176132db935SJakub KicinskiScatter-gather frames are supported on both RX and TX paths. On TX, SG support 177132db935SJakub Kicinskiis configurable via ethtool; on RX it is always enabled. 178132db935SJakub Kicinski 179132db935SJakub KicinskiThe DPAA2 hardware can process jumbo Ethernet frames of up to 10K bytes. 180132db935SJakub Kicinski 181132db935SJakub KicinskiThe Ethernet driver defines a static flow hashing scheme that distributes 182132db935SJakub Kicinskitraffic based on a 5-tuple key: src IP, dst IP, IP proto, L4 src port, 183132db935SJakub KicinskiL4 dst port. No user configuration is supported for now. 184132db935SJakub Kicinski 185132db935SJakub KicinskiHardware specific statistics for the network interface as well as some 186132db935SJakub Kicinskinon-standard driver stats can be consulted through ethtool -S option. 187