X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fnics%2Fark.rst;h=da61814b5dbcb1e4d3bc8f6255e735e455320295;hb=735155ee3b7c126b14ac28c5667d5a2d811ddf4c;hp=064ed11c535acf9c7e3001440493989a70162f86;hpb=1131cbf0fb2b700f13446fe06fe498d90290f042;p=dpdk.git diff --git a/doc/guides/nics/ark.rst b/doc/guides/nics/ark.rst index 064ed11c53..da61814b5d 100644 --- a/doc/guides/nics/ark.rst +++ b/doc/guides/nics/ark.rst @@ -1,34 +1,7 @@ -.. BSD LICENSE - - Copyright (c) 2015-2017 Atomic Rules LLC +.. SPDX-License-Identifier: BSD-3-Clause + Copyright (c) 2015-2021 Atomic Rules LLC 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 Atomic Rules LLC 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. - ARK Poll Mode Driver ==================== @@ -146,34 +119,150 @@ Data Path Interface Ingress RX and Egress TX operation is by the nominal DPDK API . The driver supports single-port, multi-queue for both RX and TX. -Refer to ``ark_ethdev.h`` for the list of supported methods to -act upon RX and TX Queues. - Configuration Information ------------------------- -**DPDK Configuration Parameters** +**DPDK Configuration Parameter** + + * **RTE_LIBRTE_ARK_MIN_TX_PKTLEN** (default 0): Sets the minimum + packet length for tx packets to the FPGA. Packets less than this + length are padded to meet the requirement. This allows padding to + be offloaded or remain in host software. + + +Dynamic PMD Extension +--------------------- + +Dynamic PMD extensions allow users to customize net/ark functionality +using their own code. Arkville RTL and this PMD support high-throughput data +movement, and these extensions allow PMD support for users' FPGA +features. +Dynamic PMD extensions operate by having users supply a shared object +file which is loaded by Arkville PMD during initialization. The +object file contains extension (or hook) functions that are registered +and then called during PMD operations. + +The allowable set of extension functions are defined and documented in +``ark_ext.h``, only the initialization function, +``rte_pmd_ark_dev_init()``, is required; all others are optional. The +following sections give a small extension example along with +instructions for compiling and using the extension. + + +Extension Example +^^^^^^^^^^^^^^^^^ + +The following example shows an extension which populates mbuf fields +during RX from user meta data coming from FPGA hardware. + +.. code-block:: c + + #include + #include + #include + #include + + /* Global structure passed to extension/hook functions */ + struct ark_user_extension { + int timestamp_dynfield_offset; + }; + + /* RX tuser field based on user's hardware */ + struct user_rx_meta { + uint64_t timestamp; + uint32_t rss; + } __rte_packed; + + /* Create ark_user_extension object for use in other hook functions */ + void *rte_pmd_ark_dev_init(struct rte_eth_dev * dev, + void * abar, int port_id ) + { + RTE_SET_USED(dev); + RTE_SET_USED(abar); + fprintf(stderr, "Called Arkville user extension for port %u\n", + port_id); + + struct ark_user_extension *xdata = rte_zmalloc("macExtS", + sizeof(struct ark_user_extension), 64); + if (!xdata) + return NULL; + + /* register dynfield for rx timestamp */ + rte_mbuf_dyn_rx_timestamp_register(&xdata->timestamp_dynfield_offset, + NULL); + + fprintf(stderr, "timestamp fields offset in extension is %d\n", + xdata->timestamp_dynfield_offset); + return xdata; + } + + /* uninitialization */ + void rte_pmd_ark_dev_uninit(struct rte_eth_dev * dev, void *user_data) + { + rte_free(user_data); + } - The following configuration options are available for the ARK PMD: + /* Hook function -- called for each RX packet + * Extract RX timestamp and RSS from meta and place in mbuf + */ + void rte_pmd_ark_rx_user_meta_hook(struct rte_mbuf *mbuf, + const uint32_t *meta, + void *user_data) + { + struct ark_user_extension *xdata = user_data; + struct user_rx_meta *user_rx = (struct user_rx_meta*)meta; + *RTE_MBUF_DYNFIELD(mbuf, xdata->timestamp_dynfield_offset, uint64_t*) = + user_rx->timestamp; + mbuf->hash.rss = user_rx->rss; + } - * **CONFIG_RTE_LIBRTE_ARK_PMD** (default y): Enables or disables inclusion - of the ARK PMD driver in the DPDK compilation. - * **CONFIG_RTE_LIBRTE_ARK_PAD_TX** (default y): When enabled TX - packets are padded to 60 bytes to support downstream MACS. +Compiling Extension +^^^^^^^^^^^^^^^^^^^ - * **CONFIG_RTE_LIBRTE_ARK_DEBUG_RX** (default n): Enables or disables debug - logging and internal checking of RX ingress logic within the ARK PMD driver. +It is recommended to the compile the extension code with +``-Wmissing-prototypes`` flag to insure correct function types. Typical +DPDK options will also be needed. - * **CONFIG_RTE_LIBRTE_ARK_DEBUG_TX** (default n): Enables or disables debug - logging and internal checking of TX egress logic within the ARK PMD driver. - * **CONFIG_RTE_LIBRTE_ARK_DEBUG_STATS** (default n): Enables or disables debug - logging of detailed packet and performance statistics gathered in - the PMD and FPGA. +An example command line is give below - * **CONFIG_RTE_LIBRTE_ARK_DEBUG_TRACE** (default n): Enables or disables debug - logging of detailed PMD events and status. +.. code-block:: console + + cc `pkg-config --cflags libdpdk` \ + -O3 -DALLOW_EXPERIMENTAL_API -fPIC -Wall -Wmissing-prototypes -c \ + -o pmd_net_ark_ext.o pmd_net_ark_ext.c + # Linking + cc -o libfx1_100g_ext.so.1 -shared \ + `pkg-config --libs libdpdk` \ + -Wl,--unresolved-symbols=ignore-all \ + -Wl,-soname,libpmd_net_ark_ext.so.1 pmd_net_ark_ext.o + +In a ``Makefile`` this would be + +.. code-block:: Makefile + + CFLAGS += $(shell pkg-config --cflags libdpdk) + CFLAGS += -O3 -DALLOW_EXPERIMENTAL_API -fPIC -Wall -Wmissing-prototypes + # Linking + LDFLAGS += $(shell pkg-config --libs libdpdk) + LDFLAGS += -Wl,--unresolved-symbols=ignore-all -Wl,-soname,libpmd_net_ark_ext.so.1 + +The application must be linked with the ``-export-dynamic`` flags if any +DPDK or application specific code will called from the extension. + + +Enabling Extension +^^^^^^^^^^^^^^^^^^ + +The extensions are enabled in the application through the use of an +environment variable ``ARK_EXT_PATH`` This variable points to the lib +extension file generated above. For example: + +.. code-block:: console + + export ARK_EXT_PATH=$(PWD)/libpmd_net_ark_ext.so.1 + testpmd ... Building DPDK @@ -187,6 +276,15 @@ By default the ARK PMD library will be built into the DPDK library. For configuring and using UIO and VFIO frameworks, please also refer :ref:`the documentation that comes with DPDK suite `. +To build with a non-zero minimum tx packet length, set the above macro in your +CFLAGS environment prior to the meson build step. I.e., + +.. code-block:: console + + export CFLAGS="-DRTE_LIBRTE_ARK_MIN_TX_PKTLEN=60" + meson build + + Supported ARK RTL PCIe Instances -------------------------------- @@ -194,6 +292,11 @@ ARK PMD supports the following Arkville RTL PCIe instances including: * ``1d6c:100d`` - AR-ARKA-FX0 [Arkville 32B DPDK Data Mover] * ``1d6c:100e`` - AR-ARKA-FX1 [Arkville 64B DPDK Data Mover] +* ``1d6c:100f`` - AR-ARKA-FX1 [Arkville 64B DPDK Data Mover for Versal] +* ``1d6c:1010`` - AR-ARKA-FX1 [Arkville 64B DPDK Data Mover for Agilex] +* ``1d6c:1017`` - AR-ARK-FX1 [Arkville 64B Multi-Homed Primary Endpoint] +* ``1d6c:1018`` - AR-ARK-FX1 [Arkville 64B Multi-Homed Secondary Endpoint] +* ``1d6c:1019`` - AR-ARK-FX1 [Arkville 64B Multi-Homed Tertiary Endpoint] Supported Operating Systems --------------------------- @@ -239,58 +342,23 @@ application runs to completion, the ARK PMD can be detached from igb_uio if nece Usage Example ------------- -This section demonstrates how to launch **testpmd** with Atomic Rules ARK -devices managed by librte_pmd_ark. - -#. Load the kernel modules: - - .. code-block:: console - - modprobe uio - insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko - - .. note:: - - The ARK PMD driver depends upon the igb_uio user space I/O kernel module - -#. Mount and request huge pages: - - .. code-block:: console - - mount -t hugetlbfs nodev /mnt/huge - echo 256 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages - -#. Bind UIO driver to ARK device at 0000:01:00.0 (using dpdk-devbind.py): - - .. code-block:: console - - ./usertools/dpdk-devbind.py --bind=igb_uio 0000:01:00.0 - - .. note:: - - The last argument to dpdk-devbind.py is the 4-tuple that indentifies a specific PCIe - device. You can use lspci -d 1d6c: to indentify all Atomic Rules devices in the system, - and thus determine the correct 4-tuple argument to dpdk-devbind.py - -#. Start testpmd with basic parameters: - - .. code-block:: console - - ./x86_64-native-linuxapp-gcc/app/testpmd -l 0-3 -n 4 -- -i - - Example output: - - .. code-block:: console - - [...] - EAL: PCI device 0000:01:00.0 on NUMA socket -1 - EAL: probe driver: 1d6c:100e rte_ark_pmd - EAL: PCI memory mapped at 0x7f9b6c400000 - PMD: eth_ark_dev_init(): Initializing 0:2:0.1 - ARKP PMD CommitID: 378f3a67 - Configuring Port 0 (socket 0) - Port 0: DC:3C:F6:00:00:01 - Checking link statuses... - Port 0 Link Up - speed 100000 Mbps - full-duplex - Done - testpmd> +Follow instructions available in the document +:ref:`compiling and testing a PMD for a NIC ` to launch +**testpmd** with Atomic Rules ARK devices managed by librte_net_ark. + +Example output: + +.. code-block:: console + + [...] + EAL: PCI device 0000:01:00.0 on NUMA socket -1 + EAL: probe driver: 1d6c:100e rte_ark_pmd + EAL: PCI memory mapped at 0x7f9b6c400000 + PMD: eth_ark_dev_init(): Initializing 0:2:0.1 + ARKP PMD CommitID: 378f3a67 + Configuring Port 0 (socket 0) + Port 0: DC:3C:F6:00:00:01 + Checking link statuses... + Port 0 Link Up - speed 100000 Mbps - full-duplex + Done + testpmd>