iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

staging: fsl-mc: DPAA2 overview readme update

Browse Source 
incorporated feedback from review comments, other misc cleanup/tweaks

Signed-off-by: Stuart Yoder <stuart.yoder@nxp.com>
Acked-by: German Rivera <german.rivera@nxp.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Stuart Yoder 2016-04-11 11:48:42 -05:00 committed by Greg Kroah-Hartman
parent 71bd14e3ec
commit 7dc0818367
1 changed files with 80 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

138
drivers/staging/fsl-mc/README.txt
View File

@ -11,11 +11,11 @@ Contents summary
-Overview of DPAA2 objects -Overview of DPAA2 objects
-DPAA2 Linux driver architecture overview -DPAA2 Linux driver architecture overview
-bus driver -bus driver
-dprc driver -DPRC driver
-allocator -allocator
-dpio driver -DPIO driver
-Ethernet -Ethernet
-mac -MAC
DPAA2 Overview DPAA2 Overview
-------------- --------------
@ -37,6 +37,9 @@ interfaces, an L2 switch, or accelerator instances.
The MC provides memory-mapped I/O command interfaces (MC portals) The MC provides memory-mapped I/O command interfaces (MC portals)
which DPAA2 software drivers use to operate on DPAA2 objects: which DPAA2 software drivers use to operate on DPAA2 objects:
The diagram below shows an overview of the DPAA2 resource management
architecture:
+--------------------------------------+ +--------------------------------------+
| OS | | OS |
| DPAA2 drivers | | DPAA2 drivers |
@ -77,13 +80,13 @@ DPIO objects.
Overview of DPAA2 Objects Overview of DPAA2 Objects
------------------------- -------------------------
The section provides a brief overview of some key objects The section provides a brief overview of some key DPAA2 objects.
in the DPAA2 hardware. A simple scenario is described illustrating A simple scenario is described illustrating the objects involved
the objects involved in creating a network interfaces. in creating a network interfaces.
-DPRC (Datapath Resource Container) -DPRC (Datapath Resource Container)
A DPRC is an container object that holds all the other A DPRC is a container object that holds all the other
types of DPAA2 objects. In the example diagram below there types of DPAA2 objects. In the example diagram below there
are 8 objects of 5 types (DPMCP, DPIO, DPBP, DPNI, and DPMAC) are 8 objects of 5 types (DPMCP, DPIO, DPBP, DPNI, and DPMAC)
in the container. in the container.
@ -101,23 +104,23 @@ the objects involved in creating a network interfaces.
| | | |
+---------------------------------------------------------+ +---------------------------------------------------------+
From the point of view of an OS, a DPRC is bus-like. Like From the point of view of an OS, a DPRC behaves similar to a plug and
a plug-and-play bus, such as PCI, DPRC commands can be used to play bus, like PCI. DPRC commands can be used to enumerate the contents
enumerate the contents of the DPRC, discover the hardware of the DPRC, discover the hardware objects present (including mappable
objects present (including mappable regions and interrupts). regions and interrupts).
dprc.1 (bus) DPRC.1 (bus)
| |
+--+--------+-------+-------+-------+ +--+--------+-------+-------+-------+
| | | | | | | | | |
dpmcp.1 dpio.1 dpbp.1 dpni.1 dpmac.1 DPMCP.1 DPIO.1 DPBP.1 DPNI.1 DPMAC.1
dpmcp.2 dpio.2 DPMCP.2 DPIO.2
dpmcp.3 DPMCP.3
Hardware objects can be created and destroyed dynamically, providing Hardware objects can be created and destroyed dynamically, providing
the ability to hot plug/unplug objects in and out of the DPRC. 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 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 to send MC commands. It has an interrupt for status events (like
hotplug). hotplug).
@ -137,10 +140,11 @@ the objects involved in creating a network interfaces.
A typical Ethernet NIC is monolithic-- the NIC device contains TX/RX A typical Ethernet NIC is monolithic-- the NIC device contains TX/RX
queuing mechanisms, configuration mechanisms, buffer management, queuing mechanisms, configuration mechanisms, buffer management,
physical ports, and interrupts. DPAA2 uses a more granular approach physical ports, and interrupts. DPAA2 uses a more granular approach
utilizing multiple hardware objects. Each object has specialized utilizing multiple hardware objects. Each object provides specialized
functions, and are used together by software to provide Ethernet network functions. Groups of these objects are used by software to provide
interface functionality. This approach provides efficient use of finite Ethernet network interface functionality. This approach provides
hardware resources, flexibility, and performance advantages. efficient use of finite hardware resources, flexibility, and
performance advantages.
The diagram below shows the objects needed for a simple The diagram below shows the objects needed for a simple
network interface configuration on a system with 2 CPUs. network interface configuration on a system with 2 CPUs.
@ -168,46 +172,52 @@ the objects involved in creating a network interfaces.
Below the objects are described. For each object a brief description Below the objects are described. For each object a brief description
is provided along with a summary of the kinds of operations the object 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 supports and a summary of key resources of the object (MMIO regions
and irqs). and IRQs).
-DPMAC (Datapath Ethernet MAC): represents an Ethernet MAC, a -DPMAC (Datapath Ethernet MAC): represents an Ethernet MAC, a
hardware device that connects to an Ethernet PHY and allows hardware device that connects to an Ethernet PHY and allows
physical transmission and reception of Ethernet frames. physical transmission and reception of Ethernet frames.
-mmio regions: none -MMIO regions: none
-irqs: dpni link change -IRQs: DPNI link change
-commands: set link up/down, link config, get stats, -commands: set link up/down, link config, get stats,
irq config, enable, reset IRQ config, enable, reset
-DPNI (Datapath Network Interface): contains TX/RX queues, -DPNI (Datapath Network Interface): contains TX/RX queues,
network interface configuration, and rx buffer pool configuration network interface configuration, and RX buffer pool configuration
mechanisms. mechanisms. The TX/RX queues are in memory and are identified by
-mmio regions: none queue number.
-irqs: link state -MMIO regions: none
-IRQs: link state
-commands: port config, offload config, queue config, -commands: port config, offload config, queue config,
parse/classify config, irq config, enable, reset parse/classify config, IRQ config, enable, reset
-DPIO (Datapath I/O): provides interfaces to enqueue and dequeue -DPIO (Datapath I/O): provides interfaces to enqueue and dequeue
packets and do hardware buffer pool management operations. For packets and do hardware buffer pool management operations. The DPAA2
optimum performance there is typically DPIO per CPU. This allows architecture separates the mechanism to access queues (the DPIO object)
each CPU to perform simultaneous enqueue/dequeue operations. from the queues themselves. The DPIO provides an MMIO interface to
-mmio regions: queue operations, buffer mgmt enqueue/dequeue packets. To enqueue something a descriptor is written
-irqs: data availability, congestion notification, buffer 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 pool depletion
-commands: irq config, enable, reset -commands: IRQ config, enable, reset
-DPBP (Datapath Buffer Pool): represents a hardware buffer -DPBP (Datapath Buffer Pool): represents a hardware buffer
pool. pool.
-mmio regions: none -MMIO regions: none
-irqs: none -IRQs: none
-commands: enable, reset -commands: enable, reset
-DPMCP (Datapath MC Portal): provides an MC command portal. -DPMCP (Datapath MC Portal): provides an MC command portal.
Used by drivers to send commands to the MC to manage Used by drivers to send commands to the MC to manage
objects. objects.
-mmio regions: MC command portal -MMIO regions: MC command portal
-irqs: command completion -IRQs: command completion
-commands: irq config, enable, reset -commands: IRQ config, enable, reset
Object Connections Object Connections
------------------ ------------------
@ -268,22 +278,22 @@ of each driver follows.
| Stack | | Stack |
+------------+ +------------+ +------------+ +------------+
| Allocator |. . . . . . . | Ethernet | | Allocator |. . . . . . . | Ethernet |
|(dpmcp,dpbp)| | (dpni) | |(DPMCP,DPBP)| | (DPNI) |
+-.----------+ +---+---+----+ +-.----------+ +---+---+----+
. . ^ | . . ^ |
. . <data avail, | |<enqueue, . . <data avail, | |<enqueue,
. . tx confirm> | | dequeue> . . tx confirm> | | dequeue>
+-------------+ . | | +-------------+ . | |
| DPRC driver | . +---+---V----+ +---------+ | DPRC driver | . +---+---V----+ +---------+
| (dprc) | . . . . . .| DPIO driver| | MAC | | (DPRC) | . . . . . .| DPIO driver| | MAC |
+----------+--+ | (dpio) | | (dpmac) | +----------+--+ | (DPIO) | | (DPMAC) |
| +------+-----+ +-----+---+ | +------+-----+ +-----+---+
|<dev add/remove> | | |<dev add/remove> | |
| | | | | |
+----+--------------+ | +--+---+ +----+--------------+ | +--+---+
| mc-bus driver | | | PHY | | MC-bus driver | | | PHY |
| | | |driver| | | | |driver|
| /fsl-mc@80c000000 | | +--+---+ | /soc/fsl-mc | | +--+---+
+-------------------+ | | +-------------------+ | |
| | | |
================================ HARDWARE =========|=================|====== ================================ HARDWARE =========|=================|======
@ -298,25 +308,27 @@ of each driver follows.
A brief description of each driver is provided below. A brief description of each driver is provided below.
mc-bus driver MC-bus driver
------------- -------------
The mc-bus driver is a platform driver and is probed from an The MC-bus driver is a platform driver and is probed from a
"/fsl-mc@xxxx" node in the device tree passed in by boot firmware. node in the device tree (compatible "fsl,qoriq-mc") passed in by boot
It is responsible for bootstrapping the DPAA2 kernel infrastructure. firmware. It is responsible for bootstrapping the DPAA2 kernel
infrastructure.
Key functions include: Key functions include:
-registering a new bus type named "fsl-mc" with the kernel, -registering a new bus type named "fsl-mc" with the kernel,
and implementing bus call-backs (e.g. match/uevent/dev_groups) and implementing bus call-backs (e.g. match/uevent/dev_groups)
-implemeting APIs for DPAA2 driver registration and for device -implementing APIs for DPAA2 driver registration and for device
add/remove add/remove
-creates an MSI irq domain -creates an MSI IRQ domain
-do a device add of the 'root' DPRC device, which is needed -doing a 'device add' to expose the 'root' DPRC, in turn triggering
to bootstrap things a bind of the root DPRC to the DPRC driver
DPRC driver DPRC driver
----------- -----------
The dprc-driver is bound DPRC objects and does runtime management 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 of a bus instance. It performs the initial bus scan of the DPRC
and handles interrupts for container events such as hot plug. and handles interrupts for container events such as hot plug by
re-scanning the DPRC.
Allocator Allocator
---------- ----------
@ -334,14 +346,20 @@ A brief description of each driver is provided below.
DPIO driver DPIO driver
----------- -----------
The DPIO driver is bound to DPIO objects and provides services that allow The DPIO driver is bound to DPIO objects and provides services that allow
other drivers such as the Ethernet driver to receive and transmit data. other drivers such as the Ethernet driver to enqueue and dequeue data for
their respective objects.
Key services include: Key services include:
-data availability notifications -data availability notifications
-hardware queuing operations (enqueue and dequeue of data) -hardware queuing operations (enqueue and dequeue of data)
-hardware buffer pool management -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 There is typically one DPIO object per physical CPU for optimum
performance, allowing each CPU to simultaneously enqueue performance, allowing different CPUs to simultaneously enqueue
and dequeue data. and dequeue data.
The DPIO driver operates on behalf of all DPAA2 drivers The DPIO driver operates on behalf of all DPAA2 drivers
@ -362,3 +380,7 @@ A brief description of each driver is provided below.
by the appropriate PHY driver via an mdio bus. The MAC driver 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 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. 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.