DPDK patches and discussions
 help / color / mirror / Atom feed
From: "Mattias Rönnblom" <hofors@lysator.liu.se>
To: Bruce Richardson <bruce.richardson@intel.com>, dev@dpdk.org
Cc: jerinj@marvell.com, mattias.ronnblom@ericsson.com,
	abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com,
	hemant.agrawal@nxp.com, pbhagavatula@marvell.com,
	pravin.pathak@intel.com
Subject: Re: [PATCH v2 04/11] eventdev: cleanup doxygen comments on info structure
Date: Tue, 23 Jan 2024 10:35:02 +0100	[thread overview]
Message-ID: <65d09512-f184-4ac4-a513-e5820754889e@lysator.liu.se> (raw)
In-Reply-To: <20240119174346.108905-5-bruce.richardson@intel.com>

On 2024-01-19 18:43, Bruce Richardson wrote:
> Some small rewording changes to the doxygen comments on struct
> rte_event_dev_info.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---
>   lib/eventdev/rte_eventdev.h | 46 ++++++++++++++++++++-----------------
>   1 file changed, 25 insertions(+), 21 deletions(-)
> 
> diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h
> index 57a2791946..872f241df2 100644
> --- a/lib/eventdev/rte_eventdev.h
> +++ b/lib/eventdev/rte_eventdev.h
> @@ -482,54 +482,58 @@ struct rte_event_dev_info {
>   	const char *driver_name;	/**< Event driver name */
>   	struct rte_device *dev;	/**< Device information */
>   	uint32_t min_dequeue_timeout_ns;
> -	/**< Minimum supported global dequeue timeout(ns) by this device */
> +	/**< Minimum global dequeue timeout(ns) supported by this device */

Are we missing a bunch of "." here and in the other fields?

>   	uint32_t max_dequeue_timeout_ns;
> -	/**< Maximum supported global dequeue timeout(ns) by this device */
> +	/**< Maximum global dequeue timeout(ns) supported by this device */
>   	uint32_t dequeue_timeout_ns;
>   	/**< Configured global dequeue timeout(ns) for this device */
>   	uint8_t max_event_queues;
> -	/**< Maximum event_queues supported by this device */
> +	/**< Maximum event queues supported by this device */
>   	uint32_t max_event_queue_flows;
> -	/**< Maximum supported flows in an event queue by this device*/
> +	/**< Maximum number of flows within an event queue supported by this device*/
>   	uint8_t max_event_queue_priority_levels;
>   	/**< Maximum number of event queue priority levels by this device.
> -	 * Valid when the device has RTE_EVENT_DEV_CAP_QUEUE_QOS capability
> +	 * Valid when the device has RTE_EVENT_DEV_CAP_QUEUE_QOS capability.
> +	 * The priority levels are evenly distributed between
> +	 * @ref RTE_EVENT_DEV_PRIORITY_HIGHEST and @ref RTE_EVENT_DEV_PRIORITY_LOWEST.

This is a change of the API, in the sense it's defining something 
previously left undefined?

If you need 6 different priority levels in an app, how do you go about 
making sure you find the correct (distinct) Eventdev levels on any event 
device supporting >= 6 levels?

#define NUM_MY_LEVELS 6

#define MY_LEVEL_TO_EVENTDEV_LEVEL(my_level) (((my_level) * 
(RTE_EVENT_DEV_PRIORITY_HIGHEST-RTE_EVENT_DEV_PRIORTY_LOWEST) / 
NUM_MY_LEVELS)

This way? One would worry a bit exactly what "evenly" means, in terms of 
rounding errors. If you have an event device with 255 priority levels of 
(say) 256 levels available in the API, which two levels are the same 
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
> +	 * The priority levels are evenly distributed between
> +	 * @ref RTE_EVENT_DEV_PRIORITY_HIGHEST and @ref RTE_EVENT_DEV_PRIORITY_LOWEST.
>   	 */
>   	uint8_t max_event_ports;
>   	/**< Maximum number of event ports supported by this device */
>   	uint8_t max_event_port_dequeue_depth;
> -	/**< Maximum number of events can be dequeued at a time from an
> -	 * event port by this device.
> -	 * A device that does not support bulk dequeue will set this as 1.
> +	/**< Maximum number of events that can be dequeued at a time from an event port
> +	 * on this device.
> +	 * A device that does not support bulk dequeue will set this to 1.
>   	 */
>   	uint32_t max_event_port_enqueue_depth;
> -	/**< Maximum number of events can be enqueued at a time from an
> -	 * event port by this device.
> -	 * A device that does not support bulk enqueue will set this as 1.
> +	/**< Maximum number of events that can be enqueued at a time to an event port
> +	 * on this device.
> +	 * A device that does not support bulk enqueue will set this to 1.
>   	 */
>   	uint8_t max_event_port_links;
> -	/**< Maximum number of queues that can be linked to a single event
> -	 * port by this device.
> +	/**< Maximum number of queues that can be linked to a single event port on this device.
>   	 */
>   	int32_t max_num_events;
>   	/**< A *closed system* event dev has a limit on the number of events it
> -	 * can manage at a time. An *open system* event dev does not have a
> -	 * limit and will specify this as -1.
> +	 * can manage at a time.
> +	 * Once the number of events tracked by an eventdev exceeds this number,
> +	 * any enqueues of NEW events will fail.
> +	 * An *open system* event dev does not have a limit and will specify this as -1.
>   	 */
>   	uint32_t event_dev_cap;
> -	/**< Event device capabilities(RTE_EVENT_DEV_CAP_)*/
> +	/**< Event device capabilities flags (RTE_EVENT_DEV_CAP_*) */
>   	uint8_t max_single_link_event_port_queue_pairs;
> -	/**< Maximum number of event ports and queues that are optimized for
> -	 * (and only capable of) single-link configurations supported by this
> -	 * device. These ports and queues are not accounted for in
> -	 * max_event_ports or max_event_queues.
> +	/**< Maximum number of event ports and queues,  supported by this device,
> +	 * that are optimized for (and only capable of) single-link configurations.
> +	 * These ports and queues are not accounted for in max_event_ports or max_event_queues.
>   	 */
>   	uint8_t max_profiles_per_port;
> -	/**< Maximum number of event queue profiles per event port.
> +	/**< Maximum number of event queue link profiles per event port.
>   	 * A device that doesn't support multiple profiles will set this as 1.
>   	 */
>   };

  reply	other threads:[~2024-01-23  9:35 UTC|newest]

Thread overview: 123+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-01-18 13:45 [PATCH v1 0/7] improve eventdev API specification/documentation Bruce Richardson
2024-01-18 13:45 ` [PATCH v1 1/7] eventdev: improve doxygen introduction text Bruce Richardson
2024-01-18 13:45 ` [PATCH v1 2/7] eventdev: move text on driver internals to proper section Bruce Richardson
2024-01-18 13:45 ` [PATCH v1 3/7] eventdev: update documentation on device capability flags Bruce Richardson
2024-01-18 13:45 ` [PATCH v1 4/7] eventdev: cleanup doxygen comments on info structure Bruce Richardson
2024-01-18 13:49   ` Bruce Richardson
2024-01-18 13:45 ` [PATCH v1 5/7] eventdev: improve function documentation for query fns Bruce Richardson
2024-01-18 13:45 ` [PATCH v1 6/7] eventdev: improve doxygen comments on configure struct Bruce Richardson
2024-01-18 13:45 ` [PATCH v1 7/7] eventdev: fix documentation for counting single-link ports Bruce Richardson
2024-01-19 17:43 ` [PATCH v2 00/11] improve eventdev API specification/documentation Bruce Richardson
2024-01-19 17:43   ` [PATCH v2 01/11] eventdev: improve doxygen introduction text Bruce Richardson
2024-01-23  8:57     ` Mattias Rönnblom
2024-01-23  9:06       ` Bruce Richardson
2024-01-24 11:37         ` Mattias Rönnblom
2024-01-31 13:45       ` Bruce Richardson
2024-01-19 17:43   ` [PATCH v2 02/11] eventdev: move text on driver internals to proper section Bruce Richardson
2024-01-19 17:43   ` [PATCH v2 03/11] eventdev: update documentation on device capability flags Bruce Richardson
2024-01-23  9:18     ` Mattias Rönnblom
2024-01-23  9:34       ` Bruce Richardson
2024-01-31 14:09       ` Bruce Richardson
2024-02-02  8:58         ` Mattias Rönnblom
2024-02-02 11:20           ` Bruce Richardson
2024-01-19 17:43   ` [PATCH v2 04/11] eventdev: cleanup doxygen comments on info structure Bruce Richardson
2024-01-23  9:35     ` Mattias Rönnblom [this message]
2024-01-23  9:43       ` Bruce Richardson
2024-01-24 11:51         ` Mattias Rönnblom
2024-01-31 14:37           ` Bruce Richardson
2024-02-02  9:24             ` Mattias Rönnblom
2024-02-02 10:30               ` Bruce Richardson
2024-01-19 17:43   ` [PATCH v2 05/11] eventdev: improve function documentation for query fns Bruce Richardson
2024-01-23  9:40     ` Mattias Rönnblom
2024-01-19 17:43   ` [PATCH v2 06/11] eventdev: improve doxygen comments on configure struct Bruce Richardson
2024-01-23  9:46     ` Mattias Rönnblom
2024-01-31 16:15       ` Bruce Richardson
2024-01-19 17:43   ` [PATCH v2 07/11] eventdev: fix documentation for counting single-link ports Bruce Richardson
2024-01-23  9:48     ` Mattias Rönnblom
2024-01-23  9:56       ` Bruce Richardson
2024-01-31 16:18         ` Bruce Richardson
2024-01-19 17:43   ` [PATCH v2 08/11] eventdev: improve doxygen comments on config fns Bruce Richardson
2024-01-23 10:00     ` Mattias Rönnblom
2024-01-23 10:07       ` Bruce Richardson
2024-01-19 17:43   ` [PATCH v2 09/11] eventdev: improve doxygen comments for control APIs Bruce Richardson
2024-01-23 10:10     ` Mattias Rönnblom
2024-01-19 17:43   ` [PATCH v2 10/11] eventdev: RFC clarify comments on scheduling types Bruce Richardson
2024-01-23 16:19     ` Mattias Rönnblom
2024-01-24 11:21       ` Bruce Richardson
2024-01-31 17:54       ` Bruce Richardson
2024-01-19 17:43   ` [PATCH v2 11/11] eventdev: RFC clarify docs on event object fields Bruce Richardson
2024-01-24 11:34     ` Mattias Rönnblom
2024-02-01 16:59       ` Bruce Richardson
2024-02-02  9:38         ` Mattias Rönnblom
2024-02-02 11:33           ` Bruce Richardson
2024-02-02 12:02             ` Bruce Richardson
2024-02-01 17:02       ` Bruce Richardson
2024-02-02  9:14         ` Bruce Richardson
2024-02-02  9:22         ` Jerin Jacob
2024-02-02  9:36           ` Bruce Richardson
2024-02-02  9:45         ` Mattias Rönnblom
2024-02-02 10:32           ` Bruce Richardson
2024-02-01  9:35     ` Bruce Richardson
2024-02-01 15:00       ` Jerin Jacob
2024-02-01 15:24         ` Bruce Richardson
2024-02-01 16:20           ` Jerin Jacob
2024-02-02 12:39   ` [PATCH v3 00/11] improve eventdev API specification/documentation Bruce Richardson
2024-02-02 12:39     ` [PATCH v3 01/11] eventdev: improve doxygen introduction text Bruce Richardson
2024-02-07 10:14       ` Jerin Jacob
2024-02-08  9:50         ` Mattias Rönnblom
2024-02-09  8:43           ` Jerin Jacob
2024-02-10  7:24             ` Mattias Rönnblom
2024-02-20 16:28               ` Bruce Richardson
2024-02-20 16:33         ` Bruce Richardson
2024-02-02 12:39     ` [PATCH v3 02/11] eventdev: move text on driver internals to proper section Bruce Richardson
2024-02-02 12:39     ` [PATCH v3 03/11] eventdev: update documentation on device capability flags Bruce Richardson
2024-02-07 10:30       ` Jerin Jacob
2024-02-20 16:42         ` Bruce Richardson
2024-02-02 12:39     ` [PATCH v3 04/11] eventdev: cleanup doxygen comments on info structure Bruce Richardson
2024-02-02 12:39     ` [PATCH v3 05/11] eventdev: improve function documentation for query fns Bruce Richardson
2024-02-02 12:39     ` [PATCH v3 06/11] eventdev: improve doxygen comments on configure struct Bruce Richardson
2024-02-02 12:39     ` [PATCH v3 07/11] eventdev: improve doxygen comments on config fns Bruce Richardson
2024-02-02 12:39     ` [PATCH v3 08/11] eventdev: improve doxygen comments for control APIs Bruce Richardson
2024-02-02 12:39     ` [PATCH v3 09/11] eventdev: improve comments on scheduling types Bruce Richardson
2024-02-08  9:18       ` Jerin Jacob
2024-02-08 10:04         ` Mattias Rönnblom
2024-02-20 17:23           ` Bruce Richardson
2024-02-02 12:39     ` [PATCH v3 10/11] eventdev: clarify docs on event object fields and op types Bruce Richardson
2024-02-09  9:14       ` Jerin Jacob
2024-02-20 17:39         ` Bruce Richardson
2024-02-21  9:31           ` Jerin Jacob
2024-02-21 10:28             ` Bruce Richardson
2024-02-20 17:50         ` Bruce Richardson
2024-02-20 18:03         ` Bruce Richardson
2024-02-02 12:39     ` [PATCH v3 11/11] eventdev: drop comment for anon union from doxygen Bruce Richardson
2024-02-21 10:32   ` [PATCH v4 00/12] improve eventdev API specification/documentation Bruce Richardson
2024-02-21 10:32     ` [PATCH v4 01/12] eventdev: improve doxygen introduction text Bruce Richardson
2024-02-26  4:51       ` [EXT] " Pavan Nikhilesh Bhagavatula
2024-02-26  9:59         ` Bruce Richardson
2024-02-29 16:13           ` Jerin Jacob
2024-02-21 10:32     ` [PATCH v4 02/12] eventdev: move text on driver internals to proper section Bruce Richardson
2024-02-26  5:01       ` [EXT] " Pavan Nikhilesh Bhagavatula
2024-02-21 10:32     ` [PATCH v4 03/12] eventdev: update documentation on device capability flags Bruce Richardson
2024-02-26  5:07       ` [EXT] " Pavan Nikhilesh Bhagavatula
2024-02-21 10:32     ` [PATCH v4 04/12] eventdev: cleanup doxygen comments on info structure Bruce Richardson
2024-02-26  5:18       ` [EXT] " Pavan Nikhilesh Bhagavatula
2024-02-21 10:32     ` [PATCH v4 05/12] eventdev: improve function documentation for query fns Bruce Richardson
2024-02-26  5:18       ` [EXT] " Pavan Nikhilesh Bhagavatula
2024-02-21 10:32     ` [PATCH v4 06/12] eventdev: improve doxygen comments on configure struct Bruce Richardson
2024-02-26  6:36       ` [EXT] " Pavan Nikhilesh Bhagavatula
2024-02-21 10:32     ` [PATCH v4 07/12] eventdev: improve doxygen comments on config fns Bruce Richardson
2024-02-26  6:43       ` [EXT] " Pavan Nikhilesh Bhagavatula
2024-02-26  6:44         ` Pavan Nikhilesh Bhagavatula
2024-02-21 10:32     ` [PATCH v4 08/12] eventdev: improve doxygen comments for control APIs Bruce Richardson
2024-02-26  6:44       ` [EXT] " Pavan Nikhilesh Bhagavatula
2024-02-21 10:32     ` [PATCH v4 09/12] eventdev: improve comments on scheduling types Bruce Richardson
2024-02-26  6:49       ` [EXT] " Pavan Nikhilesh Bhagavatula
2024-02-21 10:32     ` [PATCH v4 10/12] eventdev: clarify docs on event object fields and op types Bruce Richardson
2024-02-26  6:52       ` [EXT] " Pavan Nikhilesh Bhagavatula
2024-02-21 10:32     ` [PATCH v4 11/12] eventdev: drop comment for anon union from doxygen Bruce Richardson
2024-02-26  6:52       ` [EXT] " Pavan Nikhilesh Bhagavatula
2024-02-21 10:32     ` [PATCH v4 12/12] eventdev: fix doxygen processing of event vector struct Bruce Richardson
2024-02-26  6:53       ` [EXT] " Pavan Nikhilesh Bhagavatula
2024-03-04 15:35       ` Thomas Monjalon
2024-03-04 15:49         ` Bruce Richardson
2024-02-23 12:36     ` [PATCH v4 00/12] improve eventdev API specification/documentation Jerin Jacob

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=65d09512-f184-4ac4-a513-e5820754889e@lysator.liu.se \
    --to=hofors@lysator.liu.se \
    --cc=abdullah.sevincer@intel.com \
    --cc=bruce.richardson@intel.com \
    --cc=dev@dpdk.org \
    --cc=hemant.agrawal@nxp.com \
    --cc=jerinj@marvell.com \
    --cc=mattias.ronnblom@ericsson.com \
    --cc=pbhagavatula@marvell.com \
    --cc=pravin.pathak@intel.com \
    --cc=sachin.saxena@oss.nxp.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).