From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <tdu@semihalf.com>
Received: from mail-lf0-f49.google.com (mail-lf0-f49.google.com
[209.85.215.49]) by dpdk.org (Postfix) with ESMTP id B1ADF1B259
for <dev@dpdk.org>; Mon, 9 Oct 2017 17:01:26 +0200 (CEST)
Received: by mail-lf0-f49.google.com with SMTP id d10so25344994lfg.11
for <dev@dpdk.org>; Mon, 09 Oct 2017 08:01:26 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=semihalf-com.20150623.gappssmtp.com; s=20150623;
h=from:to:cc:subject:date:message-id:in-reply-to:references;
bh=Vpu57FP1g04dehu+O9apM7P6J/LdStGxVitnu2MhRxo=;
b=kiET0iN9U0BxdZzLiqoV2bfNr+1/MD0BHFoE2FJPiNKGrcfURfEDXrROhdZtyLDTYz
cZ+1igt+y8l99JpXORhDlFP1pU8LL+KJLUNJIQoynrRSJ6ybpMHANGa2aUSCclwDkV8Z
9bD96+mvqnpKfCJ19dJYrOlbsjvgEz8Us6jI1r0gpseIgIxOquzRHABMcg2ryG9Annaz
8FvMAasH1sSUTTjv3WFVR5U1XDyZhDyz0D3+5qYqzPgk+mxM5ddzeThi74qGLx5A7C4G
abCspXyWF6bVOPli5+rFJmwgf3MLgnY4j7Ui7eCO4tq9XU29xv7HdkHYHfVP2MOHqRAX
A/aw==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20161025;
h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to
:references;
bh=Vpu57FP1g04dehu+O9apM7P6J/LdStGxVitnu2MhRxo=;
b=X5O2/ijPf4DpImq9zIfrBS5wxIcdQ5Lt5CrXrEd4U+qhJ5qgjFXv2uPD9haTe9lzqj
oe7/FwAk+FxgiYUg1QTeTFDJ5jYcTSg8LnRKvO1m5GxAOkHx/5dSYy+kT6YyydsBGG6G
KVQqqArO7Ti7KQsoa5i7hBlmHc4NX5x39bT4pNF3zKi2ThHctNNOhgv0QY5Y2s++Jjk5
+pAYsV1LGZNOnKHsDczpbA2qJDahgnVC3mMGcwZk7EueK2yVU51IVBhXV8Qthj1XTDSi
K3obJe701OlK4U2vgf/dpxWBbxcMP7uzX8u2MsMzgb/rlya3fwV+SuxrxP4IW2qXBg4d
lb/Q==
X-Gm-Message-State: AMCzsaV6HoOg4im5Fgq9vUP4tv8I6Bw2CXXGGSleWKyoYAvzcvD79XQ4
Cu4KqepKcQNTOCztKQuJ/MEW7iyEJQo=
X-Google-Smtp-Source: AOwi7QCLThCFscBxsmRMqklS3ZzSndD8DEtLKQblBkwy7AaWvYxZ7VvXgplbXnJSIBd7xzc1U9ANqQ==
X-Received: by 10.46.14.18 with SMTP id 18mr3374985ljo.133.1507561285682;
Mon, 09 Oct 2017 08:01:25 -0700 (PDT)
Received: from tdu.semihalf.local (31-172-191-173.noc.fibertech.net.pl.
[31.172.191.173])
by smtp.gmail.com with ESMTPSA id z64sm1352637lfa.91.2017.10.09.08.01.24
(version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128);
Mon, 09 Oct 2017 08:01:24 -0700 (PDT)
From: Tomasz Duszynski <tdu@semihalf.com>
To: dev@dpdk.org
Cc: mw@semihalf.com, dima@marvell.com, nsamsono@marvell.com,
Jianbo.liu@linaro.org, Tomasz Duszynski <tdu@semihalf.com>,
Jacek Siuda <jck@semihalf.com>
Date: Mon, 9 Oct 2017 17:00:44 +0200
Message-Id: <1507561244-20115-17-git-send-email-tdu@semihalf.com>
X-Mailer: git-send-email 2.7.4
In-Reply-To: <1507561244-20115-1-git-send-email-tdu@semihalf.com>
References: <1507031500-11473-1-git-send-email-tdu@semihalf.com>
<1507561244-20115-1-git-send-email-tdu@semihalf.com>
Subject: [dpdk-dev] [PATCH v4 16/16] doc: add mrvl net pmd documentation
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <http://dpdk.org/ml/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://dpdk.org/ml/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <http://dpdk.org/ml/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
X-List-Received-Date: Mon, 09 Oct 2017 15:01:27 -0000
Add documentation for the MRVL NET PMD driver.
Signed-off-by: Jacek Siuda <jck@semihalf.com>
Signed-off-by: Tomasz Duszynski <jck@semihalf.com>
---
doc/guides/nics/features/mrvl.ini | 2 +
doc/guides/nics/index.rst | 1 +
doc/guides/nics/mrvl.rst | 256 ++++++++++++++++++++++++++++++++++++++
3 files changed, 259 insertions(+)
create mode 100644 doc/guides/nics/mrvl.rst
diff --git a/doc/guides/nics/features/mrvl.ini b/doc/guides/nics/features/mrvl.ini
index 3643b8b..00d9621 100644
--- a/doc/guides/nics/features/mrvl.ini
+++ b/doc/guides/nics/features/mrvl.ini
@@ -19,3 +19,5 @@ L3 checksum offload = Y
L4 checksum offload = Y
Packet type parsing = Y
Basic stats = Y
+ARMv8 = Y
+Usage doc = Y
diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst
index 4115141..df19ec7 100644
--- a/doc/guides/nics/index.rst
+++ b/doc/guides/nics/index.rst
@@ -56,6 +56,7 @@ Network Interface Controller Drivers
liquidio
mlx4
mlx5
+ mrvl
nfp
qede
sfc_efx
diff --git a/doc/guides/nics/mrvl.rst b/doc/guides/nics/mrvl.rst
new file mode 100644
index 0000000..462bc0e
--- /dev/null
+++ b/doc/guides/nics/mrvl.rst
@@ -0,0 +1,256 @@
+.. BSD LICENSE
+ Copyright(c) 2017 Semihalf. All rights reserved.
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+ * Neither the name of Semihalf nor the names of its
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+MRVL Poll Mode Driver
+======================
+
+The MRVL PMD (librte_pmd_mrvl) provides poll mode driver support
+for the Marvell PPv2 (Packet Processor v2) 1/10 Gbps adapter.
+
+Detailed information about SoCs that use PPv2 can be obtained here:
+
+* https://www.marvell.com/embedded-processors/armada-70xx/
+* https://www.marvell.com/embedded-processors/armada-80xx/
+
+.. Note::
+
+ Due to external dependencies, this driver is disabled by default. It must
+ be enabled manually by setting relevant configuration option manually.
+ Please refer to `Config File Options`_ section for further details.
+
+
+Features
+--------
+
+Features of the MRVL PMD are:
+
+- Speed capabilities
+- Link status
+- Queue start/stop
+- MTU update
+- Jumbo frame
+- Promiscuous mode
+- Allmulticast mode
+- Unicast MAC filter
+- Multicast MAC filter
+- RSS hash
+- VLAN filter
+- CRC offload
+- L3 checksum offload
+- L4 checksum offload
+- Packet type parsing
+- Basic stats
+- QoS
+
+
+Limitations
+-----------
+
+- Number of lcores is limited to 9 by MUSDK internal design. If more lcores
+ need to be allocated, locking will have to be considered. Number of available
+ lcores can be changed via ``MRVL_MUSDK_HIFS_RESERVED`` define in
+ ``mrvl_ethdev.c`` source file.
+
+- Flushing vlans added for filtering is not possible due to MUSDK missing
+ functionality. Current workaround is to reset board so that PPv2 has a
+ chance to start in a sane state.
+
+
+Prerequisites
+-------------
+
+- Custom Linux Kernel sources available
+ `here <https://github.com/MarvellEmbeddedProcessors/linux-marvell/tree/linux-4.4.52-armada-17.08>`__.
+
+- Out of tree `mvpp2x_sysfs` kernel module sources available
+ `here <https://github.com/MarvellEmbeddedProcessors/mvpp2x-marvell/tree/mvpp2x-armada-17.08>`__.
+
+- MUSDK (Marvell User-Space SDK) sources available
+ `here <https://github.com/MarvellEmbeddedProcessors/musdk-marvell/tree/musdk-armada-17.08>`__.
+
+ MUSDK is a light-weight library that provides direct access to Marvell's
+ PPv2 (Packet Processor v2). Alternatively prebuilt MUSDK library can be
+ requested from `Marvell Extranet <https://extranet.marvell.com>`_. Once
+ approval has been granted, library can be found by typing ``musdk`` in
+ the search box.
+
+ MUSDK must be configured with the following features:
+
+ .. code-block:: console
+
+ --enable-bpool-dma=64
+
+- DPDK environment
+
+ Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup
+ DPDK environment.
+
+
+Config File Options
+-------------------
+
+The following options can be modified in the ``config`` file.
+
+- ``CONFIG_RTE_LIBRTE_MRVL_PMD`` (default ``n``)
+
+ Toggle compilation of the librte_pmd_mrvl driver.
+
+- ``CONFIG_RTE_LIBRTE_MRVL_DEBUG`` (default ``n``)
+
+ Toggle display of debugging messages.
+
+- ``CONFIG_RTE_MRVL_MUSDK_DMA_MEMSIZE`` (default ``41943040``)
+
+ Size in bytes of the contiguous memory region that MUSDK will allocate
+ for run-time DMA-able data buffers.
+
+
+QoS Configuration
+-----------------
+
+QoS configuration is done through external configuration file. Path to the
+file must be given as `cfg` in driver's vdev parameter list.
+
+Configuration syntax
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+ [port <portnum> default]
+ default_tc = <default_tc>
+ qos_mode = <qos_priority>
+
+ [port <portnum> tc <traffic_class>]
+ rxq = <rx_queue_list>
+ pcp = <pcp_list>
+ dscp = <dscp_list>
+
+ [port <portnum> tc <traffic_class>]
+ rxq = <rx_queue_list>
+ pcp = <pcp_list>
+ dscp = <dscp_list>
+
+Where:
+
+- ``<portnum>``: DPDK Port number (0..n).
+
+- ``<default_tc>``: Default traffic class (e.g. 0)
+
+- ``<qos_priority>``: QoS priority for mapping (`ip`, `vlan`, `ip/vlan` or `vlan/ip`).
+
+- ``<traffic_class>``: Traffic Class to be configured.
+
+- ``<rx_queue_list>``: List of DPDK RX queues (e.g. 0 1 3-4)
+
+- ``<pcp_list>``: List of PCP values to handle in particular TC (e.g. 0 1 3-4 7).
+
+- ``<dscp_list>``: List of DSCP values to handle in particular TC (e.g. 0-12 32-48 63).
+
+Setting PCP/DSCP values for the default TC is not required. All PCP/DSCP
+values not assigned explicitly to particular TC will be handled by the
+default TC.
+
+Configuration file example
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ [port 0 default]
+ default_tc = 0
+ qos_mode = ip
+
+ [port 0 tc 0]
+ rxq = 0 1
+
+ [port 0 tc 1]
+ rxq = 2
+ pcp = 5 6 7
+ dscp = 26-38
+
+ [port 1 default]
+ default_tc = 0
+ qos_mode = vlan/ip
+
+ [port 1 tc 0]
+ rxq = 0
+
+ [port 1 tc 1]
+ rxq = 1 2
+ pcp = 5 6 7
+ dscp = 26-38
+
+Usage example
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2,cfg=/home/user/mrvl.conf \
+ -c 7 -- -i -a --disable-hw-vlan-strip --rxq=2
+
+
+Building DPDK
+-------------
+
+Driver needs precompiled MUSDK library during compilation. Please consult
+``doc/musdk_get_started.txt`` for the detailed build instructions.
+
+Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with
+the path to the MUSDK installation directory needs to be exported.
+
+
+Usage Example
+-------------
+
+MRVL PMD requires extra out of tree kernel modules to function properly.
+`musdk_uio` and `mv_pp_uio` sources are part of the MUSDK. Please consult
+``doc/musdk_get_started.txt`` for the detailed build instructions.
+For `mvpp2x_sysfs` please consult ``Documentation/pp22_sysfs.txt`` for the
+detailed build instructions.
+
+.. code-block:: console
+
+ insmod musdk_uio.ko
+ insmod mv_pp_uio.ko
+ insmod mvpp2x_sysfs.ko
+
+Additionally interfaces used by DPDK application need to be put up:
+
+.. code-block:: console
+
+ ip link set eth0 up
+ ip link set eth1 up
+
+In order to run testpmd example application following command can be used:
+
+.. code-block:: console
+
+ ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2 -c 7 -- \
+ --burst=128 --txd=2048 --rxd=1024 --rxq=2 --txq=2 --nb-cores=2 \
+ -i -a --disable-hw-vlan-strip --rss-udp
--
2.7.4