[dpdk-dev] [PATCH v2 3/3] igb_uio: deprecate sys files

[Helin Zhang <helin.zhang@intel.com>]

It deprecated sys files of 'extended_tag' and
'max_read_request_size', and announced the planned ABI changes of
them.

Signed-off-by: Helin Zhang <helin.zhang@intel.com>
---
 doc/guides/linux_gsg/enable_func.rst      | 47 -------------------
 doc/guides/nics/i40e.rst                  | 76 +++++++++++++++++++++++++++++++
 doc/guides/rel_notes/deprecation.rst      |  6 +++
 lib/librte_eal/common/include/rte_pci.h   |  2 +-
 lib/librte_eal/linuxapp/igb_uio/igb_uio.c | 72 ++++-------------------------
 5 files changed, 91 insertions(+), 112 deletions(-)
 create mode 100644 doc/guides/nics/i40e.rst

v2:
 - Kept the sys files as they were, and added ABI change announcement for them.
 - Moved high performance part of i40e from 'GSG' to a new for .nics'.

diff --git a/doc/guides/linux_gsg/enable_func.rst b/doc/guides/linux_gsg/enable_func.rst
index c3fa6d3..f59f25c 100644
--- a/doc/guides/linux_gsg/enable_func.rst
+++ b/doc/guides/linux_gsg/enable_func.rst
@@ -176,50 +176,3 @@ Also, if ``INTEL_IOMMU_DEFAULT_ON`` is not set in the kernel, the ``intel_iommu=
 This ensures that the Intel IOMMU is being initialized as expected.
 
 Please note that while using ``iommu=pt`` is compulsory for ``igb_uio driver``, the ``vfio-pci`` driver can actually work with both ``iommu=pt`` and ``iommu=on``.
-
-High Performance of Small Packets on 40G NIC
---------------------------------------------
-
-As there might be firmware fixes for performance enhancement in latest version
-of firmware image, the firmware update might be needed for getting high performance.
-Check with the local Intel's Network Division application engineers for firmware updates.
-The base driver to support firmware version of FVL3E will be integrated in the next
-DPDK release, so currently the validated firmware version is 4.2.6.
-
-Enabling Extended Tag and Setting Max Read Request Size
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-PCI configurations of ``extended_tag`` and max _read_requ st_size have big impacts on performance of small packets on 40G NIC.
-Enabling extended_tag and setting ``max_read_request_size`` to small size such as 128 bytes provide great helps to high performance of small packets.
-
-*   These can be done in some BIOS implementations.
-
-*   For other BIOS implementations, PCI configurations can be changed by using command of ``setpci``, or special configurations in DPDK config file of ``common_linux``.
-
-    *   Bits 7:5 at address of 0xA8 of each PCI device is used for setting the max_read_request_size,
-        and bit 8 of 0xA8 of each PCI device is used for enabling/disabling the extended_tag.
-        lspci and setpci can be used to read the values of 0xA8 and then write it back after being changed.
-
-    *   In config file of common_linux, below three configurations can be changed for the same purpose.
-
-        ``CONFIG_RTE_PCI_CONFIG``
-
-        ``CONFIG_RTE_PCI_EXTENDED_TAG``
-
-        ``CONFIG_RTE_PCI_MAX_READ_REQUEST_SIZE``
-
-Use 16 Bytes RX Descriptor Size
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-As i40e PMD supports both 16 and 32 bytes RX descriptor sizes, and 16 bytes size can provide helps to high performance of small packets.
-Configuration of ``CONFIG_RTE_LIBRTE_I40E_16BYTE_RX_DESC`` in config files can be changed to use 16 bytes size RX descriptors.
-
-High Performance and per Packet Latency Tradeoff
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Due to the hardware design, the interrupt signal inside NIC is needed for per
-packet descriptor write-back. The minimum interval of interrupts could be set
-at compile time by ``CONFIG_RTE_LIBRTE_I40E_ITR_INTERVAL`` in configuration files.
-Though there is a default configuration, the interval could be tuned by the
-users with that configuration item depends on what the user cares about more,
-performance or per packet latency.
diff --git a/doc/guides/nics/i40e.rst b/doc/guides/nics/i40e.rst
new file mode 100644
index 0000000..b6f089f
--- /dev/null
+++ b/doc/guides/nics/i40e.rst
@@ -0,0 +1,76 @@
+..  BSD LICENSE
+    Copyright(c) 2010-2016 Intel Corporation. All rights reserved.
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+    * Neither the name of Intel Corporation nor the names of its
+    contributors may be used to endorse or promote products derived
+    from this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+I40E Poll Mode Driver
+=====================
+
+The I40E PMD (**librte_pmd_i40e**) provides poll mode driver support
+for **Intel X710/XL710/X722** 10/40 Gbps family of adapters.
+
+High performance of small packets
+---------------------------------
+
+As there might be firmware fixes or enhancements for performance in newer
+version of firmware images, firmware update might be necessary for getting
+high performance. In addition, host driver version is also important for
+DPDK VF performance if kernel PF driver is being used. Check with the local
+Intel Network Division application engineers for helps on firmware upgrade
+and kernel driver upgrade. Release 16.04 will be validated with NVM 5.xx.
+
+Extended Tag
+~~~~~~~~~~~~
+
+PCI configuration of ``extended_tag`` has big impact on small packet size
+performance of 40G ports. Enabling ``extended_tag`` can help 40G port to
+achieve the best performance, especially for small packet size.
+
+- Disabling/enabling ``extended_tag`` can be done in some BIOS implementations.
+- If BIOS does not enable it, and does not support changing it, tools
+  (e.g. ``setpci`` on Linux) can be used to enable or disable ``extended_tag``.
+- From release 16.04, ``extended_tag`` is enabled by default during port
+  initialization, users don't need to care about that anymore.
+
+Use 16 bytes RX descriptor size
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As i40e PMD supports both 16 and 32 bytes RX descriptor sizes, and 16 bytes
+size may help a bit for high performance of small packet size. Configuration
+of ``CONFIG_RTE_LIBRTE_I40E_16BYTE_RX_DESC`` in config files can be changed
+to use 16 bytes size RX descriptors.
+
+High performance and per packet latency tradeoff
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Due to the hardware design, the interrupt signal inside NIC is needed for per
+packet descriptor write-back. The minimum interval of interrupts could be set
+at compile time by ``CONFIG_RTE_LIBRTE_I40E_ITR_INTERVAL`` in configuration
+files. Though there is a default configuration, the interval could be tuned by
+the users with that configuration item depends on what the user cares about
+more, performance or per packet latency.
diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index e94d4a2..b7e0a4f 100644
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -49,3 +49,9 @@ Deprecation Notices
   commands (such as RETA update in testpmd).  This should impact
   CMDLINE_PARSE_RESULT_BUFSIZE, STR_TOKEN_SIZE and RDLINE_BUF_SIZE.
   It should be integrated in release 2.3.
+
+* ABI changes are planned for release 16.07. The eal function of
+  pci_config_space_set is deprecated in release 16.04, and will be removed
+  from 16.07. Macros of CONFIG_RTE_PCI_CONFIG, CONFIG_RTE_PCI_EXTENDED_TAG and
+  CONFIG_RTE_PCI_MAX_READ_REQUEST_SIZE will be removed. sysfile of extended_tag
+  and max_read_request_size created by kernel module igb_uio will be removed.
diff --git a/lib/librte_eal/common/include/rte_pci.h b/lib/librte_eal/common/include/rte_pci.h
index 189d509..e4fb82d 100644
--- a/lib/librte_eal/common/include/rte_pci.h
+++ b/lib/librte_eal/common/include/rte_pci.h
@@ -587,7 +587,7 @@ void rte_eal_pci_ioport_write(struct rte_pci_ioport *p,
  *   A pointer to a rte_pci_device structure describing the device
  *   to use
  */
-void pci_config_space_set(struct rte_pci_device *dev) __rte_deprecated;
+void pci_config_space_set(struct rte_pci_device *dev);
 #endif /* RTE_PCI_CONFIG */
 
 #ifdef __cplusplus
diff --git a/lib/librte_eal/linuxapp/igb_uio/igb_uio.c b/lib/librte_eal/linuxapp/igb_uio/igb_uio.c
index f5617d2..01b4ca6 100644
--- a/lib/librte_eal/linuxapp/igb_uio/igb_uio.c
+++ b/lib/librte_eal/linuxapp/igb_uio/igb_uio.c
@@ -40,15 +40,6 @@
 
 #include "compat.h"
 
-#ifdef RTE_PCI_CONFIG
-#define PCI_SYS_FILE_BUF_SIZE      10
-#define PCI_DEV_CAP_REG            0xA4
-#define PCI_DEV_CTRL_REG           0xA8
-#define PCI_DEV_CAP_EXT_TAG_MASK   0x20
-#define PCI_DEV_CTRL_EXT_TAG_SHIFT 8
-#define PCI_DEV_CTRL_EXT_TAG_MASK  (1 << PCI_DEV_CTRL_EXT_TAG_SHIFT)
-#endif
-
 /**
  * A structure describing the private information for a uio device.
  */
@@ -94,19 +85,9 @@ store_max_vfs(struct device *dev, struct device_attribute *attr,
 static ssize_t
 show_extended_tag(struct device *dev, struct device_attribute *attr, char *buf)
 {
-	struct pci_dev *pci_dev = to_pci_dev(dev);
-	uint32_t val = 0;
+	dev_info(dev, "Deprecated\n");
 
-	pci_read_config_dword(pci_dev, PCI_DEV_CAP_REG, &val);
-	if (!(val & PCI_DEV_CAP_EXT_TAG_MASK)) /* Not supported */
-		return snprintf(buf, PCI_SYS_FILE_BUF_SIZE, "%s\n", "invalid");
-
-	val = 0;
-	pci_bus_read_config_dword(pci_dev->bus, pci_dev->devfn,
-					PCI_DEV_CTRL_REG, &val);
-
-	return snprintf(buf, PCI_SYS_FILE_BUF_SIZE, "%s\n",
-		(val & PCI_DEV_CTRL_EXT_TAG_MASK) ? "on" : "off");
+	return 0;
 }
 
 static ssize_t
@@ -115,36 +96,9 @@ store_extended_tag(struct device *dev,
 		   const char *buf,
 		   size_t count)
 {
-	struct pci_dev *pci_dev = to_pci_dev(dev);
-	uint32_t val = 0, enable;
-
-	if (strncmp(buf, "on", 2) == 0)
-		enable = 1;
-	else if (strncmp(buf, "off", 3) == 0)
-		enable = 0;
-	else
-		return -EINVAL;
-
-	pci_cfg_access_lock(pci_dev);
-	pci_bus_read_config_dword(pci_dev->bus, pci_dev->devfn,
-					PCI_DEV_CAP_REG, &val);
-	if (!(val & PCI_DEV_CAP_EXT_TAG_MASK)) { /* Not supported */
-		pci_cfg_access_unlock(pci_dev);
-		return -EPERM;
-	}
+	dev_info(dev, "Deprecated\n");
 
-	val = 0;
-	pci_bus_read_config_dword(pci_dev->bus, pci_dev->devfn,
-					PCI_DEV_CTRL_REG, &val);
-	if (enable)
-		val |= PCI_DEV_CTRL_EXT_TAG_MASK;
-	else
-		val &= ~PCI_DEV_CTRL_EXT_TAG_MASK;
-	pci_bus_write_config_dword(pci_dev->bus, pci_dev->devfn,
-					PCI_DEV_CTRL_REG, val);
-	pci_cfg_access_unlock(pci_dev);
-
-	return count;
+	return 0;
 }
 
 static ssize_t
@@ -152,10 +106,9 @@ show_max_read_request_size(struct device *dev,
 			   struct device_attribute *attr,
 			   char *buf)
 {
-	struct pci_dev *pci_dev = to_pci_dev(dev);
-	int val = pcie_get_readrq(pci_dev);
+	dev_info(dev, "Deprecated\n");
 
-	return snprintf(buf, PCI_SYS_FILE_BUF_SIZE, "%d\n", val);
+	return 0;
 }
 
 static ssize_t
@@ -164,18 +117,9 @@ store_max_read_request_size(struct device *dev,
 			    const char *buf,
 			    size_t count)
 {
-	struct pci_dev *pci_dev = to_pci_dev(dev);
-	unsigned long size = 0;
-	int ret;
+	dev_info(dev, "Deprecated\n");
 
-	if (0 != kstrtoul(buf, 0, &size))
-		return -EINVAL;
-
-	ret = pcie_set_readrq(pci_dev, (int)size);
-	if (ret < 0)
-		return ret;
-
-	return count;
+	return 0;
 }
 #endif
 
-- 
1.9.3