nics/szedata2.rst

   1 ..  BSD LICENSE
   2     Copyright 2015 - 2016 CESNET
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of CESNET nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 SZEDATA2 poll mode driver library
  32 =================================
  33
  34 The SZEDATA2 poll mode driver library implements support for the Netcope
  35 FPGA Boards (**NFB-***), FPGA-based programmable NICs.
  36 The SZEDATA2 PMD uses interface provided by the libsze2 library to communicate
  37 with the NFB cards over the sze2 layer.
  38
  39 More information about the
  40 `NFB cards <http://www.netcope.com/en/products/fpga-boards>`_
  41 and used technology
  42 (`Netcope Development Kit <http://www.netcope.com/en/products/fpga-development-kit>`_)
  43 can be found on the `Netcope Technologies website <http://www.netcope.com/>`_.
  44
  45 .. note::
  46
  47    This driver has external dependencies.
  48    Therefore it is disabled in default configuration files.
  49    It can be enabled by setting ``CONFIG_RTE_LIBRTE_PMD_SZEDATA2=y``
  50    and recompiling.
  51
  52 .. note::
  53
  54    Currently the driver is supported only on x86_64 architectures.
  55    Only x86_64 versions of the external libraries are provided.
  56
  57 Prerequisites
  58 -------------
  59
  60 This PMD requires kernel modules which are responsible for initialization and
  61 allocation of resources needed for sze2 layer function.
  62 Communication between PMD and kernel modules is mediated by libsze2 library.
  63 These kernel modules and library are not part of DPDK and must be installed
  64 separately:
  65
  66 *  **libsze2 library**
  67
  68    The library provides API for initialization of sze2 transfers, receiving and
  69    transmitting data segments.
  70
  71 *  **Kernel modules**
  72
  73    * combov3
  74    * szedata2_cv3
  75
  76    Kernel modules manage initialization of hardware, allocation and
  77    sharing of resources for user space applications.
  78
  79 Information about getting the dependencies can be found `here
  80 <http://www.netcope.com/en/company/community-support/dpdk-libsze2>`_.
  81
  82 Configuration
  83 -------------
  84
  85 These configuration options can be modified before compilation in the
  86 ``.config`` file:
  87
  88 *  ``CONFIG_RTE_LIBRTE_PMD_SZEDATA2`` default value: **n**
  89
  90    Value **y** enables compilation of szedata2 PMD.
  91
  92 *  ``CONFIG_RTE_LIBRTE_PMD_SZEDATA2_AS`` default value: **0**
  93
  94    This option defines type of firmware address space and must be set
  95    according to the used card and mode.
  96    Currently supported values are:
  97
  98    * **0** - for cards (modes):
  99
 100       * NFB-100G1 (100G1)
 101
 102    * **1** - for cards (modes):
 103
 104       * NFB-100G2Q (100G1)
 105
 106    * **2** - for cards (modes):
 107
 108       * NFB-40G2 (40G2)
 109       * NFB-100G2C (100G2)
 110       * NFB-100G2Q (40G2)
 111
 112    * **3** - for cards (modes):
 113
 114       * NFB-40G2 (10G8)
 115       * NFB-100G2Q (10G8)
 116
 117    * **4** - for cards (modes):
 118
 119       * NFB-100G1 (10G10)
 120
 121    * **5** - for experimental firmwares and future use
 122
 123 Using the SZEDATA2 PMD
 124 ----------------------
 125
 126 From DPDK version 16.04 the type of SZEDATA2 PMD is changed to PMD_PDEV.
 127 SZEDATA2 device is automatically recognized during EAL initialization.
 128 No special command line options are needed.
 129
 130 Kernel modules have to be loaded before running the DPDK application.
 131
 132 Example of usage
 133 ----------------
 134
 135 Read packets from 0. and 1. receive channel and write them to 0. and 1.
 136 transmit channel:
 137
 138 .. code-block:: console
 139
 140    $RTE_TARGET/app/testpmd -l 0-3 -n 2 \
 141    -- --port-topology=chained --rxq=2 --txq=2 --nb-cores=2 -i -a
 142
 143 Example output:
 144
 145 .. code-block:: console
 146
 147    [...]
 148    EAL: PCI device 0000:06:00.0 on NUMA socket -1
 149    EAL:   probe driver: 1b26:c1c1 rte_szedata2_pmd
 150    PMD: Initializing szedata2 device (0000:06:00.0)
 151    PMD: SZEDATA2 path: /dev/szedataII0
 152    PMD: Available DMA channels RX: 8 TX: 8
 153    PMD: resource0 phys_addr = 0xe8000000 len = 134217728 virt addr = 7f48f8000000
 154    PMD: szedata2 device (0000:06:00.0) successfully initialized
 155    Interactive-mode selected
 156    Auto-start selected
 157    Configuring Port 0 (socket 0)
 158    Port 0: 00:11:17:00:00:00
 159    Checking link statuses...
 160    Port 0 Link Up - speed 10000 Mbps - full-duplex
 161    Done
 162    Start automatic packet forwarding
 163      io packet forwarding - CRC stripping disabled - packets/burst=32
 164      nb forwarding cores=2 - nb forwarding ports=1
 165      RX queues=2 - RX desc=128 - RX free threshold=0
 166      RX threshold registers: pthresh=0 hthresh=0 wthresh=0
 167      TX queues=2 - TX desc=512 - TX free threshold=0
 168      TX threshold registers: pthresh=0 hthresh=0 wthresh=0
 169      TX RS bit threshold=0 - TXQ flags=0x0
 170    testpmd>