target/linux/layerscape/patches-4.4/7166-staging-fsl-mc-DPAA2-overview-readme-update.patch

   1 From 720bf9c9a6fdff63ecc4b382a5092c0020fb7b42 Mon Sep 17 00:00:00 2001
   2 From: Stuart Yoder <stuart.yoder@nxp.com>
   3 Date: Mon, 11 Apr 2016 11:48:42 -0500
   4 Subject: [PATCH 166/226] staging: fsl-mc: DPAA2 overview readme update
   5
   6 incorporated feedback from review comments, other misc cleanup/tweaks
   7
   8 Signed-off-by: Stuart Yoder <stuart.yoder@nxp.com>
   9 Acked-by: German Rivera <german.rivera@nxp.com>
  10 Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
  11 ---
  12  drivers/staging/fsl-mc/README.txt |  138 +++++++++++++++++++++----------------
  13  1 file changed, 80 insertions(+), 58 deletions(-)
  14
  15 --- a/drivers/staging/fsl-mc/README.txt
  16 +++ b/drivers/staging/fsl-mc/README.txt
  17 @@ -11,11 +11,11 @@ Contents summary
  18     -Overview of DPAA2 objects
  19     -DPAA2 Linux driver architecture overview
  20          -bus driver
  21 -        -dprc driver
  22 +        -DPRC driver
  23          -allocator
  24 -        -dpio driver
  25 +        -DPIO driver
  26          -Ethernet
  27 -        -mac
  28 +        -MAC
  29
  30  DPAA2 Overview
  31  --------------
  32 @@ -37,6 +37,9 @@ interfaces, an L2 switch, or accelerator
  33  The MC provides memory-mapped I/O command interfaces (MC portals)
  34  which DPAA2 software drivers use to operate on DPAA2 objects:
  35
  36 +The diagram below shows an overview of the DPAA2 resource management
  37 +architecture:
  38 +
  39           +--------------------------------------+
  40           |                  OS                  |
  41           |                        DPAA2 drivers |
  42 @@ -77,13 +80,13 @@ DPIO objects.
  43
  44  Overview of DPAA2 Objects
  45  -------------------------
  46 -The section provides a brief overview of some key objects
  47 -in the DPAA2 hardware.  A simple scenario is described illustrating
  48 -the objects involved in creating a network interfaces.
  49 +The section provides a brief overview of some key DPAA2 objects.
  50 +A simple scenario is described illustrating the objects involved
  51 +in creating a network interfaces.
  52
  53  -DPRC (Datapath Resource Container)
  54
  55 -    A DPRC is an container object that holds all the other
  56 +    A DPRC is a container object that holds all the other
  57      types of DPAA2 objects.  In the example diagram below there
  58      are 8 objects of 5 types (DPMCP, DPIO, DPBP, DPNI, and DPMAC)
  59      in the container.
  60 @@ -101,23 +104,23 @@ the objects involved in creating a netwo
  61      |                                                         |
  62      +---------------------------------------------------------+
  63
  64 -    From the point of view of an OS, a DPRC is bus-like.  Like
  65 -    a plug-and-play bus, such as PCI, DPRC commands can be used to
  66 -    enumerate the contents of the DPRC, discover the hardware
  67 -    objects present (including mappable regions and interrupts).
  68 +    From the point of view of an OS, a DPRC behaves similar to a plug and
  69 +    play bus, like PCI.  DPRC commands can be used to enumerate the contents
  70 +    of the DPRC, discover the hardware objects present (including mappable
  71 +    regions and interrupts).
  72
  73 -     dprc.1 (bus)
  74 +     DPRC.1 (bus)
  75         |
  76         +--+--------+-------+-------+-------+
  77            |        |       |       |       |
  78 -        dpmcp.1  dpio.1  dpbp.1  dpni.1  dpmac.1
  79 -        dpmcp.2  dpio.2
  80 -        dpmcp.3
  81 +        DPMCP.1  DPIO.1  DPBP.1  DPNI.1  DPMAC.1
  82 +        DPMCP.2  DPIO.2
  83 +        DPMCP.3
  84
  85      Hardware objects can be created and destroyed dynamically, providing
  86      the ability to hot plug/unplug objects in and out of the DPRC.
  87
  88 -    A DPRC has a mappable mmio region (an MC portal) that can be used
  89 +    A DPRC has a mappable MMIO region (an MC portal) that can be used
  90      to send MC commands.  It has an interrupt for status events (like
  91      hotplug).
  92
  93 @@ -137,10 +140,11 @@ the objects involved in creating a netwo
  94      A typical Ethernet NIC is monolithic-- the NIC device contains TX/RX
  95      queuing mechanisms, configuration mechanisms, buffer management,
  96      physical ports, and interrupts.  DPAA2 uses a more granular approach
  97 -    utilizing multiple hardware objects.  Each object has specialized
  98 -    functions, and are used together by software to provide Ethernet network
  99 -    interface functionality.  This approach provides efficient use of finite
 100 -    hardware resources, flexibility, and performance advantages.
 101 +    utilizing multiple hardware objects.  Each object provides specialized
 102 +    functions. Groups of these objects are used by software to provide
 103 +    Ethernet network interface functionality.  This approach provides
 104 +    efficient use of finite hardware resources, flexibility, and
 105 +    performance advantages.
 106
 107      The diagram below shows the objects needed for a simple
 108      network interface configuration on a system with 2 CPUs.
 109 @@ -168,46 +172,52 @@ the objects involved in creating a netwo
 110
 111      Below the objects are described.  For each object a brief description
 112      is provided along with a summary of the kinds of operations the object
 113 -    supports and a summary of key resources of the object (mmio regions
 114 -    and irqs).
 115 +    supports and a summary of key resources of the object (MMIO regions
 116 +    and IRQs).
 117
 118         -DPMAC (Datapath Ethernet MAC): represents an Ethernet MAC, a
 119          hardware device that connects to an Ethernet PHY and allows
 120          physical transmission and reception of Ethernet frames.
 121 -           -mmio regions: none
 122 -           -irqs: dpni link change
 123 +           -MMIO regions: none
 124 +           -IRQs: DPNI link change
 125             -commands: set link up/down, link config, get stats,
 126 -             irq config, enable, reset
 127 +            IRQ config, enable, reset
 128
 129         -DPNI (Datapath Network Interface): contains TX/RX queues,
 130 -        network interface configuration, and rx buffer pool configuration
 131 -        mechanisms.
 132 -           -mmio regions: none
 133 -           -irqs: link state
 134 +        network interface configuration, and RX buffer pool configuration
 135 +        mechanisms.  The TX/RX queues are in memory and are identified by
 136 +        queue number.
 137 +           -MMIO regions: none
 138 +           -IRQs: link state
 139             -commands: port config, offload config, queue config,
 140 -            parse/classify config, irq config, enable, reset
 141 +            parse/classify config, IRQ config, enable, reset
 142
 143         -DPIO (Datapath I/O): provides interfaces to enqueue and dequeue
 144 -        packets and do hardware buffer pool management operations.  For
 145 -        optimum performance there is typically DPIO per CPU.  This allows
 146 -        each CPU to perform simultaneous enqueue/dequeue operations.
 147 -           -mmio regions: queue operations, buffer mgmt
 148 -           -irqs: data availability, congestion notification, buffer
 149 +        packets and do hardware buffer pool management operations.  The DPAA2
 150 +        architecture separates the mechanism to access queues (the DPIO object)
 151 +        from the queues themselves.  The DPIO provides an MMIO interface to
 152 +        enqueue/dequeue packets.  To enqueue something a descriptor is written
 153 +        to the DPIO MMIO region, which includes the target queue number.
 154 +        There will typically be one DPIO assigned to each CPU.  This allows all
 155 +        CPUs to simultaneously perform enqueue/dequeued operations.  DPIOs are
 156 +        expected to be shared by different DPAA2 drivers.
 157 +           -MMIO regions: queue operations, buffer management
 158 +           -IRQs: data availability, congestion notification, buffer
 159                    pool depletion
 160 -           -commands: irq config, enable, reset
 161 +           -commands: IRQ config, enable, reset
 162
 163         -DPBP (Datapath Buffer Pool): represents a hardware buffer
 164          pool.
 165 -           -mmio regions: none
 166 -           -irqs: none
 167 +           -MMIO regions: none
 168 +           -IRQs: none
 169             -commands: enable, reset
 170
 171         -DPMCP (Datapath MC Portal): provides an MC command portal.
 172          Used by drivers to send commands to the MC to manage
 173          objects.
 174 -           -mmio regions: MC command portal
 175 -           -irqs: command completion
 176 -           -commands: irq config, enable, reset
 177 +           -MMIO regions: MC command portal
 178 +           -IRQs: command completion
 179 +           -commands: IRQ config, enable, reset
 180
 181      Object Connections
 182      ------------------
 183 @@ -268,22 +278,22 @@ of each driver follows.
 184                                               |   Stack    |
 185                   +------------+              +------------+
 186                   | Allocator  |. . . . . . . |  Ethernet  |
 187 -                 |(dpmcp,dpbp)|              |   (dpni)   |
 188 +                 |(DPMCP,DPBP)|              |   (DPNI)   |
 189                   +-.----------+              +---+---+----+
 190                    .          .                   ^   |
 191                   .            .     <data avail, |   |<enqueue,
 192                  .              .     tx confirm> |   | dequeue>
 193      +-------------+             .                |   |
 194      | DPRC driver |              .           +---+---V----+     +---------+
 195 -    |   (dprc)    |               . . . . . .| DPIO driver|     |   MAC   |
 196 -    +----------+--+                          |  (dpio)    |     | (dpmac) |
 197 +    |   (DPRC)    |               . . . . . .| DPIO driver|     |   MAC   |
 198 +    +----------+--+                          |  (DPIO)    |     | (DPMAC) |
 199                 |                             +------+-----+     +-----+---+
 200                 |<dev add/remove>                    |                 |
 201                 |                                    |                 |
 202            +----+--------------+                     |              +--+---+
 203 -          |   mc-bus driver   |                     |              | PHY  |
 204 +          |   MC-bus driver   |                     |              | PHY  |
 205            |                   |                     |              |driver|
 206 -          | /fsl-mc@80c000000 |                     |              +--+---+
 207 +          | /soc/fsl-mc       |                     |              +--+---+
 208            +-------------------+                     |                 |
 209                                                      |                 |
 210   ================================ HARDWARE =========|=================|======
 211 @@ -298,25 +308,27 @@ of each driver follows.
 212
 213  A brief description of each driver is provided below.
 214
 215 -    mc-bus driver
 216 +    MC-bus driver
 217      -------------
 218 -    The mc-bus driver is a platform driver and is probed from an
 219 -    "/fsl-mc@xxxx" node in the device tree passed in by boot firmware.
 220 -    It is responsible for bootstrapping the DPAA2 kernel infrastructure.
 221 +    The MC-bus driver is a platform driver and is probed from a
 222 +    node in the device tree (compatible "fsl,qoriq-mc") passed in by boot
 223 +    firmware.  It is responsible for bootstrapping the DPAA2 kernel
 224 +    infrastructure.
 225      Key functions include:
 226         -registering a new bus type named "fsl-mc" with the kernel,
 227          and implementing bus call-backs (e.g. match/uevent/dev_groups)
 228 -       -implemeting APIs for DPAA2 driver registration and for device
 229 +       -implementing APIs for DPAA2 driver registration and for device
 230          add/remove
 231 -       -creates an MSI irq domain
 232 -       -do a device add of the 'root' DPRC device, which is needed
 233 -        to bootstrap things
 234 +       -creates an MSI IRQ domain
 235 +       -doing a 'device add' to expose the 'root' DPRC, in turn triggering
 236 +        a bind of the root DPRC to the DPRC driver
 237
 238      DPRC driver
 239      -----------
 240 -    The dprc-driver is bound DPRC objects and does runtime management
 241 +    The DPRC driver is bound to DPRC objects and does runtime management
 242      of a bus instance.  It performs the initial bus scan of the DPRC
 243 -    and handles interrupts for container events such as hot plug.
 244 +    and handles interrupts for container events such as hot plug by
 245 +    re-scanning the DPRC.
 246
 247      Allocator
 248      ----------
 249 @@ -334,14 +346,20 @@ A brief description of each driver is pr
 250      DPIO driver
 251      -----------
 252      The DPIO driver is bound to DPIO objects and provides services that allow
 253 -    other drivers such as the Ethernet driver to receive and transmit data.
 254 +    other drivers such as the Ethernet driver to enqueue and dequeue data for
 255 +    their respective objects.
 256      Key services include:
 257          -data availability notifications
 258          -hardware queuing operations (enqueue and dequeue of data)
 259          -hardware buffer pool management
 260
 261 +    To transmit a packet the Ethernet driver puts data on a queue and
 262 +    invokes a DPIO API.  For receive, the Ethernet driver registers
 263 +    a data availability notification callback.  To dequeue a packet
 264 +    a DPIO API is used.
 265 +
 266      There is typically one DPIO object per physical CPU for optimum
 267 -    performance, allowing each CPU to simultaneously enqueue
 268 +    performance, allowing different CPUs to simultaneously enqueue
 269      and dequeue data.
 270
 271      The DPIO driver operates on behalf of all DPAA2 drivers
 272 @@ -362,3 +380,7 @@ A brief description of each driver is pr
 273      by the appropriate PHY driver via an mdio bus.  The MAC driver
 274      plays a role of being a proxy between the PHY driver and the
 275      MC.  It does this proxy via the MC commands to a DPMAC object.
 276 +    If the PHY driver signals a link change, the MAC driver notifies
 277 +    the MC via a DPMAC command.  If a network interface is brought
 278 +    up or down, the MC notifies the DPMAC driver via an interrupt and
 279 +    the driver can take appropriate action.