doc/guides/sample_app_ug/qos_metering.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2014 Intel Corporation.
   3
   4 QoS Metering Sample Application
   5 ===============================
   6
   7 The QoS meter sample application is an example that demonstrates the use of DPDK to provide QoS marking and metering,
   8 as defined by RFC2697 for Single Rate Three Color Marker (srTCM) and RFC 2698 for Two Rate Three Color Marker (trTCM) algorithm.
   9
  10 Overview
  11 --------
  12
  13 The application uses a single thread for reading the packets from the RX port,
  14 metering, marking them with the appropriate color (green, yellow or red) and writing them to the TX port.
  15
  16 A policing scheme can be applied before writing the packets to the TX port by dropping or
  17 changing the color of the packet in a static manner depending on both the input and output colors of the packets that are processed by the meter.
  18
  19 The operation mode can be selected as compile time out of the following options:
  20
  21 *   Simple forwarding
  22
  23 *   srTCM color blind
  24
  25 *   srTCM color aware
  26
  27 *   srTCM color blind
  28
  29 *   srTCM color aware
  30
  31 Please refer to RFC2697 and RFC2698 for details about the srTCM and trTCM configurable parameters
  32 (CIR, CBS and EBS for srTCM; CIR, PIR, CBS and PBS for trTCM).
  33
  34 The color blind modes are functionally equivalent with the color-aware modes when
  35 all the incoming packets are colored as green.
  36
  37 Compiling the Application
  38 -------------------------
  39
  40 To compile the sample application see :doc:`compiling`.
  41
  42 The application is located in the ``qos_meter`` sub-directory.
  43
  44 Running the Application
  45 -----------------------
  46
  47 The application execution command line is as below:
  48
  49 .. code-block:: console
  50
  51     ./dpdk-qos_meter [EAL options] -- -p PORTMASK
  52
  53 The application is constrained to use a single core in the EAL core mask and 2 ports only in the application port mask
  54 (first port from the port mask is used for RX and the other port in the core mask is used for TX).
  55
  56 Refer to *DPDK Getting Started Guide* for general information on running applications and
  57 the Environment Abstraction Layer (EAL) options.
  58
  59 Explanation
  60 -----------
  61
  62 Selecting one of the metering modes is done with these defines:
  63
  64 .. literalinclude:: ../../../examples/qos_meter/main.c
  65         :language: c
  66         :start-after: Traffic metering configuration. 8<
  67         :end-before: >8 End of traffic metering configuration.
  68
  69 To simplify debugging (for example, by using the traffic generator RX side MAC address based packet filtering feature),
  70 the color is defined as the LSB byte of the destination MAC address.
  71
  72 The traffic meter parameters are configured in the application source code with following default values:
  73
  74 .. literalinclude:: ../../../examples/qos_meter/main.c
  75         :language: c
  76         :start-after: Traffic meter parameters are configured in the application. 8<
  77         :end-before: >8 End of traffic meter parameters are configured in the application.
  78
  79 Assuming the input traffic is generated at line rate and all packets are 64 bytes Ethernet frames (IPv4 packet size of 46 bytes)
  80 and green, the expected output traffic should be marked as shown in the following table:
  81
  82 .. _table_qos_metering_1:
  83
  84 .. table:: Output Traffic Marking
  85
  86    +-------------+------------------+-------------------+----------------+
  87    | **Mode**    | **Green (Mpps)** | **Yellow (Mpps)** | **Red (Mpps)** |
  88    |             |                  |                   |                |
  89    +=============+==================+===================+================+
  90    | srTCM blind | 1                | 1                 | 12.88          |
  91    |             |                  |                   |                |
  92    +-------------+------------------+-------------------+----------------+
  93    | srTCM color | 1                | 1                 | 12.88          |
  94    |             |                  |                   |                |
  95    +-------------+------------------+-------------------+----------------+
  96    | trTCM blind | 1                | 0.5               | 13.38          |
  97    |             |                  |                   |                |
  98    +-------------+------------------+-------------------+----------------+
  99    | trTCM color | 1                | 0.5               | 13.38          |
 100    |             |                  |                   |                |
 101    +-------------+------------------+-------------------+----------------+
 102    | FWD         | 14.88            | 0                 | 0              |
 103    |             |                  |                   |                |
 104    +-------------+------------------+-------------------+----------------+
 105
 106 To set up the policing scheme as desired, it is necessary to modify the main.h source file,
 107 where this policy is implemented as a static structure, as follows:
 108
 109 .. literalinclude:: ../../../examples/qos_meter/main.h
 110         :language: c
 111         :start-after: Policy implemented as a static structure. 8<
 112         :end-before: >8 End of policy implemented as a static structure.
 113
 114 Where rows indicate the input color, columns indicate the output color,
 115 and the value that is stored in the table indicates the action to be taken for that particular case.
 116
 117 There are four different actions:
 118
 119 *   GREEN: The packet's color is changed to green.
 120
 121 *   YELLOW: The packet's color is changed to yellow.
 122
 123 *   RED: The packet's color is changed to red.
 124
 125 *   DROP: The packet is dropped.
 126
 127 In this particular case:
 128
 129 *   Every packet which input and output color are the same, keeps the same color.
 130
 131 *   Every packet which color has improved is dropped (this particular case can't happen, so these values will not be used).
 132
 133 *   For the rest of the cases, the color is changed to red.
 134
 135 .. note::
 136     * In color blind mode, first row GREEN color is only valid.
 137     * To drop the packet, policer_table action has to be set to DROP.