Re: [dpdk-dev] [PATCH v7 1/5] lib/librte_ether: change function name of tunnel port config

[Thomas Monjalon <thomas.monjalon@6wind.com>]

2016-03-09 00:53, Lu, Wenzhuo:
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> > 2016-03-04 10:35, Wenzhuo Lu:
> > > The names of function for tunnel port configuration are not accurate.
> > > They're tunnel_add/del, better change them to tunnel_port_add/del.
> > 
> > As a lot of ethdev API, it is really badly documented.
> > 
> > Please explain why this renaming and let's try to reword the
> > doxygen:
> >  * Add UDP tunneling port of an Ethernet device for filtering a specific
> >  * tunneling packet by UDP port number.
> 
> As we discussed before, these APIs only change the UDP port value of the tunnel. 
> But according to their names, seems like they're trying to add/delete a whole tunnel.
> The names don't tell us what the functions really do, so we want to change the names.

Neither the comment nor the name explain what means filtering here.
I think we should explain more.
We add a port number and a protocol type. What is it made for?

> > Please what are the values of
> > struct rte_eth_udp_tunnel {
> >     uint16_t udp_port;
> >     uint8_t prot_type;
> > };
> 
> > When I see an API struct without any comment, I feel it must be dropped.
> I'm confused.  I don't do anything about this structure. You want me to add more comments for it?

Yes please, comment at least prot_type. Which values to set?
Any reference to some constants?

> > By the way, it is yet another filtering API, so it must be totally reworked.
> 
> Not quite understand. I only try to change the name. If rework needed, could we do this with a new patch?

I know you are trying to improve the situation :)
I'm just saying that the whole filtering APIs suck and we need to re-think it.
But it's another discussion. Let's improve this one for 16.04 while talking
about future design in other threads.

> > > As it may be an ABI change if change the names directly, the new
> > > functions are added but not remove the old ones. The old ones will be
> > > removed in the next release after an ABI change announcement.
> > 
> > Please make the announce in this patch.
> 
> Sure, I'll do that.

Thanks

> > > --- a/lib/librte_ether/rte_ethdev.h
> > > +++ b/lib/librte_ether/rte_ethdev.h
> > > @@ -3403,6 +3415,9 @@ rte_eth_dev_rss_hash_conf_get(uint8_t port_id,
> > > int  rte_eth_dev_udp_tunnel_add(uint8_t port_id,
> > >  			   struct rte_eth_udp_tunnel *tunnel_udp);
> > 
> > You must deprecate this one and put a comment above with something like
> > @see rte_eth_dev_udp_tunnel_port_add.
> I'll add this. Thanks.
> 
> > 
> > > +int
> > > +rte_eth_dev_udp_tunnel_port_add(uint8_t port_id,
> > > +				struct rte_eth_udp_tunnel *tunnel_udp);
> > 
> > You must move it below the doxygen comment.
> OK. Honestly, I'd like to act like that. But seems the style is to put the function above the comment.(Don't know the reason.)

Do you mean the function below the comment?

> It'll be a little strange if I do something different.

Just check the doxygen output.
We must have the comments associated with the new function
and a deprecation comment with the old one.

> > > --- a/lib/librte_ether/rte_ether_version.map
> > > +++ b/lib/librte_ether/rte_ether_version.map
> > > @@ -114,6 +114,8 @@ DPDK_2.2 {
> > >  	rte_eth_tx_queue_setup;
> > >  	rte_eth_xstats_get;
> > >  	rte_eth_xstats_reset;
> > > +	rte_eth_dev_udp_tunnel_port_add;
> > > +	rte_eth_dev_udp_tunnel_port_delete;
> > >
> > >  	local: *;
> > >  };
> > 
> > Panu already made a comment about adding a new section for 16.04.
> 
> Thanks for the info. Let me follow it.