doc/guides/sample_app_ug/bbdev_app.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Intel Corporation
   3
   4 ..  bbdev_app:
   5
   6 Loop-back Sample Application using Baseband Device (bbdev)
   7 ==========================================================
   8
   9 The baseband sample application is a simple example of packet processing using
  10 the Data Plane Development Kit (DPDK) for baseband workloads using Wireless
  11 Device abstraction library.
  12
  13 Overview
  14 --------
  15
  16 The Baseband device sample application performs a loop-back operation using a
  17 baseband device capable of transceiving data packets.
  18 A packet is received on an ethernet port -> enqueued for downlink baseband
  19 operation -> dequeued from the downlink baseband device -> enqueued for uplink
  20 baseband operation -> dequeued from the baseband device -> then the received
  21 packet is compared with the baseband operations output. Then it's looped back to
  22 the ethernet port.
  23
  24 *   The MAC header is preserved in the packet
  25
  26 Limitations
  27 -----------
  28
  29 * Only one baseband device and one ethernet port can be used.
  30
  31 Compiling the Application
  32 -------------------------
  33
  34 DPDK needs to be built with ``baseband_turbo_sw`` PMD driver enabled along
  35 with ``FLEXRAN SDK`` Libraries. Refer to *SW Turbo Poll Mode Driver*
  36 documentation for more details on this.
  37
  38 To compile the sample application see :doc:`compiling`.
  39
  40
  41 Running the Application
  42 -----------------------
  43
  44 The application accepts a number of command line options:
  45
  46 .. code-block:: console
  47
  48     $ ./<build_dir>/examples/dpdk-bbdev [EAL options] -- [-e ENCODING_CORES] /
  49     [-d DECODING_CORES] [-p ETH_PORT_ID] [-b BBDEV_ID]
  50
  51 where:
  52
  53 * ``e ENCODING_CORES``: hexmask for encoding lcores (default = 0x2)
  54 * ``d DECODING_CORES``: hexmask for decoding lcores (default = 0x4)
  55 * ``p ETH_PORT_ID``: ethernet port ID (default = 0)
  56 * ``b BBDEV_ID``: BBDev ID (default = 0)
  57
  58 The application requires that baseband devices is capable of performing
  59 the specified baseband operation are available on application initialization.
  60 This means that HW baseband device/s must be bound to a DPDK driver or
  61 a SW baseband device/s (virtual BBdev) must be created (using --vdev).
  62
  63 To run the application in linux environment with the turbo_sw baseband device
  64 using the allow option for pci device running on 1 encoding lcore and 1 decoding lcore
  65 issue the command:
  66
  67 .. code-block:: console
  68
  69     $ ./<build_dir>/examples/dpdk-bbdev --vdev='baseband_turbo_sw' -a <NIC0PCIADDR> \
  70     -c 0x38 --socket-mem=2,2 --file-prefix=bbdev -- -e 0x10 -d 0x20
  71
  72 where, NIC0PCIADDR is the PCI address of the Rx port
  73
  74 This command creates one virtual bbdev devices ``baseband_turbo_sw`` where the
  75 device gets linked to a corresponding ethernet port as allowed by
  76 the parameter -a.
  77 3 cores are allocated to the application, and assigned as:
  78
  79  - core 3 is the main and used to print the stats live on screen,
  80
  81  - core 4 is the encoding lcore performing Rx and Turbo Encode operations
  82
  83  - core 5 is the downlink lcore performing Turbo Decode, validation and Tx
  84    operations
  85
  86
  87 Refer to the *DPDK Getting Started Guide* for general information on running
  88 applications and the Environment Abstraction Layer (EAL) options.
  89
  90 Using Packet Generator with baseband device sample application
  91 --------------------------------------------------------------
  92
  93 To allow the bbdev sample app to do the loopback, an influx of traffic is required.
  94 This can be done by using DPDK Pktgen to burst traffic on two ethernet ports, and
  95 it will print the transmitted along with the looped-back traffic on Rx ports.
  96 Executing the command below will generate traffic on the two allowed ethernet
  97 ports.
  98
  99 .. code-block:: console
 100
 101     $ ./pktgen-3.4.0/app/x86_64-native-linux-gcc/pktgen -c 0x3 \
 102     --socket-mem=1,1 --file-prefix=pg -a <NIC1PCIADDR> -- -m 1.0 -P
 103
 104 where:
 105
 106 * ``-c COREMASK``: A hexadecimal bitmask of cores to run on
 107 * ``--socket-mem``: Memory to allocate on specific sockets (use comma separated values)
 108 * ``--file-prefix``: Prefix for hugepage filenames
 109 * ``-a <NIC1PCIADDR>``: Add a PCI device in allow list. The argument format is <[domain:]bus:devid.func>.
 110 * ``-m <string>``: Matrix for mapping ports to logical cores.
 111 * ``-P``: PROMISCUOUS mode
 112
 113
 114 Refer to *The Pktgen Application* documents for general information on running
 115 Pktgen with DPDK applications.