From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 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 Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org 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. */ }; -- 2.40.1