From patchwork Thu Jan 18 13:45:51 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 135954 X-Patchwork-Delegate: jerinj@marvell.com Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 06449438F3; Thu, 18 Jan 2024 14:46:20 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id F35BF42D9D; Thu, 18 Jan 2024 14:46:15 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [198.175.65.13]) by mails.dpdk.org (Postfix) with ESMTP id 03B4F40285 for ; Thu, 18 Jan 2024 14:46:13 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1705585574; x=1737121574; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=WPaCCs7XUYug4BgpoKg8uxcxnhqUYNt7+Ihn9a6O3FM=; b=C8I4jo+bUVOPiRLqTP/i3sVDSbMrrWSAG2aAP2US1v71TgGfHu+2F4LH R9AMTxY4tOvzkob30BpfQyI3kXYISi5Y0DxkzuAInYwmGSZX7eT/xvCxd dOQeUZKAGVLY9yoWaKIvScHIeoom+JHN9pribb4h7hhUnox4wZgqfatx4 hk1ysed/Qd6czdRGo0E53PtB+AjUckuMhk6SdbEbes85sjZKmj47uWK0q RH0BBPzgfGITmosYQszeI3pj3kA7JUSZ9h6vcwQxV+q2vrq6D45iSb2LD D4DBEC/Sdbb/K6Pao4BdT0tW59qqSNXdSRAqgjPdBzCTOZUnhTKZbY8L/ Q==; X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="7542765" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="7542765" Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orvoesa105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 18 Jan 2024 05:46:14 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="734274125" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="734274125" Received: from silpixa00400957.ir.intel.com (HELO silpixa00401385.ir.intel.com) ([10.237.214.26]) by orsmga003.jf.intel.com with ESMTP; 18 Jan 2024 05:46:12 -0800 From: Bruce Richardson To: dev@dpdk.org Cc: Bruce Richardson , Jerin Jacob Subject: [PATCH v1 1/7] eventdev: improve doxygen introduction text Date: Thu, 18 Jan 2024 13:45:51 +0000 Message-Id: <20240118134557.73172-2-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240118134557.73172-1-bruce.richardson@intel.com> References: <20240118134557.73172-1-bruce.richardson@intel.com> MIME-Version: 1.0 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 Make some textual improvements to the introduction to eventdev and event devices in the eventdev header file. This text appears in the doxygen output for the header file, and introduces the key concepts, for example: events, event devices, queues, ports and scheduling. This patch makes the following improvements: * small textual fixups, e.g. correcting use of singular/plural * rewrites of some sentences to improve clarity * using doxygen markdown to split the whole large block up into sections, thereby making it easier to read. No large-scale changes are made, and blocks are not reordered Signed-off-by: Bruce Richardson --- lib/eventdev/rte_eventdev.h | 112 +++++++++++++++++++++--------------- 1 file changed, 66 insertions(+), 46 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index ec9b02455d..a36c89c7a4 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -12,12 +12,13 @@ * @file * * RTE Event Device API + * ==================== * * In a polling model, lcores poll ethdev ports and associated rx queues - * directly to look for packet. In an event driven model, by contrast, lcores - * call the scheduler that selects packets for them based on programmer - * specified criteria. Eventdev library adds support for event driven - * programming model, which offer applications automatic multicore scaling, + * directly to look for packets. In an event driven model, in contrast, lcores + * call a scheduler that selects packets for them based on programmer + * specified criteria. The eventdev library adds support for the event driven + * programming model, which offers applications automatic multicore scaling, * dynamic load balancing, pipelining, packet ingress order maintenance and * synchronization services to simplify application packet processing. * @@ -25,12 +26,15 @@ * * - The application-oriented Event API that includes functions to setup * an event device (configure it, setup its queues, ports and start it), to - * establish the link between queues to port and to receive events, and so on. + * establish the links between queues and ports to receive events, and so on. * * - The driver-oriented Event API that exports a function allowing - * an event poll Mode Driver (PMD) to simultaneously register itself as + * an event poll Mode Driver (PMD) to register itself as * an event device driver. * + * Application-oriented Event API + * ------------------------------ + * * Event device components: * * +-----------------+ @@ -75,27 +79,33 @@ * | | * +-----------------------------------------------------------+ * - * Event device: A hardware or software-based event scheduler. + * **Event device**: A hardware or software-based event scheduler. * - * Event: A unit of scheduling that encapsulates a packet or other datatype - * like SW generated event from the CPU, Crypto work completion notification, - * Timer expiry event notification etc as well as metadata. - * The metadata includes flow ID, scheduling type, event priority, event_type, + * **Event**: A unit of scheduling that encapsulates a packet or other datatype, + * such as: SW generated event from the CPU, crypto work completion notification, + * timer expiry event notification etc., as well as metadata about the packet or data. + * The metadata includes a flow ID (if any), scheduling type, event priority, event_type, * sub_event_type etc. * - * Event queue: A queue containing events that are scheduled by the event dev. + * **Event queue**: A queue containing events that are scheduled by the event device. * An event queue contains events of different flows associated with scheduling * types, such as atomic, ordered, or parallel. + * Each event given to an eventdev must have a valid event queue id field in the metadata, + * to specify on which event queue in the device the event must be placed, + * for later scheduling to a core. * - * Event port: An application's interface into the event dev for enqueue and + * **Event port**: An application's interface into the event dev for enqueue and * dequeue operations. Each event port can be linked with one or more * event queues for dequeue operations. - * - * By default, all the functions of the Event Device API exported by a PMD - * are lock-free functions which assume to not be invoked in parallel on - * different logical cores to work on the same target object. For instance, - * the dequeue function of a PMD cannot be invoked in parallel on two logical - * cores to operates on same event port. Of course, this function + * Each port should be associated with a single core (enqueue and dequeue is not thread-safe). + * To schedule events to a core, the event device will schedule them to the event port(s) + * being polled by that core. + * + * *NOTE*: By default, all the functions of the Event Device API exported by a PMD + * are lock-free functions, which must not be invoked on the same object in parallel on + * different logical cores. + * For instance, the dequeue function of a PMD cannot be invoked in parallel on two logical + * cores to operate on same event port. Of course, this function * can be invoked in parallel by different logical cores on different ports. * It is the responsibility of the upper level application to enforce this rule. * @@ -107,22 +117,19 @@ * * Event devices are dynamically registered during the PCI/SoC device probing * phase performed at EAL initialization time. - * When an Event device is being probed, a *rte_event_dev* structure and - * a new device identifier are allocated for that device. Then, the - * event_dev_init() function supplied by the Event driver matching the probed - * device is invoked to properly initialize the device. + * When an Event device is being probed, an *rte_event_dev* structure is allocated + * for it and the event_dev_init() function supplied by the Event driver + * is invoked to properly initialize the device. * - * The role of the device init function consists of resetting the hardware or - * software event driver implementations. + * The role of the device init function is to reset the device hardware or + * to initialize the software event driver implementation. * - * If the device init operation is successful, the correspondence between - * the device identifier assigned to the new device and its associated - * *rte_event_dev* structure is effectively registered. - * Otherwise, both the *rte_event_dev* structure and the device identifier are - * freed. + * If the device init operation is successful, the device is assigned a device + * id (dev_id) for application use. + * Otherwise, the *rte_event_dev* structure is freed. * * The functions exported by the application Event API to setup a device - * designated by its device identifier must be invoked in the following order: + * must be invoked in the following order: * - rte_event_dev_configure() * - rte_event_queue_setup() * - rte_event_port_setup() @@ -130,10 +137,15 @@ * - rte_event_dev_start() * * Then, the application can invoke, in any order, the functions - * exported by the Event API to schedule events, dequeue events, enqueue events, - * change event queue(s) to event port [un]link establishment and so on. - * - * Application may use rte_event_[queue/port]_default_conf_get() to get the + * exported by the Event API to dequeue events, enqueue events, + * and link and unlink event queue(s) to event ports. + * + * Before configuring a device, an application should call rte_event_dev_info_get() + * to determine the capabilities of the event device, and any queue or port + * limits of that device. The parameters set in the various device configuration + * structures may need to be adjusted based on the max values provided in the + * device information structure returned from the info_get API. + * An application may use rte_event_[queue/port]_default_conf_get() to get the * default configuration to set up an event queue or event port by * overriding few default values. * @@ -145,7 +157,11 @@ * when the device is stopped. * * Finally, an application can close an Event device by invoking the - * rte_event_dev_close() function. + * rte_event_dev_close() function. Once closed, a device cannot be + * reconfigured or restarted. + * + * Driver-Oriented Event API + * ------------------------- * * Each function of the application Event API invokes a specific function * of the PMD that controls the target device designated by its device @@ -164,10 +180,13 @@ * supplied in the *event_dev_ops* structure of the *rte_event_dev* structure. * * For performance reasons, the address of the fast-path functions of the - * Event driver is not contained in the *event_dev_ops* structure. + * Event driver are not contained in the *event_dev_ops* structure. * Instead, they are directly stored at the beginning of the *rte_event_dev* * structure to avoid an extra indirect memory access during their invocation. * + * Event Enqueue, Dequeue and Scheduling + * ------------------------------------- + * * RTE event device drivers do not use interrupts for enqueue or dequeue * operation. Instead, Event drivers export Poll-Mode enqueue and dequeue * functions to applications. @@ -179,21 +198,22 @@ * crypto work completion notification etc * * The *dequeue* operation gets one or more events from the event ports. - * The application process the events and send to downstream event queue through - * rte_event_enqueue_burst() if it is an intermediate stage of event processing, - * on the final stage, the application may use Tx adapter API for maintaining - * the ingress order and then send the packet/event on the wire. + * The application processes the events and sends them to a downstream event queue through + * rte_event_enqueue_burst(), if it is an intermediate stage of event processing. + * On the final stage of processing, the application may use the Tx adapter API for maintaining + * the event ingress order while sending the packet/event on the wire via NIC Tx. * * The point at which events are scheduled to ports depends on the device. * For hardware devices, scheduling occurs asynchronously without any software * intervention. Software schedulers can either be distributed * (each worker thread schedules events to its own port) or centralized * (a dedicated thread schedules to all ports). Distributed software schedulers - * perform the scheduling in rte_event_dequeue_burst(), whereas centralized - * scheduler logic need a dedicated service core for scheduling. - * The RTE_EVENT_DEV_CAP_DISTRIBUTED_SCHED capability flag is not set - * indicates the device is centralized and thus needs a dedicated scheduling - * thread that repeatedly calls software specific scheduling function. + * perform the scheduling inside the enqueue or dequeue functions, whereas centralized + * software schedulers need a dedicated service core for scheduling. + * The absence of the RTE_EVENT_DEV_CAP_DISTRIBUTED_SCHED capability flag + * indicates that the device is centralized and thus needs a dedicated scheduling + * thread, generally a service core, + * that repeatedly calls the software specific scheduling function. * * An event driven worker thread has following typical workflow on fastpath: * \code{.c} From patchwork Thu Jan 18 13:45:52 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 135955 X-Patchwork-Delegate: jerinj@marvell.com Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id C99CB438F3; Thu, 18 Jan 2024 14:46:26 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 1A87542DA6; Thu, 18 Jan 2024 14:46:17 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [198.175.65.13]) by mails.dpdk.org (Postfix) with ESMTP id 9F87D42D89 for ; Thu, 18 Jan 2024 14:46:15 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1705585576; x=1737121576; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=y2Ve+nG3X8nOWMsHnECp86Z1V/xau0sRwjR7SSfULMo=; b=bTHtxTloQ6LF8vUvnYTOFUi3zBOhTJBm0R/oI+HnX50s5HaySnRR5lHy SZwvjo5Fj3JiC65ITdzJUuRCDmnKyGPUbAzR0mRYUDat3x3n3gXE5Ohif 98q9FMnsK/yYS8DBo04X3kGtdYVjpiSeJDmiKbgJ4O4NHgblFdOb8pVgz BHfwlblV/r7GP0wxsNr1nZ6aXyUv0XLflsSEexfmY9jwaOi5t/FdLIUl1 LU9wbG2u7eGwrIH/ivI8v+wOpAEf8/yygEGpF2UHFhs+fMSKvClm/KXaW YLiYkhTw1XWYRKJufDsCFru3rTb3ZW/IpIRhGfwyx5ZpANa00bj9a8gle g==; X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="7542773" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="7542773" Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orvoesa105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 18 Jan 2024 05:46:15 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="734274132" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="734274132" Received: from silpixa00400957.ir.intel.com (HELO silpixa00401385.ir.intel.com) ([10.237.214.26]) by orsmga003.jf.intel.com with ESMTP; 18 Jan 2024 05:46:13 -0800 From: Bruce Richardson To: dev@dpdk.org Cc: Bruce Richardson , Jerin Jacob Subject: [PATCH v1 2/7] eventdev: move text on driver internals to proper section Date: Thu, 18 Jan 2024 13:45:52 +0000 Message-Id: <20240118134557.73172-3-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240118134557.73172-1-bruce.richardson@intel.com> References: <20240118134557.73172-1-bruce.richardson@intel.com> MIME-Version: 1.0 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 Inside the doxygen introduction text, some internal details of how eventdev works was mixed in with application-relevant details. Move these details on probing etc. to the driver-relevant section. Signed-off-by: Bruce Richardson --- lib/eventdev/rte_eventdev.h | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index a36c89c7a4..949e957f1b 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -112,22 +112,6 @@ * In all functions of the Event API, the Event device is * designated by an integer >= 0 named the device identifier *dev_id* * - * At the Event driver level, Event devices are represented by a generic - * data structure of type *rte_event_dev*. - * - * Event devices are dynamically registered during the PCI/SoC device probing - * phase performed at EAL initialization time. - * When an Event device is being probed, an *rte_event_dev* structure is allocated - * for it and the event_dev_init() function supplied by the Event driver - * is invoked to properly initialize the device. - * - * The role of the device init function is to reset the device hardware or - * to initialize the software event driver implementation. - * - * If the device init operation is successful, the device is assigned a device - * id (dev_id) for application use. - * Otherwise, the *rte_event_dev* structure is freed. - * * The functions exported by the application Event API to setup a device * must be invoked in the following order: * - rte_event_dev_configure() @@ -163,6 +147,22 @@ * Driver-Oriented Event API * ------------------------- * + * At the Event driver level, Event devices are represented by a generic + * data structure of type *rte_event_dev*. + * + * Event devices are dynamically registered during the PCI/SoC device probing + * phase performed at EAL initialization time. + * When an Event device is being probed, an *rte_event_dev* structure is allocated + * for it and the event_dev_init() function supplied by the Event driver + * is invoked to properly initialize the device. + * + * The role of the device init function is to reset the device hardware or + * to initialize the software event driver implementation. + * + * If the device init operation is successful, the device is assigned a device + * id (dev_id) for application use. + * Otherwise, the *rte_event_dev* structure is freed. + * * Each function of the application Event API invokes a specific function * of the PMD that controls the target device designated by its device * identifier. From patchwork Thu Jan 18 13:45:53 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 135956 X-Patchwork-Delegate: jerinj@marvell.com Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id E0B0C438F3; Thu, 18 Jan 2024 14:46:33 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 5382142D9A; Thu, 18 Jan 2024 14:46:19 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [198.175.65.13]) by mails.dpdk.org (Postfix) with ESMTP id 6080842DAC for ; Thu, 18 Jan 2024 14:46:17 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1705585577; x=1737121577; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=5rbLLqD8oaCo0oh2qcgy4Y/lFT/lNjrP4dPiU/DsDAU=; b=LmHW0b9c7C7+bHNP4XVa5XIl03FO2JIzJold6XDnl0vbM09jMsl+A5PV xELyExiMIYuUR+hooSCSdmVasTxDzea9674HFfsCyW8Sc101zr8ie6lSU 2L1AlyTbMXVNmq6vcNjI3Q5JKJv7jtMWXCBx+Epnp1/02KDIKHxcKZfuG If1CUMtBlSgeeazYYLsdrjDQADKp9Q2+lfG+tSOtMTcdol+ZZCm7LqjIA QSQ6UFVGC/O8cfvnvHOO5pLe+AANpKyoB0jYd7qyh3VZSZIkVaip+hYip 2S0m/+sG5vDvD6/kfc7NwjxVL4lTi5x47z51dS7znQiFR01jph0BOeWQp A==; X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="7542779" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="7542779" Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orvoesa105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 18 Jan 2024 05:46:17 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="734274136" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="734274136" Received: from silpixa00400957.ir.intel.com (HELO silpixa00401385.ir.intel.com) ([10.237.214.26]) by orsmga003.jf.intel.com with ESMTP; 18 Jan 2024 05:46:15 -0800 From: Bruce Richardson To: dev@dpdk.org Cc: Bruce Richardson , Jerin Jacob Subject: [PATCH v1 3/7] eventdev: update documentation on device capability flags Date: Thu, 18 Jan 2024 13:45:53 +0000 Message-Id: <20240118134557.73172-4-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240118134557.73172-1-bruce.richardson@intel.com> References: <20240118134557.73172-1-bruce.richardson@intel.com> MIME-Version: 1.0 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 Update the device capability docs, to: * include more cross-references * split longer text into paragraphs, in most cases with each flag having a single-line summary at the start of the doc block * general comment rewording and clarification as appropriate Signed-off-by: Bruce Richardson --- lib/eventdev/rte_eventdev.h | 130 ++++++++++++++++++++++++++---------- 1 file changed, 93 insertions(+), 37 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index 949e957f1b..57a2791946 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -243,143 +243,199 @@ struct rte_event; /* Event device capability bitmap flags */ #define RTE_EVENT_DEV_CAP_QUEUE_QOS (1ULL << 0) /**< Event scheduling prioritization is based on the priority and weight - * associated with each event queue. Events from a queue with highest priority - * is scheduled first. If the queues are of same priority, weight of the queues + * associated with each event queue. + * + * Events from a queue with highest priority + * are scheduled first. If the queues are of same priority, weight of the queues * are considered to select a queue in a weighted round robin fashion. * Subsequent dequeue calls from an event port could see events from the same * event queue, if the queue is configured with an affinity count. Affinity * count is the number of subsequent dequeue calls, in which an event port * should use the same event queue if the queue is non-empty * + * NOTE: A device may use both queue prioritization and event prioritization + * (@ref RTE_EVENT_DEV_CAP_EVENT_QOS capability) when making packet scheduling decisions. + * * @see rte_event_queue_setup(), rte_event_queue_attr_set() */ #define RTE_EVENT_DEV_CAP_EVENT_QOS (1ULL << 1) /**< Event scheduling prioritization is based on the priority associated with - * each event. Priority of each event is supplied in *rte_event* structure + * each event. + * + * Priority of each event is supplied in *rte_event* structure * on each enqueue operation. + * If this capability is not set, the priority field of the event structure + * is ignored for each event. * + * NOTE: A device may use both queue prioritization (@ref RTE_EVENT_DEV_CAP_QUEUE_QOS capability) + * and event prioritization when making packet scheduling decisions. + * @see rte_event_enqueue_burst() */ #define RTE_EVENT_DEV_CAP_DISTRIBUTED_SCHED (1ULL << 2) /**< Event device operates in distributed scheduling mode. + * * In distributed scheduling mode, event scheduling happens in HW or - * rte_event_dequeue_burst() or the combination of these two. + * rte_event_dequeue_burst() / rte_event_enqueue_burst() or the combination of these two. * If the flag is not set then eventdev is centralized and thus needs a * dedicated service core that acts as a scheduling thread . * - * @see rte_event_dequeue_burst() + * @see rte_event_dev_service_id_get */ #define RTE_EVENT_DEV_CAP_QUEUE_ALL_TYPES (1ULL << 3) /**< Event device is capable of enqueuing events of any type to any queue. + * * If this capability is not set, the queue only supports events of the - * *RTE_SCHED_TYPE_* type that it was created with. + * *RTE_SCHED_TYPE_* type that it was created with. + * Any events of other types scheduled to the queue will handled in an + * implementation-dependent manner. They may be dropped by the + * event device, or enqueued with the scheduling type adjusted to the + * correct/supported value. * - * @see RTE_SCHED_TYPE_* values + * @see rte_event_enqueue_burst + * @see RTE_SCHED_TYPE_ATOMIC RTE_SCHED_TYPE_ORDERED RTE_SCHED_TYPE_PARALLEL */ #define RTE_EVENT_DEV_CAP_BURST_MODE (1ULL << 4) /**< Event device is capable of operating in burst mode for enqueue(forward, - * release) and dequeue operation. If this capability is not set, application - * still uses the rte_event_dequeue_burst() and rte_event_enqueue_burst() but - * PMD accepts only one event at a time. + * release) and dequeue operation. + * + * If this capability is not set, application + * can still use the rte_event_dequeue_burst() and rte_event_enqueue_burst() but + * PMD accepts or returns only one event at a time. * * @see rte_event_dequeue_burst() rte_event_enqueue_burst() */ #define RTE_EVENT_DEV_CAP_IMPLICIT_RELEASE_DISABLE (1ULL << 5) /**< Event device ports support disabling the implicit release feature, in * which the port will release all unreleased events in its dequeue operation. + * * If this capability is set and the port is configured with implicit release * disabled, the application is responsible for explicitly releasing events - * using either the RTE_EVENT_OP_FORWARD or the RTE_EVENT_OP_RELEASE event + * using either the @ref RTE_EVENT_OP_FORWARD or the @ref RTE_EVENT_OP_RELEASE event * enqueue operations. * * @see rte_event_dequeue_burst() rte_event_enqueue_burst() */ #define RTE_EVENT_DEV_CAP_NONSEQ_MODE (1ULL << 6) -/**< Event device is capable of operating in none sequential mode. The path - * of the event is not necessary to be sequential. Application can change - * the path of event at runtime. If the flag is not set, then event each event - * will follow a path from queue 0 to queue 1 to queue 2 etc. If the flag is - * set, events may be sent to queues in any order. If the flag is not set, the - * eventdev will return an error when the application enqueues an event for a +/**< Event device is capable of operating in non-sequential mode. + * + * The path of the event is not necessary to be sequential. Application can change + * the path of event at runtime and events may be sent to queues in any order. + * + * If the flag is not set, then event each event will follow a path from queue 0 + * to queue 1 to queue 2 etc. + * The eventdev will return an error when the application enqueues an event for a * qid which is not the next in the sequence. */ #define RTE_EVENT_DEV_CAP_RUNTIME_PORT_LINK (1ULL << 7) -/**< Event device is capable of configuring the queue/port link at runtime. +/**< Event device is capable of reconfiguring the queue/port link at runtime. + * * If the flag is not set, the eventdev queue/port link is only can be - * configured during initialization. + * configured during initialization, or by stopping the device and + * then later restarting it after reconfiguration. + * + * @see rte_event_port_link rte_event_port_unlink */ #define RTE_EVENT_DEV_CAP_MULTIPLE_QUEUE_PORT (1ULL << 8) -/**< Event device is capable of setting up the link between multiple queue - * with single port. If the flag is not set, the eventdev can only map a - * single queue to each port or map a single queue to many port. +/**< Event device is capable of setting up links between multiple queues and a single port. + * + * If the flag is not set, each port may only be linked to a single queue, and + * so can only receive events from that queue. + * However, each queue may be linked to multiple ports. + * + * @see rte_event_port_link */ #define RTE_EVENT_DEV_CAP_CARRY_FLOW_ID (1ULL << 9) -/**< Event device preserves the flow ID from the enqueued - * event to the dequeued event if the flag is set. Otherwise, - * the content of this field is implementation dependent. +/**< Event device preserves the flow ID from the enqueued event to the dequeued event. + * + * If this flag is not set, + * the content of the flow-id field in dequeued events is implementation dependent. + * + * @see rte_event_dequeue_burst */ #define RTE_EVENT_DEV_CAP_MAINTENANCE_FREE (1ULL << 10) /**< Event device *does not* require calls to rte_event_maintain(). + * * An event device that does not set this flag requires calls to * rte_event_maintain() during periods when neither * rte_event_dequeue_burst() nor rte_event_enqueue_burst() are called * on a port. This will allow the event device to perform internal * processing, such as flushing buffered events, return credits to a * global pool, or process signaling related to load balancing. + * + * @see rte_event_maintain */ #define RTE_EVENT_DEV_CAP_RUNTIME_QUEUE_ATTR (1ULL << 11) /**< Event device is capable of changing the queue attributes at runtime i.e - * after rte_event_queue_setup() or rte_event_start() call sequence. If this - * flag is not set, eventdev queue attributes can only be configured during + * after rte_event_queue_setup() or rte_event_dev_start() call sequence. + * + * If this flag is not set, eventdev queue attributes can only be configured during * rte_event_queue_setup(). + * + * @see rte_event_queue_setup */ #define RTE_EVENT_DEV_CAP_PROFILE_LINK (1ULL << 12) -/**< Event device is capable of supporting multiple link profiles per event port - * i.e., the value of `rte_event_dev_info::max_profiles_per_port` is greater - * than one. +/**< Event device is capable of supporting multiple link profiles per event port. + * + * + * When set, the value of `rte_event_dev_info::max_profiles_per_port` is greater + * than one, and multiple profiles may be configured and then switched at runtime. + * If not set, only a single profile may be configured, which may itself be + * runtime adjustable (if @ref RTE_EVENT_DEV_CAP_RUNTIME_PORT_LINK is set). + * + * @see rte_event_port_profile_links_set rte_event_port_profile_links_get + * @see rte_event_port_profile_switch + * @see RTE_EVENT_DEV_CAP_RUNTIME_PORT_LINK */ /* Event device priority levels */ #define RTE_EVENT_DEV_PRIORITY_HIGHEST 0 -/**< Highest priority expressed across eventdev subsystem +/**< Highest priority expressed across eventdev subsystem. + * * @see rte_event_queue_setup(), rte_event_enqueue_burst() * @see rte_event_port_link() */ #define RTE_EVENT_DEV_PRIORITY_NORMAL 128 -/**< Normal priority expressed across eventdev subsystem +/**< Normal priority expressed across eventdev subsystem. + * * @see rte_event_queue_setup(), rte_event_enqueue_burst() * @see rte_event_port_link() */ #define RTE_EVENT_DEV_PRIORITY_LOWEST 255 -/**< Lowest priority expressed across eventdev subsystem +/**< Lowest priority expressed across eventdev subsystem. + * * @see rte_event_queue_setup(), rte_event_enqueue_burst() * @see rte_event_port_link() */ /* Event queue scheduling weights */ #define RTE_EVENT_QUEUE_WEIGHT_HIGHEST 255 -/**< Highest weight of an event queue +/**< Highest weight of an event queue. + * * @see rte_event_queue_attr_get(), rte_event_queue_attr_set() */ #define RTE_EVENT_QUEUE_WEIGHT_LOWEST 0 -/**< Lowest weight of an event queue +/**< Lowest weight of an event queue. + * * @see rte_event_queue_attr_get(), rte_event_queue_attr_set() */ /* Event queue scheduling affinity */ #define RTE_EVENT_QUEUE_AFFINITY_HIGHEST 255 -/**< Highest scheduling affinity of an event queue +/**< Highest scheduling affinity of an event queue. + * * @see rte_event_queue_attr_get(), rte_event_queue_attr_set() */ #define RTE_EVENT_QUEUE_AFFINITY_LOWEST 0 -/**< Lowest scheduling affinity of an event queue +/**< Lowest scheduling affinity of an event queue. + * * @see rte_event_queue_attr_get(), rte_event_queue_attr_set() */ From patchwork Thu Jan 18 13:45:54 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 135957 X-Patchwork-Delegate: jerinj@marvell.com Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id CA520438F3; Thu, 18 Jan 2024 14:46:44 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id CA3A142DC4; Thu, 18 Jan 2024 14:46:21 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [198.175.65.13]) by mails.dpdk.org (Postfix) with ESMTP id 10BBF42DAC for ; Thu, 18 Jan 2024 14:46:18 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1705585580; x=1737121580; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=11aSEg2nL6//uztpAIuumf7gXQju8+rBk/EBkxQm5ro=; b=NYzm2czZFVHLCtV2/pr5o7fTIbPMX+zxJUQ7vmUfJRs3oPyle/gr9GUk uGoEi1LbcoCsEX0fytq9GVNT61BESwit1s6MrLvve5XlqlIh29izWEHls +9V9uFbyn0Z1IE801361ksDHj8t/p+GzRv+/XnSvEGtVDysOZvSMqa3X5 FHgvrGUi+tjCpQQjqlDIGMZXOSGilUVzYrm5KOtxcx2PlEOMoyiRqq0uJ EDIpXcs1oNf9pFbM1d81gxB0UWr4gA2VaEFdqWGz/ozQHOjgVUnPphPLK 8eQ9+EXxeQZ8mqUl2oMSsvzaTtb7+8Yms0g157KSmxJmGKD8UCuDi0OF1 w==; X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="7542790" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="7542790" Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orvoesa105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 18 Jan 2024 05:46:18 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="734274142" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="734274142" Received: from silpixa00400957.ir.intel.com (HELO silpixa00401385.ir.intel.com) ([10.237.214.26]) by orsmga003.jf.intel.com with ESMTP; 18 Jan 2024 05:46:17 -0800 From: Bruce Richardson To: dev@dpdk.org Cc: Bruce Richardson , Jerin Jacob Subject: [PATCH v1 4/7] eventdev: cleanup doxygen comments on info structure Date: Thu, 18 Jan 2024 13:45:54 +0000 Message-Id: <20240118134557.73172-5-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240118134557.73172-1-bruce.richardson@intel.com> References: <20240118134557.73172-1-bruce.richardson@intel.com> MIME-Version: 1.0 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 Some small rewording changes to the doxygen comments on struct rte_event_dev_info. Signed-off-by: Bruce Richardson --- lib/eventdev/rte_eventdev.c | 2 +- lib/eventdev/rte_eventdev.h | 46 ++++++++++++++++++++----------------- 2 files changed, 26 insertions(+), 22 deletions(-) diff --git a/lib/eventdev/rte_eventdev.c b/lib/eventdev/rte_eventdev.c index 94628a66ef..9bf7c7be89 100644 --- a/lib/eventdev/rte_eventdev.c +++ b/lib/eventdev/rte_eventdev.c @@ -83,7 +83,7 @@ rte_event_dev_socket_id(uint8_t dev_id) rte_eventdev_trace_socket_id(dev_id, dev, dev->data->socket_id); - return dev->data->socket_id; + return dev->data->socket_id < 0 ? 0 : dev->data->socket_id; } int diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index 57a2791946..872f241df2 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -482,54 +482,58 @@ struct rte_event_dev_info { const char *driver_name; /**< Event driver name */ struct rte_device *dev; /**< Device information */ uint32_t min_dequeue_timeout_ns; - /**< Minimum supported global dequeue timeout(ns) by this device */ + /**< Minimum global dequeue timeout(ns) supported by this device */ uint32_t max_dequeue_timeout_ns; - /**< Maximum supported global dequeue timeout(ns) by this device */ + /**< Maximum global dequeue timeout(ns) supported by this device */ uint32_t dequeue_timeout_ns; /**< Configured global dequeue timeout(ns) for this device */ uint8_t max_event_queues; - /**< Maximum event_queues supported by this device */ + /**< Maximum event queues supported by this device */ uint32_t max_event_queue_flows; - /**< Maximum supported flows in an event queue by this device*/ + /**< Maximum number of flows within an event queue supported by this device*/ uint8_t max_event_queue_priority_levels; /**< Maximum number of event queue priority levels by this device. - * Valid when the device has RTE_EVENT_DEV_CAP_QUEUE_QOS capability + * Valid when the device has RTE_EVENT_DEV_CAP_QUEUE_QOS capability. + * The priority levels are evenly distributed between + * @ref RTE_EVENT_DEV_PRIORITY_HIGHEST and @ref RTE_EVENT_DEV_PRIORITY_LOWEST. */ uint8_t max_event_priority_levels; /**< Maximum number of event priority levels by this device. * Valid when the device has RTE_EVENT_DEV_CAP_EVENT_QOS capability + * The priority levels are evenly distributed between + * @ref RTE_EVENT_DEV_PRIORITY_HIGHEST and @ref RTE_EVENT_DEV_PRIORITY_LOWEST. */ uint8_t max_event_ports; /**< Maximum number of event ports supported by this device */ uint8_t max_event_port_dequeue_depth; - /**< Maximum number of events can be dequeued at a time from an - * event port by this device. - * A device that does not support bulk dequeue will set this as 1. + /**< Maximum number of events that can be dequeued at a time from an event port + * on this device. + * A device that does not support bulk dequeue will set this to 1. */ uint32_t max_event_port_enqueue_depth; - /**< Maximum number of events can be enqueued at a time from an - * event port by this device. - * A device that does not support bulk enqueue will set this as 1. + /**< Maximum number of events that can be enqueued at a time to an event port + * on this device. + * A device that does not support bulk enqueue will set this to 1. */ uint8_t max_event_port_links; - /**< Maximum number of queues that can be linked to a single event - * port by this device. + /**< Maximum number of queues that can be linked to a single event port on this device. */ int32_t max_num_events; /**< A *closed system* event dev has a limit on the number of events it - * can manage at a time. An *open system* event dev does not have a - * limit and will specify this as -1. + * can manage at a time. + * Once the number of events tracked by an eventdev exceeds this number, + * any enqueues of NEW events will fail. + * An *open system* event dev does not have a limit and will specify this as -1. */ uint32_t event_dev_cap; - /**< Event device capabilities(RTE_EVENT_DEV_CAP_)*/ + /**< Event device capabilities flags (RTE_EVENT_DEV_CAP_*) */ uint8_t max_single_link_event_port_queue_pairs; - /**< Maximum number of event ports and queues that are optimized for - * (and only capable of) single-link configurations supported by this - * device. These ports and queues are not accounted for in - * max_event_ports or max_event_queues. + /**< Maximum number of event ports and queues, supported by this device, + * that are optimized for (and only capable of) single-link configurations. + * These ports and queues are not accounted for in max_event_ports or max_event_queues. */ uint8_t max_profiles_per_port; - /**< Maximum number of event queue profiles per event port. + /**< Maximum number of event queue link profiles per event port. * A device that doesn't support multiple profiles will set this as 1. */ }; From patchwork Thu Jan 18 13:45:55 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 135958 X-Patchwork-Delegate: jerinj@marvell.com Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 7E9B6438F3; Thu, 18 Jan 2024 14:46:52 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id F1D0242DA3; Thu, 18 Jan 2024 14:46:23 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [198.175.65.13]) by mails.dpdk.org (Postfix) with ESMTP id 877EE42DAC for ; Thu, 18 Jan 2024 14:46:20 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1705585581; x=1737121581; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=L5m5miMiYE21agROvRXl0A3v7/+usNFxKwe9mRepIpA=; b=RuJz57X1IiEHTxfAXLV2jG8OHQYROuYJC4OUlp432/pk9BFDAkSqWboC pAbuwAR/n29rSDTzhoM12WRx/x2fnlrvUlezblYcvO/bVJ53V6zL0JP3A kFeWwQLeWHxNJkLBzOOzn+tFq2InYmCtc0/Jm8W2Mm1sN6ltxtY7P3s3i qZEGJEZ8bDhAva83ss1VKntBmUXssvCZ4zhYnim62hUt5oZDuz+5seB9g qRBp7jog+M2mlbqcfiwZSB+qx/iINpAq6SBHGZxkUhhIeW5Y1YqK8lvKB 2lpuEXHwWnGvHy1Ud+rLUEtYs2CrBZzpF5D2R0Zsu46OZCWgFR0VLXF8l A==; X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="7542795" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="7542795" Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orvoesa105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 18 Jan 2024 05:46:20 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="734274148" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="734274148" Received: from silpixa00400957.ir.intel.com (HELO silpixa00401385.ir.intel.com) ([10.237.214.26]) by orsmga003.jf.intel.com with ESMTP; 18 Jan 2024 05:46:18 -0800 From: Bruce Richardson To: dev@dpdk.org Cc: Bruce Richardson , Jerin Jacob Subject: [PATCH v1 5/7] eventdev: improve function documentation for query fns Date: Thu, 18 Jan 2024 13:45:55 +0000 Message-Id: <20240118134557.73172-6-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240118134557.73172-1-bruce.richardson@intel.com> References: <20240118134557.73172-1-bruce.richardson@intel.com> MIME-Version: 1.0 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 General improvements to the doxygen docs for eventdev functions for querying basic information: * number of devices * id for a particular device * socket id of device * capability information for a device Signed-off-by: Bruce Richardson --- lib/eventdev/rte_eventdev.h | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index 872f241df2..c57c93a22e 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -440,8 +440,7 @@ struct rte_event; */ /** - * Get the total number of event devices that have been successfully - * initialised. + * Get the total number of event devices available for application use. * * @return * The total number of usable event devices. @@ -456,8 +455,10 @@ rte_event_dev_count(void); * Event device name to select the event device identifier. * * @return - * Returns event device identifier on success. - * - <0: Failure to find named event device. + * Event device identifier (dev_id >= 0) on success. + * Negative error code on failure: + * - -EINVAL - input name parameter is invalid + * - -ENODEV - no event device found with that name */ int rte_event_dev_get_dev_id(const char *name); @@ -470,7 +471,8 @@ rte_event_dev_get_dev_id(const char *name); * @return * The NUMA socket id to which the device is connected or * a default of zero if the socket could not be determined. - * -(-EINVAL) dev_id value is out of range. + * -EINVAL on error, where the given dev_id value does not + * correspond to any event device. */ int rte_event_dev_socket_id(uint8_t dev_id); @@ -539,18 +541,20 @@ struct rte_event_dev_info { }; /** - * Retrieve the contextual information of an event device. + * Retrieve details of an event device's capabilities and configuration limits. * * @param dev_id * The identifier of the device. * * @param[out] dev_info * A pointer to a structure of type *rte_event_dev_info* to be filled with the - * contextual information of the device. + * information about the device's capabilities. * * @return - * - 0: Success, driver updates the contextual information of the event device - * - <0: Error code returned by the driver info get function. + * - 0: Success, information about the event device is present in dev_info. + * - <0: Failure, error code returned by the function. + * - -EINVAL - invalid input parameters, e.g. incorrect device id + * - -ENOTSUP - device does not support returning capabilities information */ int rte_event_dev_info_get(uint8_t dev_id, struct rte_event_dev_info *dev_info); From patchwork Thu Jan 18 13:45:56 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 135959 X-Patchwork-Delegate: jerinj@marvell.com Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 27DB3438F3; Thu, 18 Jan 2024 14:46:59 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 30EB142DD1; Thu, 18 Jan 2024 14:46:25 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [198.175.65.13]) by mails.dpdk.org (Postfix) with ESMTP id 8EA8542DC9 for ; Thu, 18 Jan 2024 14:46:22 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1705585583; x=1737121583; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=VdnUqDrGM2/e2tMufxjZ0eJYKdinvpliMXZWcxc2voM=; b=ktjIasyoClXTB3bUteynrkWB9EWv9fFkbaASfwMoPoIjO8NVhAGtflRV PTWjKt36AUpwt/9eAMkzM65mUzetI5ysVAXviZqL1LQTSROoGVqAUbKP5 V+XfD0FB4/EYQHtZJR3nhb+HVYIhFosMm1KXMKocz3S+W6i6YuFxH7Oui 5VuJOw/65FuoULihfrg6r8gnj60rUabpy9uxEa6pWC3wxx/rHtG6QgGiB wPTxWrPDFZr4fCELgTdlzbRrtTUwzkPVrzi2SQ/aoP32/zqID0lRTnw0j W/C/DAgMSe4qVp25vWI2Jt5Arl+J0FogXtaayJHFMyYKVjjbUNzeOex9L w==; X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="7542801" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="7542801" Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orvoesa105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 18 Jan 2024 05:46:22 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="734274157" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="734274157" Received: from silpixa00400957.ir.intel.com (HELO silpixa00401385.ir.intel.com) ([10.237.214.26]) by orsmga003.jf.intel.com with ESMTP; 18 Jan 2024 05:46:20 -0800 From: Bruce Richardson To: dev@dpdk.org Cc: Bruce Richardson , Jerin Jacob Subject: [PATCH v1 6/7] eventdev: improve doxygen comments on configure struct Date: Thu, 18 Jan 2024 13:45:56 +0000 Message-Id: <20240118134557.73172-7-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240118134557.73172-1-bruce.richardson@intel.com> References: <20240118134557.73172-1-bruce.richardson@intel.com> MIME-Version: 1.0 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 General rewording and cleanup on the rte_event_dev_config structure. Improved the wording of some sentences and created linked cross-references out of the existing references to the dev_info structure. Signed-off-by: Bruce Richardson --- lib/eventdev/rte_eventdev.h | 47 +++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index c57c93a22e..4139ccb982 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -599,9 +599,9 @@ rte_event_dev_attr_get(uint8_t dev_id, uint32_t attr_id, struct rte_event_dev_config { uint32_t dequeue_timeout_ns; /**< rte_event_dequeue_burst() timeout on this device. - * This value should be in the range of *min_dequeue_timeout_ns* and - * *max_dequeue_timeout_ns* which previously provided in - * rte_event_dev_info_get() + * This value should be in the range of @ref rte_event_dev_info.min_dequeue_timeout_ns and + * @ref rte_event_dev_info.max_dequeue_timeout_ns returned by + * @ref rte_event_dev_info_get() * The value 0 is allowed, in which case, default dequeue timeout used. * @see RTE_EVENT_DEV_CFG_PER_DEQUEUE_TIMEOUT */ @@ -609,40 +609,41 @@ struct rte_event_dev_config { /**< In a *closed system* this field is the limit on maximum number of * events that can be inflight in the eventdev at a given time. The * limit is required to ensure that the finite space in a closed system - * is not overwhelmed. The value cannot exceed the *max_num_events* - * as provided by rte_event_dev_info_get(). + * is not overwhelmed. + * Once the limit has been reached, any enqueues of NEW events to the + * system will fail. + * The value cannot exceed @ref rte_event_dev_info.max_num_events + * returned by rte_event_dev_info_get(). * This value should be set to -1 for *open system*. */ uint8_t nb_event_queues; /**< Number of event queues to configure on this device. - * This value cannot exceed the *max_event_queues* which previously - * provided in rte_event_dev_info_get() + * This value cannot exceed @ref rte_event_dev_info.max_event_queues + * returned by rte_event_dev_info_get() */ uint8_t nb_event_ports; /**< Number of event ports to configure on this device. - * This value cannot exceed the *max_event_ports* which previously - * provided in rte_event_dev_info_get() + * This value cannot exceed @ref rte_event_dev_info.max_event_ports + * returned by rte_event_dev_info_get() */ uint32_t nb_event_queue_flows; - /**< Number of flows for any event queue on this device. - * This value cannot exceed the *max_event_queue_flows* which previously - * provided in rte_event_dev_info_get() + /**< Max number of flows needed for a single event queue on this device. + * This value cannot exceed @ref rte_event_dev_info.max_event_queue_flows + * returned by rte_event_dev_info_get() */ uint32_t nb_event_port_dequeue_depth; - /**< Maximum number of events can be dequeued at a time from an - * event port by this device. - * This value cannot exceed the *max_event_port_dequeue_depth* - * which previously provided in rte_event_dev_info_get(). + /**< Max number of events that can be dequeued at a time from an event port on this device. + * This value cannot exceed @ref rte_event_dev_info.max_event_port_dequeue_depth + * returned by rte_event_dev_info_get(). * Ignored when device is not RTE_EVENT_DEV_CAP_BURST_MODE capable. - * @see rte_event_port_setup() + * @see rte_event_port_setup() rte_event_dequeue_burst() */ uint32_t nb_event_port_enqueue_depth; - /**< Maximum number of events can be enqueued at a time from an - * event port by this device. - * This value cannot exceed the *max_event_port_enqueue_depth* - * which previously provided in rte_event_dev_info_get(). + /**< Maximum number of events can be enqueued at a time to an event port on this device. + * This value cannot exceed @ref rte_event_dev_info.max_event_port_enqueue_depth + * returned by rte_event_dev_info_get(). * Ignored when device is not RTE_EVENT_DEV_CAP_BURST_MODE capable. - * @see rte_event_port_setup() + * @see rte_event_port_setup() rte_event_enqueue_burst() */ uint32_t event_dev_cfg; /**< Event device config flags(RTE_EVENT_DEV_CFG_)*/ @@ -652,7 +653,7 @@ struct rte_event_dev_config { * queues; this value cannot exceed *nb_event_ports* or * *nb_event_queues*. If the device has ports and queues that are * optimized for single-link usage, this field is a hint for how many - * to allocate; otherwise, regular event ports and queues can be used. + * to allocate; otherwise, regular event ports and queues will be used. */ }; From patchwork Thu Jan 18 13:45:57 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 135960 X-Patchwork-Delegate: jerinj@marvell.com Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id C34D3438F3; Thu, 18 Jan 2024 14:47:05 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 6BDAA42DD6; Thu, 18 Jan 2024 14:46:27 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [198.175.65.13]) by mails.dpdk.org (Postfix) with ESMTP id EEFC942DB6; Thu, 18 Jan 2024 14:46:24 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1705585585; x=1737121585; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=d9zfdXC5jS+0Zak46W9jh71OEYLEL5OgYuI7m3WAsJc=; b=JRo6zu+gfqA/XMoFjIICQ1N6ZyACrWsUhWCNm48TEOejdauIGpPKmwgi QGBgm4VmINrrcz5xUL655LOU/tuIF3hNfIGfAc6c+uTx2cHXlcDzIeMef 35seb2N8k+d1NedtEysIjkKfey7gKAsBhReolRnpSlx1kAQr9QfMwobiI GBACv/Cz4bYTLGLLq7bVDt04TnSlWuSTHZA+CgzW1rLWyRMjJAtHZOqDv qgDoxbzO55wKYPXIjr4xJ1K7w6B2v8oVlY/Ny3w2SxFN4KBQ39KI4yV0c eDZDVjkSqnTGS6tVa9FQ4I6+nXIrcH1FL+aTPZ3Zta5yCslNYftClc0EX A==; X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="7542811" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="7542811" Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orvoesa105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 18 Jan 2024 05:46:25 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10956"; a="734274164" X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="734274164" Received: from silpixa00400957.ir.intel.com (HELO silpixa00401385.ir.intel.com) ([10.237.214.26]) by orsmga003.jf.intel.com with ESMTP; 18 Jan 2024 05:46:21 -0800 From: Bruce Richardson To: dev@dpdk.org Cc: Bruce Richardson , stable@dpdk.org, Jerin Jacob , Harry van Haaren , Pavan Nikhilesh , Timothy McDaniel Subject: [PATCH v1 7/7] eventdev: fix documentation for counting single-link ports Date: Thu, 18 Jan 2024 13:45:57 +0000 Message-Id: <20240118134557.73172-8-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240118134557.73172-1-bruce.richardson@intel.com> References: <20240118134557.73172-1-bruce.richardson@intel.com> MIME-Version: 1.0 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 The documentation of how single-link port-queue pairs were counted in the rte_event_dev_config structure did not match the actual implementation and, if following the documentation, certain valid port/queue configurations would have been impossible to configure. Fix this by changing the documentation to match the implementation - however confusing that implementation ends up being. Bugzilla ID: 1368 Fixes: 75d113136f38 ("eventdev: express DLB/DLB2 PMD constraints") Cc: stable@dpdk.org Signed-off-by: Bruce Richardson --- lib/eventdev/rte_eventdev.h | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) -- 2.40.1 diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index 4139ccb982..3b8f5b8101 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -490,7 +490,10 @@ struct rte_event_dev_info { uint32_t dequeue_timeout_ns; /**< Configured global dequeue timeout(ns) for this device */ uint8_t max_event_queues; - /**< Maximum event queues supported by this device */ + /**< Maximum event queues supported by this device. + * This excludes any queue-port pairs covered by the + * *max_single_link_event_port_queue_pairs* value in this structure. + */ uint32_t max_event_queue_flows; /**< Maximum number of flows within an event queue supported by this device*/ uint8_t max_event_queue_priority_levels; @@ -506,7 +509,10 @@ struct rte_event_dev_info { * @ref RTE_EVENT_DEV_PRIORITY_HIGHEST and @ref RTE_EVENT_DEV_PRIORITY_LOWEST. */ uint8_t max_event_ports; - /**< Maximum number of event ports supported by this device */ + /**< Maximum number of event ports supported by this device + * This excludes any queue-port pairs covered by the + * *max_single_link_event_port_queue_pairs* value in this structure. + */ uint8_t max_event_port_dequeue_depth; /**< Maximum number of events that can be dequeued at a time from an event port * on this device. @@ -618,13 +624,23 @@ struct rte_event_dev_config { */ uint8_t nb_event_queues; /**< Number of event queues to configure on this device. - * This value cannot exceed @ref rte_event_dev_info.max_event_queues - * returned by rte_event_dev_info_get() + * This value *includes* any single-link queue-port pairs to be used. + * This value cannot exceed @ref rte_event_dev_info.max_event_queues + + * @ref rte_event_dev_info.max_single_link_event_port_queue_pairs + * returned by rte_event_dev_info_get(). + * The number of non-single-link queues i.e. this value less + * *nb_single_link_event_port_queues* in this struct, cannot exceed + * @ref rte_event_dev_info.max_event_queues */ uint8_t nb_event_ports; /**< Number of event ports to configure on this device. - * This value cannot exceed @ref rte_event_dev_info.max_event_ports - * returned by rte_event_dev_info_get() + * This value *includes* any single-link queue-port pairs to be used. + * This value cannot exceed @ref rte_event_dev_info.max_event_ports + + * @ref rte_event_dev_info.max_single_link_event_port_queue_pairs + * returned by rte_event_dev_info_get(). + * The number of non-single-link ports i.e. this value less + * *nb_single_link_event_port_queues* in this struct, cannot exceed + * @ref rte_event_dev_info.max_event_ports */ uint32_t nb_event_queue_flows; /**< Max number of flows needed for a single event queue on this device.