| 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. |