1.. include:: <isonum.txt>
2
3DPAA2 DPIO (Data Path I/O) Overview
4===================================
5
6:Copyright: |copy| 2016-2018 NXP
7
8This document provides an overview of the Freescale DPAA2 DPIO
9drivers
10
11Introduction
12============
13
14A DPAA2 DPIO (Data Path I/O) is a hardware object that provides
15interfaces to enqueue and dequeue frames to/from network interfaces
16and other accelerators.  A DPIO also provides hardware buffer
17pool management for network interfaces.
18
19This document provides an overview the Linux DPIO driver, its
20subcomponents, and its APIs.
21
22See
23Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst
24for a general overview of DPAA2 and the general DPAA2 driver architecture
25in Linux.
26
27Driver Overview
28---------------
29
30The DPIO driver is bound to DPIO objects discovered on the fsl-mc bus and
31provides 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
39The 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
62The diagram below shows how the DPIO driver components fit with the other
63DPAA2 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
97DPIO 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
106DPIO 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
141QBman 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
154Other (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.
161