[dpdk-dev] [PATCH v5 12/20] pci: deprecate misnamed functions

[Gaetan Rivet <gaetan.rivet@6wind.com>]

Rename misnamed functions and describe the change in a deprecation
notice.

Signed-off-by: Gaetan Rivet <gaetan.rivet@6wind.com>
---
 doc/guides/rel_notes/deprecation.rst | 10 ++++++
 lib/librte_pci/include/rte_pci.h     | 63 ++++++++++++++++++++++++++++++++++++
 lib/librte_pci/rte_pci.c             | 26 +++++++++++++++
 lib/librte_pci/rte_pci_version.map   |  4 +++
 4 files changed, 103 insertions(+)

diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index 4e4d97b..ef2264f 100644
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -98,3 +98,13 @@ Deprecation Notices
   The non-"do-sig" versions of the hash tables will be removed
   (including the ``signature_offset`` parameter)
   and the "do-sig" versions renamed accordingly.
+
+* pci: Several exposed functions are misnamed.
+  The following functions are deprecated starting from v17.11 and are replaced:
+
+  - ``eal_parse_pci_BDF`` replaced by ``pci_parse_BDF``
+  - ``eal_parse_pci_DomBDF`` replaced by ``pci_parse_DomBDF``
+  - ``rte_eal_compare_pci_addr`` replaced by ``pci_addr_cmp``
+  - ``rte_pci_device_name`` replaced by ``pci_device_name``
+
+  The functions are only renamed. Their behavior is not affected.
diff --git a/lib/librte_pci/include/rte_pci.h b/lib/librte_pci/include/rte_pci.h
index fe4d411..38cbdb3 100644
--- a/lib/librte_pci/include/rte_pci.h
+++ b/lib/librte_pci/include/rte_pci.h
@@ -135,6 +135,7 @@ struct mapped_pci_resource {
 TAILQ_HEAD(mapped_pci_res_list, mapped_pci_resource);
 
 /**
+ * @deprecated
  * Utility function to produce a PCI Bus-Device-Function value
  * given a string representation. Assumes that the BDF is provided without
  * a domain prefix (i.e. domain returned is always 0)
@@ -151,6 +152,22 @@ int eal_parse_pci_BDF(const char *input, struct rte_pci_addr *dev_addr);
 
 /**
  * Utility function to produce a PCI Bus-Device-Function value
+ * given a string representation. Assumes that the BDF is provided without
+ * a domain prefix (i.e. domain returned is always 0)
+ *
+ * @param input
+ *	The input string to be parsed. Should have the format XX:XX.X
+ * @param dev_addr
+ *	The PCI Bus-Device-Function address to be returned.
+ *	Domain will always be returned as 0
+ * @return
+ *  0 on success, negative on error.
+ */
+int pci_bdf_parse(const char *input, struct rte_pci_addr *dev_addr);
+
+/**
+ * @deprecated
+ * Utility function to produce a PCI Bus-Device-Function value
  * given a string representation. Assumes that the BDF is provided including
  * a domain prefix.
  *
@@ -164,6 +181,21 @@ int eal_parse_pci_BDF(const char *input, struct rte_pci_addr *dev_addr);
 int eal_parse_pci_DomBDF(const char *input, struct rte_pci_addr *dev_addr);
 
 /**
+ * Utility function to produce a PCI Bus-Device-Function value
+ * given a string representation. Assumes that the BDF is provided including
+ * a domain prefix.
+ *
+ * @param input
+ *	The input string to be parsed. Should have the format XXXX:XX:XX.X
+ * @param dev_addr
+ *	The PCI Bus-Device-Function address to be returned
+ * @return
+ *  0 on success, negative on error.
+ */
+int pci_dbdf_parse(const char *input, struct rte_pci_addr *dev_addr);
+
+/**
+ * @deprecated
  * Utility function to write a pci device name, this device name can later be
  * used to retrieve the corresponding rte_pci_addr using eal_parse_pci_*
  * BDF helpers.
@@ -179,6 +211,22 @@ void rte_pci_device_name(const struct rte_pci_addr *addr,
 			 char *output, size_t size);
 
 /**
+ * Utility function to write a pci device name, this device name can later be
+ * used to retrieve the corresponding rte_pci_addr using eal_parse_pci_*
+ * BDF helpers.
+ *
+ * @param addr
+ *	The PCI Bus-Device-Function address
+ * @param output
+ *	The output buffer string
+ * @param size
+ *	The output buffer size
+ */
+void pci_device_name(const struct rte_pci_addr *addr,
+		     char *output, size_t size);
+
+/**
+ * @deprecated
  * Utility function to compare two PCI device addresses.
  *
  * @param addr
@@ -194,6 +242,21 @@ int rte_eal_compare_pci_addr(const struct rte_pci_addr *addr,
 			     const struct rte_pci_addr *addr2);
 
 /**
+ * Utility function to compare two PCI device addresses.
+ *
+ * @param addr
+ *	The PCI Bus-Device-Function address to compare
+ * @param addr2
+ *	The PCI Bus-Device-Function address to compare
+ * @return
+ *	0 on equal PCI address.
+ *	Positive on addr is greater than addr2.
+ *	Negative on addr is less than addr2, or error.
+ */
+int pci_addr_cmp(const struct rte_pci_addr *addr,
+		 const struct rte_pci_addr *addr2);
+
+/**
  * Map a particular resource from a file.
  *
  * @param requested_addr
diff --git a/lib/librte_pci/rte_pci.c b/lib/librte_pci/rte_pci.c
index cbb5359..fc2fc7f 100644
--- a/lib/librte_pci/rte_pci.c
+++ b/lib/librte_pci/rte_pci.c
@@ -73,6 +73,12 @@ get_u8_pciaddr_field(const char *in, void *_u8, char dlm)
 int
 eal_parse_pci_BDF(const char *input, struct rte_pci_addr *dev_addr)
 {
+	return pci_bdf_parse(input, dev_addr);
+}
+
+int
+pci_bdf_parse(const char *input, struct rte_pci_addr *dev_addr)
+{
 	const char *in = input;
 
 	dev_addr->domain = 0;
@@ -91,6 +97,12 @@ eal_parse_pci_BDF(const char *input, struct rte_pci_addr *dev_addr)
 int
 eal_parse_pci_DomBDF(const char *input, struct rte_pci_addr *dev_addr)
 {
+	return pci_dbdf_parse(input, dev_addr);
+}
+
+int
+pci_dbdf_parse(const char *input, struct rte_pci_addr *dev_addr)
+{
 	const char *in = input;
 	unsigned long val;
 	char *end;
@@ -117,6 +129,13 @@ void
 rte_pci_device_name(const struct rte_pci_addr *addr,
 		    char *output, size_t size)
 {
+	pci_device_name(addr, output, size);
+}
+
+void
+pci_device_name(const struct rte_pci_addr *addr,
+		char *output, size_t size)
+{
 	RTE_VERIFY(size >= PCI_PRI_STR_SIZE);
 	RTE_VERIFY(snprintf(output, size, PCI_PRI_FMT,
 			    addr->domain, addr->bus,
@@ -127,6 +146,13 @@ int
 rte_eal_compare_pci_addr(const struct rte_pci_addr *addr,
 			 const struct rte_pci_addr *addr2)
 {
+	return pci_addr_cmp(addr, addr2);
+}
+
+int
+pci_addr_cmp(const struct rte_pci_addr *addr,
+	     const struct rte_pci_addr *addr2)
+{
 	uint64_t dev_addr, dev_addr2;
 
 	if ((addr == NULL) || (addr2 == NULL))
diff --git a/lib/librte_pci/rte_pci_version.map b/lib/librte_pci/rte_pci_version.map
index a940259..8d180e3 100644
--- a/lib/librte_pci/rte_pci_version.map
+++ b/lib/librte_pci/rte_pci_version.map
@@ -3,6 +3,10 @@ DPDK_17.11 {
 
 	eal_parse_pci_BDF;
 	eal_parse_pci_DomBDF;
+	pci_addr_cmp;
+	pci_bdf_parse;
+	pci_dbdf_parse;
+	pci_device_name;
 	pci_map_resource;
 	pci_unmap_resource;
 	rte_eal_compare_pci_addr;
-- 
2.1.4