doc/guides/nics/ark.rst

   1 .. SPDX-License-Identifier: BSD-3-Clause
   2     Copyright (c) 2015-2017 Atomic Rules LLC
   3     All rights reserved.
   4
   5 ARK Poll Mode Driver
   6 ====================
   7
   8 The ARK PMD is a DPDK poll-mode driver for the Atomic Rules Arkville
   9 (ARK) family of devices.
  10
  11 More information can be found at the `Atomic Rules website
  12 <http://atomicrules.com>`_.
  13
  14 Overview
  15 --------
  16
  17 The Atomic Rules Arkville product is DPDK and AXI compliant product
  18 that marshals packets across a PCIe conduit between host DPDK mbufs and
  19 FPGA AXI streams.
  20
  21 The ARK PMD, and the spirit of the overall Arkville product,
  22 has been to take the DPDK API/ABI as a fixed specification;
  23 then implement much of the business logic in FPGA RTL circuits.
  24 The approach of *working backwards* from the DPDK API/ABI and having
  25 the GPP host software *dictate*, while the FPGA hardware *copes*,
  26 results in significant performance gains over a naive implementation.
  27
  28 While this document describes the ARK PMD software, it is helpful to
  29 understand what the FPGA hardware is and is not. The Arkville RTL
  30 component provides a single PCIe Physical Function (PF) supporting
  31 some number of RX/Ingress and TX/Egress Queues. The ARK PMD controls
  32 the Arkville core through a dedicated opaque Core BAR (CBAR).
  33 To allow users full freedom for their own FPGA application IP,
  34 an independent FPGA Application BAR (ABAR) is provided.
  35
  36 One popular way to imagine Arkville's FPGA hardware aspect is as the
  37 FPGA PCIe-facing side of a so-called Smart NIC. The Arkville core does
  38 not contain any MACs, and is link-speed independent, as well as
  39 agnostic to the number of physical ports the application chooses to
  40 use. The ARK driver exposes the familiar PMD interface to allow packet
  41 movement to and from mbufs across multiple queues.
  42
  43 However FPGA RTL applications could contain a universe of added
  44 functionality that an Arkville RTL core does not provide or can
  45 not anticipate. To allow for this expectation of user-defined
  46 innovation, the ARK PMD provides a dynamic mechanism of adding
  47 capabilities without having to modify the ARK PMD.
  48
  49 The ARK PMD is intended to support all instances of the Arkville
  50 RTL Core, regardless of configuration, FPGA vendor, or target
  51 board. While specific capabilities such as number of physical
  52 hardware queue-pairs are negotiated; the driver is designed to
  53 remain constant over a broad and extendable feature set.
  54
  55 Intentionally, Arkville by itself DOES NOT provide common NIC
  56 capabilities such as offload or receive-side scaling (RSS).
  57 These capabilities would be viewed as a gate-level "tax" on
  58 Green-box FPGA applications that do not require such function.
  59 Instead, they can be added as needed with essentially no
  60 overhead to the FPGA Application.
  61
  62 The ARK PMD also supports optional user extensions, through dynamic linking.
  63 The ARK PMD user extensions are a feature of Arkville’s DPDK
  64 net/ark poll mode driver, allowing users to add their
  65 own code to extend the net/ark functionality without
  66 having to make source code changes to the driver. One motivation for
  67 this capability is that while DPDK provides a rich set of functions
  68 to interact with NIC-like capabilities (e.g. MAC addresses and statistics),
  69 the Arkville RTL IP does not include a MAC.  Users can supply their
  70 own MAC or custom FPGA applications, which may require control from
  71 the PMD.  The user extension is the means providing the control
  72 between the user's FPGA application and the existing DPDK features via
  73 the PMD.
  74
  75 Device Parameters
  76 -------------------
  77
  78 The ARK PMD supports device parameters that are used for packet
  79 routing and for internal packet generation and packet checking.  This
  80 section describes the supported parameters.  These features are
  81 primarily used for diagnostics, testing, and performance verification
  82 under the guidance of an Arkville specialist.  The nominal use of
  83 Arkville does not require any configuration using these parameters.
  84
  85 "Pkt_dir"
  86
  87 The Packet Director controls connectivity between Arkville's internal
  88 hardware components. The features of the Pkt_dir are only used for
  89 diagnostics and testing; it is not intended for nominal use.  The full
  90 set of features are not published at this level.
  91
  92 Format:
  93 Pkt_dir=0x00110F10
  94
  95 "Pkt_gen"
  96
  97 The packet generator parameter takes a file as its argument.  The file
  98 contains configuration parameters used internally for regression
  99 testing and are not intended to be published at this level.  The
 100 packet generator is an internal Arkville hardware component.
 101
 102 Format:
 103 Pkt_gen=./config/pg.conf
 104
 105 "Pkt_chkr"
 106
 107 The packet checker parameter takes a file as its argument.  The file
 108 contains configuration parameters used internally for regression
 109 testing and are not intended to be published at this level.  The
 110 packet checker is an internal Arkville hardware component.
 111
 112 Format:
 113 Pkt_chkr=./config/pc.conf
 114
 115
 116 Data Path Interface
 117 -------------------
 118
 119 Ingress RX and Egress TX operation is by the nominal DPDK API .
 120 The driver supports single-port, multi-queue for both RX and TX.
 121
 122 Configuration Information
 123 -------------------------
 124
 125 **DPDK Configuration Parameters**
 126
 127   The following configuration options are available for the ARK PMD:
 128
 129    * **CONFIG_RTE_LIBRTE_ARK_PMD** (default y): Enables or disables inclusion
 130      of the ARK PMD driver in the DPDK compilation.
 131
 132    * **CONFIG_RTE_LIBRTE_ARK_PAD_TX** (default y):  When enabled TX
 133      packets are padded to 60 bytes to support downstream MACS.
 134
 135    * **CONFIG_RTE_LIBRTE_ARK_DEBUG_RX** (default n): Enables or disables debug
 136      logging and internal checking of RX ingress logic within the ARK PMD driver.
 137
 138    * **CONFIG_RTE_LIBRTE_ARK_DEBUG_TX** (default n): Enables or disables debug
 139      logging and internal checking of TX egress logic within the ARK PMD driver.
 140
 141    * **CONFIG_RTE_LIBRTE_ARK_DEBUG_STATS** (default n): Enables or disables debug
 142      logging of detailed packet and performance statistics gathered in
 143      the PMD and FPGA.
 144
 145    * **CONFIG_RTE_LIBRTE_ARK_DEBUG_TRACE** (default n): Enables or disables debug
 146      logging of detailed PMD events and status.
 147
 148
 149 Building DPDK
 150 -------------
 151
 152 See the :ref:`DPDK Getting Started Guide for Linux <linux_gsg>` for
 153 instructions on how to build DPDK.
 154
 155 By default the ARK PMD library will be built into the DPDK library.
 156
 157 For configuring and using UIO and VFIO frameworks, please also refer :ref:`the
 158 documentation that comes with DPDK suite <linux_gsg>`.
 159
 160 Supported ARK RTL PCIe Instances
 161 --------------------------------
 162
 163 ARK PMD supports the following Arkville RTL PCIe instances including:
 164
 165 * ``1d6c:100d`` - AR-ARKA-FX0 [Arkville 32B DPDK Data Mover]
 166 * ``1d6c:100e`` - AR-ARKA-FX1 [Arkville 64B DPDK Data Mover]
 167
 168 Supported Operating Systems
 169 ---------------------------
 170
 171 Any Linux distribution fulfilling the conditions described in ``System Requirements``
 172 section of :ref:`the DPDK documentation <linux_gsg>` or refer to *DPDK
 173 Release Notes*.  ARM and PowerPC architectures are not supported at this time.
 174
 175
 176 Supported Features
 177 ------------------
 178
 179 * Dynamic ARK PMD extensions
 180 * Multiple receive and transmit queues
 181 * Jumbo frames up to 9K
 182 * Hardware Statistics
 183
 184 Unsupported Features
 185 --------------------
 186
 187 Features that may be part of, or become part of, the Arkville RTL IP that are
 188 not currently supported or exposed by the ARK PMD include:
 189
 190 * PCIe SR-IOV Virtual Functions (VFs)
 191 * Arkville's Packet Generator Control and Status
 192 * Arkville's Packet Director Control and Status
 193 * Arkville's Packet Checker Control and Status
 194 * Arkville's Timebase Management
 195
 196 Pre-Requisites
 197 --------------
 198
 199 #. Prepare the system as recommended by DPDK suite.  This includes environment
 200    variables, hugepages configuration, tool-chains and configuration
 201
 202 #. Insert igb_uio kernel module using the command 'modprobe igb_uio'
 203
 204 #. Bind the intended ARK device to igb_uio module
 205
 206 At this point the system should be ready to run DPDK applications. Once the
 207 application runs to completion, the ARK PMD can be detached from igb_uio if necessary.
 208
 209 Usage Example
 210 -------------
 211
 212 Follow instructions available in the document
 213 :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to launch
 214 **testpmd** with Atomic Rules ARK devices managed by librte_pmd_ark.
 215
 216 Example output:
 217
 218 .. code-block:: console
 219
 220    [...]
 221    EAL: PCI device 0000:01:00.0 on NUMA socket -1
 222    EAL:   probe driver: 1d6c:100e rte_ark_pmd
 223    EAL:   PCI memory mapped at 0x7f9b6c400000
 224    PMD: eth_ark_dev_init(): Initializing 0:2:0.1
 225    ARKP PMD CommitID: 378f3a67
 226    Configuring Port 0 (socket 0)
 227    Port 0: DC:3C:F6:00:00:01
 228    Checking link statuses...
 229    Port 0 Link Up - speed 100000 Mbps - full-duplex
 230    Done
 231    testpmd>