From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <gaetan.rivet@6wind.com>
Received: from mail-wm0-f65.google.com (mail-wm0-f65.google.com [74.125.82.65])
 by dpdk.org (Postfix) with ESMTP id E1A181BA91
 for <dev@dpdk.org>; Thu, 26 Oct 2017 12:06:43 +0200 (CEST)
Received: by mail-wm0-f65.google.com with SMTP id p75so6852299wmg.3
 for <dev@dpdk.org>; Thu, 26 Oct 2017 03:06:43 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=6wind-com.20150623.gappssmtp.com; s=20150623;
 h=from:to:cc:subject:date:message-id:in-reply-to:references
 :in-reply-to:references;
 bh=RLYiLopUULhgvcSnnM8HNURrjxTMbnok2oEIv/OXIfg=;
 b=f2pTIlxyi7DVj2mNbijYJvlZULCww+H+2trJS6gYvI5v22ajpp2T6T/seWrl/voU7/
 uOSC0ziVnQ4QnolqkPEYbl0g1Tbkh4Yp7myl5mJ9P0EDuyY75bYCTWdUDVBTSa8Q40Ws
 YpzNXpA5jwp2lup6MEy5PUA2e/5n5WjDoFOGp+RdPUohKX3YpH/I5H6lk/wMIWiQ//cU
 BTgOmOLRsuEMEiN/UDYHYinIbzXYSdH4WiC735GHLBjdZunRg/djSmdLZ/sXTdcMQPYi
 r7rqWqnEqiwGGbtaMT2O3ncDOrnODjggqHkrb8RDImJF3JiJXIoA4aSTq+ixW/DhlXED
 X9tQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20161025;
 h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to
 :references:in-reply-to:references;
 bh=RLYiLopUULhgvcSnnM8HNURrjxTMbnok2oEIv/OXIfg=;
 b=eNj2FR/4uXOis4GEaVGO8SsLW/nJKDnYMVY+TXpIXDNapgzKsRDLiCZc74jRVFGOCn
 zpvfSdcBs+RTbS9dj9/acgEVqSI1WUGUuVOLPCFtG6axAFD78cJf9JhQcyZtmbdUic4x
 d7r5x2FkNhcsEwDOdM3BqpPrGqkh7Om+KEdvee7ZCb65vfgfNXedB0NjLCtvtMa47m32
 8imJIH4bDUhkxWNPhJhvHZls54lkSOSKEVg+MkI32LkSjBGHjzy4pOIMQULlwljPwT6o
 70tlwY1dcGOH9C2XnotolsHJj4a1pFblyWRZ1EZnNdROPFPnx3++hPUAahnClN+ugrQN
 2kzQ==
X-Gm-Message-State: AMCzsaXwHS4IdMk+sKgxn7+gUx4aVxEXlL9vOk7XIlDPvpDt5X3v3kRV
 Qv8nPu7ye2hyM7fG8pIErxYFNYkH
X-Google-Smtp-Source: ABhQp+SWqNPV9rmmh3k0TD2aqR7tDPkmBSxbHxd2CAN1i01SQQpAXUx2m6U2FwqrvUXQQpuQPBYaRQ==
X-Received: by 10.80.165.20 with SMTP id y20mr24395155edb.72.1509012403044;
 Thu, 26 Oct 2017 03:06:43 -0700 (PDT)
Received: from bidouze.dev.6wind.com (host.78.145.23.62.rev.coltfrance.com.
 [62.23.145.78])
 by smtp.gmail.com with ESMTPSA id u12sm3339619edk.45.2017.10.26.03.06.41
 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128);
 Thu, 26 Oct 2017 03:06:42 -0700 (PDT)
From: Gaetan Rivet <gaetan.rivet@6wind.com>
To: dev@dpdk.org
Cc: Gaetan Rivet <gaetan.rivet@6wind.com>
Date: Thu, 26 Oct 2017 12:05:58 +0200
Message-Id: <524e8365bacb2c9955ff99a2943ef1ce265c3f1c.1509012196.git.gaetan.rivet@6wind.com>
X-Mailer: git-send-email 2.1.4
In-Reply-To: <cover.1509012196.git.gaetan.rivet@6wind.com>
References: <cover.1508970254.git.gaetan.rivet@6wind.com>
 <cover.1509012196.git.gaetan.rivet@6wind.com>
In-Reply-To: <cover.1509012196.git.gaetan.rivet@6wind.com>
References: <cover.1509012196.git.gaetan.rivet@6wind.com>
Subject: [dpdk-dev] [PATCH v8 13/25] pci: deprecate misnamed functions
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <http://dpdk.org/ml/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://dpdk.org/ml/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <http://dpdk.org/ml/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
X-List-Received-Date: Thu, 26 Oct 2017 10:06:44 -0000

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    |  9 +++++++
 lib/librte_eal/common/eal_common_pci.c  | 27 ++++++++++++++++---
 lib/librte_eal/common/include/rte_pci.h | 47 +++++++++++++++++++++++++++++++++
 lib/librte_eal/rte_eal_version.map      |  3 +++
 4 files changed, 82 insertions(+), 4 deletions(-)

diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index d07f38c..277c78d 100644
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -60,3 +60,12 @@ Deprecation Notices
 
 * librte_meter: The API will change to accommodate configuration profiles.
   Most of the API functions will have an additional opaque parameter.
+
+* 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.
diff --git a/lib/librte_eal/common/eal_common_pci.c b/lib/librte_eal/common/eal_common_pci.c
index f896289..2230e09 100644
--- 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
--- 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
--- 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;
-- 
2.1.4