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