pci: deprecate misnamed functions

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

Signed-off-by: Gaetan Rivet <gaetan.rivet@6wind.com>

diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index d07f38c..4293014 100644 (file)
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -28,6 +28,15 @@ Deprecation Notices
   The change will be only for the name.
   Functional aspects of the API or data-structure will remain same.
 
+* pci: Several exposed functions are misnamed.
+  The following functions are deprecated starting from v17.11 and are replaced:
+
+  - ``eal_parse_pci_BDF`` replaced by ``rte_pci_bdf_parse``
+  - ``eal_parse_pci_DomBDF`` replaced by ``rte_pci_dbdf_parse``
+  - ``rte_eal_compare_pci_addr`` replaced by ``rte_pci_addr_cmp``
+
+  The functions are only renamed. Their behavior is not affected.
+
 * ethdev: Tx offloads will no longer be enabled by default in 17.11.
   Instead, the ``rte_eth_txmode`` structure will be extended with
   bit field to enable each Tx offload.

diff --git a/lib/librte_eal/common/eal_common_pci.c b/lib/librte_eal/common/eal_common_pci.c
index f896289..2230e09 100644 (file)
--- a/lib/librte_eal/common/eal_common_pci.c
+++ b/lib/librte_eal/common/eal_common_pci.c
@@ -106,7 +106,7 @@ 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)
+rte_pci_bdf_parse(const char *input, struct rte_pci_addr *dev_addr)
 {
        const char *in = input;
 
@@ -124,7 +124,13 @@ 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)
+eal_parse_pci_BDF(const char *input, struct rte_pci_addr *dev_addr)
+{
+       return rte_pci_bdf_parse(input, dev_addr);
+}
+
+int
+rte_pci_dbdf_parse(const char *input, struct rte_pci_addr *dev_addr)
 {
        const char *in = input;
        unsigned long val;
@@ -148,6 +154,12 @@ eal_parse_pci_DomBDF(const char *input, struct rte_pci_addr *dev_addr)
        return 0;
 }
 
+int
+eal_parse_pci_DomBDF(const char *input, struct rte_pci_addr *dev_addr)
+{
+       return rte_pci_dbdf_parse(input, dev_addr);
+}
+
 void
 rte_pci_device_name(const struct rte_pci_addr *addr,
                     char *output, size_t size)
@@ -159,8 +171,8 @@ rte_pci_device_name(const struct rte_pci_addr *addr,
 }
 
 int
-rte_eal_compare_pci_addr(const struct rte_pci_addr *addr,
-                          const struct rte_pci_addr *addr2)
+rte_pci_addr_cmp(const struct rte_pci_addr *addr,
+                const struct rte_pci_addr *addr2)
 {
        uint64_t dev_addr, dev_addr2;
 
@@ -180,6 +192,13 @@ rte_eal_compare_pci_addr(const struct rte_pci_addr *addr,
                 return 0;
 }
 
+int
+rte_eal_compare_pci_addr(const struct rte_pci_addr *addr,
+                          const struct rte_pci_addr *addr2)
+{
+       return rte_pci_addr_cmp(addr, addr2);
+}
+
 void
 pci_name_set(struct rte_pci_device *dev)
 {

diff --git a/lib/librte_eal/common/include/rte_pci.h b/lib/librte_eal/common/include/rte_pci.h
index a366f3f..9ac19d5 100644 (file)
--- a/lib/librte_eal/common/include/rte_pci.h
+++ b/lib/librte_eal/common/include/rte_pci.h
@@ -253,6 +253,22 @@ TAILQ_HEAD(mapped_pci_res_list, mapped_pci_resource);
  * @return
  *  0 on success, negative on error.
  */
+int rte_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 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 eal_parse_pci_BDF(const char *input, struct rte_pci_addr *dev_addr);
 
 /**
@@ -267,6 +283,21 @@ int eal_parse_pci_BDF(const char *input, struct rte_pci_addr *dev_addr);
  * @return
  *  0 on success, negative on error.
  */
+int rte_pci_dbdf_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.
+ *
+ * @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 eal_parse_pci_DomBDF(const char *input, struct rte_pci_addr *dev_addr);
 
 /**
@@ -296,6 +327,22 @@ void rte_pci_device_name(const struct rte_pci_addr *addr, char *output,
  *     Positive on addr is greater than addr2.
  *     Negative on addr is less than addr2, or error.
  */
+int rte_pci_addr_cmp(const struct rte_pci_addr *addr,
+                    const struct rte_pci_addr *addr2);
+
+/**
+ * @deprecated
+ * 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 rte_eal_compare_pci_addr(const struct rte_pci_addr *addr,
                             const struct rte_pci_addr *addr2);
 

diff --git a/lib/librte_eal/rte_eal_version.map b/lib/librte_eal/rte_eal_version.map
index f22869a..5cad972 100644 (file)
--- a/lib/librte_eal/rte_eal_version.map
+++ b/lib/librte_eal/rte_eal_version.map
@@ -253,6 +253,9 @@ DPDK_17.11 {
        rte_eal_vfio_intr_mode;
        rte_lcore_has_role;
        rte_memcpy_ptr;
+       rte_pci_addr_cmp;
+       rte_pci_bdf_parse;
+       rte_pci_dbdf_parse;
        rte_pci_device_name;
        rte_pci_get_iommu_class;
        rte_pci_match;