From patchwork Wed Feb 21 10:32:13 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 136960 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 5A94543B61; Wed, 21 Feb 2024 11:32:56 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 255D040DFD; Wed, 21 Feb 2024 11:32:38 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.15]) by mails.dpdk.org (Postfix) with ESMTP id F2FED40A7A for ; Wed, 21 Feb 2024 11:32:34 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1708511555; x=1740047555; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=k/5dlU9izFhQpEpGZK+oUdpakEj1XgvZRvY1liU5WP8=; b=O6Lit5ODkpnxV/C8/RKcDBRIaaZYuS2WeYIjtzLb4kl2Y7h/0yEJVOmX fU2cW09Exz3jNyIaWvzEEbxG+cpfjgZQodt0mRl+yKXg6sURjF5hmJz2j cIV5gMb70jUGLDxjg8TvUvVe7vWQX3UOaitOuSKioeq6TLN5HnHhqll8j 0Bdx3yF8bdpM1/greRxiSwhX09JJkyZm6mZtWzRvl/ImW5JllSjFYeq4x 2+F1P9LG1M24g7hlToZ6g3v5gE+du/c5BBIuSDCypyVjBnkb3IfmQLOoE 8BzteRfciZahSSYmInnxR4CeAmzZlWv60WFvH/AZXTWJi/xykBzb0Cee/ g==; X-IronPort-AV: E=McAfee;i="6600,9927,10990"; a="2800709" X-IronPort-AV: E=Sophos;i="6.06,175,1705392000"; d="scan'208";a="2800709" Received: from orviesa007.jf.intel.com ([10.64.159.147]) by fmvoesa109.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 21 Feb 2024 02:32:35 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.06,175,1705392000"; d="scan'208";a="5392992" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by orviesa007.jf.intel.com with ESMTP; 21 Feb 2024 02:32:33 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: Bruce Richardson Subject: [PATCH v4 04/12] eventdev: cleanup doxygen comments on info structure Date: Wed, 21 Feb 2024 10:32:13 +0000 Message-Id: <20240221103221.933238-5-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240221103221.933238-1-bruce.richardson@intel.com> References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240221103221.933238-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 Acked-by: Pavan Nikhilesh --- 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 f7b98a6cfa..b9ec3fc45e 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -537,57 +537,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. */ };