From patchwork Fri Feb 2 12:39:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 136320 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 80DAE43A4F; Fri, 2 Feb 2024 13:40:32 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 6BF3142E54; Fri, 2 Feb 2024 13:40:32 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id B3E5242E54 for ; Fri, 2 Feb 2024 13:40:30 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706877631; x=1738413631; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=Fp0X5mTo+Fd0nhJqt27+7YxUKMiO2FvRGnKUGguTMy0=; b=ld3w0FWLBLqWrfbfRgT0RMkWr3mamQbFqu9Y3yo3+/gNi35KgFHDFjV6 6s+C8zG786U+PGUEIgm4GiuETT/NllKZT0oAY7BVuUzFo/8Jnx+Gpgk4X +eYPPOW1kAYEQ7DR34Mbg7TKoo70hUj3jKwaYe8nxo3NzzA28qbXomddt uNhIIfXqZTP1ftJOklspjDbmMZNBb5ESBAOp1+zTUixufHefKoUm92QSZ e8AUMf/9TJFh0qC0nhwvNecUxuh5cvVtTFy5i+/4nkWvCX7QLJVW0d/uK FUzoUTi5XJFErL3NfZyvVZyoZqn1o5pKuZ/FgVcrbpNdK23uui/q9hYAS g==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="54306" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="54306" Received: from fmviesa006.fm.intel.com ([10.60.135.146]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 04:40:30 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="347546" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:27 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v3 01/11] eventdev: improve doxygen introduction text Date: Fri, 2 Feb 2024 12:39:43 +0000 Message-Id: <20240202123953.77166-2-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240202123953.77166-1-bruce.richardson@intel.com> References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240202123953.77166-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 --- V3: reworked following feedback from Mattias --- lib/eventdev/rte_eventdev.h | 132 ++++++++++++++++++++++-------------- 1 file changed, 81 insertions(+), 51 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index ec9b02455d..a741832e8e 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -12,25 +12,33 @@ * @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, - * dynamic load balancing, pipelining, packet ingress order maintenance and - * synchronization services to simplify application packet processing. + * In a traditional run-to-completion application model, lcores pick up packets + * from Ethdev ports and associated RX queues, run the packet processing to completion, + * and enqueue the completed packets to a TX queue. NIC-level receive-side scaling (RSS) + * may be used to balance the load across multiple CPU cores. + * + * In contrast, in an event-driver model, as supported by this "eventdev" library, + * incoming packets are fed into an event device, which schedules those packets across + * the available lcores, in accordance with its configuration. + * This event-driven programming model offers applications automatic multicore scaling, + * dynamic load balancing, pipelining, packet order maintenance, synchronization, + * and prioritization/quality of service. * * The Event Device API is composed of two parts: * * - 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 +83,39 @@ * | | * +-----------------------------------------------------------+ * - * 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, - * sub_event_type etc. + * **Event**: Represents an item of work and is the smallest unit of scheduling. + * An event carries metadata, such as queue ID, scheduling type, and event priority, + * and data such as one or more packets or other kinds of buffers. + * Some examples of events are: + * - a software-generated item of work originating from a lcore, + * perhaps carrying a packet to be processed, + * - a crypto work completion notification + * - a timer expiry notification. * - * 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 event device 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. * - * 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 + * Enqueue and dequeue from a port is not thread-safe, and the expected use-case is + * that each port is polled by only a single lcore. [If this is not the case, + * a suitable synchronization mechanism should be used to prevent simultaneous + * access from multiple lcores.] + * To schedule events to an lcore, the event device will schedule them to the event port(s) + * being polled by that lcore. + * + * *NOTE*: By default, all the functions of the Event Device API exported by a PMD + * are non-thread-safe 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 +127,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 +147,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 +167,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 @@ -163,11 +189,14 @@ * performs an indirect invocation of the corresponding driver function * 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. + * For performance reasons, the addresses of the fast-path functions of the + * 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 +208,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 an RTE service that should be mapped to one or more service cores) + * that repeatedly calls the software specific scheduling function. * * An event driven worker thread has following typical workflow on fastpath: * \code{.c} From patchwork Fri Feb 2 12:39:44 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 136321 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 878E643A4F; Fri, 2 Feb 2024 13:40:40 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id ED09A42E6D; Fri, 2 Feb 2024 13:40:34 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id 6C4AD42E58 for ; Fri, 2 Feb 2024 13:40:33 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706877633; x=1738413633; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=OVFbyX7UsEzrmWtpL9RevyzS16aWTVXBpXJ69xTk5FM=; b=bV1qN2z0DJi0LoigDPDWFZv4EICylhyWFZyTFbxR1/TH9vGY8VLaUPbV xafIzix6GArq3uFxdCiia6yBLPzmRhGhjk7qHte9ZFc5JxxAte1/SMQ4l bJUawFC3ihwa+Ksof1HtMy2dQROkYhtC3seFhxy6Hj8YvIdzRHg8tbeTH 7B8FmfjqbZNbLaWnoNE5IIX+Uxm38CglNO9gAZKQ9l01VSABo8Q+1r1cH Q2rRELzFQlUA5aaPaZHjpLaFQniAOUtCBPEIz3OTVfCph1PVJbPh0ZtFb HCmjPTRzjvZlxbfk3ocP50PGJTqMh85mV2XwShyKQC4nN2VnB9Sw9lXUY Q==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="54329" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="54329" Received: from fmviesa006.fm.intel.com ([10.60.135.146]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 04:40:33 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="347553" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:31 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v3 02/11] eventdev: move text on driver internals to proper section Date: Fri, 2 Feb 2024 12:39:44 +0000 Message-Id: <20240202123953.77166-3-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240202123953.77166-1-bruce.richardson@intel.com> References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240202123953.77166-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 a741832e8e..37493464f9 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -122,22 +122,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() @@ -173,6 +157,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 Fri Feb 2 12:39:45 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 136322 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 0014543A4F; Fri, 2 Feb 2024 13:40:46 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 2418142E5E; Fri, 2 Feb 2024 13:40:39 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id AF92542E63 for ; Fri, 2 Feb 2024 13:40:36 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706877637; x=1738413637; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=DzYCMLXxu3B262mm4OlS1C0hzLeOmXkEAfiIghGFbSk=; b=e8lhCCJVxuQXj3NB3Re6js9pyXOzHkOJmy5WTIwacvmEp/Hrs6JEF6Kg ZoFSswR1XaenkA3yQlsFClPHmNrohLqXVPMoyFHAQM1d9nqYqg7sSEFYF KKL4cOSbXPyReGagO9saAPWWpu7eAMYRRuaGc61xOQkFKcYPa7X4M5hZP OUeaDUASuXWUreZSFg5KP1X5jY1LXCUP+1/PXktOdKLgq++GWj+JXtPwu NjU1MOHudDHGyhIsSBZ8Xl+mvpFycsnCBHEFn/Un6Y5WIdK9k5vRGoUCo zCKqox4z8luGowb1MTIEHZGWn5IE0yFVe0lm50fYdGqKQ98AxF+oj+eej w==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="54349" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="54349" Received: from fmviesa006.fm.intel.com ([10.60.135.146]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 04:40:36 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="347559" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:34 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v3 03/11] eventdev: update documentation on device capability flags Date: Fri, 2 Feb 2024 12:39:45 +0000 Message-Id: <20240202123953.77166-4-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240202123953.77166-1-bruce.richardson@intel.com> References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240202123953.77166-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 --- V3: Updated following feedback from Mattias --- lib/eventdev/rte_eventdev.h | 130 +++++++++++++++++++++++++----------- 1 file changed, 92 insertions(+), 38 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index 37493464f9..a33024479d 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -253,143 +253,197 @@ 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. * - * @see RTE_SCHED_TYPE_* values + * If this capability is not set, each queue only supports events of the + * *RTE_SCHED_TYPE_* type that it was created with. + * The behaviour when events of other scheduling types are sent to the queue is + * currently undefined. + * + * @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, event 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 level for events and queues. + * * @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 level for events and queues. + * * @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 level for events and queues. + * * @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 Fri Feb 2 12:39:46 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 136323 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 6967143A4F; Fri, 2 Feb 2024 13:40:54 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 4B10A42E67; Fri, 2 Feb 2024 13:40:49 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id E817342E58 for ; Fri, 2 Feb 2024 13:40:46 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706877647; x=1738413647; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=yC/dT2QYvQlT5qerGThnLor8yKan4gd6cQ7jgloR+l8=; b=FbPsAI1SSIePA1NK3jyxY9TWdE6dfLk3wpgmguME/RDbBaAxos1INqvq uKmHrKBXTuLpfs1CJs65c3vSG3ua/L85WUXNbFdMZ3F8y9e+PKQDAWcOP mHqAKWkpF+hgpKtcvunCSyqKWsUXWGO41FXmzGqquC4U9QLoF1bzT4OLa 3zhhTdp95dx4k/yQ0Cp43+skYRBhvmdloVO7xYm5Sh+frAGVE52N1/qnA 5dmebQWL8RD85Otv8NnDQiwOOwCKbFaYEhjaobVS0BtjQEUnB57z3OITP boLQsHrPbyVskm/vQ5YMIrJBA0J60dEh4s7EL1r+8lgc1tPTrt2Fs0+ZU Q==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="54373" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="54373" Received: from fmviesa006.fm.intel.com ([10.60.135.146]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 04:40:41 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="347570" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:37 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v3 04/11] eventdev: cleanup doxygen comments on info structure Date: Fri, 2 Feb 2024 12:39:46 +0000 Message-Id: <20240202123953.77166-5-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240202123953.77166-1-bruce.richardson@intel.com> References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240202123953.77166-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 --- V3: reworked following feedback - added closing "." on comments - added more cross-reference links - reworded priority level comments --- lib/eventdev/rte_eventdev.h | 85 +++++++++++++++++++++++++------------ 1 file changed, 58 insertions(+), 27 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index a33024479d..da3f72d89e 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -487,57 +487,88 @@ rte_event_dev_socket_id(uint8_t dev_id); * Event device information */ struct rte_event_dev_info { - const char *driver_name; /**< Event driver name */ - struct rte_device *dev; /**< Device information */ + 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 */ + /**< 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 count excludes any queues covered by @ref max_single_link_event_port_queue_pairs. + */ 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 + /**< Maximum number of event queue priority levels supported by this device. + * + * Valid when the device has @ref RTE_EVENT_DEV_CAP_QUEUE_QOS capability. + * + * The implementation shall normalize priority values specified between + * @ref RTE_EVENT_DEV_PRIORITY_HIGHEST and @ref RTE_EVENT_DEV_PRIORITY_LOWEST + * to map them internally to this range of priorities. + * [For devices supporting a power-of-2 number of priority levels, this + * normalization will be done via a right-shift operation, so only the top + * log2(max_levels) bits will be used by the event device.] + * + * @see rte_event_queue_conf.priority */ 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 + * + * Valid when the device has @ref RTE_EVENT_DEV_CAP_EVENT_QOS capability. + * + * The implementation shall normalize priority values specified between + * @ref RTE_EVENT_DEV_PRIORITY_HIGHEST and @ref RTE_EVENT_DEV_PRIORITY_LOWEST + * to map them internally to this range of priorities. + * [For devices supporting a power-of-2 number of priority levels, this + * normalization will be done via a right-shift operation, so only the top + * log2(max_levels) bits will be used by the event device.] + * + * @see rte_event.priority */ uint8_t max_event_ports; - /**< Maximum number of event ports supported by this device */ + /**< Maximum number of event ports supported by this device. + * + * This count excludes any ports covered by @ref max_single_link_event_port_queue_pairs. + */ 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 burst dequeue + * (@ref RTE_EVENT_DEV_CAP_BURST_MODE) 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 burst enqueue + * (@ref RTE_EVENT_DEV_CAP_BURST_MODE) 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 @ref max_event_ports + * or @ref 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 Fri Feb 2 12:39:47 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 136324 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 72AAB43A4F; Fri, 2 Feb 2024 13:41:02 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 69DD442E84; Fri, 2 Feb 2024 13:40:50 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id 0EB2D42E50 for ; Fri, 2 Feb 2024 13:40:46 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706877647; x=1738413647; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=i8OwGytzddBIU9b3SWNszKNUjectXoAlnrfUBjrMvmM=; b=X+mWhS1PuUdWzf9INfMwV//aqJ1WpHa5yOppfZFvXwBNBfLOVUacc/6G 5HtPwjoLGUavnIM5/bLoF/CTp4KX2h8dxobcI5sbigAH1kB1pbj6T5V96 +0iMVjHcLRMSjoHHYzYptSyaUWT1QlVa/i4LhyInuUGIJB2EW0hbjBDaB uHREzd7LY5sqE49f+GYCac7uN2Dnj3mC1E1Q3M/zpFnYkF4Msm+sJebAf tyl1oBQb0hApFs4Zj5EUOCbDrbJ29Q2jYtJHJOe2dEvb5E3nBxp/PxL27 xgKCBYYe+tu6ueZV0Vb8W9KLj52+GEn+bBD5JaOA/SSZKx26SKpyFKxQP A==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="54378" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="54378" Received: from fmviesa006.fm.intel.com ([10.60.135.146]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 04:40:44 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="347593" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:40 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v3 05/11] eventdev: improve function documentation for query fns Date: Fri, 2 Feb 2024 12:39:47 +0000 Message-Id: <20240202123953.77166-6-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240202123953.77166-1-bruce.richardson@intel.com> References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240202123953.77166-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 --- V3: minor changes following review --- 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 da3f72d89e..3cba13e2c4 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -448,8 +448,7 @@ struct rte_event; */ /** - * Get the total number of event devices that have been successfully - * initialised. + * Get the total number of event devices. * * @return * The total number of usable event devices. @@ -464,8 +463,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); @@ -478,7 +479,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); @@ -574,18 +576,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 Fri Feb 2 12:39:48 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 136325 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 1294E43A4F; Fri, 2 Feb 2024 13:41:12 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id EC0F542E80; Fri, 2 Feb 2024 13:40:53 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id DC77542E92 for ; Fri, 2 Feb 2024 13:40:51 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706877652; x=1738413652; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=qxxITldscmKPMOXetLsOJUSFkZD9dIaCohkYcIuMfww=; b=djuKnXsPbloYrGWoywxMUxmhCmWGGRIu3BhXyAkgffdxkall6R8RN6S8 J/tm03xMg3yeBbOZbCqFNFkPnFCLu6NufIeiGXoHr3fc/TjlFm7TC3v69 NgpyOZquSQrkFIndOeJ9eyaZvMcgxWXBv8OnEaPOp5l3Ranbd/M+sN+2z gYEVFnMfgAtKNN3AVZcrqVMBzi5kfewbgqkDBTxpXPqSMO+4iB/ozyBlS 312yRxVRouTkN6od+QTkdjY2Xq/IOYDUqFlhQX2RcFz3PyDdgqmFlfgZy HZ30iTPC11dX6nDkXrcSr/ZoInpc8ka80iP7gA57wtG5vEUkRhxjYv4JZ Q==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="54391" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="54391" Received: from fmviesa006.fm.intel.com ([10.60.135.146]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 04:40:46 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="347605" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:44 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v3 06/11] eventdev: improve doxygen comments on configure struct Date: Fri, 2 Feb 2024 12:39:48 +0000 Message-Id: <20240202123953.77166-7-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240202123953.77166-1-bruce.richardson@intel.com> References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240202123953.77166-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. As part of the rework, fix issue with how single-link port-queue pairs were counted in the rte_event_dev_config structure. This 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 Bugzilla ID: 1368 Fixes: 75d113136f38 ("eventdev: express DLB/DLB2 PMD constraints") Signed-off-by: Bruce Richardson --- V3: - minor tweaks following review - merged in doc fix for bugzilla 1368 into this patch, since it fit with other clarifications to the config struct. --- lib/eventdev/rte_eventdev.h | 61 ++++++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 24 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index 3cba13e2c4..027f5936fb 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -634,9 +634,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 */ @@ -644,40 +644,53 @@ 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(). - * This value should be set to -1 for *open system*. + * is not exhausted. + * 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 systems*, that is, + * those systems returning -1 in @ref rte_event_dev_info.max_num_events. + * + * @see rte_event_port_conf.new_event_threshold */ 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 *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 the *max_event_ports* which previously - * provided in 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; - /**< 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_)*/ @@ -687,7 +700,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 Fri Feb 2 12:39:49 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 136326 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 68BC443A4F; Fri, 2 Feb 2024 13:41:19 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 1305F42E9E; Fri, 2 Feb 2024 13:40:56 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id C169B42E7A for ; Fri, 2 Feb 2024 13:40:53 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706877654; x=1738413654; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=Ep8pV4fN+slfMBbyL+otof5icWbCg5ItzVFXIa64c1c=; b=UodxkqCMsW8Sm1eyyCuV4olcR9uY+Wv1NlngdWBZdVYPUoTuVJIbZ2LF KxJi7erGTF7sS9Xx4sv/BBvuhfJtinwbQzlyVPRnFYa/ChrqxUj5iR2DW EBGogNRpc7B03lAHLjg3IAxJMOCtcum5qbkLHL2nP4ARMptKu6yJbjE+0 Y/kfU59xiOAm2Qz8LcfZJwn3000m4HvGie4ZBiFTvm5i3WrMeRKBLOyqk 9sYrTyCXsHaNtRpOenZYo/RCBXb88eplhooWCuUKXqZ8PsRjcTPbS8Ko3 X7SLehv7902Jle5HrjSgOxRlBuQG59J/Sbuat21yahnce4C8rKhAC84YO A==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="54419" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="54419" Received: from fmviesa006.fm.intel.com ([10.60.135.146]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 04:40:50 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="347618" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:48 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v3 07/11] eventdev: improve doxygen comments on config fns Date: Fri, 2 Feb 2024 12:39:49 +0000 Message-Id: <20240202123953.77166-8-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240202123953.77166-1-bruce.richardson@intel.com> References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240202123953.77166-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 Improve the documentation text for the configuration functions and structures for configuring an eventdev, as well as ports and queues. Clarify text where possible, and ensure references come through as links in the html output. Signed-off-by: Bruce Richardson --- V3: Update following review, mainly: - change ranges starting with 0, to just say "less than" - put in "." at end of sentences & bullet points --- lib/eventdev/rte_eventdev.h | 221 +++++++++++++++++++++++------------- 1 file changed, 144 insertions(+), 77 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index 027f5936fb..e2923a69fb 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -707,12 +707,14 @@ struct rte_event_dev_config { /** * Configure an event device. * - * This function must be invoked first before any other function in the - * API. This function can also be re-invoked when a device is in the - * stopped state. + * This function must be invoked before any other configuration function in the + * API, when preparing an event device for application use. + * This function can also be re-invoked when a device is in the stopped state. * - * The caller may use rte_event_dev_info_get() to get the capability of each - * resources available for this event device. + * The caller should use rte_event_dev_info_get() to get the capabilities and + * resource limits for this event device before calling this API. + * Many values in the dev_conf input parameter are subject to limits given + * in the device information returned from rte_event_dev_info_get(). * * @param dev_id * The identifier of the device to configure. @@ -722,6 +724,9 @@ struct rte_event_dev_config { * @return * - 0: Success, device configured. * - <0: Error code returned by the driver configuration function. + * - -ENOTSUP - device does not support configuration. + * - -EINVAL - invalid input parameter. + * - -EBUSY - device has already been started. */ int rte_event_dev_configure(uint8_t dev_id, @@ -731,14 +736,35 @@ rte_event_dev_configure(uint8_t dev_id, /* Event queue configuration bitmap flags */ #define RTE_EVENT_QUEUE_CFG_ALL_TYPES (1ULL << 0) -/**< Allow ATOMIC,ORDERED,PARALLEL schedule type enqueue +/**< Allow events with schedule types ATOMIC, ORDERED, and PARALLEL to be enqueued to this queue. * + * The scheduling type to be used is that specified in each individual event. + * This flag can only be set when configuring queues on devices reporting the + * @ref RTE_EVENT_DEV_CAP_QUEUE_ALL_TYPES capability. + * + * Without this flag, only events with the specific scheduling type configured at queue setup + * can be sent to the queue. + * + * @see RTE_EVENT_DEV_CAP_QUEUE_ALL_TYPES * @see RTE_SCHED_TYPE_ORDERED, RTE_SCHED_TYPE_ATOMIC, RTE_SCHED_TYPE_PARALLEL * @see rte_event_enqueue_burst() */ #define RTE_EVENT_QUEUE_CFG_SINGLE_LINK (1ULL << 1) /**< This event queue links only to a single event port. * + * No load-balancing of events is performed, as all events + * sent to this queue end up at the same event port. + * The number of queues on which this flag is to be set must be + * configured at device configuration time, by setting + * @ref rte_event_dev_config.nb_single_link_event_port_queues + * parameter appropriately. + * + * This flag serves as a hint only, any devices without specific + * support for single-link queues can fall-back automatically to + * using regular queues with a single destination port. + * + * @see rte_event_dev_info.max_single_link_event_port_queue_pairs + * @see rte_event_dev_config.nb_single_link_event_port_queues * @see rte_event_port_setup(), rte_event_port_link() */ @@ -746,56 +772,79 @@ rte_event_dev_configure(uint8_t dev_id, struct rte_event_queue_conf { uint32_t nb_atomic_flows; /**< The maximum number of active flows this queue can track at any - * given time. If the queue is configured for atomic scheduling (by - * applying the RTE_EVENT_QUEUE_CFG_ALL_TYPES flag to event_queue_cfg - * or RTE_SCHED_TYPE_ATOMIC flag to schedule_type), then the - * value must be in the range of [1, nb_event_queue_flows], which was - * previously provided in rte_event_dev_configure(). + * given time. + * + * If the queue is configured for atomic scheduling (by + * applying the @ref RTE_EVENT_QUEUE_CFG_ALL_TYPES flag to + * @ref rte_event_queue_conf.event_queue_cfg + * or @ref RTE_SCHED_TYPE_ATOMIC flag to @ref rte_event_queue_conf.schedule_type), then the + * value must be in the range of [1, @ref rte_event_dev_config.nb_event_queue_flows], + * which was previously provided in rte_event_dev_configure(). + * + * If the queue is not configured for atomic scheduling this value is ignored. */ uint32_t nb_atomic_order_sequences; /**< The maximum number of outstanding events waiting to be * reordered by this queue. In other words, the number of entries in - * this queue’s reorder buffer.When the number of events in the + * this queue’s reorder buffer. When the number of events in the * reorder buffer reaches to *nb_atomic_order_sequences* then the - * scheduler cannot schedule the events from this queue and invalid - * event will be returned from dequeue until one or more entries are + * scheduler cannot schedule the events from this queue and no + * events will be returned from dequeue until one or more entries are * freed up/released. + * * If the queue is configured for ordered scheduling (by applying the - * RTE_EVENT_QUEUE_CFG_ALL_TYPES flag to event_queue_cfg or - * RTE_SCHED_TYPE_ORDERED flag to schedule_type), then the value must - * be in the range of [1, nb_event_queue_flows], which was + * @ref RTE_EVENT_QUEUE_CFG_ALL_TYPES flag to @ref rte_event_queue_conf.event_queue_cfg or + * @ref RTE_SCHED_TYPE_ORDERED flag to @ref rte_event_queue_conf.schedule_type), + * then the value must be in the range of + * [1, @ref rte_event_dev_config.nb_event_queue_flows], which was * previously supplied to rte_event_dev_configure(). + * + * If the queue is not configured for ordered scheduling, then this value is ignored. */ uint32_t event_queue_cfg; /**< Queue cfg flags(EVENT_QUEUE_CFG_) */ uint8_t schedule_type; /**< Queue schedule type(RTE_SCHED_TYPE_*). - * Valid when RTE_EVENT_QUEUE_CFG_ALL_TYPES bit is not set in - * event_queue_cfg. + * + * Valid when @ref RTE_EVENT_QUEUE_CFG_ALL_TYPES flag is not set in + * @ref rte_event_queue_conf.event_queue_cfg. + * + * If the @ref RTE_EVENT_QUEUE_CFG_ALL_TYPES flag is set, then this field is ignored. + * + * @see RTE_SCHED_TYPE_ORDERED, RTE_SCHED_TYPE_ATOMIC, RTE_SCHED_TYPE_PARALLEL */ uint8_t priority; /**< Priority for this event queue relative to other event queues. + * * The requested priority should in the range of - * [RTE_EVENT_DEV_PRIORITY_HIGHEST, RTE_EVENT_DEV_PRIORITY_LOWEST]. + * [@ref RTE_EVENT_DEV_PRIORITY_HIGHEST, @ref RTE_EVENT_DEV_PRIORITY_LOWEST]. * The implementation shall normalize the requested priority to * event device supported priority value. - * Valid when the device has RTE_EVENT_DEV_CAP_QUEUE_QOS capability + * + * Valid when the device has @ref RTE_EVENT_DEV_CAP_QUEUE_QOS capability, + * ignored otherwise */ uint8_t weight; /**< Weight of the event queue relative to other event queues. + * * The requested weight should be in the range of - * [RTE_EVENT_DEV_WEIGHT_HIGHEST, RTE_EVENT_DEV_WEIGHT_LOWEST]. + * [@ref RTE_EVENT_QUEUE_WEIGHT_HIGHEST, @ref RTE_EVENT_QUEUE_WEIGHT_LOWEST]. * The implementation shall normalize the requested weight to event * device supported weight value. - * Valid when the device has RTE_EVENT_DEV_CAP_QUEUE_QOS capability. + * + * Valid when the device has @ref RTE_EVENT_DEV_CAP_QUEUE_QOS capability, + * ignored otherwise. */ uint8_t affinity; /**< Affinity of the event queue relative to other event queues. + * * The requested affinity should be in the range of - * [RTE_EVENT_DEV_AFFINITY_HIGHEST, RTE_EVENT_DEV_AFFINITY_LOWEST]. + * [@ref RTE_EVENT_QUEUE_AFFINITY_HIGHEST, @ref RTE_EVENT_QUEUE_AFFINITY_LOWEST]. * The implementation shall normalize the requested affinity to event * device supported affinity value. - * Valid when the device has RTE_EVENT_DEV_CAP_QUEUE_QOS capability. + * + * Valid when the device has @ref RTE_EVENT_DEV_CAP_QUEUE_QOS capability, + * ignored otherwise. */ }; @@ -810,7 +859,7 @@ struct rte_event_queue_conf { * The identifier of the device. * @param queue_id * The index of the event queue to get the configuration information. - * The value must be in the range [0, nb_event_queues - 1] + * The value must be less than @ref rte_event_dev_config.nb_event_queues * previously supplied to rte_event_dev_configure(). * @param[out] queue_conf * The pointer to the default event queue configuration data. @@ -830,8 +879,9 @@ rte_event_queue_default_conf_get(uint8_t dev_id, uint8_t queue_id, * @param dev_id * The identifier of the device. * @param queue_id - * The index of the event queue to setup. The value must be in the range - * [0, nb_event_queues - 1] previously supplied to rte_event_dev_configure(). + * The index of the event queue to setup. The value must be + * less than @ref rte_event_dev_config.nb_event_queues previously supplied to + * rte_event_dev_configure(). * @param queue_conf * The pointer to the configuration data to be used for the event queue. * NULL value is allowed, in which case default configuration used. @@ -840,60 +890,60 @@ rte_event_queue_default_conf_get(uint8_t dev_id, uint8_t queue_id, * * @return * - 0: Success, event queue correctly set up. - * - <0: event queue configuration failed + * - <0: event queue configuration failed. */ int rte_event_queue_setup(uint8_t dev_id, uint8_t queue_id, const struct rte_event_queue_conf *queue_conf); /** - * The priority of the queue. + * Queue attribute id for the priority of the queue. */ #define RTE_EVENT_QUEUE_ATTR_PRIORITY 0 /** - * The number of atomic flows configured for the queue. + * Queue attribute id for the number of atomic flows configured for the queue. */ #define RTE_EVENT_QUEUE_ATTR_NB_ATOMIC_FLOWS 1 /** - * The number of atomic order sequences configured for the queue. + * Queue attribute id for the number of atomic order sequences configured for the queue. */ #define RTE_EVENT_QUEUE_ATTR_NB_ATOMIC_ORDER_SEQUENCES 2 /** - * The cfg flags for the queue. + * Queue attribute id for the configuration flags for the queue. */ #define RTE_EVENT_QUEUE_ATTR_EVENT_QUEUE_CFG 3 /** - * The schedule type of the queue. + * Queue attribute id for the schedule type of the queue. */ #define RTE_EVENT_QUEUE_ATTR_SCHEDULE_TYPE 4 /** - * The weight of the queue. + * Queue attribute id for the weight of the queue. */ #define RTE_EVENT_QUEUE_ATTR_WEIGHT 5 /** - * Affinity of the queue. + * Queue attribute id for the affinity of the queue. */ #define RTE_EVENT_QUEUE_ATTR_AFFINITY 6 /** - * Get an attribute from a queue. + * Get an attribute of an event queue. * * @param dev_id - * Eventdev id + * The identifier of the device. * @param queue_id - * Eventdev queue id + * The index of the event queue to query. The value must be less than + * @ref rte_event_dev_config.nb_event_queues previously supplied to rte_event_dev_configure(). * @param attr_id - * The attribute ID to retrieve + * The attribute ID to retrieve (RTE_EVENT_QUEUE_ATTR_*). * @param[out] attr_value - * A pointer that will be filled in with the attribute value if successful + * A pointer that will be filled in with the attribute value if successful. * * @return * - 0: Successfully returned value - * - -EINVAL: invalid device, queue or attr_id provided, or attr_value was - * NULL + * - -EINVAL: invalid device, queue or attr_id provided, or attr_value was NULL. * - -EOVERFLOW: returned when attr_id is set to - * RTE_EVENT_QUEUE_ATTR_SCHEDULE_TYPE and event_queue_cfg is set to - * RTE_EVENT_QUEUE_CFG_ALL_TYPES + * @ref RTE_EVENT_QUEUE_ATTR_SCHEDULE_TYPE and @ref RTE_EVENT_QUEUE_CFG_ALL_TYPES is + * set in the queue configuration flags. */ int rte_event_queue_attr_get(uint8_t dev_id, uint8_t queue_id, uint32_t attr_id, @@ -903,19 +953,20 @@ rte_event_queue_attr_get(uint8_t dev_id, uint8_t queue_id, uint32_t attr_id, * Set an event queue attribute. * * @param dev_id - * Eventdev id + * The identifier of the device. * @param queue_id - * Eventdev queue id + * The index of the event queue to configure. The value must be less than + * @ref rte_event_dev_config.nb_event_queues previously supplied to rte_event_dev_configure(). * @param attr_id - * The attribute ID to set + * The attribute ID to set (RTE_EVENT_QUEUE_ATTR_*). * @param attr_value - * The attribute value to set + * The attribute value to set. * * @return * - 0: Successfully set attribute. - * - -EINVAL: invalid device, queue or attr_id. - * - -ENOTSUP: device does not support setting the event attribute. - * - <0: failed to set event queue attribute + * - <0: failed to set event queue attribute. + * - -EINVAL: invalid device, queue or attr_id. + * - -ENOTSUP: device does not support setting the event attribute. */ int rte_event_queue_attr_set(uint8_t dev_id, uint8_t queue_id, uint32_t attr_id, @@ -933,7 +984,10 @@ rte_event_queue_attr_set(uint8_t dev_id, uint8_t queue_id, uint32_t attr_id, */ #define RTE_EVENT_PORT_CFG_SINGLE_LINK (1ULL << 1) /**< This event port links only to a single event queue. + * The queue it links with should be similarly configured with the + * @ref RTE_EVENT_QUEUE_CFG_SINGLE_LINK flag. * + * @see RTE_EVENT_QUEUE_CFG_SINGLE_LINK * @see rte_event_port_setup(), rte_event_port_link() */ #define RTE_EVENT_PORT_CFG_HINT_PRODUCER (1ULL << 2) @@ -949,7 +1003,7 @@ rte_event_queue_attr_set(uint8_t dev_id, uint8_t queue_id, uint32_t attr_id, #define RTE_EVENT_PORT_CFG_HINT_CONSUMER (1ULL << 3) /**< Hint that this event port will primarily dequeue events from the system. * A PMD can optimize its internal workings by assuming that this port is - * primarily going to consume events, and not enqueue FORWARD or RELEASE + * primarily going to consume events, and not enqueue NEW or FORWARD * events. * * Note that this flag is only a hint, so PMDs must operate under the @@ -975,48 +1029,55 @@ struct rte_event_port_conf { /**< A backpressure threshold for new event enqueues on this port. * Use for *closed system* event dev where event capacity is limited, * and cannot exceed the capacity of the event dev. + * * Configuring ports with different thresholds can make higher priority * traffic less likely to be backpressured. * For example, a port used to inject NIC Rx packets into the event dev * can have a lower threshold so as not to overwhelm the device, * while ports used for worker pools can have a higher threshold. - * This value cannot exceed the *nb_events_limit* + * This value cannot exceed the @ref rte_event_dev_config.nb_events_limit value * which was previously supplied to rte_event_dev_configure(). - * This should be set to '-1' for *open system*. + * + * This should be set to '-1' for *open system*, i.e when + * @ref rte_event_dev_info.max_num_events == -1. */ uint16_t dequeue_depth; - /**< Configure number of bulk dequeues for this event port. - * This value cannot exceed the *nb_event_port_dequeue_depth* - * which previously supplied to rte_event_dev_configure(). - * Ignored when device is not RTE_EVENT_DEV_CAP_BURST_MODE capable. + /**< Configure the maximum size of burst dequeues for this event port. + * This value cannot exceed the @ref rte_event_dev_config.nb_event_port_dequeue_depth value + * which was previously supplied to rte_event_dev_configure(). + * + * Ignored when device does not support the @ref RTE_EVENT_DEV_CAP_BURST_MODE capability. */ uint16_t enqueue_depth; - /**< Configure number of bulk enqueues for this event port. - * This value cannot exceed the *nb_event_port_enqueue_depth* - * which previously supplied to rte_event_dev_configure(). - * Ignored when device is not RTE_EVENT_DEV_CAP_BURST_MODE capable. + /**< Configure the maximum size of burst enqueues to this event port. + * This value cannot exceed the @ref rte_event_dev_config.nb_event_port_enqueue_depth value + * which was previously supplied to rte_event_dev_configure(). + * + * Ignored when device does not support the @ref RTE_EVENT_DEV_CAP_BURST_MODE capability. */ - uint32_t event_port_cfg; /**< Port cfg flags(EVENT_PORT_CFG_) */ + uint32_t event_port_cfg; /**< Port configuration flags(EVENT_PORT_CFG_) */ }; /** * Retrieve the default configuration information of an event port designated * by its *port_id* from the event driver for an event device. * - * This function intended to be used in conjunction with rte_event_port_setup() - * where caller needs to set up the port by overriding few default values. + * This function is intended to be used in conjunction with rte_event_port_setup() + * where the caller can set up the port by just overriding few default values. * * @param dev_id * The identifier of the device. * @param port_id * The index of the event port to get the configuration information. - * The value must be in the range [0, nb_event_ports - 1] + * The value must be less than @ref rte_event_dev_config.nb_event_ports * previously supplied to rte_event_dev_configure(). * @param[out] port_conf - * The pointer to the default event port configuration data + * The pointer to a structure to store the default event port configuration data. * @return * - 0: Success, driver updates the default event port configuration data. * - <0: Error code returned by the driver info get function. + * - -EINVAL - invalid input parameter. + * - -ENOTSUP - function is not supported for this device. * * @see rte_event_port_setup() */ @@ -1030,19 +1091,25 @@ rte_event_port_default_conf_get(uint8_t dev_id, uint8_t port_id, * @param dev_id * The identifier of the device. * @param port_id - * The index of the event port to setup. The value must be in the range - * [0, nb_event_ports - 1] previously supplied to rte_event_dev_configure(). + * The index of the event port to setup. The value must be less than + * @ref rte_event_dev_config.nb_event_ports previously supplied to + * rte_event_dev_configure(). * @param port_conf - * The pointer to the configuration data to be used for the queue. - * NULL value is allowed, in which case default configuration used. + * The pointer to the configuration data to be used for the port. + * NULL value is allowed, in which case the default configuration is used. * * @see rte_event_port_default_conf_get() * * @return * - 0: Success, event port correctly set up. - * - <0: Port configuration failed - * - (-EDQUOT) Quota exceeded(Application tried to link the queue configured - * with RTE_EVENT_QUEUE_CFG_SINGLE_LINK to more than one event ports) + * - <0: Port configuration failed. + * - -EINVAL - Invalid input parameter. + * - -EBUSY - Port already started. + * - -ENOTSUP - Function not supported on this device, or a NULL pointer passed + * as the port_conf parameter, and no default configuration function available + * for this device. + * - -EDQUOT - Application tried to link a queue configured + * with @ref RTE_EVENT_QUEUE_CFG_SINGLE_LINK to more than one event port. */ int rte_event_port_setup(uint8_t dev_id, uint8_t port_id, @@ -1072,8 +1139,8 @@ typedef void (*rte_eventdev_port_flush_t)(uint8_t dev_id, * @param dev_id * The identifier of the device. * @param port_id - * The index of the event port to setup. The value must be in the range - * [0, nb_event_ports - 1] previously supplied to rte_event_dev_configure(). + * The index of the event port to quiesce. The value must be less than + * @ref rte_event_dev_config.nb_event_ports previously supplied to rte_event_dev_configure(). * @param release_cb * Callback function invoked once per flushed event. * @param args From patchwork Fri Feb 2 12:39:50 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 136327 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 54E2843A4F; Fri, 2 Feb 2024 13:41:26 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 4FCA142EA0; Fri, 2 Feb 2024 13:40:57 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id DF6D742E8B for ; Fri, 2 Feb 2024 13:40:54 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706877655; x=1738413655; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=NPSSjXz5I2AgI19Rp1SjE5YBkkLBsA82iqVj1WGlXmU=; b=meyCYD78kLewTiMKSKPivZrRSAY7eAKjtZ3e3iYxZMct+en2U9jLNPwy ais0c+OVsc1I9sk3k2QmZidH38DRj5h+PCW2OY3p9qaITHG4B5Ar4j32D irGuwLems2mjhU87q9JG/VehjOhvRc4a+wD4aIphce5xJD+qZxWz+ktay MK0lk/wcP/CBHI+72Ej38PFhtYv1JFe0PeIjGcm55MrFwQ0urU55qnmOk 5FszGP/OEgFfGJPQ110Y07Rc8M/4FNtYEOIlrX0bGHdrgLg76PeAhzz6H inGSv826Szj4JXWgzfuzGhPr+QX1TB1O0CSgiN7BZm1qY//3cHgiYtEqz g==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="54461" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="54461" Received: from fmviesa006.fm.intel.com ([10.60.135.146]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 04:40:54 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="347622" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:52 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v3 08/11] eventdev: improve doxygen comments for control APIs Date: Fri, 2 Feb 2024 12:39:50 +0000 Message-Id: <20240202123953.77166-9-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240202123953.77166-1-bruce.richardson@intel.com> References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240202123953.77166-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 doxygen comments for the port attributes, start and stop (and related functions) are improved. Signed-off-by: Bruce Richardson --- V3: add missing "." on end of sentences/lines. --- lib/eventdev/rte_eventdev.h | 47 +++++++++++++++++++++++-------------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index e2923a69fb..a7d8c28015 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -1151,19 +1151,21 @@ rte_event_port_quiesce(uint8_t dev_id, uint8_t port_id, rte_eventdev_port_flush_t release_cb, void *args); /** - * The queue depth of the port on the enqueue side + * Port attribute id for the maximum size of a burst enqueue operation supported on a port. */ #define RTE_EVENT_PORT_ATTR_ENQ_DEPTH 0 /** - * The queue depth of the port on the dequeue side + * Port attribute id for the maximum size of a dequeue burst which can be returned from a port. */ #define RTE_EVENT_PORT_ATTR_DEQ_DEPTH 1 /** - * The new event threshold of the port + * Port attribute id for the new event threshold of the port. + * Once the number of events in the system exceeds this threshold, the enqueue of NEW-type + * events will fail. */ #define RTE_EVENT_PORT_ATTR_NEW_EVENT_THRESHOLD 2 /** - * The implicit release disable attribute of the port + * Port attribute id for the implicit release disable attribute of the port. */ #define RTE_EVENT_PORT_ATTR_IMPLICIT_RELEASE_DISABLE 3 @@ -1171,17 +1173,18 @@ rte_event_port_quiesce(uint8_t dev_id, uint8_t port_id, * Get an attribute from a port. * * @param dev_id - * Eventdev id + * The identifier of the device. * @param port_id - * Eventdev port id + * The index of the event port to query. The value must be less than + * @ref rte_event_dev_config.nb_event_ports previously supplied to rte_event_dev_configure(). * @param attr_id - * The attribute ID to retrieve + * The attribute ID to retrieve (RTE_EVENT_PORT_ATTR_*) * @param[out] attr_value * A pointer that will be filled in with the attribute value if successful * * @return - * - 0: Successfully returned value - * - (-EINVAL) Invalid device, port or attr_id, or attr_value was NULL + * - 0: Successfully returned value. + * - (-EINVAL) Invalid device, port or attr_id, or attr_value was NULL. */ int rte_event_port_attr_get(uint8_t dev_id, uint8_t port_id, uint32_t attr_id, @@ -1190,17 +1193,19 @@ rte_event_port_attr_get(uint8_t dev_id, uint8_t port_id, uint32_t attr_id, /** * Start an event device. * - * The device start step is the last one and consists of setting the event - * queues to start accepting the events and schedules to event ports. + * The device start step is the last one in device setup, and enables the event + * ports and queues to start accepting events and scheduling them to event ports. * * On success, all basic functions exported by the API (event enqueue, * event dequeue and so on) can be invoked. * * @param dev_id - * Event device identifier + * Event device identifier. * @return * - 0: Success, device started. - * - -ESTALE : Not all ports of the device are configured + * - -EINVAL: Invalid device id provided. + * - -ENOTSUP: Device does not support this operation. + * - -ESTALE : Not all ports of the device are configured. * - -ENOLINK: Not all queues are linked, which could lead to deadlock. */ int @@ -1242,18 +1247,22 @@ typedef void (*rte_eventdev_stop_flush_t)(uint8_t dev_id, * callback function must be registered in every process that can call * rte_event_dev_stop(). * + * Only one callback function may be registered. Each new call replaces + * the existing registered callback function with the new function passed in. + * * To unregister a callback, call this function with a NULL callback pointer. * * @param dev_id * The identifier of the device. * @param callback - * Callback function invoked once per flushed event. + * Callback function to be invoked once per flushed event. + * Pass NULL to unset any previously-registered callback function. * @param userdata * Argument supplied to callback. * * @return * - 0 on success. - * - -EINVAL if *dev_id* is invalid + * - -EINVAL if *dev_id* is invalid. * * @see rte_event_dev_stop() */ @@ -1264,12 +1273,14 @@ int rte_event_dev_stop_flush_callback_register(uint8_t dev_id, * Close an event device. The device cannot be restarted! * * @param dev_id - * Event device identifier + * Event device identifier. * * @return * - 0 on successfully closing device - * - <0 on failure to close device - * - (-EAGAIN) if device is busy + * - <0 on failure to close device. + * - -EINVAL - invalid device id. + * - -ENOTSUP - operation not supported for this device. + * - -EAGAIN - device is busy. */ int rte_event_dev_close(uint8_t dev_id); From patchwork Fri Feb 2 12:39: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: 136328 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 54EDA43A4F; Fri, 2 Feb 2024 13:41:35 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 0612642E8C; Fri, 2 Feb 2024 13:41:06 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id A66CA402E8 for ; Fri, 2 Feb 2024 13:41:04 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706877665; x=1738413665; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=5DxhVtBTH0rOnqBaNAwGp13tji+djesWBoIko0QjPO4=; b=PYv5V3oAygesYpdcXNfcSrGSYU8VM8+d5PghJzZuqRaETTltrcD97dd9 afMa6uUJ4MDFdaoI03a5XOS54SoH77r2Tt1lOY6Ct8HKaft2CxPhcUqY1 ncNw22ztcfrxN7D24JuV9Hx3EGc5UFxmuD6MBUaQJ4Xei/TH7hwdbov4P Upk1PcWGTJOWMDt+xGI46EgZagmP48BNlBu3K99yi5/jhFvOthkb0oo4q tBSYsEJTTYFj53wGlsXzK5xnkfzulB00YNdD6/edtvoJdaCw+wFZnSjgb eu2uLDaYwo2BhBbp1RKFnNTLfFM/RVh1jRedGwZ27o0d0DvDSyUiO8RUU g==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="54483" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="54483" Received: from fmviesa006.fm.intel.com ([10.60.135.146]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 04:40:58 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="347645" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:55 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v3 09/11] eventdev: improve comments on scheduling types Date: Fri, 2 Feb 2024 12:39:51 +0000 Message-Id: <20240202123953.77166-10-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240202123953.77166-1-bruce.richardson@intel.com> References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240202123953.77166-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 description of ordered and atomic scheduling given in the eventdev doxygen documentation was not always clear. Try and simplify this so that it is clearer for the end-user of the application Signed-off-by: Bruce Richardson --- V3: extensive rework following feedback. Please re-review! --- lib/eventdev/rte_eventdev.h | 73 +++++++++++++++++++++++-------------- 1 file changed, 45 insertions(+), 28 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index a7d8c28015..8d72765ae7 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -1347,25 +1347,35 @@ struct rte_event_vector { /**< Ordered scheduling * * Events from an ordered flow of an event queue can be scheduled to multiple - * ports for concurrent processing while maintaining the original event order. + * ports for concurrent processing while maintaining the original event order, + * i.e. the order in which they were first enqueued to that queue. * This scheme enables the user to achieve high single flow throughput by - * avoiding SW synchronization for ordering between ports which bound to cores. - * - * The source flow ordering from an event queue is maintained when events are - * enqueued to their destination queue within the same ordered flow context. - * An event port holds the context until application call - * rte_event_dequeue_burst() from the same port, which implicitly releases - * the context. - * User may allow the scheduler to release the context earlier than that - * by invoking rte_event_enqueue_burst() with RTE_EVENT_OP_RELEASE operation. - * - * Events from the source queue appear in their original order when dequeued - * from a destination queue. - * Event ordering is based on the received event(s), but also other - * (newly allocated or stored) events are ordered when enqueued within the same - * ordered context. Events not enqueued (e.g. released or stored) within the - * context are considered missing from reordering and are skipped at this time - * (but can be ordered again within another context). + * avoiding SW synchronization for ordering between ports which are polled + * by different cores. + * + * After events are dequeued from a set of ports, as those events are re-enqueued + * to another queue (with the op field set to @ref RTE_EVENT_OP_FORWARD), the event + * device restores the original event order - including events returned from all + * ports in the set - before the events arrive on the destination queue. + * + * Any events not forwarded i.e. dropped explicitly via RELEASE or implicitly + * released by the next dequeue operation on a port, are skipped by the reordering + * stage and do not affect the reordering of other returned events. + * + * Any NEW events sent on a port are not ordered with respect to FORWARD events sent + * on the same port, since they have no original event order. They also are not + * ordered with respect to NEW events enqueued on other ports. + * However, NEW events to the same destination queue from the same port are guaranteed + * to be enqueued in the order they were submitted via rte_event_enqueue_burst(). + * + * NOTE: + * In restoring event order of forwarded events, the eventdev API guarantees that + * all events from the same flow (i.e. same @ref rte_event.flow_id, + * @ref rte_event.priority and @ref rte_event.queue_id) will be put in the original + * order before being forwarded to the destination queue. + * Some eventdevs may implement stricter ordering to achieve this aim, + * for example, restoring the order across *all* flows dequeued from the same ORDERED + * queue. * * @see rte_event_queue_setup(), rte_event_dequeue_burst(), RTE_EVENT_OP_RELEASE */ @@ -1373,18 +1383,25 @@ struct rte_event_vector { #define RTE_SCHED_TYPE_ATOMIC 1 /**< Atomic scheduling * - * Events from an atomic flow of an event queue can be scheduled only to a + * Events from an atomic flow, identified by a combination of @ref rte_event.flow_id, + * @ref rte_event.queue_id and @ref rte_event.priority, can be scheduled only to a * single port at a time. The port is guaranteed to have exclusive (atomic) * access to the associated flow context, which enables the user to avoid SW - * synchronization. Atomic flows also help to maintain event ordering - * since only one port at a time can process events from a flow of an - * event queue. - * - * The atomic queue synchronization context is dedicated to the port until - * application call rte_event_dequeue_burst() from the same port, - * which implicitly releases the context. User may allow the scheduler to - * release the context earlier than that by invoking rte_event_enqueue_burst() - * with RTE_EVENT_OP_RELEASE operation. + * synchronization. Atomic flows also maintain event ordering + * since only one port at a time can process events from each flow of an + * event queue, and events within a flow are not reordered within the scheduler. + * + * An atomic flow is locked to a port when events from that flow are first + * scheduled to that port. That lock remains in place until the + * application calls rte_event_dequeue_burst() from the same port, + * which implicitly releases the lock (if @ref RTE_EVENT_PORT_CFG_DISABLE_IMPL_REL flag is not set). + * User may allow the scheduler to release the lock earlier than that by invoking + * rte_event_enqueue_burst() with RTE_EVENT_OP_RELEASE operation for each event from that flow. + * + * NOTE: The lock is only released once the last event from the flow, outstanding on the port, + * is released. So long as there is one event from an atomic flow scheduled to + * a port/core (including any events in the port's dequeue queue, not yet read + * by the application), that port will hold the synchronization lock for that flow. * * @see rte_event_queue_setup(), rte_event_dequeue_burst(), RTE_EVENT_OP_RELEASE */ From patchwork Fri Feb 2 12:39: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: 136329 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 5E61643A4F; Fri, 2 Feb 2024 13:41:42 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 32F3042EA4; Fri, 2 Feb 2024 13:41:07 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id 922F3402E8 for ; Fri, 2 Feb 2024 13:41:05 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706877666; x=1738413666; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=0lQxTjmfd7B8O0fajP3oZ69CTv13Dg6NOW2tNvKejJo=; b=CzCo3EjgzwKpuEpHeVDjEwb/CiKHAzlrQUUdOLjDDQtHRUv67+rKEkA6 f7MJ1WvHxX+qNR2Jngu7gid1Io1VejnQZZWRoa57PqoFf4cC1GdqvwwCj dc6s6x2aQ34T6WGK8kfCoQlsi99eXdCrQTsnC8Y4PuXgAZylqXlK9wUKg Z6downqtrBqPUNrQR5Ri6MLzy7RqgLAaI2gPpcvmSKrzhq0157PbPy4D6 cXN8JMiFL2/Vym3gfi8Pa7lJvd8cXmytQ+b3s/2HWYsP0cMYXsSuSTNJu 8asTWb6TjhlciG2JsJnAErzwz2y0uL0RXtw36hTA1j/Q6BtJbPvI/JjhM Q==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="54490" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="54490" Received: from fmviesa006.fm.intel.com ([10.60.135.146]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 04:41:01 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="347666" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:59 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v3 10/11] eventdev: clarify docs on event object fields and op types Date: Fri, 2 Feb 2024 12:39:52 +0000 Message-Id: <20240202123953.77166-11-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240202123953.77166-1-bruce.richardson@intel.com> References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240202123953.77166-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 Clarify the meaning of the NEW, FORWARD and RELEASE event types. For the fields in "rte_event" struct, enhance the comments on each to clarify the field's use, and whether it is preserved between enqueue and dequeue, and it's role, if any, in scheduling. Signed-off-by: Bruce Richardson --- V3: updates following review --- lib/eventdev/rte_eventdev.h | 161 +++++++++++++++++++++++++----------- 1 file changed, 111 insertions(+), 50 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index 8d72765ae7..58219e027e 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -1463,47 +1463,54 @@ struct rte_event_vector { /* Event enqueue operations */ #define RTE_EVENT_OP_NEW 0 -/**< The event producers use this operation to inject a new event to the - * event device. +/**< The @ref rte_event.op field must be set to this operation type to inject a new event, + * i.e. one not previously dequeued, into the event device, to be scheduled + * for processing. */ #define RTE_EVENT_OP_FORWARD 1 -/**< The CPU use this operation to forward the event to different event queue or - * change to new application specific flow or schedule type to enable - * pipelining. +/**< The application must set the @ref rte_event.op field to this operation type to return a + * previously dequeued event to the event device to be scheduled for further processing. * - * This operation must only be enqueued to the same port that the + * This event *must* be enqueued to the same port that the * event to be forwarded was dequeued from. + * + * The event's fields, including (but not limited to) flow_id, scheduling type, + * destination queue, and event payload e.g. mbuf pointer, may all be updated as + * desired by the application, but the @ref rte_event.impl_opaque field must + * be kept to the same value as was present when the event was dequeued. */ #define RTE_EVENT_OP_RELEASE 2 /**< Release the flow context associated with the schedule type. * - * If current flow's scheduler type method is *RTE_SCHED_TYPE_ATOMIC* - * then this function hints the scheduler that the user has completed critical - * section processing in the current atomic context. - * The scheduler is now allowed to schedule events from the same flow from - * an event queue to another port. However, the context may be still held - * until the next rte_event_dequeue_burst() call, this call allows but does not - * force the scheduler to release the context early. - * - * Early atomic context release may increase parallelism and thus system + * If current flow's scheduler type method is @ref RTE_SCHED_TYPE_ATOMIC + * then this operation type hints the scheduler that the user has completed critical + * section processing for this event in the current atomic context, and that the + * scheduler may unlock any atomic locks held for this event. + * If this is the last event from an atomic flow, i.e. all flow locks are released, + * the scheduler is now allowed to schedule events from that flow from to another port. + * However, the atomic locks may be still held until the next rte_event_dequeue_burst() + * call; enqueuing an event with opt type @ref RTE_EVENT_OP_RELEASE allows, + * but does not force, the scheduler to release the atomic locks early. + * + * Early atomic lock release may increase parallelism and thus system * performance, but the user needs to design carefully the split into critical * vs non-critical sections. * - * If current flow's scheduler type method is *RTE_SCHED_TYPE_ORDERED* - * then this function hints the scheduler that the user has done all that need - * to maintain event order in the current ordered context. - * The scheduler is allowed to release the ordered context of this port and - * avoid reordering any following enqueues. - * - * Early ordered context release may increase parallelism and thus system - * performance. + * If current flow's scheduler type method is @ref RTE_SCHED_TYPE_ORDERED + * then this operation type informs the scheduler that the current event has + * completed processing and will not be returned to the scheduler, i.e. + * it has been dropped, and so the reordering context for that event + * should be considered filled. * - * If current flow's scheduler type method is *RTE_SCHED_TYPE_PARALLEL* - * or no scheduling context is held then this function may be an NOOP, - * depending on the implementation. + * Events with this operation type must only be enqueued to the same port that the + * event to be released was dequeued from. The @ref rte_event.impl_opaque + * field in the release event must have the same value as that in the original dequeued event. * - * This operation must only be enqueued to the same port that the - * event to be released was dequeued from. + * If a dequeued event is re-enqueued with operation type of @ref RTE_EVENT_OP_RELEASE, + * then any subsequent enqueue of that event - or a copy of it - must be done as event of type + * @ref RTE_EVENT_OP_NEW, not @ref RTE_EVENT_OP_FORWARD. This is because any context for + * the originally dequeued event, i.e. atomic locks, or reorder buffer entries, will have + * been removed or invalidated by the release operation. */ /** @@ -1517,56 +1524,110 @@ struct rte_event { /** Event attributes for dequeue or enqueue operation */ struct { uint32_t flow_id:20; - /**< Targeted flow identifier for the enqueue and - * dequeue operation. - * The value must be in the range of - * [0, nb_event_queue_flows - 1] which - * previously supplied to rte_event_dev_configure(). + /**< Target flow identifier for the enqueue and dequeue operation. + * + * For @ref RTE_SCHED_TYPE_ATOMIC, this field is used to identify a + * flow for atomicity within a queue & priority level, such that events + * from each individual flow will only be scheduled to one port at a time. + * + * This field is preserved between enqueue and dequeue when + * a device reports the @ref RTE_EVENT_DEV_CAP_CARRY_FLOW_ID + * capability. Otherwise the value is implementation dependent + * on dequeue. */ uint32_t sub_event_type:8; /**< Sub-event types based on the event source. + * + * This field is preserved between enqueue and dequeue. + * This field is for application or event adapter use, + * and is not considered in scheduling decisions. + * * @see RTE_EVENT_TYPE_CPU */ uint32_t event_type:4; - /**< Event type to classify the event source. - * @see RTE_EVENT_TYPE_ETHDEV, (RTE_EVENT_TYPE_*) + /**< Event type to classify the event source. (RTE_EVENT_TYPE_*) + * + * This field is preserved between enqueue and dequeue + * This field is for application or event adapter use, + * and is not considered in scheduling decisions. */ uint8_t op:2; - /**< The type of event enqueue operation - new/forward/ - * etc.This field is not preserved across an instance - * and is undefined on dequeue. - * @see RTE_EVENT_OP_NEW, (RTE_EVENT_OP_*) + /**< The type of event enqueue operation - new/forward/ etc. + * + * This field is *not* preserved across an instance + * and is implementation dependent on dequeue. + * + * @see RTE_EVENT_OP_NEW + * @see RTE_EVENT_OP_FORWARD + * @see RTE_EVENT_OP_RELEASE */ uint8_t rsvd:4; - /**< Reserved for future use */ + /**< Reserved for future use. + * + * Should be set to zero on enqueue. + */ uint8_t sched_type:2; /**< Scheduler synchronization type (RTE_SCHED_TYPE_*) * associated with flow id on a given event queue * for the enqueue and dequeue operation. + * + * This field is used to determine the scheduling type + * for events sent to queues where @ref RTE_EVENT_QUEUE_CFG_ALL_TYPES + * is configured. + * For queues where only a single scheduling type is available, + * this field must be set to match the configured scheduling type. + * + * This field is preserved between enqueue and dequeue. + * + * @see RTE_SCHED_TYPE_ORDERED + * @see RTE_SCHED_TYPE_ATOMIC + * @see RTE_SCHED_TYPE_PARALLEL */ uint8_t queue_id; /**< Targeted event queue identifier for the enqueue or * dequeue operation. - * The value must be in the range of - * [0, nb_event_queues - 1] which previously supplied to - * rte_event_dev_configure(). + * The value must be less than @ref rte_event_dev_config.nb_event_queues + * which was previously supplied to rte_event_dev_configure(). + * + * This field is preserved between enqueue on dequeue. */ uint8_t priority; /**< Event priority relative to other events in the * event queue. The requested priority should in the - * range of [RTE_EVENT_DEV_PRIORITY_HIGHEST, - * RTE_EVENT_DEV_PRIORITY_LOWEST]. + * range of [@ref RTE_EVENT_DEV_PRIORITY_HIGHEST, + * @ref RTE_EVENT_DEV_PRIORITY_LOWEST]. + * * The implementation shall normalize the requested * priority to supported priority value. - * Valid when the device has - * RTE_EVENT_DEV_CAP_EVENT_QOS capability. + * [For devices with where the supported priority range is a power-of-2, the + * normalization will be done via bit-shifting, so only the highest + * log2(num_priorities) bits will be used by the event device] + * + * Valid when the device has @ref RTE_EVENT_DEV_CAP_EVENT_QOS capability + * and this field is preserved between enqueue and dequeue, + * though with possible loss of precision due to normalization and + * subsequent de-normalization. (For example, if a device only supports 8 + * priority levels, only the high 3 bits of this field will be + * used by that device, and hence only the value of those 3 bits are + * guaranteed to be preserved between enqueue and dequeue.) + * + * Ignored when device does not support @ref RTE_EVENT_DEV_CAP_EVENT_QOS + * capability, and it is implementation dependent if this field is preserved + * between enqueue and dequeue. */ uint8_t impl_opaque; - /**< Implementation specific opaque value. - * An implementation may use this field to hold + /**< Opaque field for event device use. + * + * An event driver implementation may use this field to hold an * implementation specific value to share between * dequeue and enqueue operation. - * The application should not modify this field. + * + * The application most not modify this field. + * Its value is implementation dependent on dequeue, + * and must be returned unmodified on enqueue when + * op type is @ref RTE_EVENT_OP_FORWARD or @ref RTE_EVENT_OP_RELEASE. + * This field is ignored on events with op type + * @ref RTE_EVENT_OP_NEW. */ }; }; From patchwork Fri Feb 2 12:39: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: 136330 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 A461F43A4F; Fri, 2 Feb 2024 13:41:50 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 4AB5A42E98; Fri, 2 Feb 2024 13:41:12 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id 649A842E98 for ; Fri, 2 Feb 2024 13:41:10 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706877670; x=1738413670; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=JRyy1r4mZqtGsqD8BymY8JEzhWuLRD3cJdvt0jFS7Uc=; b=UgXX1u3S9VLZxW5MZrCV5eUsb64rO+soudx1zE6votLoui04ddrOi9Zt gWoyocBiafCLVfjPYXuWSV9GGkpuy1XwVKVfUZGfzJqEjkebxw7iHNDgw ZCaCDTp1sOuulJ0E+2Z1zPnoV67W4MLmXAUNuSjkL4FQky9wJUzWq+Tzh 4WCcDBdZZZNbmiVrYE8oUHvbrg97kVfb0NrpA4+y9DQWSlgdhiAXuEmQU FmBOa1SJna5Sqen+MTsJI7sMGb3iNszBGbF/vSyiep1+yVteN8T3MDEHh ruKSfNhGytwodNSJTIVpN5eoK0XyenhYsaxQPgLznh1BbKryU7HejTItt g==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="54521" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="54521" Received: from fmviesa006.fm.intel.com ([10.60.135.146]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 04:41:07 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="347701" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:41:05 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v3 11/11] eventdev: drop comment for anon union from doxygen Date: Fri, 2 Feb 2024 12:39:53 +0000 Message-Id: <20240202123953.77166-12-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240202123953.77166-1-bruce.richardson@intel.com> References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240202123953.77166-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 the comments on the unnamed unions in the rte_event structure regular comments rather than doxygen ones. The comments do not add anything meaningful to the doxygen output. Signed-off-by: Bruce Richardson --- lib/eventdev/rte_eventdev.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index 58219e027e..e31c927905 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -1518,7 +1518,7 @@ struct rte_event_vector { * for dequeue and enqueue operation */ struct rte_event { - /** WORD0 */ + /* WORD0 */ union { uint64_t event; /** Event attributes for dequeue or enqueue operation */ @@ -1631,7 +1631,7 @@ struct rte_event { */ }; }; - /** WORD1 */ + /* WORD1 */ union { uint64_t u64; /**< Opaque 64-bit value */