From: Stuart Yoder <stuart.yoder@nxp.com>
To: <gregkh@linuxfoundation.org>
Cc: <devel@driverdev.osuosl.org>, <linux-kernel@vger.kernel.org>,
<agraf@suse.de>, <arnd@arndb.de>, <leoyang.li@nxp.com>,
<ioana.ciornei@nxp.com>, <catalin.horghidan@nxp.com>,
<laurentiu.tudor@nxp.com>, <ruxandra.radulescu@nxp.com>,
<roy.pledge@nxp.com>, Stuart Yoder <stuart.yoder@nxp.com>
Subject: [PATCH v4 1/8] bus: fsl-mc: dpio: add DPIO driver overview document
Date: Thu, 15 Dec 2016 17:56:19 -0600 [thread overview]
Message-ID: <1481846186-7783-2-git-send-email-stuart.yoder@nxp.com> (raw)
In-Reply-To: <1481846186-7783-1-git-send-email-stuart.yoder@nxp.com>
add document describing the dpio driver and it's role, components
and major interfaces
Signed-off-by: Stuart Yoder <stuart.yoder@nxp.com>
---
Notes:
-v4
-updated copyright
drivers/staging/fsl-mc/bus/dpio/dpio-driver.txt | 135 ++++++++++++++++++++++++
1 file changed, 135 insertions(+)
create mode 100644 drivers/staging/fsl-mc/bus/dpio/dpio-driver.txt
diff --git a/drivers/staging/fsl-mc/bus/dpio/dpio-driver.txt b/drivers/staging/fsl-mc/bus/dpio/dpio-driver.txt
new file mode 100644
index 0000000..0ba6771
--- /dev/null
+++ b/drivers/staging/fsl-mc/bus/dpio/dpio-driver.txt
@@ -0,0 +1,135 @@
+Copyright 2016 NXP
+
+Introduction
+------------
+
+A DPAA2 DPIO (Data Path I/O) is a hardware object that provides
+interfaces to enqueue and dequeue frames to/from network interfaces
+and other accelerators. A DPIO also provides hardware buffer
+pool management for network interfaces.
+
+This document provides an overview the Linux DPIO driver, its
+subcomponents, and its APIs.
+
+See Documentation/dpaa2/overview.txt for a general overview of DPAA2
+and the general DPAA2 driver architecture in Linux.
+
+Driver Overview
+---------------
+
+The DPIO driver is bound to DPIO objects discovered on the fsl-mc bus and
+provides services that:
+ A) allow other drivers, such as the Ethernet driver, to enqueue and dequeue
+ frames for their respective objects
+ B) allow drivers to register callbacks for data availability notifications
+ when data becomes available on a queue or channel
+ C) allow drivers to manage hardware buffer pools
+
+The Linux DPIO driver consists of 3 primary components--
+ DPIO object driver-- fsl-mc driver that manages the DPIO object
+ DPIO service-- provides APIs to other Linux drivers for services
+ QBman portal interface-- sends portal commands, gets responses
+
+ fsl-mc other
+ bus drivers
+ | |
+ +---+----+ +------+-----+
+ |DPIO obj| |DPIO service|
+ | driver |---| (DPIO) |
+ +--------+ +------+-----+
+ |
+ +------+-----+
+ | QBman |
+ | portal i/f |
+ +------------+
+ |
+ hardware
+
+The diagram below shows how the DPIO driver components fit with the other
+DPAA2 Linux driver components:
+ +------------+
+ | OS Network |
+ | Stack |
+ +------------+ +------------+
+ | Allocator |. . . . . . . | Ethernet |
+ |(DPMCP,DPBP)| | (DPNI) |
+ +-.----------+ +---+---+----+
+ . . ^ |
+ . . <data avail, | |<enqueue,
+ . . tx confirm> | | dequeue>
+ +-------------+ . | |
+ | DPRC driver | . +--------+ +------------+
+ | (DPRC) | . . |DPIO obj| |DPIO service|
+ +----------+--+ | driver |-| (DPIO) |
+ | +--------+ +------+-----+
+ |<dev add/remove> +------|-----+
+ | | QBman |
+ +----+--------------+ | portal i/f |
+ | MC-bus driver | +------------+
+ | | |
+ | /soc/fsl-mc | |
+ +-------------------+ |
+ |
+ =========================================|=========|========================
+ +-+--DPIO---|-----------+
+ | | |
+ | QBman Portal |
+ +-----------------------+
+
+ ============================================================================
+
+
+DPIO Object Driver (dpio-driver.c)
+----------------------------------
+
+ The dpio-driver component registers with the fsl-mc bus to handle objects of
+ type "dpio". The implementation of probe() handles basic initialization
+ of the DPIO including mapping of the DPIO regions (the QBman SW portal)
+ and initializing interrupts and registering irq handlers. The dpio-driver
+ registers the probed DPIO with dpio-service.
+
+DPIO service (dpio-service.c, dpaa2-io.h)
+------------------------------------------
+
+ The dpio service component provides queuing, notification, and buffers
+ management services to DPAA2 drivers, such as the Ethernet driver. A system
+ will typically allocate 1 DPIO object per CPU to allow queuing operations
+ to happen simultaneously across all CPUs.
+
+ Notification handling
+ dpaa2_io_service_register()
+ dpaa2_io_service_deregister()
+ dpaa2_io_service_rearm()
+
+ Queuing
+ dpaa2_io_service_pull_fq()
+ dpaa2_io_service_pull_channel()
+ dpaa2_io_service_enqueue_fq()
+ dpaa2_io_service_enqueue_qd()
+ dpaa2_io_store_create()
+ dpaa2_io_store_destroy()
+ dpaa2_io_store_next()
+
+ Buffer pool management
+ dpaa2_io_service_release()
+ dpaa2_io_service_acquire()
+
+QBman portal interface (qbman-portal.c)
+---------------------------------------
+
+ The qbman-portal component provides APIs to do the low level hardware
+ bit twiddling for operations such as:
+ -initializing Qman software portals
+ -building and sending portal commands
+ -portal interrupt configuration and processing
+
+ The qbman-portal APIs are not public to other drivers, and are
+ only used by dpio-service.
+
+Other (dpaa2-fd.h, dpaa2-global.h)
+----------------------------------
+
+ Frame descriptor and scatter-gather definitions and the APIs used to
+ manipulate them are defined in dpaa2-fd.h.
+
+ Dequeue result struct and parsing APIs are defined in dpaa2-global.h.
--
1.9.0
next prev parent reply other threads:[~2016-12-16 0:04 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-12-15 23:56 [PATCH v4 0/8] staging: fsl-mc: add dpio driver Stuart Yoder
2016-12-15 23:56 ` Stuart Yoder [this message]
2016-12-15 23:56 ` [PATCH v4 2/8] bus: fsl-mc: dpio: add APIs for DPIO objects Stuart Yoder
2016-12-15 23:56 ` [PATCH v4 3/8] bus: fsl-mc: dpio: add frame descriptor and scatter/gather APIs Stuart Yoder
2016-12-15 23:56 ` [PATCH v4 4/8] bus: fsl-mc: dpio: add global dpaa2 definitions Stuart Yoder
2016-12-15 23:56 ` [PATCH v4 5/8] bus: fsl-mc: dpio: add QBMan portal APIs for DPAA2 Stuart Yoder
2016-12-16 7:57 ` kbuild test robot
2016-12-16 16:29 ` Stuart Yoder
2016-12-15 23:56 ` [PATCH v4 6/8] bus: fsl-mc: dpio: add the DPAA2 DPIO service interface Stuart Yoder
2016-12-15 23:56 ` [PATCH v4 7/8] bus: fsl-mc: dpio: add the DPAA2 DPIO object driver Stuart Yoder
2016-12-15 23:56 ` [PATCH v4 8/8] bus: fsl-mc: dpio: add maintainer for DPIO Stuart Yoder
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1481846186-7783-2-git-send-email-stuart.yoder@nxp.com \
--to=stuart.yoder@nxp.com \
--cc=agraf@suse.de \
--cc=arnd@arndb.de \
--cc=catalin.horghidan@nxp.com \
--cc=devel@driverdev.osuosl.org \
--cc=gregkh@linuxfoundation.org \
--cc=ioana.ciornei@nxp.com \
--cc=laurentiu.tudor@nxp.com \
--cc=leoyang.li@nxp.com \
--cc=linux-kernel@vger.kernel.org \
--cc=roy.pledge@nxp.com \
--cc=ruxandra.radulescu@nxp.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).