tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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.