From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from EUR02-HE1-obe.outbound.protection.outlook.com (mail-eopbgr10079.outbound.protection.outlook.com [40.107.1.79]) by dpdk.org (Postfix) with ESMTP id C1FDE1BE0 for ; Wed, 7 Nov 2018 16:13:08 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=Mellanox.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=dIRahF/uw/vNHlW2QwvF6HSeln07js13fK098vY8Id0=; b=OP8ODa0AsPdlZ5lgFfgsBnWNyGcshIyizEJ7UexFXGyRR1MbgIpHsB1mAoaVT+nuRMqcczYMUSUpGEe7bDQ1MyzODHQkP9K6Kh1Vm+NR+WC7zDFQdruV0ExsoHn3w41O6mZm8je3qTAgGiKoOVk/MXYcONMnUFVMzxyb5fT6tV8= Received: from VI1PR0502MB3743.eurprd05.prod.outlook.com (52.134.8.154) by VI1PR0502MB3102.eurprd05.prod.outlook.com (10.175.20.16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.1294.21; Wed, 7 Nov 2018 15:13:07 +0000 Received: from VI1PR0502MB3743.eurprd05.prod.outlook.com ([fe80::84d3:8812:d45c:98e4]) by VI1PR0502MB3743.eurprd05.prod.outlook.com ([fe80::84d3:8812:d45c:98e4%4]) with mapi id 15.20.1294.034; Wed, 7 Nov 2018 15:13:07 +0000 From: Ophir Munk To: Adrien Mazarguil CC: Ferruh Yigit , Andrew Rybchenko , "dev@dpdk.org" , Thomas Monjalon , Asaf Penso , Shahaf Shuler , Olga Shern Thread-Topic: [dpdk-dev] [PATCH v2] ethdev: document RSS default key and types Thread-Index: AQHUdnuTE9UKU0bjB02/QczzO0OvtKVEDEOAgAAxJTCAABurAIAADKLw Date: Wed, 7 Nov 2018 15:13:07 +0000 Message-ID: References: <1541259953-4273-1-git-send-email-ophirmu@mellanox.com> <1541582611-1609-1-git-send-email-ophirmu@mellanox.com> <20181107093109.GG4638@6wind.com> <20181107140604.GL4638@6wind.com> In-Reply-To: <20181107140604.GL4638@6wind.com> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: authentication-results: spf=none (sender IP is ) smtp.mailfrom=ophirmu@mellanox.com; x-originating-ip: [193.47.165.251] x-ms-publictraffictype: Email x-microsoft-exchange-diagnostics: 1; VI1PR0502MB3102; 6:rf6P2sjbM1CDka0UyELhzEPjff5CQ39NRlxz7QTXA5MF0LchhDHC7Y8xGStBC1EzyE1uIKknRijTKoD5LqFFEJbiaKZe+xfEaF5Ith/F4PnyqZgPCJX3XUdHsTgtBGlFY0cSTTnREtuECRm2D7yrI2WwBMJfBkJbgnUlDCOsvaBlXDIydbQvPk0Dm4gwhCNi5GQbfDu4C/yiaIMyXsN46iLm4GuYprlmW6qE9IbpY3lKGNvsznujr6SUVc/FpD/xgg6LsoQTKduibf2HBydjO4Jh6iakFD/QZBHYkt5Tk6FBwTmBkx4uVO8WyixK+vk/Xk6Vrpr1ReSkauJwZ7gw94eidGOXr4ucczDG7EsgH4YcvHNLZdy+Q+ZZVllILJQI/wlv48gwXCydVSzrglys7kCv/heupFofp1DblPwj4ZHiWEc+U/tuKmM+Xd3J1lIxveMekRDOtq9T80cMag/Crg==; 5:TVOVBL97up87xYJoBtUKXyTNpjBmLpd56H+zEFYYbHooPnN/i4sSZSC6sq91TuIHi2vaYBsJjRot/iRr0B/I6TCjK5q131zNY2/FSllKFzDfR5z9oSRqyNxWBzZ8UE41VigZ2dk8QBn6QOYWckgrPhPV5uiemd92QJCzwAPAo/o=; 7:W8N0wnhWHOwDkRzTARxfjp0tgKQYYeMfkzkp57Z87zEClxkqrMJZFdjhb11lspa0plGueEZnihSK3kEMiRBmBuomxi9+7rEOQYCjnojcUKH4GAAu8cXRok6HYQLZkPKjXBF2PlF8GJ/ieKls8ZK9YQ== x-ms-exchange-antispam-srfa-diagnostics: SOS; x-ms-office365-filtering-correlation-id: 5f9a9e15-0dc7-4772-2d71-08d644c385bd x-ms-office365-filtering-ht: Tenant x-microsoft-antispam: BCL:0; PCL:0; RULEID:(7020095)(4652040)(8989299)(5600074)(711020)(4618075)(4534185)(4627221)(201703031133081)(201702281549075)(8990200)(2017052603328)(7153060)(7193020); SRVR:VI1PR0502MB3102; x-ms-traffictypediagnostic: VI1PR0502MB3102: x-ld-processed: a652971c-7d2e-4d9b-a6a4-d149256f461b,ExtAddr x-microsoft-antispam-prvs: x-exchange-antispam-report-test: UriScan:(278428928389397)(228905959029699); x-ms-exchange-senderadcheck: 1 x-exchange-antispam-report-cfa-test: BCL:0; PCL:0; RULEID:(8211001083)(6040522)(2401047)(8121501046)(5005006)(10201501046)(3002001)(93006095)(93001095)(3231382)(944501410)(52105095)(6055026)(148016)(149066)(150057)(6041310)(20161123558120)(20161123562045)(20161123564045)(20161123560045)(201703131423095)(201702281528075)(20161123555045)(201703061421075)(201703061406153)(201708071742011)(7699051)(76991095); SRVR:VI1PR0502MB3102; BCL:0; PCL:0; RULEID:; SRVR:VI1PR0502MB3102; x-forefront-prvs: 08497C3D99 x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(396003)(346002)(376002)(366004)(39860400002)(136003)(199004)(189003)(13464003)(11346002)(86362001)(186003)(476003)(66066001)(26005)(105586002)(106356001)(4326008)(486006)(6246003)(2900100001)(575784001)(256004)(2906002)(68736007)(76176011)(97736004)(107886003)(53546011)(6506007)(446003)(5660300001)(7696005)(9686003)(316002)(53936002)(55016002)(54906003)(33656002)(99286004)(6436002)(14454004)(74316002)(478600001)(7736002)(305945005)(81156014)(81166006)(229853002)(93886005)(6116002)(71190400001)(71200400001)(3846002)(8676002)(8936002)(102836004)(25786009)(6916009); DIR:OUT; SFP:1101; SCL:1; SRVR:VI1PR0502MB3102; H:VI1PR0502MB3743.eurprd05.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; A:1; MX:1; received-spf: None (protection.outlook.com: mellanox.com does not designate permitted sender hosts) x-microsoft-antispam-message-info: N2mDpeic8NuRCrWRThXuhFm3Z/ZMKlq3lZsZaoQ5npPaSHJQBq7v2F3ji0wcr58C2G8i+xGlMlqlbThEB0Unu/3tQyLYZTRFagZ2Bwvd3bICVq6+53emZcJDBjXEeXxKTLvsh3ZugwFkiExmw2nkaH4wV3Xr7lYPFixrm64mSJpQU1Y/fgR29H1tFZhghusNUTFcvA4PKboJeA6/nC6awFPyFI/ZILPIIl9P+W9uuPGu19BP/dIxDDmfrxAjJUvREej1NxiwC0d1CFTnekJjt8yQaZQLYzKbx71q+zPTMvFbYG5F0BPqS9s6Pdbivx+PeM5Dcghn4vUs3RtV1I+bbw5iXqREqaR3khZVQo3O7II= spamdiagnosticoutput: 1:99 spamdiagnosticmetadata: NSPM Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-OriginatorOrg: Mellanox.com X-MS-Exchange-CrossTenant-Network-Message-Id: 5f9a9e15-0dc7-4772-2d71-08d644c385bd X-MS-Exchange-CrossTenant-originalarrivaltime: 07 Nov 2018 15:13:07.1489 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: a652971c-7d2e-4d9b-a6a4-d149256f461b X-MS-Exchange-Transport-CrossTenantHeadersStamped: VI1PR0502MB3102 Subject: Re: [dpdk-dev] [PATCH v2] ethdev: document RSS default key and types 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: , X-List-Received-Date: Wed, 07 Nov 2018 15:13:09 -0000 > -----Original Message----- > From: Adrien Mazarguil [mailto:adrien.mazarguil@6wind.com] > Sent: Wednesday, November 07, 2018 4:06 PM > To: Ophir Munk > Cc: Ferruh Yigit ; Andrew Rybchenko > ; dev@dpdk.org; Thomas Monjalon > ; Asaf Penso ; Shahaf > Shuler ; Olga Shern > Subject: Re: [dpdk-dev] [PATCH v2] ethdev: document RSS default key and > types >=20 > On Wed, Nov 07, 2018 at 12:39:24PM +0000, Ophir Munk wrote: > > > -----Original Message----- > > > From: Adrien Mazarguil [mailto:adrien.mazarguil@6wind.com] > > > Sent: Wednesday, November 07, 2018 11:31 AM > > > To: Ophir Munk > > > Cc: Ferruh Yigit ; Andrew Rybchenko > > > ; dev@dpdk.org; Thomas Monjalon > > > ; Asaf Penso ; Shahaf > > > Shuler ; Olga Shern > > > Subject: Re: [dpdk-dev] [PATCH v2] ethdev: document RSS default key > > > and types > > > > > > On Wed, Nov 07, 2018 at 09:23:42AM +0000, Ophir Munk wrote: > > > > struct rte_flow_action_rss include fields 'key' and 'types'. > > > > Field 'key' is a pointer to bytes array (uint8_t *) which contains > > > > the specific RSS hash key. > > > > If an application is only interested in default RSS operation it > > > > should not care about the specific hash key. The application can > > > > set the hash key to NULL such that any PMD uses its default RSS key= . > > > > > > > > Field 'types' is a uint64_t bits flag used to specify a specific > > > > RSS hash type such as ETH_RSS_IP (see ETH_RSS_*). > > > > If an application does not care about the specific RSS type it can > > > > set this field to 0 such that any PMD uses its default type. > > > > > > > > Signed-off-by: Ophir Munk > > > > --- > > > > lib/librte_ethdev/rte_flow.h | 9 +++++++-- > > > > 1 file changed, 7 insertions(+), 2 deletions(-) > > > > > > > > diff --git a/lib/librte_ethdev/rte_flow.h > > > > b/lib/librte_ethdev/rte_flow.h index c0fe879..ca9e135 100644 > > > > --- a/lib/librte_ethdev/rte_flow.h > > > > +++ b/lib/librte_ethdev/rte_flow.h > > > > @@ -1782,10 +1782,15 @@ struct rte_flow_action_rss { > > > > * through. > > > > */ > > > > uint32_t level; > > > > - uint64_t types; /**< Specific RSS hash types (see ETH_RSS_*). */ > > > > + /** > > > > + * Specific RSS hash types (see ETH_RSS_*), > > > > + * or 0 for PMD specific default. > > > > + */ > > > > + uint64_t types; > > > > uint32_t key_len; /**< Hash key length in bytes. */ > > > > uint32_t queue_num; /**< Number of entries in @p queue. */ > > > > - const uint8_t *key; /**< Hash key. */ > > > > + /** Hash key, or NULL for PMD specific default key. */ > > > > + const uint8_t *key; > > > > > > I'd suggest to document that on key_len instead. If key_len is > > > nonzero, key cannot be NULL anyway. > > > > The decision if a key/len combination is valid is done in the PMD actio= n > validation API. > > For example, in MLX5 key=3D=3DNULL and key_len=3D=3D40 is accepted. > > The combination key=3D=3DNULL and key_len=3D=3D0 should always succeeds= , > however the "must" parameter for RSS default is key=3D=3DNULL and not > key_len=3D=3D0. >=20 > I understand this is how the mlx5 PMD implemented it, but my point is tha= t it > makes more sense API-wise to define key_len =3D=3D 0 as the trigger for a= default > RSS hash key than key =3D=3D NULL. >=20 > My suggestion is to follow the same trend as memcpy(), mmap(), snprintf() > and other well-known functions that take a size when dealing with > NULL/undefined pointers. Only size matters! :) >=20 Please let's stay backward compatible and consistent with previous dpdk rel= eases where key=3D=3DNULL is used in struct rte_eth_rss_conf (see code snippet in [1]). We should avoid confusing applications with setting key=3D=3DNULL with lega= cy RSS and key_len=3D=3D0 with rte_flows. With regard to trends APIs - I was thinking about free() where a NULL point= er is acceptable :) [1] File lib/librte_ethdev/rte_ethdev.h: /** * A structure used to configure the Receive Side Scaling (RSS) feature * of an Ethernet port. * If not NULL, the *rss_key* pointer of the *rss_conf* structure points * to an array holding the RSS key to use for hashing specific header * fields of received packets. The length of this array should be indicated * by *rss_key_len* below. Otherwise, a default random hash key is used by * the device driver. * * The *rss_key_len* field of the *rss_conf* structure indicates the length * in bytes of the array pointed by *rss_key*. To be compatible, this lengt= h * will be checked in i40e only. Others assume 40 bytes to be used as befor= e. * * .......... */ struct rte_eth_rss_conf { uint8_t *rss_key; /**< If not NULL, 40-byte hash key. */ uint8_t rss_key_len; /**< hash key length in bytes. */ uint64_t rss_hf; /**< Hash functions to apply - see below. */ }; > -- > Adrien Mazarguil > 6WIND