Documentation/networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver.rst

   1 .. include:: <isonum.txt>
   2
   3 DPAA2 DPIO (Data Path I/O) Overview
   4 ===================================
   5
   6 :Copyright: |copy| 2016-2018 NXP
   7
   8 This document provides an overview of the Freescale DPAA2 DPIO
   9 drivers
  10
  11 Introduction
  12 ============
  13
  14 A DPAA2 DPIO (Data Path I/O) is a hardware object that provides
  15 interfaces to enqueue and dequeue frames to/from network interfaces
  16 and other accelerators.  A DPIO also provides hardware buffer
  17 pool management for network interfaces.
  18
  19 This document provides an overview the Linux DPIO driver, its
  20 subcomponents, and its APIs.
  21
  22 See
  23 Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst
  24 for a general overview of DPAA2 and the general DPAA2 driver architecture
  25 in Linux.
  26
  27 Driver Overview
  28 ---------------
  29
  30 The DPIO driver is bound to DPIO objects discovered on the fsl-mc bus and
  31 provides services that:
  32
  33   A. allow other drivers, such as the Ethernet driver, to enqueue and dequeue
  34      frames for their respective objects
  35   B. allow drivers to register callbacks for data availability notifications
  36      when data becomes available on a queue or channel
  37   C. allow drivers to manage hardware buffer pools
  38
  39 The Linux DPIO driver consists of 3 primary components--
  40    DPIO object driver-- fsl-mc driver that manages the DPIO object
  41
  42    DPIO service-- provides APIs to other Linux drivers for services
  43
  44    QBman portal interface-- sends portal commands, gets responses::
  45
  46           fsl-mc          other
  47            bus           drivers
  48             |               |
  49         +---+----+   +------+-----+
  50         |DPIO obj|   |DPIO service|
  51         | driver |---|  (DPIO)    |
  52         +--------+   +------+-----+
  53                             |
  54                      +------+-----+
  55                      |    QBman   |
  56                      | portal i/f |
  57                      +------------+
  58                             |
  59                          hardware
  60
  61
  62 The diagram below shows how the DPIO driver components fit with the other
  63 DPAA2 Linux driver components::
  64
  65                                                    +------------+
  66                                                    | OS Network |
  67                                                    |   Stack    |
  68                  +------------+                    +------------+
  69                  | Allocator  |. . . . . . .       |  Ethernet  |
  70                  |(DPMCP,DPBP)|                    |   (DPNI)   |
  71                  +-.----------+                    +---+---+----+
  72                   .          .                         ^   |
  73                  .            .           <data avail, |   |<enqueue,
  74                 .              .           tx confirm> |   | dequeue>
  75     +-------------+             .                      |   |
  76     | DPRC driver |              .    +--------+ +------------+
  77     |   (DPRC)    |               . . |DPIO obj| |DPIO service|
  78     +----------+--+                   | driver |-|  (DPIO)    |
  79                |                      +--------+ +------+-----+
  80                |<dev add/remove>                 +------|-----+
  81                |                                 |   QBman    |
  82           +----+--------------+                  | portal i/f |
  83           |   MC-bus driver   |                  +------------+
  84           |                   |                     |
  85           | /soc/fsl-mc       |                     |
  86           +-------------------+                     |
  87                                                     |
  88  =========================================|=========|========================
  89                                         +-+--DPIO---|-----------+
  90                                         |           |           |
  91                                         |        QBman Portal   |
  92                                         +-----------------------+
  93
  94  ============================================================================
  95
  96
  97 DPIO Object Driver (dpio-driver.c)
  98 ----------------------------------
  99
 100    The dpio-driver component registers with the fsl-mc bus to handle objects of
 101    type "dpio".  The implementation of probe() handles basic initialization
 102    of the DPIO including mapping of the DPIO regions (the QBman SW portal)
 103    and initializing interrupts and registering irq handlers.  The dpio-driver
 104    registers the probed DPIO with dpio-service.
 105
 106 DPIO service  (dpio-service.c, dpaa2-io.h)
 107 ------------------------------------------
 108
 109    The dpio service component provides queuing, notification, and buffers
 110    management services to DPAA2 drivers, such as the Ethernet driver.  A system
 111    will typically allocate 1 DPIO object per CPU to allow queuing operations
 112    to happen simultaneously across all CPUs.
 113
 114    Notification handling
 115       dpaa2_io_service_register()
 116
 117       dpaa2_io_service_deregister()
 118
 119       dpaa2_io_service_rearm()
 120
 121    Queuing
 122       dpaa2_io_service_pull_fq()
 123
 124       dpaa2_io_service_pull_channel()
 125
 126       dpaa2_io_service_enqueue_fq()
 127
 128       dpaa2_io_service_enqueue_qd()
 129
 130       dpaa2_io_store_create()
 131
 132       dpaa2_io_store_destroy()
 133
 134       dpaa2_io_store_next()
 135
 136    Buffer pool management
 137       dpaa2_io_service_release()
 138
 139       dpaa2_io_service_acquire()
 140
 141 QBman portal interface (qbman-portal.c)
 142 ---------------------------------------
 143
 144    The qbman-portal component provides APIs to do the low level hardware
 145    bit twiddling for operations such as:
 146
 147       - initializing Qman software portals
 148       - building and sending portal commands
 149       - portal interrupt configuration and processing
 150
 151    The qbman-portal APIs are not public to other drivers, and are
 152    only used by dpio-service.
 153
 154 Other (dpaa2-fd.h, dpaa2-global.h)
 155 ----------------------------------
 156
 157    Frame descriptor and scatter-gather definitions and the APIs used to
 158    manipulate them are defined in dpaa2-fd.h.
 159
 160    Dequeue result struct and parsing APIs are defined in dpaa2-global.h.