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