From: Stuart Yoder <stuart.yoder@nxp.com>
To: <gregkh@linuxfoundation.org>
Cc: <german.rivera@nxp.com>, <devel@driverdev.osuosl.org>,
<linux-kernel@vger.kernel.org>, <agraf@suse.de>, <arnd@arndb.de>,
<leoyang.li@nxp.com>, Stuart Yoder <stuart.yoder@nxp.com>
Subject: [PATCH 2/9] bus: fsl-mc: dpio: add DPIO driver overview document
Date: Fri, 21 Oct 2016 09:01:42 -0500 [thread overview]
Message-ID: <1477058509-12547-3-git-send-email-stuart.yoder@nxp.com> (raw)
In-Reply-To: <1477058509-12547-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>
---
Documentation/dpaa2/dpio-driver.txt | 135 ++++++++++++++++++++++++++++++++++++
1 file changed, 135 insertions(+)
create mode 100644 Documentation/dpaa2/dpio-driver.txt
diff --git a/Documentation/dpaa2/dpio-driver.txt b/Documentation/dpaa2/dpio-driver.txt
new file mode 100644
index 0000000..5c192b3
--- /dev/null
+++ b/Documentation/dpaa2/dpio-driver.txt
@@ -0,0 +1,135 @@
+Copyright (C) 2016 Freescale Semiconductor Inc.
+
+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-10-21 14:09 UTC|newest]
Thread overview: 27+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-10-21 14:01 [PATCH 0/9] staging: fsl-mc: move bus driver out of staging, add dpio Stuart Yoder
2016-10-21 14:01 ` [PATCH 1/9] staging: fsl-mc: move bus driver out of staging Stuart Yoder
2016-10-21 14:01 ` Stuart Yoder [this message]
2016-10-21 14:01 ` [PATCH 3/9] bus: fsl-mc: dpio: add APIs for DPIO objects Stuart Yoder
2016-11-02 14:50 ` Ruxandra Ioana Radulescu
2016-11-04 14:06 ` Stuart Yoder
2016-10-21 14:01 ` [PATCH 4/9] bus: fsl-mc: dpio: add frame descriptor and scatter/gather APIs Stuart Yoder
[not found] ` <VI1PR0401MB2638FACBE40822E26ABBD7018DA30@VI1PR0401MB2638.eurprd04.prod.outlook.com>
2016-11-04 13:22 ` Ruxandra Ioana Radulescu
2016-11-04 14:32 ` Stuart Yoder
2016-11-04 15:04 ` Ruxandra Ioana Radulescu
2016-11-07 23:29 ` Stuart Yoder
2016-10-21 14:01 ` [PATCH 5/9] bus: fsl-mc: dpio: add global dpaa2 definitions Stuart Yoder
2016-10-21 14:01 ` [PATCH 6/9] bus: fsl-mc: dpio: add QBMan portal APIs for DPAA2 Stuart Yoder
[not found] ` <VI1PR0401MB26389BCC00429B2C3396C3CD8DA30@VI1PR0401MB2638.eurprd04.prod.outlook.com>
2016-11-10 15:03 ` Ruxandra Ioana Radulescu
2016-11-10 17:25 ` Stuart Yoder
2016-11-28 18:09 ` Ruxandra Ioana Radulescu
2016-11-29 23:07 ` Stuart Yoder
2016-10-21 14:01 ` [PATCH 7/9] bus: fsl-mc: dpio: add the DPAA2 DPIO service interface Stuart Yoder
[not found] ` <VI1PR0401MB2638B079498EFB89BD8AA5BA8DA30@VI1PR0401MB2638.eurprd04.prod.outlook.com>
2016-11-04 14:46 ` Ruxandra Ioana Radulescu
2016-11-12 0:10 ` Stuart Yoder
2016-10-21 14:01 ` [PATCH 8/9] bus: fsl-mc: dpio: add the DPAA2 DPIO object driver Stuart Yoder
[not found] ` <VI1PR0401MB263842A73049105182B1041E8DA30@VI1PR0401MB2638.eurprd04.prod.outlook.com>
2016-11-04 15:11 ` Ruxandra Ioana Radulescu
2016-11-10 0:20 ` Stuart Yoder
2016-10-21 14:01 ` [PATCH 9/9] bus: fsl-mc: dpio: add maintainer for DPIO Stuart Yoder
2016-10-24 14:34 ` [PATCH 0/9] staging: fsl-mc: move bus driver out of staging, add dpio Alexander Graf
2016-10-26 2:35 ` Stuart Yoder
2016-10-26 7:02 ` Alexander Graf
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=1477058509-12547-3-git-send-email-stuart.yoder@nxp.com \
--to=stuart.yoder@nxp.com \
--cc=agraf@suse.de \
--cc=arnd@arndb.de \
--cc=devel@driverdev.osuosl.org \
--cc=german.rivera@nxp.com \
--cc=gregkh@linuxfoundation.org \
--cc=leoyang.li@nxp.com \
--cc=linux-kernel@vger.kernel.org \
/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).