From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id C9E6C45552; Tue, 16 Jul 2024 00:12:04 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A2683402BB; Tue, 16 Jul 2024 00:12:04 +0200 (CEST) Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by mails.dpdk.org (Postfix) with ESMTP id D872240274 for ; Tue, 16 Jul 2024 00:12:02 +0200 (CEST) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 6FCD91007; Mon, 15 Jul 2024 15:12:27 -0700 (PDT) Received: from ampere-altra-2-1.usa.Arm.com (ampere-altra-2-1.usa.arm.com [10.118.91.158]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPA id BC5C23F766; Mon, 15 Jul 2024 15:12:01 -0700 (PDT) From: Wathsala Vithanage To: dev@dpdk.org, Thomas Monjalon , Ferruh Yigit , Andrew Rybchenko Cc: nd@arm.com, Wathsala Vithanage , Dhruv Tripathi Subject: [RFC v2] ethdev: an API for cache stashing hints Date: Mon, 15 Jul 2024 22:11:41 +0000 Message-Id: <20240715221141.16153-1-wathsala.vithanage@arm.com> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org An application provides cache stashing hints to the ethernet devices to improve memory access latencies from the CPU and the NIC. This patch introduces three distinct hints for this purpose. The RTE_ETH_DEV_STASH_HINT_HOST_WILLNEED hint indicates that the host (CPU) requires the data written by the NIC immediately. This implies that the CPU expects to read data from its local cache rather than LLC or main memory if possible. This would improve memory access latency in the Rx path. For PCI devices with TPH capability, these hints translate into DWHR (Device Writes Host Reads) access pattern. This hint is only valid for receive queues. The RTE_ETH_DEV_STASH_HINT_BI_DIR_DATA hint indicates that the host and the device access the data structure equally. Rx/Tx queue descriptors fit the description of such data. This hint applies to both Rx and Tx directions.  In the PCI TPH context, this hint translates into a Bi-Directional access pattern. RTE_ETH_DEV_STASH_HINT_DEV_ONLY hint indicates that the CPU is not involved in a given device's receive or transmit paths. This implies that only devices are involved in the IO path. Depending on the implementation, this hint may result in data getting placed in a cache close to the device or not cached at all. For PCI devices with TPH capability, this hint translates into D*D* (DWDR, DRDW, DWDW, DRDR) access patterns. This is a bidirectional hint, and it can be applied to both Rx and Tx queues.   The RTE_ETH_DEV_STASH_HINT_HOST_DONTNEED hint indicates that the device reads data written by the host (CPU) that may still be in the host's local cache but is not required by the host anytime soon. This hint is intended to prevent unnecessary cache invalidations that cause interconnect latencies when a device writes to a buffer already in host cache memory. In DPDK, this could happen with the recycling of mbufs where a mbuf is placed in the Tx queue that then gets back into mempool and gets recycled back into the Rx queue, all while a copy is being held in the CPU's local cache unnecessarily. By using this hint on supported platforms, the mbuf will be invalidated after the device completes the buffer reading, but it will be well before the buffer gets recycled and updated in the Rx path. This hint is only valid for transmit queues.  Applications use three main interfaces in the ethdev library to discover and set cache stashing hints. rte_eth_dev_stashing_hints_tx interface is used to set hints on a Tx queue. rte_eth_dev_stashing_hints_rx interface is used to set hints on an Rx queue. Both of these functions take the following parameters as inputs: a port_id (the id of the ethernet device), a cpu_id (the target CPU), a cache_level (the level of the cache hierarchy the data should be stashed into), a queue_id (the queue the hints are applied to). In addition to the above list of parameters, a type parameter indicates the type of the object the application expects to be stashed by the hardware. Depending on the hardware, these may vary. Intel E810 NICs support the stashing of Rx/Tx descriptors, packet headers, and packet payloads. These are indicated by the macros RTE_ETH_DEV_STASH_TYPE_DESC, RTE_ETH_DEV_STASH_TYPE_HEADER, RTE_ETH_DEV_STASH_TYPE_PAYLOAD. Hardware capable of stashing data at any given offset into a packet can use the RTE_ETH_DEV_STASH_TYPE_OFFSET type. When an offset is used, the offset parameter in the above two functions should be set appropriately. rte_eth_dev_stashing_hints_discover is used to discover the object types and hints supported in the platform and the device. The function takes types and hints pointers used as a bit vector to indicate hints and types supported by the NIC. An application that intends to use stashing hints should first discover supported hints and types and then use the functions rte_eth_dev_stashing_hints_tx and rte_eth_dev_stashing_hints_rx as required to set stashing hints accordingly. eth_dev_ops structure has been updated with two new ops that a PMD should implement to support cache stashing hints. A PMD that intends to support cache stashing hints should initialize the set_stashing_hints function pointer to a function that issues hints to the underlying hardware in compliance with platform capabilities. The same PMD should also implement a function that can return two-bit fields indicating supported types and hints and then initialize the discover_stashing_hints function pointer with it. If the NIC supports cache stashing hints, the NIC should always set the RTE_ETH_DEV_CAPA_CACHE_STASHING device capability. Signed-off-by: Wathsala Vithanage Reviewed-by: Dhruv Tripathi --- .mailmap | 1 + lib/ethdev/ethdev_driver.h | 67 +++++++++++ lib/ethdev/rte_ethdev.c | 153 +++++++++++++++++++++++++ lib/ethdev/rte_ethdev.h | 225 +++++++++++++++++++++++++++++++++++++ lib/ethdev/version.map | 6 + 5 files changed, 452 insertions(+) diff --git a/.mailmap b/.mailmap index f1e64286a1..9c28b74655 100644 --- a/.mailmap +++ b/.mailmap @@ -338,6 +338,7 @@ Dexia Li Dexuan Cui Dharmik Thakkar Dheemanth Mallikarjun +Dhruv Tripathi Diana Wang Didier Pallard Dilshod Urazov diff --git a/lib/ethdev/ethdev_driver.h b/lib/ethdev/ethdev_driver.h index 883e59a927..b90dc8793b 100644 --- a/lib/ethdev/ethdev_driver.h +++ b/lib/ethdev/ethdev_driver.h @@ -1235,6 +1235,70 @@ typedef int (*eth_count_aggr_ports_t)(struct rte_eth_dev *dev); typedef int (*eth_map_aggr_tx_affinity_t)(struct rte_eth_dev *dev, uint16_t tx_queue_id, uint8_t affinity); +/** + * @internal + * Set cache stashing hint in the ethernet device. + * + * @param dev + * Port (ethdev) handle. + * @param cpuid + * ID of the targeted CPU. + * @param cache_level + * Level of the cache to stash data. + * @param queue_id + * List of receive queue ids used in rte_eth_rx_burst(). + * @param queue_direction + * RTE_ETH_DEV_QUEUE_TYPE_RX if queue that corresponds to queue_id is an + * rx queue. + * RTE_ETH_DEV_QUEUE_TYPE_TX if queue that corresponds to queue_id is a + * tx queue. + * @param types + * A vector of stashing types to apply hints on a given queue direction. + * hints are applied on the types specified in types vector. + * types can include queue descriptors (RTE_ETH_DEV_STASH_TYPE_DESC), + * packet headers (RTE_ETH_DEV_STASH_TYPE_HEADER), + * packet payloads (RTE_ETH_DEV_STASH_TYPE_PAYLOAD) or + * to an offset (RTE_ETH_DEV_STASH_TYPE_OFFSET) in to a packet. + * types have to be compatible with the queue_direction or an -EINVAL will + * be returned. + * @param hints + * Cache stashing hints + * @param offset + * Offset into the packet if RTE_ETH_DEV_STASH_TYPE_OFFSET is set in hints. + * + * @return + * -ENOTSUP if the device or the platform does not support cache stashing. + * -ENOSYS if the underlying PMD hasn't implemented cache stashing feature. + * -EINVAL on invalid arguments. + * 0 on success. + */ +typedef int (*eth_set_stashing_hints_t)(struct rte_eth_dev *dev, uint16_t cpuid, + uint8_t cache_level, + uint16_t queue_id, uint8_t queue_direction, + uint16_t types, uint8_t hints, off_t offset); + +/** + * @internal + * Discover cache stashing hints and object types supported in the ethernet device. + * + * @param dev + * Port (ethdev) handle. + * @param types + * Set bits for supported object types. + * @param hints + * Set bits for supported stashing hints. + * + * @return + * -ENOTSUP if the device or the platform does not support cache stashing. + * -ENOSYS if the underlying PMD hasn't implemented cache stashing feature. + * -EINVAL on NULL values for types or hints parameters. + * On return, types and hints parameters will have bits set for supported + * object types and hints. + * 0 on success. + */ +typedef int (*eth_discover_stashing_hints_t)(struct rte_eth_dev *dev, + uint16_t *types, uint16_t *hints); + /** * @internal A structure containing the functions exported by an Ethernet driver. */ @@ -1257,6 +1321,9 @@ struct eth_dev_ops { eth_mac_addr_remove_t mac_addr_remove; /**< Remove MAC address */ eth_mac_addr_add_t mac_addr_add; /**< Add a MAC address */ eth_mac_addr_set_t mac_addr_set; /**< Set a MAC address */ + eth_set_stashing_hints_t set_stashing_hints; /**< Set cache stashing*/ + /**Discover supported stashing hints*/ + eth_discover_stashing_hints_t discover_stashing_hints; /** Set list of multicast addresses */ eth_set_mc_addr_list_t set_mc_addr_list; mtu_set_t mtu_set; /**< Set MTU */ diff --git a/lib/ethdev/rte_ethdev.c b/lib/ethdev/rte_ethdev.c index f1c658f49e..fafc94223e 100644 --- a/lib/ethdev/rte_ethdev.c +++ b/lib/ethdev/rte_ethdev.c @@ -153,6 +153,7 @@ static const struct { {RTE_ETH_DEV_CAPA_RXQ_SHARE, "RXQ_SHARE"}, {RTE_ETH_DEV_CAPA_FLOW_RULE_KEEP, "FLOW_RULE_KEEP"}, {RTE_ETH_DEV_CAPA_FLOW_SHARED_OBJECT_KEEP, "FLOW_SHARED_OBJECT_KEEP"}, + {RTE_ETH_DEV_CAPA_CACHE_STASHING, "CACHE_STASHING"}, }; enum { @@ -7008,4 +7009,156 @@ int rte_eth_dev_map_aggr_tx_affinity(uint16_t port_id, uint16_t tx_queue_id, return ret; } +int +rte_eth_dev_validate_stashing_hints(uint16_t port_id, uint16_t queue_id, + uint8_t queue_direction, uint16_t types, + uint16_t hints) +{ + struct rte_eth_dev *dev; + struct rte_eth_dev_info dev_info; + uint16_t nb_queues; + + RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); + + /* + * Check for invalid types + */ + if (!RTE_ETH_DEV_STASH_TYPE_VALID(types)) { + RTE_ETHDEV_LOG_LINE(ERR, "Invalid stashing type"); + return -EINVAL; + } + + /* + * Ensure that hints (HOST_DONOTNEED, HOST_WILLNEED, BI_DIR_DATA, and + * DEV_ONLY etc.) are not mixed incorrectly in the hint argument. + * Only hints of one queue direction (Rx or Tx) can be combined in the + * hint argument. If the hint argument contains hint types compatible + * with both Rx and Tx directions it can be applied to any queue of the + * two queue types. + */ + if (!RTE_ETH_DEV_STASH_HINT_IS_RXTX(hints)) { + /* + * This is not a Rx and a Tx hint. + * Therefore it can only be applied to single queue direction. + */ + if (RTE_ETH_DEV_STASH_HINT_IS_TX(hints) == + RTE_ETH_DEV_STASH_HINT_IS_RX(hints)) { + RTE_ETHDEV_LOG_LINE(ERR, "This hint is not compatible " + "with both Rx and Tx paths"); + return -EINVAL; + } + /* + * Ensure that hint is compatible with the specified queue + * direction in the queue_direction argument. + */ + if (((queue_direction == RTE_ETH_DEV_QUEUE_TYPE_TX) && + RTE_ETH_DEV_STASH_HINT_IS_RX(hints)) || + ((queue_direction == RTE_ETH_DEV_QUEUE_TYPE_RX) && + RTE_ETH_DEV_STASH_HINT_IS_TX(hints))) { + RTE_ETHDEV_LOG_LINE(ERR, "Hints are not applicable to " + "this queue type"); + return -EINVAL; + } + } + + dev = &rte_eth_devices[port_id]; + + nb_queues = (queue_direction == RTE_ETH_DEV_QUEUE_TYPE_RX) ? + dev->data->nb_rx_queues : + dev->data->nb_tx_queues; + + if (queue_id >= nb_queues) { + RTE_ETHDEV_LOG_LINE(ERR, "Invalid Rx queue_id=%u", queue_id); + return -EINVAL; + } + + rte_eth_dev_info_get(port_id, &dev_info); + + if ((dev_info.dev_capa & RTE_ETH_DEV_CAPA_CACHE_STASHING) != + RTE_ETH_DEV_CAPA_CACHE_STASHING) + return -ENOTSUP; + + if (*dev->dev_ops->set_stashing_hints == NULL) { + RTE_ETHDEV_LOG_LINE(ERR, "Stashing hints are not implemented " + "in %s for %s", dev_info.driver_name, + dev_info.device->name); + return -ENOSYS; + } + + return 0; +} + +int +rte_eth_dev_stashing_hints_rx(uint16_t port_id, uint16_t cpuid, + uint8_t cache_level, uint16_t queue_id, + uint16_t types, off_t offset, + uint16_t hints) +{ + struct rte_eth_dev *dev; + + int ret = rte_eth_dev_validate_stashing_hints(port_id, queue_id, + RTE_ETH_DEV_QUEUE_TYPE_RX, + types, hints); + if (ret < 0) + return ret; + + dev = &rte_eth_devices[port_id]; + + return eth_err(port_id, (*dev->dev_ops->set_stashing_hints)(dev, cpuid, + cache_level, queue_id, RTE_ETH_DEV_QUEUE_TYPE_RX, + types, hints, offset)); +} + +int +rte_eth_dev_stashing_hints_tx(uint16_t port_id, uint16_t cpuid, + uint8_t cache_level, uint16_t queue_id, + uint16_t types, off_t offset, + uint16_t hints) +{ + struct rte_eth_dev *dev; + + int ret = rte_eth_dev_validate_stashing_hints(port_id, queue_id, + RTE_ETH_DEV_QUEUE_TYPE_TX, + types, hints); + if (ret < 0) + return ret; + + dev = &rte_eth_devices[port_id]; + + return eth_err(port_id, + (*dev->dev_ops->set_stashing_hints) (dev, cpuid, + cache_level, queue_id, RTE_ETH_DEV_QUEUE_TYPE_TX, types, + hints, offset)); +} + +int +rte_eth_dev_stashing_hints_discover(uint16_t port_id, uint16_t *types, + uint16_t *hints) +{ + struct rte_eth_dev *dev; + struct rte_eth_dev_info dev_info; + + RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); + + if (!types || !hints) + return -EINVAL; + + dev = &rte_eth_devices[port_id]; + rte_eth_dev_info_get(port_id, &dev_info); + + if ((dev_info.dev_capa & RTE_ETH_DEV_CAPA_CACHE_STASHING) != + RTE_ETH_DEV_CAPA_CACHE_STASHING) + return -ENOTSUP; + + if (*dev->dev_ops->discover_stashing_hints == NULL) { + RTE_ETHDEV_LOG_LINE(ERR, "Stashing hints are not implemented " + "in %s for %s", dev_info.driver_name, + dev_info.device->name); + return -ENOSYS; + } + return eth_err(port_id, + (*dev->dev_ops->discover_stashing_hints) + (dev, types, hints)); +} + RTE_LOG_REGISTER_DEFAULT(rte_eth_dev_logtype, INFO); diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h index 548fada1c7..a42f272885 100644 --- a/lib/ethdev/rte_ethdev.h +++ b/lib/ethdev/rte_ethdev.h @@ -1648,6 +1648,9 @@ struct rte_eth_conf { #define RTE_ETH_DEV_CAPA_FLOW_SHARED_OBJECT_KEEP RTE_BIT64(4) /**@}*/ +/** Device supports stashing to CPU/system caches. */ +#define RTE_ETH_DEV_CAPA_CACHE_STASHING RTE_BIT64(5) + /* * Fallback default preferred Rx/Tx port parameters. * These are used if an application requests default parameters @@ -1819,6 +1822,8 @@ struct rte_eth_dev_info { struct rte_eth_dev_portconf default_txportconf; /** Generic device capabilities (RTE_ETH_DEV_CAPA_). */ uint64_t dev_capa; + uint16_t stashing_hints_capa; + uint16_t stashing_types_capa; /** * Switching information for ports on a device with a * embedded managed interconnect/switch. @@ -5964,6 +5969,226 @@ int rte_eth_cman_config_set(uint16_t port_id, const struct rte_eth_cman_config * __rte_experimental int rte_eth_cman_config_get(uint16_t port_id, struct rte_eth_cman_config *config); + + +/** Queue type is RX. */ +#define RTE_ETH_DEV_QUEUE_TYPE_RX 0 +/** Queue type is TX. */ +#define RTE_ETH_DEV_QUEUE_TYPE_TX 1 + +/**@{@name Ethernet device cache stashing hints + *@see rte_eth_dev_stashing_hints_discover + *@see rte_eth_dev_stashing_hints_rx + *@see rte_eth_dev_stashing_hints_tx + */ +/** + * Data read by the device could still be in a CPU local cache memory but + * not required by the CPU before ethernet device is done with Tx. + * In other words CPU does not mind evicting the relevant cache line(s) + * from it's local cache. + */ +#define RTE_ETH_DEV_STASH_HINT_HOST_DONTNEED 0x001 + +/** + * Data is read and written equally by the CPU and the NIC. + */ +#define RTE_ETH_DEV_STASH_HINT_BI_DIR_DATA 0x100 + +/** + * Data written by the device is read by a CPU immediately. CPU prefers + * availability of the data in it's local cache memory by the time read + * takes place. + */ +#define RTE_ETH_DEV_STASH_HINT_HOST_WILLNEED 0x010 + +/** + * Data written by the device is only read by device. + * Host CPUs do not read this data or write to the location of the data. + */ +#define RTE_ETH_DEV_STASH_HINT_DEV_ONLY 0x200 + + +#define __RTE_ETH_DEV_STASH_HINT_TX_MASK 0x00f + +#define __RTE_ETH_DEV_STASH_HINT_RX_MASK 0x0f0 + +#define __RTE_ETH_DEV_STASH_HINT_RXTX_MASK 0xf00 + + +/**@}*/ + +#define RTE_ETH_DEV_STASH_HINT_IS_TX(h) \ + ((!((h) & ~(__RTE_ETH_DEV_STASH_HINT_TX_MASK))) && (h)) + +#define RTE_ETH_DEV_STASH_HINT_IS_RX(h) \ + ((!((h) & ~(__RTE_ETH_DEV_STASH_HINT_RX_MASK))) && (h)) + +#define RTE_ETH_DEV_STASH_HINT_IS_RXTX(h) \ + ((!((h) & ~(__RTE_ETH_DEV_STASH_HINT_RXTX_MASK))) && (h)) + +/**@{@name Stashable Rx/Tx queue object types supported by the ethernet device + *@see rte_eth_dev_stashing_hints_discover + *@see rte_eth_dev_stashing_hints_rx + *@see rte_eth_dev_stashing_hints_tx + */ + +/** + * Apply stashing hint to data at a given offset from the start of a + * received packet. + */ +#define RTE_ETH_DEV_STASH_TYPE_OFFSET 0x0001 + +/** Apply stashing hint to an rx descriptor. */ +#define RTE_ETH_DEV_STASH_TYPE_DESC 0x0002 + +/** Apply stashing hint to a header of a received packet. */ +#define RTE_ETH_DEV_STASH_TYPE_HEADER 0x0004 + +/** Apply stashing hint to a payload of a received packet. */ +#define RTE_ETH_DEV_STASH_TYPE_PAYLOAD 0x0008 +#define __RTE_ETH_DEV_STASH_TYPE_MASK 0x000f +/**@}*/ + +#define RTE_ETH_DEV_STASH_TYPE_VALID(t) \ + ((!((t) & (~__RTE_ETH_DEV_STASH_TYPE_MASK))) && (t)) + +/** + * + * @warning + * @b EXPERIMENTAL: this API may change, or be removed, without prior notice + * + * @internal + * Helper function to validate stashing hints. + */ +__rte_experimental +int rte_eth_dev_validate_stashing_hints(uint16_t port_id, uint16_t queue_id, + uint8_t queue_direction, uint16_t type, + uint16_t hint); +/** + * + * @warning + * @b EXPERIMENTAL: this API may change, or be removed, without prior notice + * + * Provide cache stashing hints for improved memory access latencies for + * packets received by the NIC. Hints the underlying hardware that CPU indicated + * in cpuid parameter prefers to have the data specified in the type parameter + * at a level in the memory hierarchy specified in cache_level parameter for + * access pattern(s) specified in hints parameter. + * This feature is available only in supported NICs and platforms. + * + * @param port_id + * The port identifier of the Ethernet device. + * @param cpuid + * ID of the targeted CPU for the hint. + * @param cache_level + * The preferred level of the cache the packets are expected at the time of + * retrieval. + * @param queue_id + * The index of the receive queue to which hints are applied. + * @param types + * A vector of stashing types to apply hints on receive queue. + * Hints are applied on the types specified in types vector. + * types can include receive queue descriptors (RTE_ETH_DEV_STASH_TYPE_DESC), + * packet headers (RTE_ETH_DEV_STASH_TYPE_HEADER), + * packet payloads (RTE_ETH_DEV_STASH_TYPE_PAYLOAD) or + * to an offset (RTE_ETH_DEV_STASH_TYPE_OFFSET) in to packet. + * Types used should be compatible with RX queues, if not -EINVAL will be + * returned. + * @param offset + * Offset into the packet if RTE_ETH_DEV_STASH_TYPE_RX_OFFSET is set in hints. + * @param hints + * A vector of stashing hints to the device and the platform. + * @return + * - (-ENODEV) on incorrect port_ids. + * - (-EINVAL) if both RX and TX types are used in conjuection in type + * parameter. + * - (-EINVAL) if hints are incompatible with RX queues. + * - (-EINVAL) on invalid queue_id. + * - (-ENOTSUP) if RTE_ETH_DEV_CAPA_CACHE_STASHING capability is unavailable. + * - (-ENOSYS) if PMD does not implement cache stashing hints. + * - (0) on Success. + */ +__rte_experimental +int rte_eth_dev_stashing_hints_rx(uint16_t port_id, uint16_t cpuid, + uint8_t cache_level, uint16_t queue_id, + uint16_t types, off_t offset, uint16_t hints); + +/** + * + * @warning + * @b EXPERIMENTAL: this API may change, or be removed, without prior notice + * + * Provide cache stashing hints for improved memory access latencies for + * packets being transmitted by the NIC. Hints the underlying hardware that CPU + * prefers to have the data specified in the type parameter at a level in the + * memory hierarchy specified in cache_level parameter for an access pattern + * specified in hints parameter. + * This feature is available only in supported NICs and platforms. + * + * @param port_id + * The port identifier of the Ethernet device. + * @param cpuid + * ID of the targeted CPU for the hint. + * @param cache_level + * The preferred level of the cache the packets are expected at the time of + * transmission. + * @param queue_id + * The index of the transmit queue which hints are applied to. + * @param types + * A vector of stashing types to apply hints on transmit queue. + * hints are applied on types specified in types vector. + * types can innclude transmit queue descriptors (RTE_ETH_DEV_STASH_TYPE_DESC), + * packet headers (RTE_ETH_DEV_STASH_TYPE_HEADER), + * packet payloads (RTE_ETH_DEV_STASH_TYPE_PAYLOAD) or + * to an offset (RTE_ETH_DEV_STASH_TYPE_OFFSET) in to packet. + * Types used should be compatible with TX queues, if not -EINVAL will be + * returned. + * @param offset + * Offset into the packet if RTE_ETH_DEV_STASH_TYPE_RX_OFFSET is set in hints. + * @param hints + * A vector of stashing hints to the device and the platform. + * @return + * - (-ENODEV) on incorrect port_ids. + * - (-EINVAL) if both RX and TX types are used in conjuection in type + * parameter. + * - (-EINVAL) if hints are incompatible with TX queues. + * - (-EINVAL) on invalid queue_id. + * - (-ENOTSUP) if RTE_ETH_DEV_CAPA_CACHE_STASHING capability is unavailable. + * - (-ENOSYS) if PMD does not implement cache stashing hints. + * - (0) on Success. + */ +__rte_experimental +int rte_eth_dev_stashing_hints_tx(uint16_t port_id, uint16_t cpuid, + uint8_t cache_level, uint16_t queue_id, + uint16_t types, off_t offset, uint16_t hints); + +/** + * + * @warning + * @b EXPERIMENTAL: this API may change, or be removed, without prior notice + * + * Discover cache stashing hints and object types supported in the ethernet + * device. + * + * @param port_id + * The port identifier of the Ethernet device. + * @param types + * Supported types vector set by the ethernet device. + * @param hints + * Supported hints vector set by the ethernet device. + * @return + * On return types and hints parameters will have bits set for supported + * object types. + * - (-ENOTSUP) if the device or the platform does not support cache stashing. + * - (-ENOSYS) if the underlying PMD hasn't implemented cache stashing + * feature. + * - (-EINVAL) on NULL values for types or hints parameters. + * - (0) on success. + */ +__rte_experimental +int rte_eth_dev_stashing_hints_discover(uint16_t port_id, uint16_t *types, + uint16_t *hints); + #include /** diff --git a/lib/ethdev/version.map b/lib/ethdev/version.map index 79f6f5293b..5eef0b4540 100644 --- a/lib/ethdev/version.map +++ b/lib/ethdev/version.map @@ -325,6 +325,12 @@ EXPERIMENTAL { rte_flow_template_table_resizable; rte_flow_template_table_resize; rte_flow_template_table_resize_complete; + + # added in 24.07 + rte_eth_dev_stashing_hints_rx; + rte_eth_dev_stashing_hints_tx; + rte_eth_dev_stashing_hints_discover; + rte_eth_dev_validate_stashing_hints; }; INTERNAL { -- 2.34.1