From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 6573CA0C40; Thu, 5 Aug 2021 13:06:06 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 239C940143; Thu, 5 Aug 2021 13:06:06 +0200 (CEST) Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by mails.dpdk.org (Postfix) with ESMTP id 5EFD740040 for ; Thu, 5 Aug 2021 13:06:04 +0200 (CEST) X-IronPort-AV: E=McAfee;i="6200,9189,10066"; a="214155944" X-IronPort-AV: E=Sophos;i="5.84,296,1620716400"; d="scan'208";a="214155944" Received: from orsmga006.jf.intel.com ([10.7.209.51]) by orsmga103.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 05 Aug 2021 04:06:02 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.84,296,1620716400"; d="scan'208";a="419782743" Received: from fmsmsx604.amr.corp.intel.com ([10.18.126.84]) by orsmga006.jf.intel.com with ESMTP; 05 Aug 2021 04:06:01 -0700 Received: from fmsmsx609.amr.corp.intel.com (10.18.126.89) by fmsmsx604.amr.corp.intel.com (10.18.126.84) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2242.10; Thu, 5 Aug 2021 04:06:01 -0700 Received: from FMSEDG603.ED.cps.intel.com (10.1.192.133) by fmsmsx609.amr.corp.intel.com (10.18.126.89) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2242.10 via Frontend Transport; Thu, 5 Aug 2021 04:06:01 -0700 Received: from NAM10-DM6-obe.outbound.protection.outlook.com (104.47.58.109) by edgegateway.intel.com (192.55.55.68) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2242.10; Thu, 5 Aug 2021 04:06:00 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=WPQbmm9tMzH9YBwdKM8z3q8C4qT1oB0YYdUu8DMON9kHEgIqQ5Qy9dOGuW8jZf4xEY26pYlV7bWM1iS/7voi/pVkGy/Jl8r8IHLjI5P6hFM/A5bXVOuYQQc9hg7AjSBpqDQdKsbWPwMCe9o75mCh57BUHmIOHO12LY9IVhCkxCyxhbwOIrzWPEN2kRUZfkdgkpfC3ZrtbXEEk0aXkrl5BQKh2T++LP4oFfct8X4IauHp4XOpDF4YF+AOrDtNuLd5peD+n/jl7F1TUVx0CVEAjxdRZCNWKHEif9ZyNm6e8LBVXxf+rkORxTfC3zeGlDlEZLrv96OcUsxKwumm6bUKhA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=6kmXhkupfDUN659AkAlfaJSl/7zmJFqL6GoTm2nlQDg=; b=ELkirNLxEKq2Px3rEtrU9lSa2umuxdg82jNucW+OeeBeIBle8X7mgmL1bWHBZ0q8GCTYL+FbDiRhsiqX7Ol/JznUWxUP6tkuYouWVO3srs0IaS1W4RlmI9fA2++mF4kTk743BIAtLEnYF87DT+aTBfTl0yAefKLebIVpinkjO40n7z25PwdtFUSIPKmQY22nn7qNTR47ItwgPxLhdzu4Jo4u5wpmJ2yC+h1w2u/3XDRaqNmATAAlXGmjBS3K91C9Q3jm7RK6dCu5vtp+SMZaDKQD+Dwrp42wLoPAt1Od/7XtXkHfvEInTM89+XmeawBmMTyNSkUTEHG4GHRaN5ch6g== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=intel.com; dmarc=pass action=none header.from=intel.com; dkim=pass header.d=intel.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=intel.onmicrosoft.com; s=selector2-intel-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=6kmXhkupfDUN659AkAlfaJSl/7zmJFqL6GoTm2nlQDg=; b=QB5OjfFaya8dOHzwCNWykjXyd6h5XyK9PlN3bvxTEOfstXvYQrEw+yCbZJexKTsVj7NPhWOozu4hPEYqPmVT043aUMRXQK+l+Q1uqV+V5HTKI566+Uj00cl88h+C0TAGrX4JOEKlkv6Z93YIzuYYPkeccYazjOmM6CeY7gs512A= Received: from DM8PR11MB5670.namprd11.prod.outlook.com (2603:10b6:8:37::12) by DM8PR11MB5638.namprd11.prod.outlook.com (2603:10b6:8:27::13) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4373.19; Thu, 5 Aug 2021 11:05:59 +0000 Received: from DM8PR11MB5670.namprd11.prod.outlook.com ([fe80::4e4:c86b:b091:bc26]) by DM8PR11MB5670.namprd11.prod.outlook.com ([fe80::4e4:c86b:b091:bc26%3]) with mapi id 15.20.4373.026; Thu, 5 Aug 2021 11:05:59 +0000 From: "Dumitrescu, Cristian" To: "jerinj@marvell.com" , Thomas Monjalon , "Yigit, Ferruh" , "Andrew Rybchenko" CC: "dev@dpdk.org" , "arybchenko@solarflare.com" , "lizh@nvidia.com" , "ajit.khaparde@broadcom.com" , "Singh, Jasvinder" , "matan@nvidia.com" Thread-Topic: [WARNING: UNSCANNABLE EXTRACTION FAILED][WARNING: UNSCANNABLE EXTRACTION FAILED][dpdk-dev] [PATCH v3] doc: mtr: add API walk through Thread-Index: AQHXieJkCkH6chOlTkiZ/cyCCgymqKtktzYQ Date: Thu, 5 Aug 2021 11:05:59 +0000 Message-ID: References: <20210804113410.3604616-1-jerinj@marvell.com> <20210805101046.4091894-1-jerinj@marvell.com> In-Reply-To: <20210805101046.4091894-1-jerinj@marvell.com> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: dlp-version: 11.5.1.3 dlp-reaction: no-action dlp-product: dlpe-windows authentication-results: marvell.com; dkim=none (message not signed) header.d=none;marvell.com; dmarc=none action=none header.from=intel.com; x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 8157bb6c-c051-4503-d8a9-08d9580101ac x-ms-traffictypediagnostic: DM8PR11MB5638: x-ms-exchange-transport-forked: True x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:10000; x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: QKD/R5DVKb7GMlxKI0ByDqZzrZO9Sn43e7xKPFXr4uHbNvyZnoaH8ShXmRVzyOQvctwImqu3+B8nOMEWsc7FdRnyzQHqHZoi+5LVrE2qRUnOhu9dcT09nycuNpyKiVuMZ5A/1pQg7/FrXvyp/Anu+kA9qqMNXCIEfwtRZVZ5/ifdKXjOZhOJeGbTy+f5jTS48rLp0MGkuyw0FZwoGFXlFpugdkgKUUDOZX7fImnEvDfQVdJM9SqV8TPpq0WmgmdkGafIq/KIhh/07k3JWrL6l6Jk2pwOIfrtoV+f50aMGzYXk/mdr1JMTFuKxBRrYCkkS54KnJW3HviKjpjgMbkue/tWbne2fL0o4mIE1Au1ZQUAaebYWusjBuyr/UpkmTAGsgMnqqn94jegn7FpQtaU9CgdKgQpR7KYS6DdLl8bCCM0yhLlwd1jrd0opeqE3+yVMJiSsfZvfvbTrB5DJHzmP0xCS9+V9lWYGIJ9L3dgIuiWd2wU2rrxdxxZ/rhDFTuRz76bS0DPBVp1enf3YvxAjXVXQJg3ZMnj8XdJcLyHVttPJbl9CIRS6BXXNVulT3zhhhZsdEmM6hAYTy5tcgnRcGuXpX9P0vRQ0AgPKUijl2ZWlMwGJLViuYZcN8sqmMrTrBdxJJycxwKeLIQstnzcc0zpR0551Np8YhCdFGhWhhAcmP7C2gZs+df9/+gZu6R6+E0hUFaxyK87Fhwbc6kNi/2HMSw1nSGWeHbz5Bu0ll/HnP8M7KeAVytuZK49M6v5q09BamtfLQUHdPDG5rasr9a51JHe+TOkAOr0F8Ta60g= x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:DM8PR11MB5670.namprd11.prod.outlook.com; PTR:; CAT:NONE; SFS:(4636009)(396003)(39860400002)(346002)(136003)(366004)(376002)(966005)(52536014)(38070700005)(53546011)(186003)(316002)(478600001)(122000001)(4326008)(66446008)(7696005)(54906003)(66556008)(66946007)(64756008)(83380400001)(76116006)(6506007)(66476007)(110136005)(33656002)(8676002)(9686003)(8936002)(71200400001)(26005)(55016002)(38100700002)(2906002)(86362001)(5660300002); DIR:OUT; SFP:1102; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: =?us-ascii?Q?ax+2Qg3ruFC9rr8OIVCuLIF35sqRCdsIGb/qEdl2DoLegc7dwd3gIBwTnKdC?= =?us-ascii?Q?5qmZo9DErQJ2vbF5k/y8aSBey50e+9SaINuWklYbMVCNwNmgq1+8eZ+VAUbS?= =?us-ascii?Q?P8p8PX6C02nh3TleMPlkjmq9WppKr9LRE0jNRaPcDkJ/4mlmOJHOiNILUiVo?= =?us-ascii?Q?YGXciGyuV+WnKpE8dWTtgkOjk0FbIOfN/GfddQymAFrDLsfhjwiD6HhKPTg3?= =?us-ascii?Q?NTDbV5ZylJDur0gri0v3mCAoOKYMGmdTNIK/QnK7UG4zkndmCt9wjRrKA4hA?= =?us-ascii?Q?6Yg8dflplRPlBy/5TayIMLj4pNlH5U3Wd33VFKg4qf+lG8WjiEbndI9YBC5Y?= =?us-ascii?Q?ZlyTw0nDz+UxN5I/Y5Yc1X9NckVVXOve8fQH0J8PAuFEJoGSO8ROFHHnA6Zd?= =?us-ascii?Q?EQaokOY83Suc8OkRn4cLBH44FE9QRsGqRWP7tXxgzvnJ92+CAhcv++JPGI3P?= =?us-ascii?Q?SYwf1X2YK7hNeyuP1ZHIgnZjdIlJZL2hnXJPAVJM+LpD5w+ho1neKG+hVZaP?= =?us-ascii?Q?mhwV+ed4ceSKRUs11vfgAjYwE+JaYDylDbq6yrcqRSh72c+7Roi672UNTzhG?= =?us-ascii?Q?ntJCsDlPLzlsRphloXzN3vywRnvlgt4QM2faegCOeuQXfindEXPFATJx6hVP?= =?us-ascii?Q?WzbhvnX1MM7yK2O9SBNuEvKcdOTMER4+D/it9NwjRZ7WWueRXCx1LwDF/k47?= =?us-ascii?Q?0lu0zkcjyt+AWlRwOVHSkPsCjnhlsCXb5TWpuq1AHUKAd4rHxI75t7gcP23J?= =?us-ascii?Q?KiXkcpEhMF8fUoGAGXOqSuuTY9yZfKxNvk++7m66b9Ee5r7SWvARTLXwdtbj?= =?us-ascii?Q?a7raP2TZ2mj9SRtYMSD4Z7E3fQQKqwqv8ep6jjFuJ7FSSMWLJOuzpXoWOMsV?= =?us-ascii?Q?wMK9gIDgvkgrE9eV5CeK4DG+XuVQfrhDyKZ8tano4lSPYlYoweOogI8sUBX7?= =?us-ascii?Q?iTyNZLcA3uxEfYgqXWaTGC/2sPjti1vw5Nelr2aOhL87Y4BWUDhf2D9DfxHe?= =?us-ascii?Q?rEK8r9gmPVbECGGYChy10IPUn/3TVQAYKsPeYJyn5ntYmAbXeGoR5C05h2r1?= =?us-ascii?Q?1yqWcH/ntaaeOkUDozIdxnNHw6bf9yfXorZCMR5J0mHX5KEvocaxuF6n2MTt?= =?us-ascii?Q?ncQlbGQGczXfnpaRO9MfXoUHm5t31i8H1Z+DyRnNZxzc6MAusvcVCbZSV91A?= =?us-ascii?Q?bW7pUhLuw4mWaUHeXaexTQdTpa6jrcVrhBFB5bNHXVeD02okumCBaLGJIXb9?= =?us-ascii?Q?lh5l/aYH3Q+fOnN7c7abjzTN5J1FG3dst7QbJvgvV4vd7/uoIu1mdV/FjdbI?= =?us-ascii?Q?fL2WEczN2xYKB2sJJ3YIyE4D?= Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: DM8PR11MB5670.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 8157bb6c-c051-4503-d8a9-08d9580101ac X-MS-Exchange-CrossTenant-originalarrivaltime: 05 Aug 2021 11:05:59.4827 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 46c98d88-e344-4ed4-8496-4ed7712e255d X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: iX80fqn4QlsESCiQSmADefJH8i07FBK9f1Zi47mScDQbqP2esbE2Qt+GlroIWjIE9r1/NZwXcfTtXWyoRt70kLCyZVW5dLouK+Ymdqk2Z1E= X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM8PR11MB5638 X-OriginatorOrg: intel.com Subject: Re: [dpdk-dev] [WARNING: UNSCANNABLE EXTRACTION FAILED][WARNING: UNSCANNABLE EXTRACTION FAILED] [PATCH v3] doc: mtr: add API walk through X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 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" HI Jerin, Thanks for your patch! Initially, it looked like an easy job to review it, but there is actually a= n elephant in the room on how to chain the meters, see below. > -----Original Message----- > From: jerinj@marvell.com > Sent: Thursday, August 5, 2021 11:11 AM > To: Dumitrescu, Cristian ; Thomas Monjalon > ; Yigit, Ferruh ; Andrew > Rybchenko > Cc: dev@dpdk.org; arybchenko@solarflare.com; lizh@nvidia.com; > ajit.khaparde@broadcom.com; Singh, Jasvinder > ; matan@nvidia.com; Jerin Jacob > > Subject: [WARNING: UNSCANNABLE EXTRACTION FAILED][WARNING: > UNSCANNABLE EXTRACTION FAILED][dpdk-dev] [PATCH v3] doc: mtr: add > API walk through >=20 > From: Jerin Jacob >=20 > Added a diagram to document meter library components > and added text for steps performed by the application to > configure the traffic meter and policing library. >=20 > Signed-off-by: Jerin Jacob > --- > v2: Fix long lines in svg file to avoid patch apply issue > v3: Fix all Thomas's comment at > http://patches.dpdk.org/project/dpdk/patch/20210804113410.3604616-1- > jerinj@marvell.com/ >=20 > doc/guides/prog_guide/img/meter.svg | 1600 +++++++++++++++++ > .../traffic_metering_and_policing.rst | 29 + > lib/ethdev/rte_mtr.h | 4 +- > 3 files changed, 1631 insertions(+), 2 deletions(-) > create mode 100644 doc/guides/prog_guide/img/meter.svg >=20 > diff --git a/doc/guides/prog_guide/img/meter.svg > b/doc/guides/prog_guide/img/meter.svg > new file mode 100644 > index 0000000000..7214c5dc2b > --- /dev/null > +++ b/doc/guides/prog_guide/img/meter.svg Just to avoid confusion with the rte_meter API (from the lib/meter library)= , may change the name to rte_mtr_meter_chaining.svg ? > diff --git a/doc/guides/prog_guide/traffic_metering_and_policing.rst > b/doc/guides/prog_guide/traffic_metering_and_policing.rst > index c0537e653c..0fe013522f 100644 > --- a/doc/guides/prog_guide/traffic_metering_and_policing.rst > +++ b/doc/guides/prog_guide/traffic_metering_and_policing.rst > @@ -20,6 +20,7 @@ The main features are: > and RFC 4115 Two Rate Three Color Marker (trTCM) > * Policer actions (per meter output color): recolor, drop > * Statistics (per policer output color) > +* Chaining the meter objects How about: Chaining multiple meter objects. >=20 > Configuration steps > ------------------- > @@ -64,3 +65,31 @@ The processing done for each input packet hitting an > MTR object is: > * Statistics: The set of counters maintained for each MTR object is > configurable and subject to the implementation support. This set inclu= des > the number of packets and bytes dropped or passed for each output colo= r. > + > +API Walk-through > +---------------- > + > +.. figure:: img/meter.* > + > + Meter components > + > +This section will introduce the reader to the critical APIs to use > +the traffic meter and policing library. > + > +In general, the following steps are performed by the application to > configure > +the traffic meter and policing library. > + > +#. Application gets the meter driver capabilities using > ``rte_mtr_capabilities_get()``. > +#. Application identifies the profile(s) needed for metering and creates= it > with > + ``rte_mtr_meter_profile_add()``. How about: The application creates the required meter profiles by using the rte_mtr_m= eter_profile_add() API function. > +#. Application identifies the policies needed and creates it with > ``rte_mtr_meter_policy_add()``. How about: The application creates the required meter policies by using the rte_mtr_m= eter_policy_add() API function. > +#. A meter object consists of a profile and a policy. Use above created > objects to create > + meter object using ``rte_mtr_create()``. Application uses > + ``struct rte_mtr_params::meter_profile_id`` and ``struct > rte_mtr_params::meter_policy_id`` > + to specify the profile (created in step 2) and policy (created in ste= p 3). It is mainly the meter object configuration that consists of a profile and = a policy, but not exactly the meter object itself. How about: The application creates a meter object using the rte_mtr_create() API func= tion. One of the previously created meter profile and meter policy are prov= ided as arguments at this step. > +#. Once the meter object is created, the application shall use > ``rte_flow_create()`` API to > + instantiate the meter object using ``RTE_FLOW_ACTION_TYPE_METER`` > action. The instantiate word might not be the best word here, as it typically indic= ates creating an object as opposed linking it to some other entity. How about: The application enables the meter object execution as part of the flow act= ion processing by calling the rte_flow_create() API function with one of th= e flow action set to ``RTE_FLOW_ACTION_TYPE_METER`` and the associated mete= r object ID set to this meter object. =09 > +#. The API allows chaining the meter objects to create complex metering > topology > + by specifying ``struct rte_mtr_meter_policy_params::actions`` action = as > + ``RTE_FLOW_ACTION_TYPE_METER`` to the parent meter object encoded > as > + ``struct rte_flow_action_meter::mtr_id``. Now this could be the elephant in the room: With the latest API changes that went in recently, the rte_mtr API now allo= ws for a list of (any) rte_flow actions to be specified per color for each = meter object, which opens up the door for a meter action to call one (or mo= re) subsequent meter actions (on the same or different meter objects) condi= tional of a specific color. Which is another (new) way to chain meters, rig= ht? Let's refer to this as the Meter Chaining - Approach B. Before these API changes, the only way to chain meters was by specifying mu= ltiple meter actions (action on the same or different meter object) for the= same rte_flow. Let's refer to this as the Meter Chaining - Approach A. The Meter Chaining - Approach A is valid. After a bit of thinking, I don't = see any reason to invalidate the approach you describe, so I agree that Met= er Chaining - Approach B is also valid, with the (small) advantage that is = conditional of a specific color. So, I think we should describe here both approaches. How about adding a new= distinct section for Meter Chaining, where we describe both approaches as = valid? It would be great if you could have a separate diagram for each appr= oach :) > diff --git a/lib/ethdev/rte_mtr.h b/lib/ethdev/rte_mtr.h > index dc246dd7af..40df0888c8 100644 > --- a/lib/ethdev/rte_mtr.h > +++ b/lib/ethdev/rte_mtr.h > @@ -219,7 +219,7 @@ struct rte_mtr_meter_policy_params { > * @see enum rte_mtr_stats_type > */ > struct rte_mtr_params { > - /** Meter profile ID. */ > + /** Meter profile ID. @see rte_mtr_meter_profile_add() */ > uint32_t meter_profile_id; >=20 > /** Meter input color in case of MTR object chaining. When non- > zero: if > @@ -259,7 +259,7 @@ struct rte_mtr_params { > */ > uint64_t stats_mask; >=20 > - /** Meter policy ID. */ > + /** Meter policy ID. @see rte_mtr_meter_policy_add() */ > uint32_t meter_policy_id; > }; >=20 > -- > 2.32.0 Thanks again for your contribution! Regards, Cristian