0001 .. include:: <isonum.txt>
0002
0003 ===================================
0004 DPAA2 DPIO (Data Path I/O) Overview
0005 ===================================
0006
0007 :Copyright: |copy| 2016-2018 NXP
0008
0009 This document provides an overview of the Freescale DPAA2 DPIO
0010 drivers
0011
0012 Introduction
0013 ============
0014
0015 A DPAA2 DPIO (Data Path I/O) is a hardware object that provides
0016 interfaces to enqueue and dequeue frames to/from network interfaces
0017 and other accelerators. A DPIO also provides hardware buffer
0018 pool management for network interfaces.
0019
0020 This document provides an overview the Linux DPIO driver, its
0021 subcomponents, and its APIs.
0022
0023 See
0024 Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst
0025 for a general overview of DPAA2 and the general DPAA2 driver architecture
0026 in Linux.
0027
0028 Driver Overview
0029 ---------------
0030
0031 The DPIO driver is bound to DPIO objects discovered on the fsl-mc bus and
0032 provides services that:
0033
0034 A. allow other drivers, such as the Ethernet driver, to enqueue and dequeue
0035 frames for their respective objects
0036 B. allow drivers to register callbacks for data availability notifications
0037 when data becomes available on a queue or channel
0038 C. allow drivers to manage hardware buffer pools
0039
0040 The Linux DPIO driver consists of 3 primary components--
0041 DPIO object driver-- fsl-mc driver that manages the DPIO object
0042
0043 DPIO service-- provides APIs to other Linux drivers for services
0044
0045 QBman portal interface-- sends portal commands, gets responses::
0046
0047 fsl-mc other
0048 bus drivers
0049 | |
0050 +---+----+ +------+-----+
0051 |DPIO obj| |DPIO service|
0052 | driver |---| (DPIO) |
0053 +--------+ +------+-----+
0054 |
0055 +------+-----+
0056 | QBman |
0057 | portal i/f |
0058 +------------+
0059 |
0060 hardware
0061
0062
0063 The diagram below shows how the DPIO driver components fit with the other
0064 DPAA2 Linux driver components::
0065
0066 +------------+
0067 | OS Network |
0068 | Stack |
0069 +------------+ +------------+
0070 | Allocator |. . . . . . . | Ethernet |
0071 |(DPMCP,DPBP)| | (DPNI) |
0072 +-.----------+ +---+---+----+
0073 . . ^ |
0074 . . <data avail, | |<enqueue,
0075 . . tx confirm> | | dequeue>
0076 +-------------+ . | |
0077 | DPRC driver | . +--------+ +------------+
0078 | (DPRC) | . . |DPIO obj| |DPIO service|
0079 +----------+--+ | driver |-| (DPIO) |
0080 | +--------+ +------+-----+
0081 |<dev add/remove> +------|-----+
0082 | | QBman |
0083 +----+--------------+ | portal i/f |
0084 | MC-bus driver | +------------+
0085 | | |
0086 | /soc/fsl-mc | |
0087 +-------------------+ |
0088 |
0089 =========================================|=========|========================
0090 +-+--DPIO---|-----------+
0091 | | |
0092 | QBman Portal |
0093 +-----------------------+
0094
0095 ============================================================================
0096
0097
0098 DPIO Object Driver (dpio-driver.c)
0099 ----------------------------------
0100
0101 The dpio-driver component registers with the fsl-mc bus to handle objects of
0102 type "dpio". The implementation of probe() handles basic initialization
0103 of the DPIO including mapping of the DPIO regions (the QBman SW portal)
0104 and initializing interrupts and registering irq handlers. The dpio-driver
0105 registers the probed DPIO with dpio-service.
0106
0107 DPIO service (dpio-service.c, dpaa2-io.h)
0108 ------------------------------------------
0109
0110 The dpio service component provides queuing, notification, and buffers
0111 management services to DPAA2 drivers, such as the Ethernet driver. A system
0112 will typically allocate 1 DPIO object per CPU to allow queuing operations
0113 to happen simultaneously across all CPUs.
0114
0115 Notification handling
0116 dpaa2_io_service_register()
0117
0118 dpaa2_io_service_deregister()
0119
0120 dpaa2_io_service_rearm()
0121
0122 Queuing
0123 dpaa2_io_service_pull_fq()
0124
0125 dpaa2_io_service_pull_channel()
0126
0127 dpaa2_io_service_enqueue_fq()
0128
0129 dpaa2_io_service_enqueue_qd()
0130
0131 dpaa2_io_store_create()
0132
0133 dpaa2_io_store_destroy()
0134
0135 dpaa2_io_store_next()
0136
0137 Buffer pool management
0138 dpaa2_io_service_release()
0139
0140 dpaa2_io_service_acquire()
0141
0142 QBman portal interface (qbman-portal.c)
0143 ---------------------------------------
0144
0145 The qbman-portal component provides APIs to do the low level hardware
0146 bit twiddling for operations such as:
0147
0148 - initializing Qman software portals
0149 - building and sending portal commands
0150 - portal interrupt configuration and processing
0151
0152 The qbman-portal APIs are not public to other drivers, and are
0153 only used by dpio-service.
0154
0155 Other (dpaa2-fd.h, dpaa2-global.h)
0156 ----------------------------------
0157
0158 Frame descriptor and scatter-gather definitions and the APIs used to
0159 manipulate them are defined in dpaa2-fd.h.
0160
0161 Dequeue result struct and parsing APIs are defined in dpaa2-global.h.
