[PATCH 8/8] staging: fsl-mc: Convert documentation to rst format
From: Bogdan Purcareata
Date: Tue Jan 16 2018 - 08:20:20 EST
From: Ioana Radulescu <ruxandra.radulescu@xxxxxxx>
Update the doc file to comply with the rst format.
It's not integrated into the documentation build structure yet,
since it's still located in drivers/staging.
Signed-off-by: Ioana Radulescu <ruxandra.radulescu@xxxxxxx>
Reviewed-by: Laurentiu Tudor <laurentiu.tudor@xxxxxxx>
---
drivers/staging/fsl-mc/README.txt | 387 ----------------------------------
drivers/staging/fsl-mc/overview.rst | 404 ++++++++++++++++++++++++++++++++++++
2 files changed, 404 insertions(+), 387 deletions(-)
delete mode 100644 drivers/staging/fsl-mc/README.txt
create mode 100644 drivers/staging/fsl-mc/overview.rst
diff --git a/drivers/staging/fsl-mc/README.txt b/drivers/staging/fsl-mc/README.txt
deleted file mode 100644
index 0ea5cd7..0000000
--- a/drivers/staging/fsl-mc/README.txt
+++ /dev/null
@@ -1,387 +0,0 @@
-Copyright (C) 2015 Freescale Semiconductor Inc.
-
-DPAA2 (Data Path Acceleration Architecture Gen2) Overview
----------------------------------------------------------
-
-This document provides an overview of the Freescale DPAA2 architecture
-and how it is integrated into the Linux kernel.
-
-Contents summary
- -DPAA2 overview
- -Overview of DPAA2 objects
- -DPAA2 Linux driver architecture overview
- -bus driver
- -DPRC driver
- -allocator
- -DPIO driver
- -Ethernet
- -MAC
-
-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 here:
- Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt
- The sysfs bind/unbind interfaces for the MC-bus can be consulted here:
- 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.
diff --git a/drivers/staging/fsl-mc/overview.rst b/drivers/staging/fsl-mc/overview.rst
new file mode 100644
index 0000000..79fede4
--- /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.
--
2.7.4