From: Ioana Radulescu <ruxandra.radulescu@nxp.com>
To: <gregkh@linuxfoundation.org>
Cc: <devel@driverdev.osuosl.org>, <linux-kernel@vger.kernel.org>,
<agraf@suse.de>, <arnd@arndb.de>,
<linux-arm-kernel@lists.infradead.org>,
<alexandru.marginean@nxp.com>, <bogdan.hamciuc@nxp.com>,
<stuyoder@gmail.com>, <laurentiu.tudor@nxp.com>,
<ruxandra.radulescu@nxp.com>, <roy.pledge@nxp.com>,
<haiying.wang@nxp.com>
Subject: [PATCH v2 2/9] staging: fsl-dpaa2/eth: Add Ethernet driver overview document
Date: Wed, 12 Apr 2017 11:25:31 -0500 [thread overview]
Message-ID: <20170412162538.25302-3-ruxandra.radulescu@nxp.com> (raw)
In-Reply-To: <20170412162538.25302-1-ruxandra.radulescu@nxp.com>
Add a README file describing the driver architecture, components
and I/O interface.
Signed-off-by: Ioana Radulescu <ruxandra.radulescu@nxp.com>
---
v2: no changes
drivers/staging/fsl-dpaa2/ethernet/README | 186 ++++++++++++++++++++++++++++++
1 file changed, 186 insertions(+)
create mode 100644 drivers/staging/fsl-dpaa2/ethernet/README
diff --git a/drivers/staging/fsl-dpaa2/ethernet/README b/drivers/staging/fsl-dpaa2/ethernet/README
new file mode 100644
index 000000000000..410952ecf657
--- /dev/null
+++ b/drivers/staging/fsl-dpaa2/ethernet/README
@@ -0,0 +1,186 @@
+Freescale DPAA2 Ethernet driver
+===============================
+
+This file provides documentation for the Freescale DPAA2 Ethernet driver.
+
+
+Contents
+========
+ Supported Platforms
+ Architecture Overview
+ Creating a Network Interface
+ Features & Offloads
+
+
+Supported Platforms
+===================
+This driver provides networking support for Freescale DPAA2 SoCs, e.g.
+LS2080A, LS2088A, LS1088A.
+
+
+Architecture Overview
+=====================
+Unlike regular NICs, in the DPAA2 architecture there is no single hardware block
+representing network interfaces; instead, several separate hardware resources
+concur to provide the networking functionality:
+ - network interfaces
+ - queues, channels
+ - buffer pools
+ - MAC/PHY
+
+All hardware resources are allocated and configured through the Management
+Complex (MC) portals. MC abstracts most of these resources as DPAA2 objects
+and exposes ABIs through which they can be configured and controlled. A few
+hardware resources, like queues, do not have a corresponding MC object and
+are treated as internal resources of other objects.
+
+For a more detailed description of the DPAA2 architecture and its object
+abstractions see:
+ drivers/staging/fsl-mc/README.txt
+
+Each Linux net device is built on top of a Datapath Network Interface (DPNI)
+object and uses Buffer Pools (DPBPs), I/O Portals (DPIOs) and Concentrators
+(DPCONs).
+
+Configuration interface:
+
+ -----------------------
+ | DPAA2 Ethernet Driver |
+ -----------------------
+ . . .
+ . . .
+ . . . . . . . . . . . .
+ . . .
+ . . .
+ ---------- ---------- -----------
+ | DPBP API | | DPNI API | | DPCON API |
+ ---------- ---------- -----------
+ . . . software
+=========== . ========== . ============ . ===================
+ . . . hardware
+ ------------------------------------------
+ | MC hardware portals |
+ ------------------------------------------
+ . . .
+ . . .
+ ------ ------ -------
+ | DPBP | | DPNI | | DPCON |
+ ------ ------ -------
+
+The DPNIs are network interfaces without a direct one-on-one mapping to PHYs.
+DPBPs represent hardware buffer pools. Packet I/O is performed in the context
+of DPCON objects, using DPIO portals for managing and communicating with the
+hardware resources.
+
+Datapath (I/O) interface:
+
+ -----------------------------------------------
+ | DPAA2 Ethernet Driver |
+ -----------------------------------------------
+ | ^ ^ | |
+ | | | | |
+ enqueue| dequeue| data | dequeue| seed |
+ (Tx) | (Rx, TxC)| avail.| request| buffers|
+ | | notify| | |
+ | | | | |
+ V | | V V
+ -----------------------------------------------
+ | DPIO Driver |
+ -----------------------------------------------
+ | | | | | software
+ | | | | | ================
+ | | | | | hardware
+ -----------------------------------------------
+ | I/O hardware portals |
+ -----------------------------------------------
+ | ^ ^ | |
+ | | | | |
+ | | | V |
+ V | ================ V
+ ---------------------- | -------------
+ queues ---------------------- | | Buffer pool |
+ ---------------------- | -------------
+ =======================
+ Channel
+
+Datapath I/O (DPIO) portals provide enqueue and dequeue services, data
+availability notifications and buffer pool management. DPIOs are shared between
+all DPAA2 objects (and implicitly all DPAA2 kernel drivers) that work with data
+frames, but must be affine to the CPUs for the purpose of traffic distribution.
+
+Frames are transmitted and received through hardware frame queues, which can be
+grouped in channels for the purpose of hardware scheduling. The Ethernet driver
+enqueues TX frames on egress queues and after transmission is complete a TX
+confirmation frame is sent back to the CPU.
+
+When frames are available on ingress queues, a data availability notification
+is sent to the CPU; notifications are raised per channel, so even if multiple
+queues in the same channel have available frames, only one notification is sent.
+After a channel fires a notification, is must be explicitly rearmed.
+
+Each network interface can have multiple Rx, Tx and confirmation queues affined
+to CPUs, and one channel (DPCON) for each CPU that services at least one queue.
+DPCONs are used to distribute ingress traffic to different CPUs via the cores'
+affine DPIOs.
+
+The role of hardware buffer pools is storage of ingress frame data. Each network
+interface has a privately owned buffer pool which it seeds with kernel allocated
+buffers.
+
+
+DPNIs are decoupled from PHYs; a DPNI can be connected to a PHY through a DPMAC
+object or to another DPNI through an internal link, but the connection is
+managed by MC and completely transparent to the Ethernet driver.
+
+ --------- --------- ---------
+ | eth if1 | | eth if2 | | eth ifn |
+ --------- --------- ---------
+ . . .
+ . . .
+ . . .
+ ---------------------------
+ | DPAA2 Ethernet Driver |
+ ---------------------------
+ . . .
+ . . .
+ . . .
+ ------ ------ ------ -------
+ | DPNI | | DPNI | | DPNI | | DPMAC |----+
+ ------ ------ ------ ------- |
+ | | | | |
+ | | | | -----
+ =========== ================== | PHY |
+ -----
+
+Creating a Network Interface
+============================
+A net device is created for each DPNI object probed on the MC bus. Each DPNI has
+a number of properties which determine the network interface configuration
+options and associated hardware resources.
+
+DPNI objects (and the other DPAA2 objects needed for a network interface) can be
+added to a container on the MC bus in one of two ways: statically, through a
+Datapath Layout Binary file (DPL) that is parsed by MC at boot time; or created
+dynamically at runtime, via the DPAA2 objects APIs.
+
+
+Features & Offloads
+===================
+Hardware checksum offloading is supported for TCP and UDP over IPv4/6 frames.
+The checksum offloads can be independently configured on RX and TX through
+ethtool.
+
+Hardware offload of unicast and multicast MAC filtering is supported on the
+ingress path and permanently enabled.
+
+Scatter-gather frames are supported on both RX and TX paths. On TX, SG support
+is configurable via ethtool; on RX it is always enabled.
+
+The DPAA2 hardware can process jumbo Ethernet frames of up to 10K bytes.
+
+The Ethernet driver defines a static flow hashing scheme that distributes
+traffic based on a 5-tuple key: src IP, dst IP, IP proto, L4 src port,
+L4 dst port. No user configuration is supported for now.
+
+Hardware specific statistics for the network interface as well as some
+non-standard driver stats can be consulted through ethtool -S option.
--
2.11.0
next prev parent reply other threads:[~2017-04-12 16:29 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-04-12 16:25 [PATCH v2 0/9] staging: Introduce the DPAA2 Ethernet driver Ioana Radulescu
2017-04-12 16:25 ` [PATCH v2 1/9] bus: fsl-mc: add DPCON object APIs Ioana Radulescu
2017-04-12 16:25 ` Ioana Radulescu [this message]
2017-04-12 16:25 ` [PATCH v2 3/9] staging: fsl-dpaa2/eth: Add APIs for DPNI objects Ioana Radulescu
2017-04-12 16:25 ` [PATCH v2 4/9] staging: fsl-dpaa2/eth: Add Freescale DPAA2 Ethernet driver Ioana Radulescu
2017-04-12 16:25 ` [PATCH v2 5/9] staging: fsl-dpaa2/eth: Add ethtool support Ioana Radulescu
2017-04-12 16:25 ` [PATCH v2 6/9] staging: fsl-dpaa2/eth: Add driver specific stats Ioana Radulescu
2017-04-12 16:25 ` [PATCH v2 7/9] staging: fsl-dpaa2/eth: Add trace points Ioana Radulescu
2017-04-12 16:25 ` [PATCH v2 8/9] staging: fsl-dpaa2/eth: Add TODO file Ioana Radulescu
2017-04-19 3:44 ` Stuart Yoder
2017-04-20 8:31 ` Ruxandra Ioana Radulescu
2017-04-12 16:25 ` [PATCH v2 9/9] staging: fsl-dpaa2/eth: Add maintainer for Ethernet driver Ioana Radulescu
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=20170412162538.25302-3-ruxandra.radulescu@nxp.com \
--to=ruxandra.radulescu@nxp.com \
--cc=agraf@suse.de \
--cc=alexandru.marginean@nxp.com \
--cc=arnd@arndb.de \
--cc=bogdan.hamciuc@nxp.com \
--cc=devel@driverdev.osuosl.org \
--cc=gregkh@linuxfoundation.org \
--cc=haiying.wang@nxp.com \
--cc=laurentiu.tudor@nxp.com \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-kernel@vger.kernel.org \
--cc=roy.pledge@nxp.com \
--cc=stuyoder@gmail.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).