From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 182ECA04C0; Fri, 25 Sep 2020 13:10:45 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 92E1D1E8FF; Fri, 25 Sep 2020 13:09:53 +0200 (CEST) Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by dpdk.org (Postfix) with ESMTP id AA4DD1E8D6 for ; Fri, 25 Sep 2020 13:09:45 +0200 (CEST) IronPort-SDR: ZPcYEGuFoHBK/oL8Bocmk38VJv0VweTxeyF71Ca2QjLMyaS1utCxC8mFDCip9eJoJ37k532OZu v7gSg071Ci+g== X-IronPort-AV: E=McAfee;i="6000,8403,9754"; a="149263082" X-IronPort-AV: E=Sophos;i="5.77,301,1596524400"; d="scan'208";a="149263082" X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga004.jf.intel.com ([10.7.209.38]) by orsmga106.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 25 Sep 2020 04:09:45 -0700 IronPort-SDR: ehthXBdana1bP3htDh6omHrwQWE8gNpIMtSvL0wZ36XcoVmTU0Z+p6kwphU3MwkKqZ8VICKDy9 +tb2iq6ZvuzA== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.77,301,1596524400"; d="scan'208";a="455787852" Received: from unknown (HELO silpixa00399126.ir.intel.com) ([10.237.222.4]) by orsmga004.jf.intel.com with ESMTP; 25 Sep 2020 04:09:43 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: patrick.fu@intel.com, Bruce Richardson , Kevin Laatz Date: Fri, 25 Sep 2020 12:08:52 +0100 Message-Id: <20200925110910.284098-8-bruce.richardson@intel.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200925110910.284098-1-bruce.richardson@intel.com> References: <20200721095140.719297-1-bruce.richardson@intel.com> <20200925110910.284098-1-bruce.richardson@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v3 07/25] raw/ioat: rename functions to be operation-agnostic X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Since the hardware supported by the ioat driver is capable of operations other than just copies, we can rename the doorbell and completion-return functions to not have "copies" in their names. These functions are not copy-specific, and so would apply for other operations which may be added later to the driver. Also add a suitable warning using deprecation attribute for any code using the old functions names. Signed-off-by: Bruce Richardson Reviewed-by: Kevin Laatz --- Note: The checkpatches warning on this patch is a false positive due to the addition of the new __rte_deprecated_msg macro in rte_common.h --- doc/guides/rawdevs/ioat.rst | 16 ++++++++-------- doc/guides/rel_notes/release_20_11.rst | 9 +++++++++ doc/guides/sample_app_ug/ioat.rst | 8 ++++---- drivers/raw/ioat/ioat_rawdev_test.c | 12 ++++++------ drivers/raw/ioat/rte_ioat_rawdev.h | 14 +++++++------- drivers/raw/ioat/rte_ioat_rawdev_fns.h | 20 ++++++++++++++++---- examples/ioat/ioatfwd.c | 4 ++-- lib/librte_eal/include/rte_common.h | 1 + 8 files changed, 53 insertions(+), 31 deletions(-) diff --git a/doc/guides/rawdevs/ioat.rst b/doc/guides/rawdevs/ioat.rst index af00d77fb..3db5f5d09 100644 --- a/doc/guides/rawdevs/ioat.rst +++ b/doc/guides/rawdevs/ioat.rst @@ -157,9 +157,9 @@ Performing Data Copies ~~~~~~~~~~~~~~~~~~~~~~~ To perform data copies using IOAT rawdev devices, the functions -``rte_ioat_enqueue_copy()`` and ``rte_ioat_do_copies()`` should be used. +``rte_ioat_enqueue_copy()`` and ``rte_ioat_perform_ops()`` should be used. Once copies have been completed, the completion will be reported back when -the application calls ``rte_ioat_completed_copies()``. +the application calls ``rte_ioat_completed_ops()``. The ``rte_ioat_enqueue_copy()`` function enqueues a single copy to the device ring for copying at a later point. The parameters to that function @@ -172,11 +172,11 @@ pointers if packet data is being copied. While the ``rte_ioat_enqueue_copy()`` function enqueues a copy operation on the device ring, the copy will not actually be performed until after the -application calls the ``rte_ioat_do_copies()`` function. This function +application calls the ``rte_ioat_perform_ops()`` function. This function informs the device hardware of the elements enqueued on the ring, and the device will begin to process them. It is expected that, for efficiency reasons, a burst of operations will be enqueued to the device via multiple -enqueue calls between calls to the ``rte_ioat_do_copies()`` function. +enqueue calls between calls to the ``rte_ioat_perform_ops()`` function. The following code from ``test_ioat_rawdev.c`` demonstrates how to enqueue a burst of copies to the device and start the hardware processing of them: @@ -210,10 +210,10 @@ a burst of copies to the device and start the hardware processing of them: return -1; } } - rte_ioat_do_copies(dev_id); + rte_ioat_perform_ops(dev_id); To retrieve information about completed copies, the API -``rte_ioat_completed_copies()`` should be used. This API will return to the +``rte_ioat_completed_ops()`` should be used. This API will return to the application a set of completion handles passed in when the relevant copies were enqueued. @@ -223,9 +223,9 @@ is correct before freeing the data buffers using the returned handles: .. code-block:: C - if (rte_ioat_completed_copies(dev_id, 64, (void *)completed_src, + if (rte_ioat_completed_ops(dev_id, 64, (void *)completed_src, (void *)completed_dst) != RTE_DIM(srcs)) { - printf("Error with rte_ioat_completed_copies\n"); + printf("Error with rte_ioat_completed_ops\n"); return -1; } for (i = 0; i < RTE_DIM(srcs); i++) { diff --git a/doc/guides/rel_notes/release_20_11.rst b/doc/guides/rel_notes/release_20_11.rst index 196209f63..c99c0b33f 100644 --- a/doc/guides/rel_notes/release_20_11.rst +++ b/doc/guides/rel_notes/release_20_11.rst @@ -83,6 +83,11 @@ New Features The ioat rawdev driver has been updated and enhanced. Changes include: * Added a per-device configuration flag to disable management of user-provided completion handles + * Renamed the ``rte_ioat_do_copies()`` API to ``rte_ioat_perform_ops()``, + and renamed the ``rte_ioat_completed_copies()`` API to ``rte_ioat_completed_ops()`` + to better reflect the APIs' purposes, and remove the implication that + they are limited to copy operations only. + [Note: The old API is still provided but marked as deprecated in the code] Removed Items @@ -178,6 +183,10 @@ API Changes * bpf: ``RTE_BPF_XTYPE_NUM`` has been dropped from ``rte_bpf_xtype``. +* raw/ioat: As noted above, the ``rte_ioat_do_copies()`` and + ``rte_ioat_completed_copies()`` functions have been renamed to + ``rte_ioat_perform_ops()`` and ``rte_ioat_completed_ops()`` respectively. + ABI Changes ----------- diff --git a/doc/guides/sample_app_ug/ioat.rst b/doc/guides/sample_app_ug/ioat.rst index 3f7d5c34a..964160dff 100644 --- a/doc/guides/sample_app_ug/ioat.rst +++ b/doc/guides/sample_app_ug/ioat.rst @@ -394,7 +394,7 @@ packet using ``pktmbuf_sw_copy()`` function and enqueue them to an rte_ring: nb_enq = ioat_enqueue_packets(pkts_burst, nb_rx, rx_config->ioat_ids[i]); if (nb_enq > 0) - rte_ioat_do_copies(rx_config->ioat_ids[i]); + rte_ioat_perform_ops(rx_config->ioat_ids[i]); } else { /* Perform packet software copy, free source packets */ int ret; @@ -433,7 +433,7 @@ The packets are received in burst mode using ``rte_eth_rx_burst()`` function. When using hardware copy mode the packets are enqueued in copying device's buffer using ``ioat_enqueue_packets()`` which calls ``rte_ioat_enqueue_copy()``. When all received packets are in the -buffer the copy operations are started by calling ``rte_ioat_do_copies()``. +buffer the copy operations are started by calling ``rte_ioat_perform_ops()``. Function ``rte_ioat_enqueue_copy()`` operates on physical address of the packet. Structure ``rte_mbuf`` contains only physical address to start of the data buffer (``buf_iova``). Thus the address is adjusted @@ -490,7 +490,7 @@ or indirect mbufs, then multiple copy operations must be used. All completed copies are processed by ``ioat_tx_port()`` function. When using -hardware copy mode the function invokes ``rte_ioat_completed_copies()`` +hardware copy mode the function invokes ``rte_ioat_completed_ops()`` on each assigned IOAT channel to gather copied packets. If software copy mode is used the function dequeues copied packets from the rte_ring. Then each packet MAC address is changed if it was enabled. After that copies are sent @@ -510,7 +510,7 @@ in burst mode using `` rte_eth_tx_burst()``. for (i = 0; i < tx_config->nb_queues; i++) { if (copy_mode == COPY_MODE_IOAT_NUM) { /* Deque the mbufs from IOAT device. */ - nb_dq = rte_ioat_completed_copies( + nb_dq = rte_ioat_completed_ops( tx_config->ioat_ids[i], MAX_PKT_BURST, (void *)mbufs_src, (void *)mbufs_dst); } else { diff --git a/drivers/raw/ioat/ioat_rawdev_test.c b/drivers/raw/ioat/ioat_rawdev_test.c index 8e7fd96af..bb40eab6b 100644 --- a/drivers/raw/ioat/ioat_rawdev_test.c +++ b/drivers/raw/ioat/ioat_rawdev_test.c @@ -62,12 +62,12 @@ test_enqueue_copies(int dev_id) PRINT_ERR("Error with rte_ioat_enqueue_copy\n"); return -1; } - rte_ioat_do_copies(dev_id); + rte_ioat_perform_ops(dev_id); usleep(10); - if (rte_ioat_completed_copies(dev_id, 1, (void *)&completed[0], + if (rte_ioat_completed_ops(dev_id, 1, (void *)&completed[0], (void *)&completed[1]) != 1) { - PRINT_ERR("Error with rte_ioat_completed_copies\n"); + PRINT_ERR("Error with rte_ioat_completed_ops\n"); return -1; } if (completed[0] != src || completed[1] != dst) { @@ -116,12 +116,12 @@ test_enqueue_copies(int dev_id) return -1; } } - rte_ioat_do_copies(dev_id); + rte_ioat_perform_ops(dev_id); usleep(100); - if (rte_ioat_completed_copies(dev_id, 64, (void *)completed_src, + if (rte_ioat_completed_ops(dev_id, 64, (void *)completed_src, (void *)completed_dst) != RTE_DIM(srcs)) { - PRINT_ERR("Error with rte_ioat_completed_copies\n"); + PRINT_ERR("Error with rte_ioat_completed_ops\n"); return -1; } for (i = 0; i < RTE_DIM(srcs); i++) { diff --git a/drivers/raw/ioat/rte_ioat_rawdev.h b/drivers/raw/ioat/rte_ioat_rawdev.h index 7067b352f..5b2c47e8c 100644 --- a/drivers/raw/ioat/rte_ioat_rawdev.h +++ b/drivers/raw/ioat/rte_ioat_rawdev.h @@ -74,19 +74,19 @@ rte_ioat_enqueue_copy(int dev_id, phys_addr_t src, phys_addr_t dst, int fence); /** - * Trigger hardware to begin performing enqueued copy operations + * Trigger hardware to begin performing enqueued operations * * This API is used to write the "doorbell" to the hardware to trigger it - * to begin the copy operations previously enqueued by rte_ioat_enqueue_copy() + * to begin the operations previously enqueued by rte_ioat_enqueue_copy() * * @param dev_id * The rawdev device id of the ioat instance */ static inline void -rte_ioat_do_copies(int dev_id); +rte_ioat_perform_ops(int dev_id); /** - * Returns details of copy operations that have been completed + * Returns details of operations that have been completed * * If the hdls_disable option was not set when the device was configured, * the function will return to the caller the user-provided "handles" for @@ -104,11 +104,11 @@ rte_ioat_do_copies(int dev_id); * NOTE: If hdls_disable configuration option for the device is set, this * parameter is ignored. * @param src_hdls - * Array to hold the source handle parameters of the completed copies. + * Array to hold the source handle parameters of the completed ops. * NOTE: If hdls_disable configuration option for the device is set, this * parameter is ignored. * @param dst_hdls - * Array to hold the destination handle parameters of the completed copies. + * Array to hold the destination handle parameters of the completed ops. * NOTE: If hdls_disable configuration option for the device is set, this * parameter is ignored. * @return @@ -117,7 +117,7 @@ rte_ioat_do_copies(int dev_id); * to the src_hdls and dst_hdls array parameters. */ static inline int -rte_ioat_completed_copies(int dev_id, uint8_t max_copies, +rte_ioat_completed_ops(int dev_id, uint8_t max_copies, uintptr_t *src_hdls, uintptr_t *dst_hdls); /* include the implementation details from a separate file */ diff --git a/drivers/raw/ioat/rte_ioat_rawdev_fns.h b/drivers/raw/ioat/rte_ioat_rawdev_fns.h index 4b7bdb8e2..b155d79c4 100644 --- a/drivers/raw/ioat/rte_ioat_rawdev_fns.h +++ b/drivers/raw/ioat/rte_ioat_rawdev_fns.h @@ -83,10 +83,10 @@ rte_ioat_enqueue_copy(int dev_id, phys_addr_t src, phys_addr_t dst, } /* - * Trigger hardware to begin performing enqueued copy operations + * Trigger hardware to begin performing enqueued operations */ static inline void -rte_ioat_do_copies(int dev_id) +rte_ioat_perform_ops(int dev_id) { struct rte_ioat_rawdev *ioat = (struct rte_ioat_rawdev *)rte_rawdevs[dev_id].dev_private; @@ -114,10 +114,10 @@ rte_ioat_get_last_completed(struct rte_ioat_rawdev *ioat, int *error) } /* - * Returns details of copy operations that have been completed + * Returns details of operations that have been completed */ static inline int -rte_ioat_completed_copies(int dev_id, uint8_t max_copies, +rte_ioat_completed_ops(int dev_id, uint8_t max_copies, uintptr_t *src_hdls, uintptr_t *dst_hdls) { struct rte_ioat_rawdev *ioat = @@ -165,4 +165,16 @@ rte_ioat_completed_copies(int dev_id, uint8_t max_copies, return count; } +static inline void +__rte_deprecated_msg("use rte_ioat_perform_ops() instead") +rte_ioat_do_copies(int dev_id) { rte_ioat_perform_ops(dev_id); } + +static inline int +__rte_deprecated_msg("use rte_ioat_completed_ops() instead") +rte_ioat_completed_copies(int dev_id, uint8_t max_copies, + uintptr_t *src_hdls, uintptr_t *dst_hdls) +{ + return rte_ioat_completed_ops(dev_id, max_copies, src_hdls, dst_hdls); +} + #endif /* _RTE_IOAT_RAWDEV_FNS_H_ */ diff --git a/examples/ioat/ioatfwd.c b/examples/ioat/ioatfwd.c index 288a75c7b..67f75737b 100644 --- a/examples/ioat/ioatfwd.c +++ b/examples/ioat/ioatfwd.c @@ -406,7 +406,7 @@ ioat_rx_port(struct rxtx_port_config *rx_config) nb_enq = ioat_enqueue_packets(pkts_burst, nb_rx, rx_config->ioat_ids[i]); if (nb_enq > 0) - rte_ioat_do_copies(rx_config->ioat_ids[i]); + rte_ioat_perform_ops(rx_config->ioat_ids[i]); } else { /* Perform packet software copy, free source packets */ int ret; @@ -452,7 +452,7 @@ ioat_tx_port(struct rxtx_port_config *tx_config) for (i = 0; i < tx_config->nb_queues; i++) { if (copy_mode == COPY_MODE_IOAT_NUM) { /* Deque the mbufs from IOAT device. */ - nb_dq = rte_ioat_completed_copies( + nb_dq = rte_ioat_completed_ops( tx_config->ioat_ids[i], MAX_PKT_BURST, (void *)mbufs_src, (void *)mbufs_dst); } else { diff --git a/lib/librte_eal/include/rte_common.h b/lib/librte_eal/include/rte_common.h index 8f487a563..2920255fc 100644 --- a/lib/librte_eal/include/rte_common.h +++ b/lib/librte_eal/include/rte_common.h @@ -85,6 +85,7 @@ typedef uint16_t unaligned_uint16_t; /******* Macro to mark functions and fields scheduled for removal *****/ #define __rte_deprecated __attribute__((__deprecated__)) +#define __rte_deprecated_msg(msg) __attribute__((__deprecated__(msg))) /** * Mark a function or variable to a weak reference. -- 2.25.1