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

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