diff options
Diffstat (limited to 'drivers/staging/fsl-mc/overview.rst')
| -rw-r--r-- | drivers/staging/fsl-mc/overview.rst | 404 |
1 files changed, 404 insertions, 0 deletions
diff --git a/drivers/staging/fsl-mc/overview.rst b/drivers/staging/fsl-mc/overview.rst new file mode 100644 index 000000000000..79fede4447d6 --- /dev/null +++ b/drivers/staging/fsl-mc/overview.rst @@ -0,0 +1,404 @@ +.. include:: <isonum.txt> + +DPAA2 (Data Path Acceleration Architecture Gen2) Overview +========================================================= + +:Copyright: |copy| 2015 Freescale Semiconductor Inc. +:Copyright: |copy| 2018 NXP + +This document provides an overview of the Freescale DPAA2 architecture +and how it is integrated into the Linux kernel. + +Introduction +============ + +DPAA2 is a hardware architecture designed for high-speeed network +packet processing. DPAA2 consists of sophisticated mechanisms for +processing Ethernet packets, queue management, buffer management, +autonomous L2 switching, virtual Ethernet bridging, and accelerator +(e.g. crypto) sharing. + +A DPAA2 hardware component called the Management Complex (or MC) manages the +DPAA2 hardware resources. The MC provides an object-based abstraction for +software drivers to use the DPAA2 hardware. +The MC uses DPAA2 hardware resources such as queues, buffer pools, and +network ports to create functional objects/devices such as network +interfaces, an L2 switch, or accelerator instances. +The MC provides memory-mapped I/O command interfaces (MC portals) +which DPAA2 software drivers use to operate on DPAA2 objects. + +The diagram below shows an overview of the DPAA2 resource management +architecture:: + + +--------------------------------------+ + | OS | + | DPAA2 drivers | + | | | + +-----------------------------|--------+ + | + | (create,discover,connect + | config,use,destroy) + | + DPAA2 | + +------------------------| mc portal |-+ + | | | + | +- - - - - - - - - - - - -V- - -+ | + | | | | + | | Management Complex (MC) | | + | | | | + | +- - - - - - - - - - - - - - - -+ | + | | + | Hardware Hardware | + | Resources Objects | + | --------- ------- | + | -queues -DPRC | + | -buffer pools -DPMCP | + | -Eth MACs/ports -DPIO | + | -network interface -DPNI | + | profiles -DPMAC | + | -queue portals -DPBP | + | -MC portals ... | + | ... | + | | + +--------------------------------------+ + + +The MC mediates operations such as create, discover, +connect, configuration, and destroy. Fast-path operations +on data, such as packet transmit/receive, are not mediated by +the MC and are done directly using memory mapped regions in +DPIO objects. + +Overview of DPAA2 Objects +========================= + +The section provides a brief overview of some key DPAA2 objects. +A simple scenario is described illustrating the objects involved +in creating a network interfaces. + +DPRC (Datapath Resource Container) +---------------------------------- + +A DPRC is a container object that holds all the other +types of DPAA2 objects. In the example diagram below there +are 8 objects of 5 types (DPMCP, DPIO, DPBP, DPNI, and DPMAC) +in the container. + +:: + + +---------------------------------------------------------+ + | DPRC | + | | + | +-------+ +-------+ +-------+ +-------+ +-------+ | + | | DPMCP | | DPIO | | DPBP | | DPNI | | DPMAC | | + | +-------+ +-------+ +-------+ +---+---+ +---+---+ | + | | DPMCP | | DPIO | | + | +-------+ +-------+ | + | | DPMCP | | + | +-------+ | + | | + +---------------------------------------------------------+ + +From the point of view of an OS, a DPRC behaves similar to a plug and +play bus, like PCI. DPRC commands can be used to enumerate the contents +of the DPRC, discover the hardware objects present (including mappable +regions and interrupts). + +:: + + DPRC.1 (bus) + | + +--+--------+-------+-------+-------+ + | | | | | + DPMCP.1 DPIO.1 DPBP.1 DPNI.1 DPMAC.1 + DPMCP.2 DPIO.2 + DPMCP.3 + +Hardware objects can be created and destroyed dynamically, providing +the ability to hot plug/unplug objects in and out of the DPRC. + +A DPRC has a mappable MMIO region (an MC portal) that can be used +to send MC commands. It has an interrupt for status events (like +hotplug). +All objects in a container share the same hardware "isolation context". +This means that with respect to an IOMMU the isolation granularity +is at the DPRC (container) level, not at the individual object +level. + +DPRCs can be defined statically and populated with objects +via a config file passed to the MC when firmware starts it. + +DPAA2 Objects for an Ethernet Network Interface +----------------------------------------------- + +A typical Ethernet NIC is monolithic-- the NIC device contains TX/RX +queuing mechanisms, configuration mechanisms, buffer management, +physical ports, and interrupts. DPAA2 uses a more granular approach +utilizing multiple hardware objects. Each object provides specialized +functions. Groups of these objects are used by software to provide +Ethernet network interface functionality. This approach provides +efficient use of finite hardware resources, flexibility, and +performance advantages. + +The diagram below shows the objects needed for a simple +network interface configuration on a system with 2 CPUs. + +:: + + +---+---+ +---+---+ + CPU0 CPU1 + +---+---+ +---+---+ + | | + +---+---+ +---+---+ + DPIO DPIO + +---+---+ +---+---+ + \ / + \ / + \ / + +---+---+ + DPNI --- DPBP,DPMCP + +---+---+ + | + | + +---+---+ + DPMAC + +---+---+ + | + port/PHY + +Below the objects are described. For each object a brief description +is provided along with a summary of the kinds of operations the object +supports and a summary of key resources of the object (MMIO regions +and IRQs). + +DPMAC (Datapath Ethernet MAC) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Represents an Ethernet MAC, a hardware device that connects to an Ethernet +PHY and allows physical transmission and reception of Ethernet frames. + +- MMIO regions: none +- IRQs: DPNI link change +- commands: set link up/down, link config, get stats, + IRQ config, enable, reset + +DPNI (Datapath Network Interface) +Contains TX/RX queues, network interface configuration, and RX buffer pool +configuration mechanisms. The TX/RX queues are in memory and are identified +by queue number. + +- MMIO regions: none +- IRQs: link state +- commands: port config, offload config, queue config, + parse/classify config, IRQ config, enable, reset + +DPIO (Datapath I/O) +~~~~~~~~~~~~~~~~~~~ +Provides interfaces to enqueue and dequeue +packets and do hardware buffer pool management operations. The DPAA2 +architecture separates the mechanism to access queues (the DPIO object) +from the queues themselves. The DPIO provides an MMIO interface to +enqueue/dequeue packets. To enqueue something a descriptor is written +to the DPIO MMIO region, which includes the target queue number. +There will typically be one DPIO assigned to each CPU. This allows all +CPUs to simultaneously perform enqueue/dequeued operations. DPIOs are +expected to be shared by different DPAA2 drivers. + +- MMIO regions: queue operations, buffer management +- IRQs: data availability, congestion notification, buffer + pool depletion +- commands: IRQ config, enable, reset + +DPBP (Datapath Buffer Pool) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Represents a hardware buffer pool. + +- MMIO regions: none +- IRQs: none +- commands: enable, reset + +DPMCP (Datapath MC Portal) +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Provides an MC command portal. +Used by drivers to send commands to the MC to manage +objects. + +- MMIO regions: MC command portal +- IRQs: command completion +- commands: IRQ config, enable, reset + +Object Connections +================== +Some objects have explicit relationships that must +be configured: + +- DPNI <--> DPMAC +- DPNI <--> DPNI +- DPNI <--> L2-switch-port + + A DPNI must be connected to something such as a DPMAC, + another DPNI, or L2 switch port. The DPNI connection + is made via a DPRC command. + +:: + + +-------+ +-------+ + | DPNI | | DPMAC | + +---+---+ +---+---+ + | | + +==========+ + +- DPNI <--> DPBP + + A network interface requires a 'buffer pool' (DPBP + object) which provides a list of pointers to memory + where received Ethernet data is to be copied. The + Ethernet driver configures the DPBPs associated with + the network interface. + +Interrupts +========== +All interrupts generated by DPAA2 objects are message +interrupts. At the hardware level message interrupts +generated by devices will normally have 3 components-- +1) a non-spoofable 'device-id' expressed on the hardware +bus, 2) an address, 3) a data value. + +In the case of DPAA2 devices/objects, all objects in the +same container/DPRC share the same 'device-id'. +For ARM-based SoC this is the same as the stream ID. + + +DPAA2 Linux Drivers Overview +============================ + +This section provides an overview of the Linux kernel drivers for +DPAA2-- 1) the bus driver and associated "DPAA2 infrastructure" +drivers and 2) functional object drivers (such as Ethernet). + +As described previously, a DPRC is a container that holds the other +types of DPAA2 objects. It is functionally similar to a plug-and-play +bus controller. +Each object in the DPRC is a Linux "device" and is bound to a driver. +The diagram below shows the Linux drivers involved in a networking +scenario and the objects bound to each driver. A brief description +of each driver follows. + +:: + + +------------+ + | OS Network | + | Stack | + +------------+ +------------+ + | Allocator |. . . . . . . | Ethernet | + |(DPMCP,DPBP)| | (DPNI) | + +-.----------+ +---+---+----+ + . . ^ | + . . <data avail, | | <enqueue, + . . tx confirm> | | dequeue> + +-------------+ . | | + | DPRC driver | . +---+---V----+ +---------+ + | (DPRC) | . . . . . .| DPIO driver| | MAC | + +----------+--+ | (DPIO) | | (DPMAC) | + | +------+-----+ +-----+---+ + |<dev add/remove> | | + | | | + +--------+----------+ | +--+---+ + | MC-bus driver | | | PHY | + | | | |driver| + | /bus/fsl-mc | | +--+---+ + +-------------------+ | | + | | + ========================= HARDWARE =========|=================|====== + DPIO | + | | + DPNI---DPBP | + | | + DPMAC | + | | + PHY ---------------+ + ============================================|======================== + +A brief description of each driver is provided below. + +MC-bus driver +------------- +The MC-bus driver is a platform driver and is probed from a +node in the device tree (compatible "fsl,qoriq-mc") passed in by boot +firmware. It is responsible for bootstrapping the DPAA2 kernel +infrastructure. +Key functions include: + +- registering a new bus type named "fsl-mc" with the kernel, + and implementing bus call-backs (e.g. match/uevent/dev_groups) +- implementing APIs for DPAA2 driver registration and for device + add/remove +- creates an MSI IRQ domain +- doing a 'device add' to expose the 'root' DPRC, in turn triggering + a bind of the root DPRC to the DPRC driver + +The binding for the MC-bus device-tree node can be consulted at +*Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt*. +The sysfs bind/unbind interfaces for the MC-bus can be consulted at +*Documentation/ABI/testing/sysfs-bus-fsl-mc*. + +DPRC driver +----------- +The DPRC driver is bound to DPRC objects and does runtime management +of a bus instance. It performs the initial bus scan of the DPRC +and handles interrupts for container events such as hot plug by +re-scanning the DPRC. + +Allocator +--------- +Certain objects such as DPMCP and DPBP are generic and fungible, +and are intended to be used by other drivers. For example, +the DPAA2 Ethernet driver needs: + +- DPMCPs to send MC commands, to configure network interfaces +- DPBPs for network buffer pools + +The allocator driver registers for these allocatable object types +and those objects are bound to the allocator when the bus is probed. +The allocator maintains a pool of objects that are available for +allocation by other DPAA2 drivers. + +DPIO driver +----------- +The DPIO driver is bound to DPIO objects and provides services that allow +other drivers such as the Ethernet driver to enqueue and dequeue data for +their respective objects. +Key services include: + +- data availability notifications +- hardware queuing operations (enqueue and dequeue of data) +- hardware buffer pool management + +To transmit a packet the Ethernet driver puts data on a queue and +invokes a DPIO API. For receive, the Ethernet driver registers +a data availability notification callback. To dequeue a packet +a DPIO API is used. +There is typically one DPIO object per physical CPU for optimum +performance, allowing different CPUs to simultaneously enqueue +and dequeue data. + +The DPIO driver operates on behalf of all DPAA2 drivers +active in the kernel-- Ethernet, crypto, compression, +etc. + +Ethernet driver +--------------- +The Ethernet driver is bound to a DPNI and implements the kernel +interfaces needed to connect the DPAA2 network interface to +the network stack. +Each DPNI corresponds to a Linux network interface. + +MAC driver +---------- +An Ethernet PHY is an off-chip, board specific component and is managed +by the appropriate PHY driver via an mdio bus. The MAC driver +plays a role of being a proxy between the PHY driver and the +MC. It does this proxy via the MC commands to a DPMAC object. +If the PHY driver signals a link change, the MAC driver notifies +the MC via a DPMAC command. If a network interface is brought +up or down, the MC notifies the DPMAC driver via an interrupt and +the driver can take appropriate action. |