1 .. include:: <isonum.txt>
3 ===================================
4 DPAA2 DPIO (Data Path I/O) Overview
5 ===================================
7 :Copyright: |copy| 2016-2018 NXP
9 This document provides an overview of the Freescale DPAA2 DPIO
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.
20 This document provides an overview the Linux DPIO driver, its
21 subcomponents, and its APIs.
24 Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst
25 for a general overview of DPAA2 and the general DPAA2 driver architecture
31 The DPIO driver is bound to DPIO objects discovered on the fsl-mc bus and
32 provides services that:
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
40 The Linux DPIO driver consists of 3 primary components--
41 DPIO object driver-- fsl-mc driver that manages the DPIO object
43 DPIO service-- provides APIs to other Linux drivers for services
45 QBman portal interface-- sends portal commands, gets responses::
50 +---+----+ +------+-----+
51 |DPIO obj| |DPIO service|
52 | driver |---| (DPIO) |
53 +--------+ +------+-----+
63 The diagram below shows how the DPIO driver components fit with the other
64 DPAA2 Linux driver components::
69 +------------+ +------------+
70 | Allocator |. . . . . . . | Ethernet |
71 |(DPMCP,DPBP)| | (DPNI) |
72 +-.----------+ +---+---+----+
74 . . <data avail, | |<enqueue,
75 . . tx confirm> | | dequeue>
77 | DPRC driver | . +--------+ +------------+
78 | (DPRC) | . . |DPIO obj| |DPIO service|
79 +----------+--+ | driver |-| (DPIO) |
80 | +--------+ +------+-----+
81 |<dev add/remove> +------|-----+
83 +----+--------------+ | portal i/f |
84 | MC-bus driver | +------------+
87 +-------------------+ |
89 =========================================|=========|========================
90 +-+--DPIO---|-----------+
93 +-----------------------+
95 ============================================================================
98 DPIO Object Driver (dpio-driver.c)
99 ----------------------------------
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.
107 DPIO service (dpio-service.c, dpaa2-io.h)
108 ------------------------------------------
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.
115 Notification handling
116 dpaa2_io_service_register()
118 dpaa2_io_service_deregister()
120 dpaa2_io_service_rearm()
123 dpaa2_io_service_pull_fq()
125 dpaa2_io_service_pull_channel()
127 dpaa2_io_service_enqueue_fq()
129 dpaa2_io_service_enqueue_qd()
131 dpaa2_io_store_create()
133 dpaa2_io_store_destroy()
135 dpaa2_io_store_next()
137 Buffer pool management
138 dpaa2_io_service_release()
140 dpaa2_io_service_acquire()
142 QBman portal interface (qbman-portal.c)
143 ---------------------------------------
145 The qbman-portal component provides APIs to do the low level hardware
146 bit twiddling for operations such as:
148 - initializing Qman software portals
149 - building and sending portal commands
150 - portal interrupt configuration and processing
152 The qbman-portal APIs are not public to other drivers, and are
153 only used by dpio-service.
155 Other (dpaa2-fd.h, dpaa2-global.h)
156 ----------------------------------
158 Frame descriptor and scatter-gather definitions and the APIs used to
159 manipulate them are defined in dpaa2-fd.h.
161 Dequeue result struct and parsing APIs are defined in dpaa2-global.h.