[dpdk-dev] [PATCH 0/4] ethdev/eal API fixes

[dpdk-dev] [PATCH 0/4] ethdev/eal API fixes

[Thomas Monjalon]

The main change of these patches is to improve naming consistency
across ethdev and EAL.
It should be applied shortly to be part of rc1. If some comments arise,
it can be fixed/improved in rc2.

Thomas Monjalon (4):
  doc: rename ABI chapter to deprecation
  pci: fix detach and uninit naming
  ethdev: refactor port release
  ethdev: fix doxygen internal comments

 MAINTAINERS                                       |  2 +-
 doc/guides/rel_notes/{abi.rst => deprecation.rst} | 19 ++++++++-----------
 doc/guides/rel_notes/index.rst                    |  2 +-
 lib/librte_eal/bsdapp/eal/rte_eal_version.map     |  2 ++
 lib/librte_eal/common/eal_common_pci.c            | 20 ++++++++++++--------
 lib/librte_eal/common/include/rte_pci.h           |  6 ++++--
 lib/librte_eal/linuxapp/eal/rte_eal_version.map   |  2 ++
 lib/librte_ether/rte_ethdev.c                     | 11 +++++------
 lib/librte_ether/rte_ethdev.h                     |  9 ++++-----
 9 files changed, 39 insertions(+), 34 deletions(-)
 rename doc/guides/rel_notes/{abi.rst => deprecation.rst} (51%)

-- 
2.4.2

[dpdk-dev] [PATCH 1/4] doc: rename ABI chapter to deprecation

[Thomas Monjalon]

This chapter is for ABI and API. That's why a renaming is required.

Remove also the examples which are now in the referenced guidelines.

Signed-off-by: Thomas Monjalon <thomas.monjalon@6wind.com>
---
 MAINTAINERS                                       |  2 +-
 doc/guides/rel_notes/{abi.rst => deprecation.rst} | 16 +++++-----------
 doc/guides/rel_notes/index.rst                    |  2 +-
 3 files changed, 7 insertions(+), 13 deletions(-)
 rename doc/guides/rel_notes/{abi.rst => deprecation.rst} (51%)

diff --git a/MAINTAINERS b/MAINTAINERS
index 2a32659..6531900 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -60,7 +60,7 @@ F: doc/guides/prog_guide/ext_app_lib_make_help.rst
 ABI versioning
 M: Neil Horman <nhorman@tuxdriver.com>
 F: lib/librte_compat/
-F: doc/guides/rel_notes/abi.rst
+F: doc/guides/rel_notes/deprecation.rst
 F: scripts/validate-abi.sh
 
 
diff --git a/doc/guides/rel_notes/abi.rst b/doc/guides/rel_notes/deprecation.rst
similarity index 51%
rename from doc/guides/rel_notes/abi.rst
rename to doc/guides/rel_notes/deprecation.rst
index 7a08830..eef01f1 100644
--- a/doc/guides/rel_notes/abi.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -1,17 +1,11 @@
-ABI policy
-==========
+Deprecation
+===========
 
 See the :doc:`guidelines document for details of the ABI policy </guidelines/versioning>`.
-ABI deprecation notices are to be posted here.
+API and ABI deprecation notices are to be posted here.
 
-
-Examples of Deprecation Notices
--------------------------------
-
-* The Macro #RTE_FOO is deprecated and will be removed with version 2.0, to be replaced with the inline function rte_bar()
-* The function rte_mbuf_grok has been updated to include new parameter in version 2.0.  Backwards compatibility will be maintained for this function until the release of version 2.1
-* The members struct foo have been reorganized in release 2.0.  Existing binary applications will have backwards compatibility in release 2.0, while newly built binaries will need to reference new structure variant struct foo2.  Compatibility will be removed in release 2.2, and all applications will require updating and rebuilding to the new structure at that time, which will be renamed to the original struct foo.
-* Significant ABI changes are planned for the librte_dostuff library.  The upcoming release 2.0 will not contain these changes, but release 2.1 will, and no backwards compatibility is planned due to the invasive nature of these changes.  Binaries using this library built prior to version 2.1 will require updating and recompilation.
+Help to update from a previous release is provided in
+:doc:`another section </rel_notes/updating_apps>`.
 
 
 Deprecation Notices
diff --git a/doc/guides/rel_notes/index.rst b/doc/guides/rel_notes/index.rst
index d790783..9d66cd8 100644
--- a/doc/guides/rel_notes/index.rst
+++ b/doc/guides/rel_notes/index.rst
@@ -48,5 +48,5 @@ Contents
     updating_apps
     known_issues
     resolved_issues
-    abi
+    deprecation
     faq
-- 
2.4.2

[dpdk-dev] [PATCH 2/4] pci: fix detach and uninit naming

[Thomas Monjalon]

There are close and detach functions in ethdev.
To keep a consistent naming, PCI functions called by ethdev detach
must be named "detach" instead of "close".
Fix also comments which mix close and uninit names.

Signed-off-by: Thomas Monjalon <thomas.monjalon@6wind.com>
---
 doc/guides/rel_notes/deprecation.rst            |  3 +++
 lib/librte_eal/bsdapp/eal/rte_eal_version.map   |  2 ++
 lib/librte_eal/common/eal_common_pci.c          | 20 ++++++++++++--------
 lib/librte_eal/common/include/rte_pci.h         |  6 ++++--
 lib/librte_eal/linuxapp/eal/rte_eal_version.map |  2 ++
 lib/librte_ether/rte_ethdev.c                   |  6 +++---
 6 files changed, 26 insertions(+), 13 deletions(-)

diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index eef01f1..5330d3b 100644
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -16,6 +16,9 @@ Deprecation Notices
   There is no backward compatibility planned from release 2.2.
   All binaries will need to be rebuilt from release 2.2.
 
+* The EAL function rte_eal_pci_close_one is deprecated because renamed to
+  rte_eal_pci_detach.
+
 * The Macros RTE_HASH_BUCKET_ENTRIES_MAX and RTE_HASH_KEY_LENGTH_MAX are
   deprecated and will be removed with version 2.2.
 
diff --git a/lib/librte_eal/bsdapp/eal/rte_eal_version.map b/lib/librte_eal/bsdapp/eal/rte_eal_version.map
index e537b42..b2d4441 100644
--- a/lib/librte_eal/bsdapp/eal/rte_eal_version.map
+++ b/lib/librte_eal/bsdapp/eal/rte_eal_version.map
@@ -115,5 +115,7 @@ DPDK_2.0 {
 DPDK_2.1 {
 	global:
 
+	rte_eal_pci_detach;
 	rte_memzone_free;
+
 } DPDK_2.0;
diff --git a/lib/librte_eal/common/eal_common_pci.c b/lib/librte_eal/common/eal_common_pci.c
index 60e40e0..16e8629 100644
--- a/lib/librte_eal/common/eal_common_pci.c
+++ b/lib/librte_eal/common/eal_common_pci.c
@@ -213,7 +213,7 @@ rte_eal_pci_probe_one_driver(struct rte_pci_driver *dr, struct rte_pci_device *d
  * driver.
  */
 static int
-rte_eal_pci_close_one_driver(struct rte_pci_driver *dr,
+rte_eal_pci_detach_dev(struct rte_pci_driver *dr,
 		struct rte_pci_device *dev)
 {
 	const struct rte_pci_id *id_table;
@@ -246,7 +246,6 @@ rte_eal_pci_close_one_driver(struct rte_pci_driver *dr,
 		RTE_LOG(DEBUG, EAL, "  remove driver: %x:%x %s\n", dev->id.vendor_id,
 				dev->id.device_id, dr->name);
 
-		/* call the driver devuninit() function */
 		if (dr->devuninit && (dr->devuninit(dev) < 0))
 			return -1;	/* negative value is an error */
 
@@ -297,7 +296,7 @@ pci_probe_all_drivers(struct rte_pci_device *dev)
  * failed, return 1 if no driver is found for this device.
  */
 static int
-pci_close_all_drivers(struct rte_pci_device *dev)
+pci_detach_all_drivers(struct rte_pci_device *dev)
 {
 	struct rte_pci_driver *dr = NULL;
 	int rc = 0;
@@ -306,7 +305,7 @@ pci_close_all_drivers(struct rte_pci_device *dev)
 		return -1;
 
 	TAILQ_FOREACH(dr, &pci_driver_list, next) {
-		rc = rte_eal_pci_close_one_driver(dr, dev);
+		rc = rte_eal_pci_detach_dev(dr, dev);
 		if (rc < 0)
 			/* negative value is an error */
 			return -1;
@@ -349,12 +348,17 @@ err_return:
 	return -1;
 }
 
+int __attribute__ ((deprecated))
+rte_eal_pci_close_one(const struct rte_pci_addr *addr)
+{
+	return rte_eal_pci_detach(addr);
+}
+
 /*
- * Find the pci device specified by pci address, then invoke close function of
- * the driver of the devive.
+ * Detach device specified by its pci address.
  */
 int
-rte_eal_pci_close_one(const struct rte_pci_addr *addr)
+rte_eal_pci_detach(const struct rte_pci_addr *addr)
 {
 	struct rte_pci_device *dev = NULL;
 	int ret = 0;
@@ -366,7 +370,7 @@ rte_eal_pci_close_one(const struct rte_pci_addr *addr)
 		if (rte_eal_compare_pci_addr(&dev->addr, addr))
 			continue;
 
-		ret = pci_close_all_drivers(dev);
+		ret = pci_detach_all_drivers(dev);
 		if (ret < 0)
 			goto err_return;
 
diff --git a/lib/librte_eal/common/include/rte_pci.h b/lib/librte_eal/common/include/rte_pci.h
index e96f389..e3ca3fc 100644
--- a/lib/librte_eal/common/include/rte_pci.h
+++ b/lib/librte_eal/common/include/rte_pci.h
@@ -416,7 +416,7 @@ int rte_eal_pci_probe_one(const struct rte_pci_addr *addr);
  * Close the single PCI device.
  *
  * Scan the content of the PCI bus, and find the pci device specified by pci
- * address, then call the close() function for registered driver that has a
+ * address, then call the devuninit() function for registered driver that has a
  * matching entry in its id_table for discovered device.
  *
  * @param addr
@@ -425,7 +425,9 @@ int rte_eal_pci_probe_one(const struct rte_pci_addr *addr);
  *   - 0 on success.
  *   - Negative on error.
  */
-int rte_eal_pci_close_one(const struct rte_pci_addr *addr);
+int rte_eal_pci_detach(const struct rte_pci_addr *addr);
+int __attribute__ ((deprecated))
+rte_eal_pci_close_one(const struct rte_pci_addr *addr);
 
 /**
  * Dump the content of the PCI bus.
diff --git a/lib/librte_eal/linuxapp/eal/rte_eal_version.map b/lib/librte_eal/linuxapp/eal/rte_eal_version.map
index e537b42..b2d4441 100644
--- a/lib/librte_eal/linuxapp/eal/rte_eal_version.map
+++ b/lib/librte_eal/linuxapp/eal/rte_eal_version.map
@@ -115,5 +115,7 @@ DPDK_2.0 {
 DPDK_2.1 {
 	global:
 
+	rte_eal_pci_detach;
 	rte_memzone_free;
+
 } DPDK_2.0;
diff --git a/lib/librte_ether/rte_ethdev.c b/lib/librte_ether/rte_ethdev.c
index 57f841e..9596047 100644
--- a/lib/librte_ether/rte_ethdev.c
+++ b/lib/librte_ether/rte_ethdev.c
@@ -584,9 +584,9 @@ rte_eth_dev_detach_pdev(uint8_t port_id, struct rte_pci_addr *addr)
 	if (rte_eal_compare_pci_addr(&vp, &freed_addr) == 0)
 		goto err;
 
-	/* invoke close func of the driver,
+	/* invoke devuninit func of the pci driver,
 	 * also remove the device from pci_device_list */
-	if (rte_eal_pci_close_one(&freed_addr))
+	if (rte_eal_pci_detach(&freed_addr))
 		goto err;
 
 	*addr = freed_addr;
@@ -656,7 +656,7 @@ rte_eth_dev_detach_vdev(uint8_t port_id, char *vdevname)
 	if (rte_eth_dev_get_name_by_port(port_id, name))
 		goto err;
 	/* walk around dev_driver_list to find the driver of the device,
-	 * then invoke close function o the driver */
+	 * then invoke uninit function of the driver */
 	if (rte_eal_vdev_uninit(name))
 		goto err;
 
-- 
2.4.2

[dpdk-dev] [PATCH 3/4] ethdev: refactor port release

[Thomas Monjalon]

Use DEV_DETACHED constant and deduplicate code in init.

Signed-off-by: Thomas Monjalon <thomas.monjalon@6wind.com>
---
 lib/librte_ether/rte_ethdev.c | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/lib/librte_ether/rte_ethdev.c b/lib/librte_ether/rte_ethdev.c
index 9596047..d00d104 100644
--- a/lib/librte_ether/rte_ethdev.c
+++ b/lib/librte_ether/rte_ethdev.c
@@ -287,7 +287,7 @@ rte_eth_dev_release_port(struct rte_eth_dev *eth_dev)
 	if (eth_dev == NULL)
 		return -EINVAL;
 
-	eth_dev->attached = 0;
+	eth_dev->attached = DEV_DETACHED;
 	nb_ports--;
 	return 0;
 }
@@ -342,8 +342,7 @@ rte_eth_dev_init(struct rte_pci_driver *pci_drv,
 			(unsigned) pci_dev->id.device_id);
 	if (rte_eal_process_type() == RTE_PROC_PRIMARY)
 		rte_free(eth_dev->data->dev_private);
-	eth_dev->attached = DEV_DETACHED;
-	nb_ports--;
+	rte_eth_dev_release_port(eth_dev);
 	return diag;
 }
 
-- 
2.4.2

[dpdk-dev] [PATCH 4/4] ethdev: fix doxygen internal comments

[Thomas Monjalon]

The internal functions must be marked with the doxygen command @internal.

The allocate and release_port functions are not restricted only to dummy
drivers.

Signed-off-by: Thomas Monjalon <thomas.monjalon@6wind.com>
---
 lib/librte_ether/rte_ethdev.h | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/lib/librte_ether/rte_ethdev.h b/lib/librte_ether/rte_ethdev.h
index 8f1cf8d..8b04edc 100644
--- a/lib/librte_ether/rte_ethdev.h
+++ b/lib/librte_ether/rte_ethdev.h
@@ -1646,8 +1646,9 @@ extern struct rte_eth_dev rte_eth_devices[];
 extern uint8_t rte_eth_dev_count(void);
 
 /**
- * Function for internal use by port hotplug functions.
+ * @internal
  * Returns a ethdev slot specified by the unique identifier name.
+ *
  * @param	name
  *  The pointer to the Unique identifier name for each Ethernet device
  * @return
@@ -1656,8 +1657,7 @@ extern uint8_t rte_eth_dev_count(void);
 extern struct rte_eth_dev *rte_eth_dev_allocated(const char *name);
 
 /**
- * Function for internal use by dummy drivers primarily, e.g. ring-based
- * driver.
+ * @internal
  * Allocates a new ethdev slot for an ethernet device and returns the pointer
  * to that slot for the driver to use.
  *
@@ -1670,8 +1670,7 @@ struct rte_eth_dev *rte_eth_dev_allocate(const char *name,
 		enum rte_eth_dev_type type);
 
 /**
- * Function for internal use by dummy drivers primarily, e.g. ring-based
- * driver.
+ * @internal
  * Release the specified ethdev port.
  *
  * @param eth_dev
-- 
2.4.2

Re: [dpdk-dev] [PATCH 0/4] ethdev/eal API fixes

[Thomas Monjalon]

2015-07-19 12:52, Thomas Monjalon:
> The main change of these patches is to improve naming consistency
> across ethdev and EAL.
> It should be applied shortly to be part of rc1. If some comments arise,
> it can be fixed/improved in rc2.
> 
> Thomas Monjalon (4):
>   doc: rename ABI chapter to deprecation
>   pci: fix detach and uninit naming
>   ethdev: refactor port release
>   ethdev: fix doxygen internal comments

Applied, do not hesitate to comment if something must be fixed.

Re: [dpdk-dev] [PATCH 0/4] ethdev/eal API fixes

[Neil Horman]

On Sun, Jul 19, 2015 at 12:52:13PM +0200, Thomas Monjalon wrote:
> The main change of these patches is to improve naming consistency
> across ethdev and EAL.
> It should be applied shortly to be part of rc1. If some comments arise,
> it can be fixed/improved in rc2.
> 
> Thomas Monjalon (4):
>   doc: rename ABI chapter to deprecation
>   pci: fix detach and uninit naming
>   ethdev: refactor port release
>   ethdev: fix doxygen internal comments
> 
>  MAINTAINERS                                       |  2 +-
>  doc/guides/rel_notes/{abi.rst => deprecation.rst} | 19 ++++++++-----------
>  doc/guides/rel_notes/index.rst                    |  2 +-
>  lib/librte_eal/bsdapp/eal/rte_eal_version.map     |  2 ++
>  lib/librte_eal/common/eal_common_pci.c            | 20 ++++++++++++--------
>  lib/librte_eal/common/include/rte_pci.h           |  6 ++++--
>  lib/librte_eal/linuxapp/eal/rte_eal_version.map   |  2 ++
>  lib/librte_ether/rte_ethdev.c                     | 11 +++++------
>  lib/librte_ether/rte_ethdev.h                     |  9 ++++-----
>  9 files changed, 39 insertions(+), 34 deletions(-)
>  rename doc/guides/rel_notes/{abi.rst => deprecation.rst} (51%)
> 
> -- 
> 2.4.2
> 
> 

Series
Acked-by: Neil Horman <nhorman@tuxdriver.com>

Re: [dpdk-dev] [PATCH 1/4] doc: rename ABI chapter to deprecation

[Dumitrescu, Cristian]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Thomas Monjalon
> Sent: Sunday, July 19, 2015 11:52 AM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH 1/4] doc: rename ABI chapter to deprecation
> 
> This chapter is for ABI and API. That's why a renaming is required.
> 
> Remove also the examples which are now in the referenced guidelines.
> 
> Signed-off-by: Thomas Monjalon <thomas.monjalon@6wind.com>
> ---
>  MAINTAINERS                                       |  2 +-
>  doc/guides/rel_notes/{abi.rst => deprecation.rst} | 16 +++++-----------
>  doc/guides/rel_notes/index.rst                    |  2 +-
>  3 files changed, 7 insertions(+), 13 deletions(-)
>  rename doc/guides/rel_notes/{abi.rst => deprecation.rst} (51%)
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 2a32659..6531900 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -60,7 +60,7 @@ F: doc/guides/prog_guide/ext_app_lib_make_help.rst
>  ABI versioning
>  M: Neil Horman <nhorman@tuxdriver.com>
>  F: lib/librte_compat/
> -F: doc/guides/rel_notes/abi.rst
> +F: doc/guides/rel_notes/deprecation.rst
>  F: scripts/validate-abi.sh
> 
> 
> diff --git a/doc/guides/rel_notes/abi.rst
> b/doc/guides/rel_notes/deprecation.rst
> similarity index 51%
> rename from doc/guides/rel_notes/abi.rst
> rename to doc/guides/rel_notes/deprecation.rst
> index 7a08830..eef01f1 100644
> --- a/doc/guides/rel_notes/abi.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -1,17 +1,11 @@
> -ABI policy
> -==========
> +Deprecation
> +===========
> 
>  See the :doc:`guidelines document for details of the ABI policy
> </guidelines/versioning>`.
> -ABI deprecation notices are to be posted here.
> +API and ABI deprecation notices are to be posted here.
> 
> -
> -Examples of Deprecation Notices
> --------------------------------
> -
> -* The Macro #RTE_FOO is deprecated and will be removed with version 2.0,
> to be replaced with the inline function rte_bar()
> -* The function rte_mbuf_grok has been updated to include new parameter
> in version 2.0.  Backwards compatibility will be maintained for this function
> until the release of version 2.1
> -* The members struct foo have been reorganized in release 2.0.  Existing
> binary applications will have backwards compatibility in release 2.0, while
> newly built binaries will need to reference new structure variant struct foo2.
> Compatibility will be removed in release 2.2, and all applications will require
> updating and rebuilding to the new structure at that time, which will be
> renamed to the original struct foo.
> -* Significant ABI changes are planned for the librte_dostuff library.  The
> upcoming release 2.0 will not contain these changes, but release 2.1 will, and
> no backwards compatibility is planned due to the invasive nature of these
> changes.  Binaries using this library built prior to version 2.1 will require
> updating and recompilation.
> +Help to update from a previous release is provided in
> +:doc:`another section </rel_notes/updating_apps>`.
> 
> 
>  Deprecation Notices
> diff --git a/doc/guides/rel_notes/index.rst b/doc/guides/rel_notes/index.rst
> index d790783..9d66cd8 100644
> --- a/doc/guides/rel_notes/index.rst
> +++ b/doc/guides/rel_notes/index.rst
> @@ -48,5 +48,5 @@ Contents
>      updating_apps
>      known_issues
>      resolved_issues
> -    abi
> +    deprecation
>      faq
> --
> 2.4.2

Hi Thomas,

There are some pending doc patches on ABI changes that have been sent and ack-ed prior to this change.

Due to this change, they cannot be applied cleanly anymore. Are you OK to integrate them with the small local change required from your side?

Thanks,
Cristian

Re: [dpdk-dev] [PATCH 1/4] doc: rename ABI chapter to deprecation

[Thomas Monjalon]

2015-07-21 13:20, Dumitrescu, Cristian:
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Thomas Monjalon
> > --- a/doc/guides/rel_notes/abi.rst
> > +++ b/doc/guides/rel_notes/deprecation.rst
> 
> There are some pending doc patches on ABI changes that have been sent and ack-ed prior to this change.
> 
> Due to this change, they cannot be applied cleanly anymore.
> Are you OK to integrate them with the small local change required from your side?

Yes it is a basic merge issue that is easily managed locally.

Though, it would be nice to have at least 3 acks on these patches,
as specified in the ABI policy.