doc/guides/sample_app_ug/ntb.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2019 Intel Corporation.
   3
   4 NTB Sample Application
   5 ======================
   6
   7 The ntb sample application shows how to use ntb rawdev driver.
   8 This sample provides interactive mode to do packet based processing
   9 between two systems.
  10
  11 This sample supports 4 types of packet forwarding mode.
  12
  13 * ``file-trans``: transmit files between two systems. The sample will
  14   be polling to receive files from the peer and save the file as
  15   ``ntb_recv_file[N]``, [N] represents the number of received file.
  16 * ``rxonly``: NTB receives packets but doesn't transmit them.
  17 * ``txonly``: NTB generates and transmits packets without receiving any.
  18 * ``iofwd``: iofwd between NTB device and ethdev.
  19
  20 Compiling the Application
  21 -------------------------
  22
  23 To compile the sample application see :doc:`compiling`.
  24
  25 The application is located in the ``ntb`` sub-directory.
  26
  27 Running the Application
  28 -----------------------
  29
  30 The application requires an available core for each port, plus one.
  31 The only available options are the standard ones for the EAL:
  32
  33 .. code-block:: console
  34
  35     ./<build_dir>/examples/dpdk-ntb -c 0xf -n 6 -- -i
  36
  37 Refer to the *DPDK Getting Started Guide* for general information on
  38 running applications and the Environment Abstraction Layer (EAL)
  39 options.
  40
  41 Command-line Options
  42 --------------------
  43
  44 The application supports the following command-line options.
  45
  46 * ``--buf-size=N``
  47
  48   Set the data size of the mbufs used to N bytes, where N < 65536.
  49   The default value is 2048.
  50
  51 * ``--fwd-mode=mode``
  52
  53   Set the packet forwarding mode as ``file-trans``, ``txonly``,
  54   ``rxonly`` or ``iofwd``.
  55
  56 * ``--nb-desc=N``
  57
  58   Set number of descriptors of queue as N, namely queue size,
  59   where 64 <= N <= 1024. The default value is 1024.
  60
  61 * ``--txfreet=N``
  62
  63   Set the transmit free threshold of TX rings to N, where 0 <= N <=
  64   the value of ``--nb-desc``. The default value is 256.
  65
  66 * ``--burst=N``
  67
  68   Set the number of packets per burst to N, where 1 <= N <= 32.
  69   The default value is 32.
  70
  71 * ``--qp=N``
  72
  73   Set the number of queues as N, where qp > 0. The default value is 1.
  74
  75 Using the application
  76 ---------------------
  77
  78 The application is console-driven using the cmdline DPDK interface:
  79
  80 .. code-block:: console
  81
  82         ntb>
  83
  84 From this interface the available commands and descriptions of what
  85 they do as follows:
  86
  87 * ``send [filepath]``: Send file to the peer host. Need to be in
  88   file-trans forwarding mode first.
  89 * ``start``: Start transmission.
  90 * ``stop``: Stop transmission.
  91 * ``show/clear port stats``: Show/Clear port stats and throughput.
  92 * ``set fwd file-trans/rxonly/txonly/iofwd``: Set packet forwarding
  93   mode.
  94 * ``quit``: Exit program.