0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004 ===============================
0005 DPAA2 Ethernet driver
0006 ===============================
0007
0008 :Copyright: |copy| 2017-2018 NXP
0009
0010 This file provides documentation for the Freescale DPAA2 Ethernet driver.
0011
0012 Supported Platforms
0013 ===================
0014 This driver provides networking support for Freescale DPAA2 SoCs, e.g.
0015 LS2080A, LS2088A, LS1088A.
0016
0017
0018 Architecture Overview
0019 =====================
0020 Unlike regular NICs, in the DPAA2 architecture there is no single hardware block
0021 representing network interfaces; instead, several separate hardware resources
0022 concur to provide the networking functionality:
0023
0024 - network interfaces
0025 - queues, channels
0026 - buffer pools
0027 - MAC/PHY
0028
0029 All hardware resources are allocated and configured through the Management
0030 Complex (MC) portals. MC abstracts most of these resources as DPAA2 objects
0031 and exposes ABIs through which they can be configured and controlled. A few
0032 hardware resources, like queues, do not have a corresponding MC object and
0033 are treated as internal resources of other objects.
0034
0035 For a more detailed description of the DPAA2 architecture and its object
0036 abstractions see
0037 *Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst*.
0038
0039 Each Linux net device is built on top of a Datapath Network Interface (DPNI)
0040 object and uses Buffer Pools (DPBPs), I/O Portals (DPIOs) and Concentrators
0041 (DPCONs).
0042
0043 Configuration interface::
0044
0045 -----------------------
0046 | DPAA2 Ethernet Driver |
0047 -----------------------
0048 . . .
0049 . . .
0050 . . . . . . . . . . . .
0051 . . .
0052 . . .
0053 ---------- ---------- -----------
0054 | DPBP API | | DPNI API | | DPCON API |
0055 ---------- ---------- -----------
0056 . . . software
0057 ======= . ========== . ============ . ===================
0058 . . . hardware
0059 ------------------------------------------
0060 | MC hardware portals |
0061 ------------------------------------------
0062 . . .
0063 . . .
0064 ------ ------ -------
0065 | DPBP | | DPNI | | DPCON |
0066 ------ ------ -------
0067
0068 The DPNIs are network interfaces without a direct one-on-one mapping to PHYs.
0069 DPBPs represent hardware buffer pools. Packet I/O is performed in the context
0070 of DPCON objects, using DPIO portals for managing and communicating with the
0071 hardware resources.
0072
0073 Datapath (I/O) interface::
0074
0075 -----------------------------------------------
0076 | DPAA2 Ethernet Driver |
0077 -----------------------------------------------
0078 | ^ ^ | |
0079 | | | | |
0080 enqueue| dequeue| data | dequeue| seed |
0081 (Tx) | (Rx, TxC)| avail.| request| buffers|
0082 | | notify| | |
0083 | | | | |
0084 V | | V V
0085 -----------------------------------------------
0086 | DPIO Driver |
0087 -----------------------------------------------
0088 | | | | | software
0089 | | | | | ================
0090 | | | | | hardware
0091 -----------------------------------------------
0092 | I/O hardware portals |
0093 -----------------------------------------------
0094 | ^ ^ | |
0095 | | | | |
0096 | | | V |
0097 V | ================ V
0098 ---------------------- | -------------
0099 queues ---------------------- | | Buffer pool |
0100 ---------------------- | -------------
0101 =======================
0102 Channel
0103
0104 Datapath I/O (DPIO) portals provide enqueue and dequeue services, data
0105 availability notifications and buffer pool management. DPIOs are shared between
0106 all DPAA2 objects (and implicitly all DPAA2 kernel drivers) that work with data
0107 frames, but must be affine to the CPUs for the purpose of traffic distribution.
0108
0109 Frames are transmitted and received through hardware frame queues, which can be
0110 grouped in channels for the purpose of hardware scheduling. The Ethernet driver
0111 enqueues TX frames on egress queues and after transmission is complete a TX
0112 confirmation frame is sent back to the CPU.
0113
0114 When frames are available on ingress queues, a data availability notification
0115 is sent to the CPU; notifications are raised per channel, so even if multiple
0116 queues in the same channel have available frames, only one notification is sent.
0117 After a channel fires a notification, is must be explicitly rearmed.
0118
0119 Each network interface can have multiple Rx, Tx and confirmation queues affined
0120 to CPUs, and one channel (DPCON) for each CPU that services at least one queue.
0121 DPCONs are used to distribute ingress traffic to different CPUs via the cores'
0122 affine DPIOs.
0123
0124 The role of hardware buffer pools is storage of ingress frame data. Each network
0125 interface has a privately owned buffer pool which it seeds with kernel allocated
0126 buffers.
0127
0128
0129 DPNIs are decoupled from PHYs; a DPNI can be connected to a PHY through a DPMAC
0130 object or to another DPNI through an internal link, but the connection is
0131 managed by MC and completely transparent to the Ethernet driver.
0132
0133 ::
0134
0135 --------- --------- ---------
0136 | eth if1 | | eth if2 | | eth ifn |
0137 --------- --------- ---------
0138 . . .
0139 . . .
0140 . . .
0141 ---------------------------
0142 | DPAA2 Ethernet Driver |
0143 ---------------------------
0144 . . .
0145 . . .
0146 . . .
0147 ------ ------ ------ -------
0148 | DPNI | | DPNI | | DPNI | | DPMAC |----+
0149 ------ ------ ------ ------- |
0150 | | | | |
0151 | | | | -----
0152 =========== ================== | PHY |
0153 -----
0154
0155 Creating a Network Interface
0156 ============================
0157 A net device is created for each DPNI object probed on the MC bus. Each DPNI has
0158 a number of properties which determine the network interface configuration
0159 options and associated hardware resources.
0160
0161 DPNI objects (and the other DPAA2 objects needed for a network interface) can be
0162 added to a container on the MC bus in one of two ways: statically, through a
0163 Datapath Layout Binary file (DPL) that is parsed by MC at boot time; or created
0164 dynamically at runtime, via the DPAA2 objects APIs.
0165
0166
0167 Features & Offloads
0168 ===================
0169 Hardware checksum offloading is supported for TCP and UDP over IPv4/6 frames.
0170 The checksum offloads can be independently configured on RX and TX through
0171 ethtool.
0172
0173 Hardware offload of unicast and multicast MAC filtering is supported on the
0174 ingress path and permanently enabled.
0175
0176 Scatter-gather frames are supported on both RX and TX paths. On TX, SG support
0177 is configurable via ethtool; on RX it is always enabled.
0178
0179 The DPAA2 hardware can process jumbo Ethernet frames of up to 10K bytes.
0180
0181 The Ethernet driver defines a static flow hashing scheme that distributes
0182 traffic based on a 5-tuple key: src IP, dst IP, IP proto, L4 src port,
0183 L4 dst port. No user configuration is supported for now.
0184
0185 Hardware specific statistics for the network interface as well as some
0186 non-standard driver stats can be consulted through ethtool -S option.
