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 ``turbo_sw`` PMD driver enabled along with
  35    ``FLEXRAN SDK`` Libraries. Refer to *SW Turbo Poll Mode Driver*
  36    documentation for more details on this.
  37
  38 #. Go to the example directory:
  39
  40     .. code-block:: console
  41
  42         export RTE_SDK=/path/to/rte_sdk
  43         cd ${RTE_SDK}/examples/bbdev_app
  44
  45 #. Set the target (a default target is used if not specified). For example:
  46
  47     .. code-block:: console
  48
  49         export RTE_TARGET=x86_64-native-linuxapp-gcc
  50
  51     See the *DPDK Getting Started Guide* for possible RTE_TARGET values.
  52
  53 #. Build the application:
  54
  55     .. code-block:: console
  56
  57         make
  58
  59 Running the Application
  60 -----------------------
  61
  62 The application accepts a number of command line options:
  63
  64 .. code-block:: console
  65
  66     $ ./build/bbdev [EAL options] -- [-e ENCODING_CORES] [-d DECODING_CORES] /
  67     [-p ETH_PORT_ID] [-b BBDEV_ID]
  68
  69 where:
  70
  71 * ``e ENCODING_CORES``: hexmask for encoding lcored (default = 0x2)
  72 * ``d DECODING_CORES``: hexmask for decoding lcores (default = 0x4)
  73 * ``p ETH_PORT_ID``: ethernet port ID (default = 0)
  74 * ``b BBDEV_ID``: BBDev ID (default = 0)
  75
  76 The application requires that baseband devices is capable of performing
  77 the specified baseband operation are available on application initialization.
  78 This means that HW baseband device/s must be bound to a DPDK driver or
  79 a SW baseband device/s (virtual BBdev) must be created (using --vdev).
  80
  81 To run the application in linuxapp environment with the turbo_sw baseband device
  82 using the whitelisted port running on 1 encoding lcore and 1 decoding lcore
  83 issue the command:
  84
  85 .. code-block:: console
  86
  87     $ ./build/bbdev --vdev='turbo_sw' -w <NIC0PCIADDR> -c 0x38 --socket-mem=2,2 \
  88     --file-prefix=bbdev -- -e 0x10 -d 0x20
  89
  90 where, NIC0PCIADDR is the PCI addresse of the Rx port
  91
  92 This command creates one virtual bbdev devices ``turbo_sw`` where the device
  93 gets linked to a corresponding ethernet port as whitelisted by the parameter -w.
  94 3 cores are allocated to the application, and assigned as:
  95
  96  - core 3 is the master and used to print the stats live on screen,
  97
  98  - core 4 is the encoding lcore performing Rx and Turbo Encode operations
  99
 100  - core 5 is the downlink lcore performing Turbo Decode, validation and Tx
 101    operations
 102
 103
 104 Refer to the *DPDK Getting Started Guide* for general information on running
 105 applications and the Environment Abstraction Layer (EAL) options.
 106
 107 Using Packet Generator with baseband device sample application
 108 --------------------------------------------------------------
 109
 110 To allow the bbdev sample app to do the loopback, an influx of traffic is required.
 111 This can be done by using DPDK Pktgen to burst traffic on two ethernet ports, and
 112 it will print the transmitted along with the looped-back traffic on Rx ports.
 113 Executing the command below will generate traffic on the two whitelisted ethernet
 114 ports.
 115
 116 .. code-block:: console
 117
 118     $ ./pktgen-3.4.0/app/x86_64-native-linuxapp-gcc/pktgen -c 0x3 \
 119     --socket-mem=1,1 --file-prefix=pg -w <NIC1PCIADDR> -- -m 1.0 -P
 120
 121 where:
 122
 123 * ``-c COREMASK``: A hexadecimal bitmask of cores to run on
 124 * ``--socket-mem``: Memory to allocate on specific sockets (use comma separated values)
 125 * ``--file-prefix``: Prefix for hugepage filenames
 126 * ``-w <NIC1PCIADDR>``: Add a PCI device in white list. The argument format is <[domain:]bus:devid.func>.
 127 * ``-m <string>``: Matrix for mapping ports to logical cores.
 128 * ``-P``: PROMISCUOUS mode
 129
 130
 131 Refer to *The Pktgen Application* documents for general information on running
 132 Pktgen with DPDK applications.