drivers/staging/fsl-mc/bus/dpio/dpio-driver.txt

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