[dpdk-dev] [PATCH v2] ethdev: document RSS default key and types

[Adrien Mazarguil]

On Wed, Nov 07, 2018 at 12:39:24PM +0000, Ophir Munk wrote:
> > -----Original Message-----
> > From: Adrien Mazarguil [mailto:adrien.mazarguil at 6wind.com]
> > Sent: Wednesday, November 07, 2018 11:31 AM
> > To: Ophir Munk <ophirmu at mellanox.com>
> > Cc: Ferruh Yigit <ferruh.yigit at intel.com>; Andrew Rybchenko
> > <arybchenko at solarflare.com>; dev at dpdk.org; Thomas Monjalon
> > <thomas at monjalon.net>; Asaf Penso <asafp at mellanox.com>; Shahaf
> > Shuler <shahafs at mellanox.com>; Olga Shern <olgas at mellanox.com>
> > 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 <ophirmu at mellanox.com>
> > > ---
> > >  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 action validation API.
> For example, in MLX5 key==NULL and key_len==40 is accepted. 
> The combination key==NULL and key_len==0 should always succeeds, however the "must" parameter for RSS default is key==NULL and not key_len==0.

I understand this is how the mlx5 PMD implemented it, but my point is that
it makes more sense API-wise to define key_len == 0 as the trigger for a
default RSS hash key than key == NULL.

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! :)

-- 
Adrien Mazarguil
6WIND