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 BDD7843A4E; Fri, 2 Feb 2024 11:30:45 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 5C96F402BF; Fri, 2 Feb 2024 11:30:45 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [198.175.65.19]) by mails.dpdk.org (Postfix) with ESMTP id 528044026E for ; Fri, 2 Feb 2024 11:30:43 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706869844; x=1738405844; h=date:from:to:cc:subject:message-id:references: content-transfer-encoding:in-reply-to:mime-version; bh=q5MMPc8/aBEFmDadbspAW10G9yjxzP6hTFw+xG+NwDk=; b=m+DZK3GNfOnwCmcc4uk1c4ppEnE9elYHQvU85HQ4XML3jdG7CMD+sY1c JHS4kA7rLiixlaLst6eRjPTgWFQaKFXPxw9UGVwY0BWHfzQfNUg4kI/O4 Ps7/G32qL1nVrI7i9dr2MeJy+AIfo5GALvHDACkNgWPiDCHKWeQOrxglg AeoxcSxOCVFI7GY6hqAK5LlJYXb0PAnIEPBDK9k2QFcmQP9GEvIS6R8cU begfD+15kQG8B+uSdZJ7ZlHbxE7pjUktXyAvNqFu+zY4BI71siOtOqAp0 IGlmpXlywuPmtf0LfzIF/gUnSFxcx3/DegBw5hEh7KDZNjsbmzXosQmnm w==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="44958" X-IronPort-AV: E=Sophos;i="6.05,237,1701158400"; d="scan'208";a="44958" Received: from fmviesa009.fm.intel.com ([10.60.135.149]) by orvoesa111.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 02:30:43 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,237,1701158400"; d="scan'208";a="34561" Received: from fmsmsx602.amr.corp.intel.com ([10.18.126.82]) by fmviesa009.fm.intel.com with ESMTP/TLS/AES256-GCM-SHA384; 02 Feb 2024 02:30:42 -0800 Received: from fmsmsx610.amr.corp.intel.com (10.18.126.90) by fmsmsx602.amr.corp.intel.com (10.18.126.82) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.35; Fri, 2 Feb 2024 02:30:41 -0800 Received: from fmsedg601.ED.cps.intel.com (10.1.192.135) by fmsmsx610.amr.corp.intel.com (10.18.126.90) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.35 via Frontend Transport; Fri, 2 Feb 2024 02:30:41 -0800 Received: from NAM11-DM6-obe.outbound.protection.outlook.com (104.47.57.169) by edgegateway.intel.com (192.55.55.70) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2507.35; Fri, 2 Feb 2024 02:30:41 -0800 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=dmnUseO+Z1Kzu3A2PfkHpfPsmxcV6zW8jd2zY4nONPC5IdjQlTJJ7VSOa8dQ4ei7Kfag8/ln8TbvheFUloEEzMgO3bnjDLnWqWSwmSwDhf1cL2TieVuo0SWrzNHsi0LYRe/FmlayWkxrMM0ESq6ZQ9O+9078X2fI3X01/DyX7nuykFu1Jcih5ZKfy8YnX9NtEa4OF4i4cBFlboACVlclm9kHFID6rAMgwhxHY2PwSQwNOxiUL9NYdLjjdYX9I7SFD+JgPVMyU30nds/B+WeWCkGfsdUkt2vLI45Y0XKxUbFcoFqZM/t/pUOoIW1asx6GMO5OecK6h4YxoKzSXSqlRg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=3voy70RWGswMZ3hAZBaCEq8cJz6Jb08mkgeQLCsa+7M=; b=F+TKtbmJ2NWoVxzUkMOXIFnHaYeALpl6xeHYpilnEseNtASUVYUK4iLreIp45lsl1VfdJZLBmZk57dEvztfL1C7Ls8vK7QzdOaC11Mm4zLgrfSXttauvghDZR7pgqsKkvNuFKYZV+OVSAC0RNHIcq7iZufDckC35JZIqTd+xPuhkDYKcuoEmE06xFRHRVLXweQdjPYFLxKuZRwlS+l3AfJJUL8PYlFsq192YoVdo++NX8lsnDz80mp1OdHWHqULbQF7qcbxlpEic4XpKItdj2L3/mUkPPVbz7Dq4EnLL+hprCkPxZILFppgSzmzFPuDMdBHREnKVmQ1893XjXA5XkQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=intel.com; dmarc=pass action=none header.from=intel.com; dkim=pass header.d=intel.com; arc=none Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=intel.com; Received: from DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) by MW3PR11MB4761.namprd11.prod.outlook.com (2603:10b6:303:53::15) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7249.27; Fri, 2 Feb 2024 10:30:39 +0000 Received: from DS0PR11MB7309.namprd11.prod.outlook.com ([fe80::df88:b743:97f8:516c]) by DS0PR11MB7309.namprd11.prod.outlook.com ([fe80::df88:b743:97f8:516c%5]) with mapi id 15.20.7249.027; Fri, 2 Feb 2024 10:30:39 +0000 Date: Fri, 2 Feb 2024 10:30:33 +0000 From: Bruce Richardson To: Mattias =?iso-8859-1?Q?R=F6nnblom?= CC: , , , , , , , Subject: Re: [PATCH v2 04/11] eventdev: cleanup doxygen comments on info structure Message-ID: References: <20240118134557.73172-1-bruce.richardson@intel.com> <20240119174346.108905-1-bruce.richardson@intel.com> <20240119174346.108905-5-bruce.richardson@intel.com> <65d09512-f184-4ac4-a513-e5820754889e@lysator.liu.se> <26f7d4b7-d46f-461b-a891-7a32d14f4b21@lysator.liu.se> <839761ae-ee75-4a77-8f00-f0848ff638a4@lysator.liu.se> Content-Type: text/plain; charset="iso-8859-1" Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <839761ae-ee75-4a77-8f00-f0848ff638a4@lysator.liu.se> X-ClientProxiedBy: DUZP191CA0051.EURP191.PROD.OUTLOOK.COM (2603:10a6:10:4fa::28) To DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|MW3PR11MB4761:EE_ X-MS-Office365-Filtering-Correlation-Id: b45fa646-d721-4055-f997-08dc23da001b X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: H9u890N1XMNgYeDGYpxDOE4oK3fXYFTphc5UpM25XSHoeE7vMzNutHWkxvpmcCe60u9fv8dSG2foYG6STkNNIEag4xOccYR9EQm/iNTldRqEiKAF3nsEpx0C17ppTCFkdKJWm0wlVLwiyGIzTMXiY86lCiBt7zphRcsacR6RyK+xqO2yZW+ozAElAbj9M57qOb8FTyra3RaTnIAMxUBytjxEPXCMXeMytlJqFOdxMeipt3CC3Zi6YRma0Q0TjqTuTEehdAcPzZNtnz0iDGxkH2XujYVLcCjlLwAeU64y4LgVmOO6/QvDHehOT5F8twm/nzZw1Qd7ZKvY3de/WdWbmZr0KafcomWmW8C8RA+ot66tlec0VVLyqapUuVcZWePz9FpzhJ/aEmnupiuXt64J//r/lduK2Ab3UXez8dK5VHJSHJO6VF10ELorGMdbBbFW5nl3NptQdy5hYqMxB8HvkwPb8kqSAL4ebMkI5pIsDW3Jho/1jM/NUJCrMZTtcK7jOoTeMb1E0rgoAYl6Cu1oClzbWEh60cKfsRe68X/2H7+pKQJzg+S1jh8By9yCqdT0 X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:DS0PR11MB7309.namprd11.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230031)(39860400002)(396003)(346002)(376002)(366004)(136003)(230922051799003)(1800799012)(451199024)(186009)(64100799003)(5660300002)(478600001)(6512007)(66946007)(6666004)(6506007)(53546011)(8936002)(6916009)(86362001)(8676002)(66476007)(4326008)(41300700001)(316002)(66556008)(296002)(66574015)(26005)(107886003)(38100700002)(82960400001)(83380400001)(44832011)(6486002)(2906002); DIR:OUT; SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?iso-8859-1?Q?UQC2o5LItsf+scAuSr62XsNB1gBaivwk9l8FlnyMwWAG+r8S7hMr2d7GVa?= =?iso-8859-1?Q?yBmiFr9UEoHViJX4+YXR9vGa2r07KuUgPuCHzuwN+3fGqtlKgT9XmfsAIM?= =?iso-8859-1?Q?zgBDfHy4DxKcGd4k8ThuFkSzSKQK8zCXXyJKQHB6C++0VDvhrXhpfqFCBI?= =?iso-8859-1?Q?+CFf/9zqSenP4qRecMFGYukoioXKEUQjKTDIHCSbtCvickncpPKJOgP+zg?= =?iso-8859-1?Q?REG+fWoUZqjIdvEMbxWfmMBjn2YA7YD2OcJ3H9LiDDYM9NeEtbpd8Yst4s?= =?iso-8859-1?Q?Ncs5LSJipJFCPcenMvBOiICJdhh4ZyJa1ssicKMUeWyh87aFGbe4BP9Z/5?= =?iso-8859-1?Q?yWvBKA1hmXGBpWZh+1kqFr+LtklXkkGHCRkV9HhRYeaWZjt2ysnLUGJoWa?= =?iso-8859-1?Q?BX8xESKm0RNUFGBr+kDxR8UykM1/YtBttJ+R5TIKGd1rnjg0Iwdff7AP8P?= =?iso-8859-1?Q?ScFyTGTA7/N7kimrAy8Q7aMVmxRH15WCpC7aHn7jbB2gt/dXJqydh79onA?= =?iso-8859-1?Q?A8N7md13Q4iYtQhZG/KtGhgK6Gqj7Iihc3GWZLyEn051Oyx4D+OS7NUaCl?= =?iso-8859-1?Q?0TaLErW+NfBYDz6Pk1YKifnHVkjIDgcNH64nSzvE0H9cjuHM7v+CQ1O3B7?= =?iso-8859-1?Q?9tdU1SMk6x4oEVT83BFDxmD6QoMq+gC74y09GjX0I9ua5/0iBcy0EEkN/0?= =?iso-8859-1?Q?h9zAt7sGRdu4gn+Z0T76hmaUybFlEVlE0/gh6G82XJJfEA711J9UDJiyaz?= =?iso-8859-1?Q?FbFEXsywAdez1OHtqfkzRC+YAdbVNxVbkKMClUpdalp0sWHoBCJDtNhqXM?= =?iso-8859-1?Q?XmQ3+NUv2ArvBARXZsLaeAAv2LPDjjnQd8liVX3ABT8NZ9WQCNPprJbGmH?= =?iso-8859-1?Q?Sxc5Acp0WPkXOZUBEjsukQhR+Q159XFr+Wlnst6ioiNithNfyBRe9QZB43?= =?iso-8859-1?Q?l0M2TRec2g1025pQz/AeYk0G+guSEA9OlczXmfCyIiSXXjwIonmZ6D5vkC?= =?iso-8859-1?Q?yTJNO6iuBqr3fDYu3wgzc3ix9CgIMNOgI8Kd8be927VKkrNGNQXY2yYXPh?= =?iso-8859-1?Q?32tG2/0ZJvf5NlfOpwW1+25rrNsCe7wqRJJJm8HYN03IoC5E6M4/dL55Bs?= =?iso-8859-1?Q?sGAo8z+IzlLY8nPQ1YZhPHTPL5qhxF32Ij7iLmHCjehmP7fOZXeUucgFep?= =?iso-8859-1?Q?gs8HmaojX2EQOboUqrbUd7y/Rn7Vi1Oh3bUqMxA1esMktfoeySStFxusR0?= =?iso-8859-1?Q?txUpcXNHyYpHytcAWq85wzEfVhdDWjShp7u6Hi1QhfQ7D5dfVET8bRhems?= =?iso-8859-1?Q?TzNABnGMtPl2KU3U8JXSsOI1pxdVgvmzhv8BXSs63pWR8d75GIIUWxuRr8?= =?iso-8859-1?Q?8lmkG1OHUUjZyOLmR8Rg8/pBMDSLR1U8Jhz3vSymqzZ/i4nOOeRfU5H9L9?= =?iso-8859-1?Q?6eNuEyfB2m5VCyK4OXGQiLPZifNnYZZI3o9oqWoVHaer5dj3Cni2gnerbN?= =?iso-8859-1?Q?WAyw9PHZF9YPmFORreIaEW3E15U8nhyshgOxbhXyN9u1ak77uQbEyhU11C?= =?iso-8859-1?Q?vTKlm3DQAvppz/6Ihn1cMqIUwEKq6A+wKPLlxuW+Am4h/ePn0wDS+VLcL/?= =?iso-8859-1?Q?Jvqne3J5qdbH0oe14x2SBRRM9qcyBR7c7/mt081OyTDQ9nHY58WOYxCA?= =?iso-8859-1?Q?=3D=3D?= X-MS-Exchange-CrossTenant-Network-Message-Id: b45fa646-d721-4055-f997-08dc23da001b X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 02 Feb 2024 10:30:39.2971 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: mhCsfWMBdict5rfjJT9Eh+pS/buxe5c2kYWVrshIrkbICmHaett1cIRZg4Os0VSpfBEQeLjMoeV8sKqQDYvOJJAQVSYxb1Tvv3cVR3Dyuzc= X-MS-Exchange-Transport-CrossTenantHeadersStamped: MW3PR11MB4761 X-OriginatorOrg: intel.com 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 On Fri, Feb 02, 2024 at 10:24:54AM +0100, Mattias Rönnblom wrote: > On 2024-01-31 15:37, Bruce Richardson wrote: > > On Wed, Jan 24, 2024 at 12:51:03PM +0100, Mattias Rönnblom wrote: > > > On 2024-01-23 10:43, Bruce Richardson wrote: > > > > On Tue, Jan 23, 2024 at 10:35:02AM +0100, Mattias Rönnblom wrote: > > > > > 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 > > > > > > --- > > > > > > 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? > > > > > > > > > > > > > Well, undefined is pretty useless for app writers, no? > > > > However, agreed that the range between HIGHEST and LOWEST is an assumption > > > > on my part, chosen because it matches what happens to the event priorities > > > > which are documented in event struct as "The implementation shall normalize > > > > the requested priority to supported priority value" - which, while better > > > > than nothing, does technically leave the details of how normalization > > > > occurs up to the implementation. > > > > > > > > > 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? > > > > > > > > Yes, round etc. will be an issue in cases of non-powers-of 2. > > > > However, I think we do need to clarify this behaviour, so I'm open to > > > > alternative suggestions as to how update this. > > > > > > > > > > In retrospect, maybe it would have been better to just express the number of > > > priority levels an event device supported, only allow [0, max_levels - 1] in > > > the prio field, and leave it to the app to do the conversion/normalization. > > > > > > > Yes, in many ways that would be better. > > > Maybe a new helper macro would at least suggest to the PMD > > > driver implementer and the application designer how this normalization > > > should work. Something like the above, but where NUM_MY_LEVELS is an input > > > parameter. Would result in an integer division though, so shouldn't be used > > > in the fast path. > > > > I think it's actually ok now, having the drivers do the work, since each > > driver can choose optimal method. For those having power-of-2 number of > > priorities, just a shift op works best. > > > > I had an application-usable macro in mind, not a macro for PMDs. Showing how > app-level priority levels should map to Eventdev API-level priority levels > would, by implication, show how event device should do the Eventdev API > priority -> PMD level priority compression. > > The event device has exactly zero freedom in choosing how to translate > Eventdev API-level priorities to its internal priorities, or risk not > differentiating between app-level priority levels. If an event device > supports 128 levels, is RTE_EVENT_DEV_PRIORITY_NORMAL and > RTE_EVENT_DEV_PRIORITY_NORMAL-1 the same PMD-level priority or not? I would > *guess* the same, but that just an assumption, and not something that > follows from "normalize", I think. > > Anyway, this is not a problem this patch set necessarily needs to solve. > Yep, a good point. Would a public macro be enough, or would it be better for drivers to provide a function to allow the app to query the internal priority level for an eventdev one directly? Other alternatives: * have an API break where we change the meaning of the priority field so that the priorities are given in the range of 0 - max_prios-1. * Keep same API, but explicitly state that devices must have a power-of-2 number of supported priorities, and hence that only the top N bits of the priority field will be valid (any devices with support for non-power-of-2 nb-priorities??) - to simplify things this could be followed by an API change where we report instead of priority levels, number of priority bits valid - if changing API for this anyway, could reduce size of event priority field - 256 event priority levels seems a lot! Cutting the field down to 4 bits, or even 3, might make sense. [It would also allow us to potentially expand the impl_opaque field up to 12 bits, allowing more than 256 outstanding events on a port, if using it for sequence numbers, or more useful metadata possibilities for devices/drivers] Not something for this patchset though, as you say. /Bruce