From patchwork Fri Oct 13 12:22:17 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Cristian Dumitrescu X-Patchwork-Id: 30354 Return-Path: X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 306431B6A1; Fri, 13 Oct 2017 14:22:41 +0200 (CEST) Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by dpdk.org (Postfix) with ESMTP id 389581B665 for ; Fri, 13 Oct 2017 14:22:33 +0200 (CEST) Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by fmsmga104.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 13 Oct 2017 05:22:28 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.43,371,1503385200"; d="scan'208";a="162293057" Received: from silpixa00382658.ir.intel.com ([10.237.223.29]) by fmsmga005.fm.intel.com with ESMTP; 13 Oct 2017 05:22:26 -0700 From: Cristian Dumitrescu To: dev@dpdk.org Cc: thomas@monjalon.net, adrien.mazarguil@6wind.com, jingjing.wu@intel.com, john.mcnamara@intel.com, hemant.agrawal@nxp.com, jerin.jacob@caviumnetworks.com, jasvinder.singh@intel.com Date: Fri, 13 Oct 2017 13:22:17 +0100 Message-Id: <1507897338-236951-5-git-send-email-cristian.dumitrescu@intel.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1507897338-236951-1-git-send-email-cristian.dumitrescu@intel.com> References: <1507301136-131382-2-git-send-email-cristian.dumitrescu@intel.com> <1507897338-236951-1-git-send-email-cristian.dumitrescu@intel.com> Subject: [dpdk-dev] [PATCH V4 4/5] doc: ethdev traffic metering and policing api X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Add new section in the Programmer Guide for the ethdev traffic metering and policing (MTR) API. Signed-off-by: Cristian Dumitrescu Acked-by: John McNamara --- Changes in v4: -Improvements from John McNamara on RST formatting doc/guides/prog_guide/index.rst | 1 + .../prog_guide/traffic_metering_and_policing.rst | 102 +++++++++++++++++++++ 2 files changed, 103 insertions(+) create mode 100644 doc/guides/prog_guide/traffic_metering_and_policing.rst diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index b5ad6b8..fbd2a72 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -44,6 +44,7 @@ Programmer's Guide mbuf_lib poll_mode_drv rte_flow + traffic_metering_and_policing traffic_management cryptodev_lib link_bonding_poll_mode_drv_lib diff --git a/doc/guides/prog_guide/traffic_metering_and_policing.rst b/doc/guides/prog_guide/traffic_metering_and_policing.rst new file mode 100644 index 0000000..89f0e68 --- /dev/null +++ b/doc/guides/prog_guide/traffic_metering_and_policing.rst @@ -0,0 +1,102 @@ +.. BSD LICENSE + Copyright(c) 2017 Intel Corporation. All rights reserved. + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + * Neither the name of Intel Corporation nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +Traffic Metering and Policing API +================================= + + +Overview +-------- + +This is the generic API for the Quality of Service (QoS) Traffic Metering and +Policing (MTR) of Ethernet devices. This API is agnostic of the underlying HW, +SW or mixed HW-SW implementation. + +The main features are: + +* Part of DPDK rte_ethdev API +* Capability query API +* Metering algorithms: RFC 2697 Single Rate Three Color Marker (srTCM), RFC 2698 + and RFC 4115 Two Rate Three Color Marker (trTCM) +* Policer actions (per meter output color): recolor, drop +* Statistics (per policer output color) + +Configuration steps +------------------- + +The metering and policing stage typically sits on top of flow classification, +which is why the MTR objects are enabled through a special "meter" action. + +The MTR objects are created and updated in their own name space (``rte_mtr``) +within the ``librte_ether`` library. Whether an MTR object is private to a +flow or potentially shared by several flows has to be specified at its +creation time. + +Once successfully created, an MTR object is hooked into the RX processing path +of the Ethernet device by linking it to one or several flows through the +dedicated "meter" flow action. One or several "meter" actions can be registered +for the same flow. An MTR object can only be destroyed if there are no flows +using it. + +Run-time processing +------------------- + +Traffic metering determines the color for the current packet (green, yellow, +red) based on the previous history for this flow as maintained by the MTR +object. The policer can do nothing, override the color the packet or drop the +packet. Statistics counters are maintained for MTR object, as configured. + +The processing done for each input packet hitting an MTR object is: + +* Traffic metering: The packet is assigned a color (the meter output color) + based on the previous traffic history reflected in the current state of the + MTR object, according to the specific traffic metering algorithm. The + traffic metering algorithm can typically work in color aware mode, in which + case the input packet already has an initial color (the input color), or in + color blind mode, which is equivalent to considering all input packets + initially colored as green. + +* Policing: There is a separate policer action configured for each meter + output color, which can: + + * Drop the packet. + + * Keep the same packet color: the policer output color matches the meter + output color (essentially a no-op action). + + * Recolor the packet: the policer output color is set to a different color + than the meter output color. The policer output color is the output color + of the packet, which is set in the packet meta-data (i.e. struct + ``rte_mbuf::sched::color``). + +* Statistics: The set of counters maintained for each MTR object is + configurable and subject to the implementation support. This set includes + the number of packets and bytes dropped or passed for each output color.