DPDK-dev Archive on lore.kernel.org
 help / color / Atom feed
* [dpdk-dev] [PATCH] doc: add deprecation notice to fix ethdev API returning void
@ 2019-07-23 14:07 Andrew Rybchenko
  2019-07-23 14:22 ` Ferruh Yigit
                   ` (2 more replies)
  0 siblings, 3 replies; 7+ messages in thread
From: Andrew Rybchenko @ 2019-07-23 14:07 UTC (permalink / raw)
  To: Thomas Monjalon, Ferruh Yigit; +Cc: dev

void return value is bad for get API (like rte_eth_dev_info-get())
since caller does not know if the function does its job or not and
output value is filled in.

void return value is bad for state changing API (like
rte_eth_promiscuous_enable()) since caller should use get API
to understand if state is really changed.

Signed-off-by: Andrew Rybchenko <arybchenko@solarflare.com>
---
 doc/guides/rel_notes/deprecation.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index 37b8592b6..79689f136 100644
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -59,6 +59,20 @@ Deprecation Notices
   Target release for removal of the legacy API will be defined once most
   PMDs have switched to rte_flow.
 
+* ethdev: update API functions returning ``void`` to return ``int`` with
+  negative errno values to indicate various error conditions (e.g.
+  invalid port ID, unsupported operation, failed operation):
+
+  - ``rte_eth_dev_info_get``
+  - ``rte_eth_promiscuous_enable`` and ``rte_eth_promiscuous_disable``
+  - ``rte_eth_allmulticast_enable`` and ``rte_eth_allmulticast_disable``
+  - ``rte_eth_link_get`` and ``rte_eth_link_get_nowait``
+  - ``rte_eth_dev_stop``
+  - ``rte_eth_dev_close``
+  - ``rte_eth_xstats_reset``
+  - ``rte_eth_macaddr_get``
+  - ``rte_eth_dev_owner_delete``
+
 * cryptodev: support for using IV with all sizes is added, J0 still can
   be used but only when IV length in following structs ``rte_crypto_auth_xform``,
   ``rte_crypto_aead_xform`` is set to zero. When IV length is greater or equal
-- 
2.17.1


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: add deprecation notice to fix ethdev API returning void
  2019-07-23 14:07 [dpdk-dev] [PATCH] doc: add deprecation notice to fix ethdev API returning void Andrew Rybchenko
@ 2019-07-23 14:22 ` Ferruh Yigit
  2019-08-06 11:24   ` Thomas Monjalon
  2019-07-23 14:38 ` Stephen Hemminger
  2019-07-24  9:17 ` Jerin Jacob Kollanukkaran
  2 siblings, 1 reply; 7+ messages in thread
From: Ferruh Yigit @ 2019-07-23 14:22 UTC (permalink / raw)
  To: Andrew Rybchenko, Thomas Monjalon; +Cc: dev

On 7/23/2019 3:07 PM, Andrew Rybchenko wrote:
> void return value is bad for get API (like rte_eth_dev_info-get())
> since caller does not know if the function does its job or not and
> output value is filled in.
> 
> void return value is bad for state changing API (like
> rte_eth_promiscuous_enable()) since caller should use get API
> to understand if state is really changed.
> 
> Signed-off-by: Andrew Rybchenko <arybchenko@solarflare.com>
> ---
>  doc/guides/rel_notes/deprecation.rst | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
> 
> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> index 37b8592b6..79689f136 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -59,6 +59,20 @@ Deprecation Notices
>    Target release for removal of the legacy API will be defined once most
>    PMDs have switched to rte_flow.
>  
> +* ethdev: update API functions returning ``void`` to return ``int`` with
> +  negative errno values to indicate various error conditions (e.g.
> +  invalid port ID, unsupported operation, failed operation):
> +
> +  - ``rte_eth_dev_info_get``
> +  - ``rte_eth_promiscuous_enable`` and ``rte_eth_promiscuous_disable``
> +  - ``rte_eth_allmulticast_enable`` and ``rte_eth_allmulticast_disable``
> +  - ``rte_eth_link_get`` and ``rte_eth_link_get_nowait``
> +  - ``rte_eth_dev_stop``
> +  - ``rte_eth_dev_close``
> +  - ``rte_eth_xstats_reset``
> +  - ``rte_eth_macaddr_get``
> +  - ``rte_eth_dev_owner_delete``
> +
>  * cryptodev: support for using IV with all sizes is added, J0 still can
>    be used but only when IV length in following structs ``rte_crypto_auth_xform``,
>    ``rte_crypto_aead_xform`` is set to zero. When IV length is greater or equal
> 

Acked-by: Ferruh Yigit <ferruh.yigit@intel.com>

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: add deprecation notice to fix ethdev API returning void
  2019-07-23 14:07 [dpdk-dev] [PATCH] doc: add deprecation notice to fix ethdev API returning void Andrew Rybchenko
  2019-07-23 14:22 ` Ferruh Yigit
@ 2019-07-23 14:38 ` Stephen Hemminger
  2019-07-23 14:52   ` Andrew Rybchenko
  2019-07-24  9:17 ` Jerin Jacob Kollanukkaran
  2 siblings, 1 reply; 7+ messages in thread
From: Stephen Hemminger @ 2019-07-23 14:38 UTC (permalink / raw)
  To: Andrew Rybchenko; +Cc: Thomas Monjalon, Ferruh Yigit, dev

On Tue, 23 Jul 2019 15:07:51 +0100
Andrew Rybchenko <arybchenko@solarflare.com> wrote:

> void return value is bad for get API (like rte_eth_dev_info-get())
> since caller does not know if the function does its job or not and
> output value is filled in.
> 
> void return value is bad for state changing API (like
> rte_eth_promiscuous_enable()) since caller should use get API
> to understand if state is really changed.
> 
> Signed-off-by: Andrew Rybchenko <arybchenko@solarflare.com>

In general this is a good ide, but for some API's it is hard
to think of a way it would help. For example:
void return is ok for close routines because if close() returns
an error the application really has no choice about what to do.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: add deprecation notice to fix ethdev API returning void
  2019-07-23 14:38 ` Stephen Hemminger
@ 2019-07-23 14:52   ` Andrew Rybchenko
  0 siblings, 0 replies; 7+ messages in thread
From: Andrew Rybchenko @ 2019-07-23 14:52 UTC (permalink / raw)
  To: Stephen Hemminger; +Cc: Thomas Monjalon, Ferruh Yigit, dev

On 7/23/19 5:38 PM, Stephen Hemminger wrote:
> On Tue, 23 Jul 2019 15:07:51 +0100
> Andrew Rybchenko <arybchenko@solarflare.com> wrote:
> 
>> void return value is bad for get API (like rte_eth_dev_info-get())
>> since caller does not know if the function does its job or not and
>> output value is filled in.
>>
>> void return value is bad for state changing API (like
>> rte_eth_promiscuous_enable()) since caller should use get API
>> to understand if state is really changed.
>>
>> Signed-off-by: Andrew Rybchenko <arybchenko@solarflare.com>
> 
> In general this is a good ide, but for some API's it is hard
> to think of a way it would help. For example:
> void return is ok for close routines because if close() returns
> an error the application really has no choice about what to do.

Yes, I agree. But application can always ignore return value.
Long-long time ago it was a surprise to me that libc close() has
non-void return value.

I intentionally provided everything which makes sense to me to
raise discussion. I was unsure in stop, close and owner delete
functions.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: add deprecation notice to fix ethdev API returning void
  2019-07-23 14:07 [dpdk-dev] [PATCH] doc: add deprecation notice to fix ethdev API returning void Andrew Rybchenko
  2019-07-23 14:22 ` Ferruh Yigit
  2019-07-23 14:38 ` Stephen Hemminger
@ 2019-07-24  9:17 ` Jerin Jacob Kollanukkaran
  2 siblings, 0 replies; 7+ messages in thread
From: Jerin Jacob Kollanukkaran @ 2019-07-24  9:17 UTC (permalink / raw)
  To: Andrew Rybchenko, Thomas Monjalon, Ferruh Yigit; +Cc: dev

> -----Original Message-----
> From: dev <dev-bounces@dpdk.org> On Behalf Of Andrew Rybchenko
> Sent: Tuesday, July 23, 2019 7:38 PM
> To: Thomas Monjalon <thomas@monjalon.net>; Ferruh Yigit
> <ferruh.yigit@intel.com>
> Cc: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH] doc: add deprecation notice to fix ethdev API
> returning void
> 
> void return value is bad for get API (like rte_eth_dev_info-get()) since caller
> does not know if the function does its job or not and output value is filled in.
> 
> void return value is bad for state changing API (like
> rte_eth_promiscuous_enable()) since caller should use get API to
> understand if state is really changed.
> 
> Signed-off-by: Andrew Rybchenko <arybchenko@solarflare.com>

Acked-by: Jerin Jacob <jerinj@marvell.com>

> ---
>  doc/guides/rel_notes/deprecation.rst | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
> 
> diff --git a/doc/guides/rel_notes/deprecation.rst
> b/doc/guides/rel_notes/deprecation.rst
> index 37b8592b6..79689f136 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -59,6 +59,20 @@ Deprecation Notices
>    Target release for removal of the legacy API will be defined once most
>    PMDs have switched to rte_flow.
> 
> +* ethdev: update API functions returning ``void`` to return ``int``
> +with
> +  negative errno values to indicate various error conditions (e.g.
> +  invalid port ID, unsupported operation, failed operation):
> +
> +  - ``rte_eth_dev_info_get``
> +  - ``rte_eth_promiscuous_enable`` and ``rte_eth_promiscuous_disable``
> +  - ``rte_eth_allmulticast_enable`` and
> + ``rte_eth_allmulticast_disable``
> +  - ``rte_eth_link_get`` and ``rte_eth_link_get_nowait``
> +  - ``rte_eth_dev_stop``
> +  - ``rte_eth_dev_close``
> +  - ``rte_eth_xstats_reset``
> +  - ``rte_eth_macaddr_get``
> +  - ``rte_eth_dev_owner_delete``
> +
>  * cryptodev: support for using IV with all sizes is added, J0 still can
>    be used but only when IV length in following structs
> ``rte_crypto_auth_xform``,
>    ``rte_crypto_aead_xform`` is set to zero. When IV length is greater or equal
> --
> 2.17.1


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: add deprecation notice to fix ethdev API returning void
  2019-07-23 14:22 ` Ferruh Yigit
@ 2019-08-06 11:24   ` Thomas Monjalon
  2019-08-10 20:29     ` Thomas Monjalon
  0 siblings, 1 reply; 7+ messages in thread
From: Thomas Monjalon @ 2019-08-06 11:24 UTC (permalink / raw)
  To: Andrew Rybchenko; +Cc: dev, Ferruh Yigit

23/07/2019 16:22, Ferruh Yigit:
> On 7/23/2019 3:07 PM, Andrew Rybchenko wrote:
> > void return value is bad for get API (like rte_eth_dev_info-get())
> > since caller does not know if the function does its job or not and
> > output value is filled in.
> > 
> > void return value is bad for state changing API (like
> > rte_eth_promiscuous_enable()) since caller should use get API
> > to understand if state is really changed.
> > 
> > Signed-off-by: Andrew Rybchenko <arybchenko@solarflare.com>
> > ---
> > +* ethdev: update API functions returning ``void`` to return ``int`` with
> > +  negative errno values to indicate various error conditions (e.g.
> > +  invalid port ID, unsupported operation, failed operation):
> > +
> > +  - ``rte_eth_dev_info_get``
> > +  - ``rte_eth_promiscuous_enable`` and ``rte_eth_promiscuous_disable``
> > +  - ``rte_eth_allmulticast_enable`` and ``rte_eth_allmulticast_disable``
> > +  - ``rte_eth_link_get`` and ``rte_eth_link_get_nowait``
> > +  - ``rte_eth_dev_stop``
> > +  - ``rte_eth_dev_close``
> > +  - ``rte_eth_xstats_reset``
> > +  - ``rte_eth_macaddr_get``
> > +  - ``rte_eth_dev_owner_delete``
> 
> Acked-by: Ferruh Yigit <ferruh.yigit@intel.com>

Acked-by: Thomas Monjalon <thomas@monjalon.net>




^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: add deprecation notice to fix ethdev API returning void
  2019-08-06 11:24   ` Thomas Monjalon
@ 2019-08-10 20:29     ` Thomas Monjalon
  0 siblings, 0 replies; 7+ messages in thread
From: Thomas Monjalon @ 2019-08-10 20:29 UTC (permalink / raw)
  To: Andrew Rybchenko; +Cc: dev, Ferruh Yigit

06/08/2019 13:24, Thomas Monjalon:
> 23/07/2019 16:22, Ferruh Yigit:
> > On 7/23/2019 3:07 PM, Andrew Rybchenko wrote:
> > > void return value is bad for get API (like rte_eth_dev_info-get())
> > > since caller does not know if the function does its job or not and
> > > output value is filled in.
> > > 
> > > void return value is bad for state changing API (like
> > > rte_eth_promiscuous_enable()) since caller should use get API
> > > to understand if state is really changed.
> > > 
> > > Signed-off-by: Andrew Rybchenko <arybchenko@solarflare.com>
> > Acked-by: Ferruh Yigit <ferruh.yigit@intel.com>
> Acked-by: Thomas Monjalon <thomas@monjalon.net>
> Acked-by: Jerin Jacob <jerinj@marvell.com>

Applied, thanks



^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, back to index

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-07-23 14:07 [dpdk-dev] [PATCH] doc: add deprecation notice to fix ethdev API returning void Andrew Rybchenko
2019-07-23 14:22 ` Ferruh Yigit
2019-08-06 11:24   ` Thomas Monjalon
2019-08-10 20:29     ` Thomas Monjalon
2019-07-23 14:38 ` Stephen Hemminger
2019-07-23 14:52   ` Andrew Rybchenko
2019-07-24  9:17 ` Jerin Jacob Kollanukkaran

DPDK-dev Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/dpdk-dev/0 dpdk-dev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dpdk-dev dpdk-dev/ https://lore.kernel.org/dpdk-dev \
		dev@dpdk.org dpdk-dev@archiver.kernel.org
	public-inbox-index dpdk-dev

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.dpdk.dev


AGPL code for this site: git clone https://public-inbox.org/ public-inbox