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