drivers/staging/fsl-mc/overview.rst

   1 .. include:: <isonum.txt>
   2
   3 DPAA2 (Data Path Acceleration Architecture Gen2) Overview
   4 =========================================================
   5
   6 :Copyright: |copy| 2015 Freescale Semiconductor Inc.
   7 :Copyright: |copy| 2018 NXP
   8
   9 This document provides an overview of the Freescale DPAA2 architecture
  10 and how it is integrated into the Linux kernel.
  11
  12 Introduction
  13 ============
  14
  15 DPAA2 is a hardware architecture designed for high-speeed network
  16 packet processing.  DPAA2 consists of sophisticated mechanisms for
  17 processing Ethernet packets, queue management, buffer management,
  18 autonomous L2 switching, virtual Ethernet bridging, and accelerator
  19 (e.g. crypto) sharing.
  20
  21 A DPAA2 hardware component called the Management Complex (or MC) manages the
  22 DPAA2 hardware resources.  The MC provides an object-based abstraction for
  23 software drivers to use the DPAA2 hardware.
  24 The MC uses DPAA2 hardware resources such as queues, buffer pools, and
  25 network ports to create functional objects/devices such as network
  26 interfaces, an L2 switch, or accelerator instances.
  27 The MC provides memory-mapped I/O command interfaces (MC portals)
  28 which DPAA2 software drivers use to operate on DPAA2 objects.
  29
  30 The diagram below shows an overview of the DPAA2 resource management
  31 architecture::
  32
  33         +--------------------------------------+
  34         |                  OS                  |
  35         |                        DPAA2 drivers |
  36         |                             |        |
  37         +-----------------------------|--------+
  38                                       |
  39                                       | (create,discover,connect
  40                                       |  config,use,destroy)
  41                                       |
  42                          DPAA2        |
  43         +------------------------| mc portal |-+
  44         |                             |        |
  45         |   +- - - - - - - - - - - - -V- - -+  |
  46         |   |                               |  |
  47         |   |   Management Complex (MC)     |  |
  48         |   |                               |  |
  49         |   +- - - - - - - - - - - - - - - -+  |
  50         |                                      |
  51         | Hardware                  Hardware   |
  52         | Resources                 Objects    |
  53         | ---------                 -------    |
  54         | -queues                   -DPRC      |
  55         | -buffer pools             -DPMCP     |
  56         | -Eth MACs/ports           -DPIO      |
  57         | -network interface        -DPNI      |
  58         |  profiles                 -DPMAC     |
  59         | -queue portals            -DPBP      |
  60         | -MC portals                ...       |
  61         |  ...                                 |
  62         |                                      |
  63         +--------------------------------------+
  64
  65
  66 The MC mediates operations such as create, discover,
  67 connect, configuration, and destroy.  Fast-path operations
  68 on data, such as packet transmit/receive, are not mediated by
  69 the MC and are done directly using memory mapped regions in
  70 DPIO objects.
  71
  72 Overview of DPAA2 Objects
  73 =========================
  74
  75 The section provides a brief overview of some key DPAA2 objects.
  76 A simple scenario is described illustrating the objects involved
  77 in creating a network interfaces.
  78
  79 DPRC (Datapath Resource Container)
  80 ----------------------------------
  81
  82 A DPRC is a container object that holds all the other
  83 types of DPAA2 objects.  In the example diagram below there
  84 are 8 objects of 5 types (DPMCP, DPIO, DPBP, DPNI, and DPMAC)
  85 in the container.
  86
  87 ::
  88
  89         +---------------------------------------------------------+
  90         | DPRC                                                    |
  91         |                                                         |
  92         |  +-------+  +-------+  +-------+  +-------+  +-------+  |
  93         |  | DPMCP |  | DPIO  |  | DPBP  |  | DPNI  |  | DPMAC |  |
  94         |  +-------+  +-------+  +-------+  +---+---+  +---+---+  |
  95         |  | DPMCP |  | DPIO  |                                   |
  96         |  +-------+  +-------+                                   |
  97         |  | DPMCP |                                              |
  98         |  +-------+                                              |
  99         |                                                         |
 100         +---------------------------------------------------------+
 101
 102 From the point of view of an OS, a DPRC behaves similar to a plug and
 103 play bus, like PCI.  DPRC commands can be used to enumerate the contents
 104 of the DPRC, discover the hardware objects present (including mappable
 105 regions and interrupts).
 106
 107 ::
 108
 109         DPRC.1 (bus)
 110            |
 111            +--+--------+-------+-------+-------+
 112               |        |       |       |       |
 113             DPMCP.1  DPIO.1  DPBP.1  DPNI.1  DPMAC.1
 114             DPMCP.2  DPIO.2
 115             DPMCP.3
 116
 117 Hardware objects can be created and destroyed dynamically, providing
 118 the ability to hot plug/unplug objects in and out of the DPRC.
 119
 120 A DPRC has a mappable MMIO region (an MC portal) that can be used
 121 to send MC commands.  It has an interrupt for status events (like
 122 hotplug).
 123 All objects in a container share the same hardware "isolation context".
 124 This means that with respect to an IOMMU the isolation granularity
 125 is at the DPRC (container) level, not at the individual object
 126 level.
 127
 128 DPRCs can be defined statically and populated with objects
 129 via a config file passed to the MC when firmware starts it.
 130
 131 DPAA2 Objects for an Ethernet Network Interface
 132 -----------------------------------------------
 133
 134 A typical Ethernet NIC is monolithic-- the NIC device contains TX/RX
 135 queuing mechanisms, configuration mechanisms, buffer management,
 136 physical ports, and interrupts.  DPAA2 uses a more granular approach
 137 utilizing multiple hardware objects.  Each object provides specialized
 138 functions. Groups of these objects are used by software to provide
 139 Ethernet network interface functionality.  This approach provides
 140 efficient use of finite hardware resources, flexibility, and
 141 performance advantages.
 142
 143 The diagram below shows the objects needed for a simple
 144 network interface configuration on a system with 2 CPUs.
 145
 146 ::
 147
 148         +---+---+ +---+---+
 149            CPU0     CPU1
 150         +---+---+ +---+---+
 151             |         |
 152         +---+---+ +---+---+
 153            DPIO     DPIO
 154         +---+---+ +---+---+
 155             \     /
 156              \   /
 157               \ /
 158            +---+---+
 159               DPNI  --- DPBP,DPMCP
 160            +---+---+
 161                |
 162                |
 163            +---+---+
 164              DPMAC
 165            +---+---+
 166                |
 167            port/PHY
 168
 169 Below the objects are described.  For each object a brief description
 170 is provided along with a summary of the kinds of operations the object
 171 supports and a summary of key resources of the object (MMIO regions
 172 and IRQs).
 173
 174 DPMAC (Datapath Ethernet MAC)
 175 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 176 Represents an Ethernet MAC, a hardware device that connects to an Ethernet
 177 PHY and allows physical transmission and reception of Ethernet frames.
 178
 179 - MMIO regions: none
 180 - IRQs: DPNI link change
 181 - commands: set link up/down, link config, get stats,
 182   IRQ config, enable, reset
 183
 184 DPNI (Datapath Network Interface)
 185 Contains TX/RX queues, network interface configuration, and RX buffer pool
 186 configuration mechanisms.  The TX/RX queues are in memory and are identified
 187 by queue number.
 188
 189 - MMIO regions: none
 190 - IRQs: link state
 191 - commands: port config, offload config, queue config,
 192   parse/classify config, IRQ config, enable, reset
 193
 194 DPIO (Datapath I/O)
 195 ~~~~~~~~~~~~~~~~~~~
 196 Provides interfaces to enqueue and dequeue
 197 packets and do hardware buffer pool management operations.  The DPAA2
 198 architecture separates the mechanism to access queues (the DPIO object)
 199 from the queues themselves.  The DPIO provides an MMIO interface to
 200 enqueue/dequeue packets.  To enqueue something a descriptor is written
 201 to the DPIO MMIO region, which includes the target queue number.
 202 There will typically be one DPIO assigned to each CPU.  This allows all
 203 CPUs to simultaneously perform enqueue/dequeued operations.  DPIOs are
 204 expected to be shared by different DPAA2 drivers.
 205
 206 - MMIO regions: queue operations, buffer management
 207 - IRQs: data availability, congestion notification, buffer
 208   pool depletion
 209 - commands: IRQ config, enable, reset
 210
 211 DPBP (Datapath Buffer Pool)
 212 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 213 Represents a hardware buffer pool.
 214
 215 - MMIO regions: none
 216 - IRQs: none
 217 - commands: enable, reset
 218
 219 DPMCP (Datapath MC Portal)
 220 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 221 Provides an MC command portal.
 222 Used by drivers to send commands to the MC to manage
 223 objects.
 224
 225 - MMIO regions: MC command portal
 226 - IRQs: command completion
 227 - commands: IRQ config, enable, reset
 228
 229 Object Connections
 230 ==================
 231 Some objects have explicit relationships that must
 232 be configured:
 233
 234 - DPNI <--> DPMAC
 235 - DPNI <--> DPNI
 236 - DPNI <--> L2-switch-port
 237
 238     A DPNI must be connected to something such as a DPMAC,
 239     another DPNI, or L2 switch port.  The DPNI connection
 240     is made via a DPRC command.
 241
 242 ::
 243
 244               +-------+  +-------+
 245               | DPNI  |  | DPMAC |
 246               +---+---+  +---+---+
 247                   |          |
 248                   +==========+
 249
 250 - DPNI <--> DPBP
 251
 252     A network interface requires a 'buffer pool' (DPBP
 253     object) which provides a list of pointers to memory
 254     where received Ethernet data is to be copied.  The
 255     Ethernet driver configures the DPBPs associated with
 256     the network interface.
 257
 258 Interrupts
 259 ==========
 260 All interrupts generated by DPAA2 objects are message
 261 interrupts.  At the hardware level message interrupts
 262 generated by devices will normally have 3 components--
 263 1) a non-spoofable 'device-id' expressed on the hardware
 264 bus, 2) an address, 3) a data value.
 265
 266 In the case of DPAA2 devices/objects, all objects in the
 267 same container/DPRC share the same 'device-id'.
 268 For ARM-based SoC this is the same as the stream ID.
 269
 270
 271 DPAA2 Linux Drivers Overview
 272 ============================
 273
 274 This section provides an overview of the Linux kernel drivers for
 275 DPAA2-- 1) the bus driver and associated "DPAA2 infrastructure"
 276 drivers and 2) functional object drivers (such as Ethernet).
 277
 278 As described previously, a DPRC is a container that holds the other
 279 types of DPAA2 objects.  It is functionally similar to a plug-and-play
 280 bus controller.
 281 Each object in the DPRC is a Linux "device" and is bound to a driver.
 282 The diagram below shows the Linux drivers involved in a networking
 283 scenario and the objects bound to each driver.  A brief description
 284 of each driver follows.
 285
 286 ::
 287
 288                                              +------------+
 289                                              | OS Network |
 290                                              |   Stack    |
 291                  +------------+              +------------+
 292                  | Allocator  |. . . . . . . |  Ethernet  |
 293                  |(DPMCP,DPBP)|              |   (DPNI)   |
 294                  +-.----------+              +---+---+----+
 295                   .          .                   ^   |
 296                  .            .     <data avail, |   | <enqueue,
 297                 .              .     tx confirm> |   | dequeue>
 298         +-------------+         .                |   |
 299         | DPRC driver |          .           +---+---V----+     +---------+
 300         |   (DPRC)    |           . . . . . .| DPIO driver|     |   MAC   |
 301         +----------+--+                      |  (DPIO)    |     | (DPMAC) |
 302                    |                         +------+-----+     +-----+---+
 303                    |<dev add/remove>                |                 |
 304                    |                                |                 |
 305           +--------+----------+                     |              +--+---+
 306           |   MC-bus driver   |                     |              | PHY  |
 307           |                   |                     |              |driver|
 308           |   /bus/fsl-mc     |                     |              +--+---+
 309           +-------------------+                     |                 |
 310                                                     |                 |
 311         ========================= HARDWARE =========|=================|======
 312                                                   DPIO                |
 313                                                     |                 |
 314                                                   DPNI---DPBP         |
 315                                                     |                 |
 316                                                   DPMAC               |
 317                                                     |                 |
 318                                                    PHY ---------------+
 319         ============================================|========================
 320
 321 A brief description of each driver is provided below.
 322
 323 MC-bus driver
 324 -------------
 325 The MC-bus driver is a platform driver and is probed from a
 326 node in the device tree (compatible "fsl,qoriq-mc") passed in by boot
 327 firmware.  It is responsible for bootstrapping the DPAA2 kernel
 328 infrastructure.
 329 Key functions include:
 330
 331 - registering a new bus type named "fsl-mc" with the kernel,
 332   and implementing bus call-backs (e.g. match/uevent/dev_groups)
 333 - implementing APIs for DPAA2 driver registration and for device
 334   add/remove
 335 - creates an MSI IRQ domain
 336 - doing a 'device add' to expose the 'root' DPRC, in turn triggering
 337   a bind of the root DPRC to the DPRC driver
 338
 339 The binding for the MC-bus device-tree node can be consulted at
 340 *Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt*.
 341 The sysfs bind/unbind interfaces for the MC-bus can be consulted at
 342 *Documentation/ABI/testing/sysfs-bus-fsl-mc*.
 343
 344 DPRC driver
 345 -----------
 346 The DPRC driver is bound to DPRC objects and does runtime management
 347 of a bus instance.  It performs the initial bus scan of the DPRC
 348 and handles interrupts for container events such as hot plug by
 349 re-scanning the DPRC.
 350
 351 Allocator
 352 ---------
 353 Certain objects such as DPMCP and DPBP are generic and fungible,
 354 and are intended to be used by other drivers.  For example,
 355 the DPAA2 Ethernet driver needs:
 356
 357 - DPMCPs to send MC commands, to configure network interfaces
 358 - DPBPs for network buffer pools
 359
 360 The allocator driver registers for these allocatable object types
 361 and those objects are bound to the allocator when the bus is probed.
 362 The allocator maintains a pool of objects that are available for
 363 allocation by other DPAA2 drivers.
 364
 365 DPIO driver
 366 -----------
 367 The DPIO driver is bound to DPIO objects and provides services that allow
 368 other drivers such as the Ethernet driver to enqueue and dequeue data for
 369 their respective objects.
 370 Key services include:
 371
 372 - data availability notifications
 373 - hardware queuing operations (enqueue and dequeue of data)
 374 - hardware buffer pool management
 375
 376 To transmit a packet the Ethernet driver puts data on a queue and
 377 invokes a DPIO API.  For receive, the Ethernet driver registers
 378 a data availability notification callback.  To dequeue a packet
 379 a DPIO API is used.
 380 There is typically one DPIO object per physical CPU for optimum
 381 performance, allowing different CPUs to simultaneously enqueue
 382 and dequeue data.
 383
 384 The DPIO driver operates on behalf of all DPAA2 drivers
 385 active in the kernel--  Ethernet, crypto, compression,
 386 etc.
 387
 388 Ethernet driver
 389 ---------------
 390 The Ethernet driver is bound to a DPNI and implements the kernel
 391 interfaces needed to connect the DPAA2 network interface to
 392 the network stack.
 393 Each DPNI corresponds to a Linux network interface.
 394
 395 MAC driver
 396 ----------
 397 An Ethernet PHY is an off-chip, board specific component and is managed
 398 by the appropriate PHY driver via an mdio bus.  The MAC driver
 399 plays a role of being a proxy between the PHY driver and the
 400 MC.  It does this proxy via the MC commands to a DPMAC object.
 401 If the PHY driver signals a link change, the MAC driver notifies
 402 the MC via a DPMAC command.  If a network interface is brought
 403 up or down, the MC notifies the DPMAC driver via an interrupt and
 404 the driver can take appropriate action.