From: Stuart Yoder <stuart.yoder@nxp.com>
To: <gregkh@linuxfoundation.org>, <german.rivera@nxp.com>
CC: <devel@driverdev.osuosl.org>, <linux-kernel@vger.kernel.org>,
        <agraf@suse.de>, <arnd@arndb.de>, <leoyang.li@nxp.com>,
        Stuart Yoder <stuart.yoder@nxp.com>
Subject: [PATCH 02/14] staging: fsl-mc: DPAA2 overview readme update
Date: Mon, 11 Apr 2016 11:48:42 -0500
Message-ID: <1460393322-15788-1-git-send-email-stuart.yoder@nxp.com>
MIME-Version: 1.0
Content-Type: text/plain
SpamDiagnosticOutput: 1:23
SpamDiagnosticMetadata: NSPM
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 11 Apr 2016 16:48:44.3354
 (UTC)
X-MS-Exchange-CrossTenant-Id: 5afe0b00-7697-4969-b663-5eab37d5f47e
X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=5afe0b00-7697-4969-b663-5eab37d5f47e;Ip=[192.88.168.50];Helo=[tx30smr01.am.freescale.net]
X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BY1PR0301MB1224
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org
Content-Length: 13259
Lines: 278

From: Stuart Yoder <stuart.yoder@nxp.com>

incorporated feedback from review comments, other misc cleanup/tweaks

Signed-off-by: Stuart Yoder <stuart.yoder@nxp.com>
---
 drivers/staging/fsl-mc/README.txt |  138 +++++++++++++++++++++----------------
 1 file changed, 80 insertions(+), 58 deletions(-)

diff --git a/drivers/staging/fsl-mc/README.txt b/drivers/staging/fsl-mc/README.txt
index 8214102..179536a 100644
--- a/drivers/staging/fsl-mc/README.txt
+++ b/drivers/staging/fsl-mc/README.txt
@@ -11,11 +11,11 @@ Contents summary
    -Overview of DPAA2 objects
    -DPAA2 Linux driver architecture overview
         -bus driver
-        -dprc driver
+        -DPRC driver
         -allocator
-        -dpio driver
+        -DPIO driver
         -Ethernet
-        -mac
+        -MAC
 
 DPAA2 Overview
 --------------
@@ -37,6 +37,9 @@ 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 |
@@ -77,13 +80,13 @@ DPIO objects.
 
 Overview of DPAA2 Objects
 -------------------------
-The section provides a brief overview of some key objects
-in the DPAA2 hardware.  A simple scenario is described illustrating
-the objects involved in creating a network interfaces.
+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 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
     are 8 objects of 5 types (DPMCP, DPIO, DPBP, DPNI, and DPMAC)
     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
-    a plug-and-play bus, such as PCI, DPRC commands can be used to
-    enumerate the contents of the DPRC, discover the hardware
-    objects present (including mappable regions and interrupts).
+    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)
+     DPRC.1 (bus)
        |
        +--+--------+-------+-------+-------+
           |        |       |       |       |
-        dpmcp.1  dpio.1  dpbp.1  dpni.1  dpmac.1
-        dpmcp.2  dpio.2
-        dpmcp.3
+        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
+    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).
 
@@ -137,10 +140,11 @@ the objects involved in creating a network interfaces.
     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 has specialized
-    functions, and are used together by software to provide Ethernet network
-    interface functionality.  This approach provides efficient use of finite
-    hardware resources, flexibility, and performance advantages.
+    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.
@@ -168,46 +172,52 @@ the objects involved in creating a network interfaces.
 
     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).
+    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
+           -MMIO regions: none
+           -IRQs: DPNI link change
            -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,
-        network interface configuration, and rx buffer pool configuration
-        mechanisms.
-           -mmio regions: none
-           -irqs: link state
+        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
+            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.  For
-        optimum performance there is typically DPIO per CPU.  This allows
-        each CPU to perform simultaneous enqueue/dequeue operations.
-           -mmio regions: queue operations, buffer mgmt
-           -irqs: data availability, congestion notification, buffer
+        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
+           -commands: IRQ config, enable, reset
 
        -DPBP (Datapath Buffer Pool): represents a hardware buffer
         pool.
-           -mmio regions: none
-           -irqs: none
+           -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
+           -MMIO regions: MC command portal
+           -IRQs: command completion
+           -commands: IRQ config, enable, reset
 
     Object Connections
     ------------------
@@ -268,22 +278,22 @@ of each driver follows.
                                              |   Stack    |
                  +------------+              +------------+
                  | Allocator  |. . . . . . . |  Ethernet  |
-                 |(dpmcp,dpbp)|              |   (dpni)   |
+                 |(DPMCP,DPBP)|              |   (DPNI)   |
                  +-.----------+              +---+---+----+
                   .          .                   ^   |
                  .            .     <data avail, |   |<enqueue,
                 .              .     tx confirm> |   | dequeue>
     +-------------+             .                |   |
     | DPRC driver |              .           +---+---V----+     +---------+
-    |   (dprc)    |               . . . . . .| DPIO driver|     |   MAC   |
-    +----------+--+                          |  (dpio)    |     | (dpmac) |
+    |   (DPRC)    |               . . . . . .| DPIO driver|     |   MAC   |
+    +----------+--+                          |  (DPIO)    |     | (DPMAC) |
                |                             +------+-----+     +-----+---+
                |<dev add/remove>                    |                 |
                |                                    |                 |
           +----+--------------+                     |              +--+---+
-          |   mc-bus driver   |                     |              | PHY  |
+          |   MC-bus driver   |                     |              | PHY  |
           |                   |                     |              |driver|
-          | /fsl-mc@80c000000 |                     |              +--+---+
+          | /soc/fsl-mc       |                     |              +--+---+
           +-------------------+                     |                 |
                                                     |                 |
  ================================ HARDWARE =========|=================|======
@@ -298,25 +308,27 @@ of each driver follows.
 
 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
-    "/fsl-mc@xxxx" node in the device tree passed in by boot firmware.
-    It is responsible for bootstrapping the DPAA2 kernel infrastructure.
+    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)
-       -implemeting APIs for DPAA2 driver registration and for device
+       -implementing APIs for DPAA2 driver registration and for device
         add/remove
-       -creates an MSI irq domain
-       -do a device add of the 'root' DPRC device, which is needed
-        to bootstrap things
+       -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
 
     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
-    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
     ----------
@@ -334,14 +346,20 @@ A brief description of each driver is provided below.
     DPIO driver
     -----------
     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:
         -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 each CPU to simultaneously enqueue
+    performance, allowing different CPUs to simultaneously enqueue
     and dequeue data.
 
     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
     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.
-- 
1.7.9.5