1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2014 Intel Corporation. 3 4QoS Scheduler Sample Application 5================================ 6 7The QoS sample application demonstrates the use of the DPDK to provide QoS scheduling. 8 9Overview 10-------- 11 12The architecture of the QoS scheduler application is shown in the following figure. 13 14.. _figure_qos_sched_app_arch: 15 16.. figure:: img/qos_sched_app_arch.* 17 18 QoS Scheduler Application Architecture 19 20 21There are two flavors of the runtime execution for this application, 22with two or three threads per each packet flow configuration being used. 23The RX thread reads packets from the RX port, 24classifies the packets based on the double VLAN (outer and inner) and 25the lower byte of the IP destination address and puts them into the ring queue. 26The worker thread dequeues the packets from the ring and calls the QoS scheduler enqueue/dequeue functions. 27If a separate TX core is used, these are sent to the TX ring. 28Otherwise, they are sent directly to the TX port. 29The TX thread, if present, reads from the TX ring and write the packets to the TX port. 30 31Compiling the Application 32------------------------- 33 34To compile the sample application see :doc:`compiling`. 35 36The application is located in the ``qos_sched`` sub-directory. 37 38 .. note:: 39 40 This application is intended as a linux only. 41 42.. note:: 43 44 Number of grinders is currently set to 8. 45 This can be modified by specifying RTE_SCHED_PORT_N_GRINDERS=N 46 in CFLAGS, where N is number of grinders. 47 48Running the Application 49----------------------- 50 51.. note:: 52 53 In order to run the application, a total of at least 4 54 G of huge pages must be set up for each of the used sockets (depending on the cores in use). 55 56The application has a number of command line options: 57 58.. code-block:: console 59 60 ./<build_dir>/examples/dpdk-qos_sched [EAL options] -- <APP PARAMS> 61 62Mandatory application parameters include: 63 64* --pfc "RX PORT, TX PORT, RX LCORE, WT LCORE, TX CORE": Packet flow configuration. 65 Multiple pfc entities can be configured in the command line, 66 having 4 or 5 items (if TX core defined or not). 67 68Optional application parameters include: 69 70* -i: It makes the application to start in the interactive mode. 71 In this mode, the application shows a command line that can be used for obtaining statistics while 72 scheduling is taking place (see interactive mode below for more information). 73 74* --mnc n: Main core index (the default value is 1). 75 76* --rsz "A, B, C": Ring sizes: 77 78* A = Size (in number of buffer descriptors) of each of the NIC RX rings read 79 by the I/O RX lcores (the default value is 128). 80 81* B = Size (in number of elements) of each of the software rings used 82 by the I/O RX lcores to send packets to worker lcores (the default value is 8192). 83 84* C = Size (in number of buffer descriptors) of each of the NIC TX rings written 85 by worker lcores (the default value is 256) 86 87* --bsz "A, B, C, D": Burst sizes 88 89* A = I/O RX lcore read burst size from the NIC RX (the default value is 64) 90 91* B = I/O RX lcore write burst size to the output software rings, 92 worker lcore read burst size from input software rings,QoS enqueue size (the default value is 64) 93 94* C = QoS dequeue size (the default value is 63) 95 96* D = Worker lcore write burst size to the NIC TX (the default value is 64) 97 98* --msz M: Mempool size (in number of mbufs) for each pfc (default 2097152) 99 100* --rth "A, B, C": The RX queue threshold parameters 101 102* A = RX prefetch threshold (the default value is 8) 103 104* B = RX host threshold (the default value is 8) 105 106* C = RX write-back threshold (the default value is 4) 107 108* --tth "A, B, C": TX queue threshold parameters 109 110* A = TX prefetch threshold (the default value is 36) 111 112* B = TX host threshold (the default value is 0) 113 114* C = TX write-back threshold (the default value is 0) 115 116* --cfg FILE: Profile configuration to load 117 118Refer to *DPDK Getting Started Guide* for general information on running applications and 119the Environment Abstraction Layer (EAL) options. 120 121The profile configuration file defines all the port/subport/pipe/traffic class/queue parameters 122needed for the QoS scheduler configuration. 123 124The profile file has the following format: 125 126.. literalinclude:: ../../../examples/qos_sched/profile.cfg 127 :start-after: Data Plane Development Kit (DPDK) Programmer's Guide 128 129Interactive mode 130~~~~~~~~~~~~~~~~ 131 132These are the commands that are currently working under the command line interface: 133 134* Control Commands 135 136* --quit: Quits the application. 137 138* General Statistics 139 140 * stats app: Shows a table with in-app calculated statistics. 141 142 * stats port X subport Y: For a specific subport, it shows the number of packets that 143 went through the scheduler properly and the number of packets that were dropped. 144 The same information is shown in bytes. 145 The information is displayed in a table separating it in different traffic classes. 146 147 * stats port X subport Y pipe Z: For a specific pipe, it shows the number of packets that 148 went through the scheduler properly and the number of packets that were dropped. 149 The same information is shown in bytes. 150 This information is displayed in a table separating it in individual queues. 151 152* Average queue size 153 154All of these commands work the same way, averaging the number of packets throughout a specific subset of queues. 155 156Two parameters can be configured for this prior to calling any of these commands: 157 158 * qavg n X: n is the number of times that the calculation will take place. 159 Bigger numbers provide higher accuracy. The default value is 10. 160 161 * qavg period X: period is the number of microseconds that will be allowed between each calculation. 162 The default value is 100. 163 164The commands that can be used for measuring average queue size are: 165 166* qavg port X subport Y: Show average queue size per subport. 167 168* qavg port X subport Y tc Z: Show average queue size per subport for a specific traffic class. 169 170* qavg port X subport Y pipe Z: Show average queue size per pipe. 171 172* qavg port X subport Y pipe Z tc A: Show average queue size per pipe for a specific traffic class. 173 174* qavg port X subport Y pipe Z tc A q B: Show average queue size of a specific queue. 175 176Example 177~~~~~~~ 178 179The following is an example command with a single packet flow configuration: 180 181.. code-block:: console 182 183 ./<build_dir>/examples/dpdk-qos_sched -l 1,5,7 -n 4 -- --pfc "3,2,5,7" --cfg ./profile.cfg 184 185This example uses a single packet flow configuration which creates one RX thread on lcore 5 reading 186from port 3 and a worker thread on lcore 7 writing to port 2. 187 188Another example with 2 packet flow configurations using different ports but sharing the same core for QoS scheduler is given below: 189 190.. code-block:: console 191 192 ./<build_dir>/examples/dpdk-qos_sched -l 1,2,6,7 -n 4 -- --pfc "3,2,2,6,7" --pfc "1,0,2,6,7" --cfg ./profile.cfg 193 194Note that independent cores for the packet flow configurations for each of the RX, WT and TX thread are also supported, 195providing flexibility to balance the work. 196 197The EAL coremask/corelist is constrained to contain the default main core 1 and the RX, WT and TX cores only. 198 199Explanation 200----------- 201 202The Port/Subport/Pipe/Traffic Class/Queue are the hierarchical entities in a typical QoS application: 203 204* A subport represents a predefined group of users. 205 206* A pipe represents an individual user/subscriber. 207 208* A traffic class is the representation of a different traffic type with a specific loss rate, 209 delay and jitter requirements; such as data voice, video or data transfers. 210 211* A queue hosts packets from one or multiple connections of the same type belonging to the same user. 212 213The traffic flows that need to be configured are application dependent. 214This application classifies based on the QinQ double VLAN tags and the IP destination address as indicated in the following table. 215 216.. _table_qos_scheduler_1: 217 218.. table:: Entity Types 219 220 +----------------+-------------------------+--------------------------------------------------+----------------------------------+ 221 | **Level Name** | **Siblings per Parent** | **QoS Functional Description** | **Selected By** | 222 | | | | | 223 +================+=========================+==================================================+==================================+ 224 | Port | - | Ethernet port | Physical port | 225 | | | | | 226 +----------------+-------------------------+--------------------------------------------------+----------------------------------+ 227 | Subport | Config (8) | Traffic shaped (token bucket) | Outer VLAN tag | 228 | | | | | 229 +----------------+-------------------------+--------------------------------------------------+----------------------------------+ 230 | Pipe | Config (4k) | Traffic shaped (token bucket) | Inner VLAN tag | 231 | | | | | 232 +----------------+-------------------------+--------------------------------------------------+----------------------------------+ 233 | Traffic Class | 13 | TCs of the same pipe services in strict priority | Destination IP address (0.0.0.X) | 234 | | | | | 235 +----------------+-------------------------+--------------------------------------------------+----------------------------------+ 236 | Queue | High Priority TC: 1, | Queue of lowest priority traffic | Destination IP address (0.0.0.X) | 237 | | Lowest Priority TC: 4 | class (Best effort) serviced in WRR | | 238 +----------------+-------------------------+--------------------------------------------------+----------------------------------+ 239 240Please refer to the "QoS Scheduler" chapter in the *DPDK Programmer's Guide* for more information about these parameters. 241