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
  31   A. allow other drivers, such as the Ethernet driver, to enqueue and dequeue
  32      frames for their respective objects
  33   B. allow drivers to register callbacks for data availability notifications
  34      when data becomes available on a queue or channel
  35   C. allow drivers to manage hardware buffer pools
  36
  37 The Linux DPIO driver consists of 3 primary components--
  38    DPIO object driver-- fsl-mc driver that manages the DPIO object
  39
  40    DPIO service-- provides APIs to other Linux drivers for services
  41
  42    QBman portal interface-- sends portal commands, gets responses::
  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                                                    +------------+
  64                                                    | OS Network |
  65                                                    |   Stack    |
  66                  +------------+                    +------------+
  67                  | Allocator  |. . . . . . .       |  Ethernet  |
  68                  |(DPMCP,DPBP)|                    |   (DPNI)   |
  69                  +-.----------+                    +---+---+----+
  70                   .          .                         ^   |
  71                  .            .           <data avail, |   |<enqueue,
  72                 .              .           tx confirm> |   | dequeue>
  73     +-------------+             .                      |   |
  74     | DPRC driver |              .    +--------+ +------------+
  75     |   (DPRC)    |               . . |DPIO obj| |DPIO service|
  76     +----------+--+                   | driver |-|  (DPIO)    |
  77                |                      +--------+ +------+-----+
  78                |<dev add/remove>                 +------|-----+
  79                |                                 |   QBman    |
  80           +----+--------------+                  | portal i/f |
  81           |   MC-bus driver   |                  +------------+
  82           |                   |                     |
  83           | /soc/fsl-mc       |                     |
  84           +-------------------+                     |
  85                                                     |
  86  =========================================|=========|========================
  87                                         +-+--DPIO---|-----------+
  88                                         |           |           |
  89                                         |        QBman Portal   |
  90                                         +-----------------------+
  91
  92  ============================================================================
  93
  94
  95 DPIO Object Driver (dpio-driver.c)
  96 ----------------------------------
  97
  98    The dpio-driver component registers with the fsl-mc bus to handle objects of
  99    type "dpio".  The implementation of probe() handles basic initialization
 100    of the DPIO including mapping of the DPIO regions (the QBman SW portal)
 101    and initializing interrupts and registering irq handlers.  The dpio-driver
 102    registers the probed DPIO with dpio-service.
 103
 104 DPIO service  (dpio-service.c, dpaa2-io.h)
 105 ------------------------------------------
 106
 107    The dpio service component provides queuing, notification, and buffers
 108    management services to DPAA2 drivers, such as the Ethernet driver.  A system
 109    will typically allocate 1 DPIO object per CPU to allow queuing operations
 110    to happen simultaneously across all CPUs.
 111
 112    Notification handling
 113       dpaa2_io_service_register()
 114
 115       dpaa2_io_service_deregister()
 116
 117       dpaa2_io_service_rearm()
 118
 119    Queuing
 120       dpaa2_io_service_pull_fq()
 121
 122       dpaa2_io_service_pull_channel()
 123
 124       dpaa2_io_service_enqueue_fq()
 125
 126       dpaa2_io_service_enqueue_qd()
 127
 128       dpaa2_io_store_create()
 129
 130       dpaa2_io_store_destroy()
 131
 132       dpaa2_io_store_next()
 133
 134    Buffer pool management
 135       dpaa2_io_service_release()
 136
 137       dpaa2_io_service_acquire()
 138
 139 QBman portal interface (qbman-portal.c)
 140 ---------------------------------------
 141
 142    The qbman-portal component provides APIs to do the low level hardware
 143    bit twiddling for operations such as:
 144
 145       - initializing Qman software portals
 146       - building and sending portal commands
 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.