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 Documentation/networking/device_drivers/freescale/dpaa2/overview.rst for
23a general overview of DPAA2 and the general DPAA2 driver architecture in Linux.
24
25Driver Overview
26---------------
27
28The DPIO driver is bound to DPIO objects discovered on the fsl-mc bus and
29provides 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
37The 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
60The diagram below shows how the DPIO driver components fit with the other
61DPAA2 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
95DPIO 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
104DPIO 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
139QBman 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
152Other (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.
159