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 #. 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='baseband_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 ``baseband_turbo_sw`` where the
  93 device gets linked to a corresponding ethernet port as whitelisted by
  94 the parameter -w.
  95 3 cores are allocated to the application, and assigned as:
  96
  97  - core 3 is the master and used to print the stats live on screen,
  98
  99  - core 4 is the encoding lcore performing Rx and Turbo Encode operations
 100
 101  - core 5 is the downlink lcore performing Turbo Decode, validation and Tx
 102    operations
 103
 104
 105 Refer to the *DPDK Getting Started Guide* for general information on running
 106 applications and the Environment Abstraction Layer (EAL) options.
 107
 108 Using Packet Generator with baseband device sample application
 109 --------------------------------------------------------------
 110
 111 To allow the bbdev sample app to do the loopback, an influx of traffic is required.
 112 This can be done by using DPDK Pktgen to burst traffic on two ethernet ports, and
 113 it will print the transmitted along with the looped-back traffic on Rx ports.
 114 Executing the command below will generate traffic on the two whitelisted ethernet
 115 ports.
 116
 117 .. code-block:: console
 118
 119     $ ./pktgen-3.4.0/app/x86_64-native-linuxapp-gcc/pktgen -c 0x3 \
 120     --socket-mem=1,1 --file-prefix=pg -w <NIC1PCIADDR> -- -m 1.0 -P
 121
 122 where:
 123
 124 * ``-c COREMASK``: A hexadecimal bitmask of cores to run on
 125 * ``--socket-mem``: Memory to allocate on specific sockets (use comma separated values)
 126 * ``--file-prefix``: Prefix for hugepage filenames
 127 * ``-w <NIC1PCIADDR>``: Add a PCI device in white list. The argument format is <[domain:]bus:devid.func>.
 128 * ``-m <string>``: Matrix for mapping ports to logical cores.
 129 * ``-P``: PROMISCUOUS mode
 130
 131
 132 Refer to *The Pktgen Application* documents for general information on running
 133 Pktgen with DPDK applications.