1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2017 Intel Corporation. 3 4Traffic Metering and Policing API 5================================= 6 7 8Overview 9-------- 10 11This is the generic API for the Quality of Service (QoS) Traffic Metering and 12Policing (MTR) of Ethernet devices. This API is agnostic of the underlying HW, 13SW or mixed HW-SW implementation. 14 15The main features are: 16 17* Part of DPDK rte_ethdev API 18* Capability query API 19* Metering algorithms: RFC 2697 Single Rate Three Color Marker (srTCM), RFC 2698 20 and RFC 4115 Two Rate Three Color Marker (trTCM) 21* Policer actions (per meter output color): recolor, drop 22* Statistics (per policer output color) 23* Chaining multiple meter objects 24* Protocol based input color selection 25 26Configuration steps 27------------------- 28 29The metering and policing stage typically sits on top of flow classification, 30which is why the MTR objects are enabled through a special "meter" action. 31 32The MTR objects are created and updated in their own name space (``rte_mtr``) 33within the ``librte_ethdev`` library. Whether an MTR object is private to a 34flow or potentially shared by several flows has to be specified at its 35creation time. 36 37Once successfully created, an MTR object is hooked into the RX processing path 38of the Ethernet device by linking it to one or several flows through the 39dedicated "meter" flow action. One or several "meter" actions can be registered 40for the same flow. An MTR object can only be destroyed if there are no flows 41using it. 42 43Run-time processing 44------------------- 45 46Traffic metering determines the color for the current packet (green, yellow, 47red) based on the previous history for this flow as maintained by the MTR 48object. The policer can do nothing, override the color the packet or drop the 49packet. Statistics counters are maintained for MTR object, as configured. 50 51The processing done for each input packet hitting an MTR object is: 52 53* Traffic metering: The packet is assigned a color (the meter output color) 54 based on the previous traffic history reflected in the current state of the 55 MTR object, according to the specific traffic metering algorithm. The 56 traffic metering algorithm can typically work in color aware mode, in which 57 case the input packet already has an initial color (the input color), or in 58 color blind mode, which is equivalent to considering all input packets 59 initially colored as green. 60 61* There is a meter policy API to manage pre-defined policies for meter. 62 Any rte_flow action list can be configured per color for each policy. 63 A meter object configured with a policy executes the actions per packet 64 according to the packet color. 65 66* Statistics: The set of counters maintained for each MTR object is 67 configurable and subject to the implementation support. This set includes 68 the number of packets and bytes dropped or passed for each output color. 69 70API walk-through 71---------------- 72 73.. _figure_rte_mtr_chaining: 74 75.. figure:: ../img/rte_mtr_meter_chaining.* 76 77 Meter components 78 79This section will introduce the reader to the critical APIs to use 80the traffic meter and policing library. 81 82In general, the application performs the following steps to configure the 83traffic meter and policing library. 84 85#. Application gets the meter driver capabilities using ``rte_mtr_capabilities_get()``. 86#. The application creates the required meter profiles by using the 87 ``rte_mtr_meter_profile_add()`` API function. 88#. The application creates the required meter policies by using the 89 ``rte_mtr_meter_policy_add()`` API function. 90#. The application creates a meter object using the ``rte_mtr_create()`` API 91 function. One of the previously created meter profile 92 (``struct rte_mtr_params::meter_profile_id``) and meter policy 93 (``struct rte_mtr_params::meter_policy_id``) are provided as arguments 94 at this step. 95#. The application enables the meter object execution as part of the flow action 96 processing by calling the ``rte_flow_create()`` API function with one of the 97 flow action set to ``RTE_FLOW_ACTION_TYPE_METER`` and the associated 98 meter object ID set to this meter object. 99#. The API allows chaining the meter objects to create complex metering topology 100 by the following methods. 101 102 * Adding multiple flow actions of the type ``RTE_FLOW_ACTION_TYPE_METER`` to 103 the same flow. 104 Each of the meter action typically refers to a different meter object. 105 106 * Adding one (or multiple) actions of the type ``RTE_FLOW_ACTION_TYPE_METER`` 107 to the list of meter actions (``struct rte_mtr_meter_policy_params::actions``) 108 specified per color as show in :numref:`figure_rte_mtr_chaining`. 109 110#. The ``rte_mtr_meter_profile_get()`` and ``rte_mtr_meter_policy_get()`` 111 API functions are available for getting the object pointers directly. 112 These pointers allow quick access to profile/policy objects and are 113 required by the ``RTE_FLOW_ACTION_TYPE_METER_MARK`` action. 114 This action may omit the policy definition to provide flexibility 115 to match a color later with the ``RTE_FLOW_ITEM_TYPE_METER_COLOR`` item. 116 117Protocol based input color selection 118------------------------------------ 119 120The API supports selecting the input color based on the packet content. 121Following is the API usage model for the same. 122 123#. Probe the protocol based input color selection device capabilities using 124 the following parameters with ``rte_mtr_capabilities_get()`` API. 125 126 * ``struct rte_mtr_capabilities::input_color_proto_mask;`` 127 * ``struct rte_mtr_capabilities::separate_input_color_table_per_port`` 128 129#. When creating the meter object using ``rte_mtr_create()``, configure 130 relevant input color selection parameters such as 131 132 * Fill the tables ``struct rte_mtr_params::dscp_table``, 133 ``struct rte_mtr_params::vlan_table`` based on input color selected. 134 135 * Update the ``struct rte_mtr_params::default_input_color`` to determine 136 the default input color in case the input packet does not match 137 the input color method. 138 139#. Use the following APIs to configure the meter object 140 141 * Select the input protocol color with ``rte_mtr_color_in_protocol_set()`` API. 142 143 * If needed, update the input color table at runtime using 144 ``rte_mtr_meter_vlan_table_update()`` and ``rte_mtr_meter_dscp_table_update()`` 145 APIs. 146 147 * Application can query the configured input color protocol and its associated 148 priority using ``rte_mtr_color_in_protocol_get()`` and 149 ``rte_mtr_color_in_protocol_priority_get()`` APIs. 150