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 28D4943A3F; Thu, 1 Feb 2024 17:59:40 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id F1B2B40608; Thu, 1 Feb 2024 17:59:39 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [198.175.65.12]) by mails.dpdk.org (Postfix) with ESMTP id 8CCB6402A9 for ; Thu, 1 Feb 2024 17:59:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706806779; x=1738342779; h=date:from:to:cc:subject:message-id:references: content-transfer-encoding:in-reply-to:mime-version; bh=AnoKJB209SDAD9k5GOXTPpvf5KABvHTRINQfl0rVmAw=; b=hcXVPNPSamAUu9Yh6pT5rCgGoQH0GDT0hOX9Cxpdeb3c2mWk+lb+xB7/ xz/E/nWDhuYa7GbdO24rlonTC2IlUZJCBAy8f1mODYn2JPXOcN/fd1Kjj lO0yepiaAEmAvrP8NfIOFupfm7O/OB0f/JO+GwVCHhwnCYwtIXGc/MLIG p6laxnyn5TRjTC8weO0HMrAwVBoWJ9A18S5YAXqUswOPJigSKDMHh3Sb+ CI0dI5Cf4OIQ+Z8BEfuE1V3OCncw2Vv4ck1zduebo3S8pNJ63Sc3PKD6j d1CO1wrA2Ysm63CC/6KrBvDw3DolwiVLFXhh0ISfRF1LvyE5qqQ2hlWQT w==; X-IronPort-AV: E=McAfee;i="6600,9927,10969"; a="11316616" X-IronPort-AV: E=Sophos;i="6.05,234,1701158400"; d="scan'208";a="11316616" Received: from orviesa002.jf.intel.com ([10.64.159.142]) by orvoesa104.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 01 Feb 2024 08:59:38 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,234,1701158400"; d="scan'208";a="30649177" Received: from orsmsx603.amr.corp.intel.com ([10.22.229.16]) by orviesa002.jf.intel.com with ESMTP/TLS/AES256-GCM-SHA384; 01 Feb 2024 08:59:37 -0800 Received: from orsmsx610.amr.corp.intel.com (10.22.229.23) by ORSMSX603.amr.corp.intel.com (10.22.229.16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.35; Thu, 1 Feb 2024 08:59:37 -0800 Received: from orsmsx610.amr.corp.intel.com (10.22.229.23) by ORSMSX610.amr.corp.intel.com (10.22.229.23) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.35; Thu, 1 Feb 2024 08:59:36 -0800 Received: from orsedg603.ED.cps.intel.com (10.7.248.4) by orsmsx610.amr.corp.intel.com (10.22.229.23) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.35 via Frontend Transport; Thu, 1 Feb 2024 08:59:36 -0800 Received: from NAM12-BN8-obe.outbound.protection.outlook.com (104.47.55.169) by edgegateway.intel.com (134.134.137.100) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2507.35; Thu, 1 Feb 2024 08:59:36 -0800 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=b7jsbit1vwIbUwBaQ83gkd1jkjkOsjZG77wVyaVkCspt5Uy6DZhCwgdneB1qhIkEMUGJNDz6wDEQwwrd7zzE94geiSH6Hbok3eOpw5OXLyy5MS78q7nQTnTyvjrtTGsltxgTuj5TDSlc668nfrAT6XFKjrVs6dfVZvQtL3KKip6mdDCwERW7BgutFkLjWNtYJroF7Y+w/AOZejEhRbMhHkIUOe510EM6Li0hxki6AWNCjUrC5uVvKyddQaqoYIWk8GfBqAl5ECWYTKx2cORyZqZjAcBAij5q/arYPvwnpuiUqU1nGbf3aizJCIgUYRa/TcC6QW5YV9wEIq3hM5qQ7Q== 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=ORRne8ioBexgGU1u0kTOglTKVU3vTRex9plgX5Qv+k4=; b=S1/oYp8EsyTVkAXegjJsRFQQErt7PtbuO6/RZTKFlEGxJ/GtNen3r6X2hkKHHz1N6JDf0YqHKUDDYBjGeoGq4CtM0DjJzaxDJ8h4onhBDxPkfDu8Bn04o7llGt9G5J01WC/dzujt5RgIWxZBENba2m9u2UaWWo9FybRX0ELB+EIVXWJkAeDVesPCMVPEyramiGgQyG6wHCxOQqJA/kWmxEstln+zpBIDGoGRXBTd7wLr/U1zOdFovUZV5nh03j8pGUTU1u6AtnKAGY+DDixGa6hSg3pFdrx7tzfCMPU4lkllNkYCLDeIwDqQGM+UANfN+R0lGzHbd+SpMejqIn/ZaQ== 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 PH0PR11MB4872.namprd11.prod.outlook.com (2603:10b6:510:32::18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7249.26; Thu, 1 Feb 2024 16:59:33 +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.017; Thu, 1 Feb 2024 16:59:33 +0000 Date: Thu, 1 Feb 2024 16:59:26 +0000 From: Bruce Richardson To: Mattias =?iso-8859-1?Q?R=F6nnblom?= CC: , , , , , , , Subject: Re: [PATCH v2 11/11] eventdev: RFC clarify docs on event object fields Message-ID: References: <20240118134557.73172-1-bruce.richardson@intel.com> <20240119174346.108905-1-bruce.richardson@intel.com> <20240119174346.108905-12-bruce.richardson@intel.com> <211a59b9-095d-418e-be82-b49f4e5d1d00@lysator.liu.se> Content-Type: text/plain; charset="iso-8859-1" Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <211a59b9-095d-418e-be82-b49f4e5d1d00@lysator.liu.se> X-ClientProxiedBy: DUZP191CA0061.EURP191.PROD.OUTLOOK.COM (2603:10a6:10:4fa::16) To DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|PH0PR11MB4872:EE_ X-MS-Office365-Filtering-Correlation-Id: f04acabe-32a6-44ff-7c50-08dc23472a0e X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: RuIK/cAzu5uxlZ0xkoyYqBk3v0boNIjmTHeIzICebYJOe+SN2Vo5w12ic0XJIYw+TL2gu4HhDmqxMH5dMvmNtUKKhXsuAdv92rVkifMoLVBCQOhgJtkkqsb8fkPqTYHKFsHAv1/Md01FIz/JghOvn7cyg3yADvvIOdCT12zxlL8elV/uvGyI7Vops5tIzdBv/936PqqL7g2KPFugU7pzvYPUfmKCnunEMjKoOwklnnUWzEtLg+MZlDG4TrTnIyuUGxZFJ7YQ4241DzWa7FKd7yvVXCh/eJpDvHP3Vw5d/vbSVNDSW6ba49tOkF0XxPWOh0hMY/l+fVExTZXboKIHzOqmfNK/GwDRmvQAV78lvBJ4i+1etdmHqXI2BxzHssGFFbcj3+Lz+otIuxtm44Li7KYLsGTDMVWpS4SAtttwBbOofwrM/p9wtLkJZG2vry0BxLksmkWXILNat1WlCH4DocpzhjbYw/sJ1kwBtHDPL9y2js5y/IiH3Q5yWCyPiuxdZfrxkjL+8caKWWBeAMOk3iy2e+1/aQ+9ffxjuxRzNPiHRmhm4gA0o9SQa5MJlaL0 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)(366004)(376002)(396003)(346002)(136003)(230922051799003)(64100799003)(186009)(1800799012)(451199024)(66899024)(53546011)(6512007)(6486002)(478600001)(86362001)(83380400001)(107886003)(66574015)(82960400001)(41300700001)(26005)(30864003)(66476007)(5660300002)(296002)(2906002)(66556008)(316002)(6916009)(6666004)(6506007)(44832011)(38100700002)(8936002)(8676002)(66946007)(4326008); DIR:OUT; SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?iso-8859-1?Q?rMpJ2zR4nSH0bP7DWLP1Dy+nNYa0ubakPG3XZD0XjITHiR10q9ZKfLZwrr?= =?iso-8859-1?Q?Ekf11OlkfOuLaVhDueW/elHOdB3dvKjVsyioLE09d9e1R2tUansEnzveSr?= =?iso-8859-1?Q?zcTJk6MAaQXODuenr0Q38ILRU/XJowEDbYWbqW4jwAqamF1GJbIya+Q3Ng?= =?iso-8859-1?Q?MpO/YCtdJbqHMfx1eW1hBTfGkNy1TZQqCd6h6t0ujqVBl0E2s6jejPSm7C?= =?iso-8859-1?Q?wmORXzRJ5lpSy1+kIpzynznu6yB1DRFSxVJaC37Jbd+LcRk2nRpiETiTBO?= =?iso-8859-1?Q?xQPS/Rh8/9ud3vPVy56HT3yqp26byDsZ6iJHoreofuuKb25Mmh8Gw0WB7/?= =?iso-8859-1?Q?4Mp8XKQfpFmtrK0tHae6vWNSczN8kL2cuOCyZ4nKrGKyHGJkqCwG7qYsJq?= =?iso-8859-1?Q?p5+JaUViL2TFhZqCkGvA9FeMrxYYm49KishoGtqmZjBOaVBTE5X9bd6TYM?= =?iso-8859-1?Q?k1z/nZs4WWkDTduytBvAxPwTZMAawyZDNnYjtB0hYP/qK79IvU87t3jd0G?= =?iso-8859-1?Q?AtKLsDQn01x5RVx+Vicj/zwRKd4AKtdUYCG9PwzZQ7SfevVb+0xv642SSn?= =?iso-8859-1?Q?RGYNFg6rTkRPz7me+4Zs6xr7Ob/+xqUHejMSnG9yQ2IcF+0TF4QKZ+Jb3w?= =?iso-8859-1?Q?zuUbpbT50IleQzg2Tva0HupOB+RyGjMd0C65Cw11NmqLLiDoMHNNiN3ujY?= =?iso-8859-1?Q?wh7o9mpW+iUawxfTbELfcfEtmQ1qUjq4FjYC3PjbsrmaNELagRu24GpROq?= =?iso-8859-1?Q?scNIzc/kAb2g1dGJhl1Wn102JndDZkR6WloRaGEObV9i653BaPV463013n?= =?iso-8859-1?Q?s6qhYqMUKUAjbCVUT4WJOkzQqxAPptJ1Br6nijtvH41gHPRGvukuN35xch?= =?iso-8859-1?Q?siYiTQUjRps5f16G3LDDN3rOwL6EC6JSvq0VJPfC6JzGuMS/VdH3knD3Bq?= =?iso-8859-1?Q?XUKodTGoQ5JW1pCUwLNEfV2qpqm/500a/I/VLu59hm+GWncPpZmALjlYgc?= =?iso-8859-1?Q?dHV/XYvY8Kv+JbmBIwcuTapTPWaX+j+7wLxQbV5u6+eKJRmacMze8Er73U?= =?iso-8859-1?Q?NMrLsVB0OL085p+rn97CVYWXAp49IVsAaiH9MaPzOIuIyqNtmzafCXsXXZ?= =?iso-8859-1?Q?d3o5TLu87t++McVNpWnR2qOZ1Y5HsxGXg6huPdoDg2LoN1ZR9r6WBZ6GB7?= =?iso-8859-1?Q?Xv7ib7kKWxQjb/Mm8bbp8wjRRjj6i9+x3Hi0qWdRge/8vW+sy5a+EEJ1G/?= =?iso-8859-1?Q?EKl1BXSkHg2bpg2n83qgKMN3oyBSuXR3OKMPp0L3zpcfFbBuhmyaFZEAfc?= =?iso-8859-1?Q?5WrRYMbhtOhgEQBBI/EOdHemk7Qj6h37JuvXdBrDXadTfhoSrojhLeu3LL?= =?iso-8859-1?Q?2Xw38XWF6s0PHqtd03a+KJc3ucTBtoZCXArjJhs3I6MxTx3y9HJ90uEL35?= =?iso-8859-1?Q?y8rqIaGfJ6hqYiqQW853SvMHFbjigdaHgPQUZKxKAXz04UHgiVsz68NDmj?= =?iso-8859-1?Q?QLw2v+oRzrQ7U07tOSjGysH6MXvtWbuojtA/cdSx5XAWhTA2tvyy+8NvWm?= =?iso-8859-1?Q?ugMn+1s7BoGQNbD5bA2DfFVyYo+lc8DoBXxElNi2XEX0G8fg9lI+cJF1gL?= =?iso-8859-1?Q?33LZhd3d/EuPTpLFm6PdhVf3SA5S1e+JLZtZ7ak6/pZPKRJJfBTIfcTA?= =?iso-8859-1?Q?=3D=3D?= X-MS-Exchange-CrossTenant-Network-Message-Id: f04acabe-32a6-44ff-7c50-08dc23472a0e X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 01 Feb 2024 16:59:33.6989 (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: /3PU/FoHicnUv6+gsC+vMdD5TaGfkE9XjF4Uf+2cZcxFz5Bn9I7fGTU00fcsqB3/BUZUkxxSM9dwyE3SfZaAqgriEcCKdGcnAzfi75pUXN4= X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH0PR11MB4872 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 Wed, Jan 24, 2024 at 12:34:50PM +0100, Mattias Rönnblom wrote: > On 2024-01-19 18:43, Bruce Richardson wrote: > > 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 > > --- > > > > As with the previous patch, please review this patch to ensure that the > > expected semantics of the various event types and event fields have not > > changed in an unexpected way. > > --- > > lib/eventdev/rte_eventdev.h | 105 ++++++++++++++++++++++++++---------- > > 1 file changed, 77 insertions(+), 28 deletions(-) > > > > diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h > > index cb13602ffb..4eff1c4958 100644 > > --- a/lib/eventdev/rte_eventdev.h > > +++ b/lib/eventdev/rte_eventdev.h > > @@ -1416,21 +1416,25 @@ 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 > > +/**< The @ref rte_event.op field should be set to this type to inject a new event to the > > * event device. > > */ > > "type" -> "value" > > "to" -> "into"? > > You could also say "to mark the event as new". > > What is new? Maybe "new (as opposed to a forwarded) event." or "new (i.e., > not previously dequeued).". > Using this latter suggested wording in V3. > "The application sets the @ref rte_event.op field of an enqueued event to > this value to mark the event as new (i.e., not previously dequeued)." > > > #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. > > +/**< SW should set the @ref rte_event.op filed to this type to return a > > + * previously dequeued event to the event device for further processing. > > "filed" -> "field" > > "SW" -> "The application" > > "to be scheduled for further processing (or transmission)" > > The wording should otherwise be the same as NEW, whatever you choose there. > Ack. > > * > > - * 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. > > OK, so you "should" mark a new event RTE_EVENT_OP_FORWARD but you "*must*" > enqueue it to the same port. > > I think you "must" do both. > Ack > > + * > > + * 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 software, but the @ref rte_event.impl_opaque field must > > "software" -> "application" > Ack > > + * 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* > > + * If current flow's scheduler type method is @ref 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 > > @@ -1442,21 +1446,19 @@ struct rte_event_vector { > > * 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 > > Isn't a missing "or @ref RTE_SCHED_TYPE_ATOMIC" just an oversight (in the > original API wording)? > No, I don't think so, because ATOMIC is described above. > > + * then this function 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* > > + * If current flow's scheduler type method is @ref RTE_SCHED_TYPE_PARALLEL > > * or no scheduling context is held then this function may be an NOOP, > > * depending on the implementation. > > Maybe you can also fix this "function" -> "operation". I suggest you delete > that sentence, because it makes no sense. > > What is says in a somewhat vague manner is that you tread into the realm of > undefined behavior if you release PARALLEL events. > Agree. Just deleting. > > * > > * This operation must only be enqueued to the same port that the > > - * event to be released was dequeued from. > > + * event to be released was dequeued from. The @ref rte_event.impl_opaque > > + * field in the release event must match that in the original dequeued event. > > I would say "same value" rather than "match". > > "The @ref rte_event.impl_opaque field in the release event have the same > value as in the original dequeued event." > Ack. > > */ > > > > /** > > @@ -1473,53 +1475,100 @@ struct rte_event { > > /**< Targeted flow identifier for the enqueue and > > * dequeue operation. > > * The value must be in the range of > > - * [0, nb_event_queue_flows - 1] which > > + * [0, @ref rte_event_dev_config.nb_event_queue_flows - 1] which > > The same comment as I had before about ranges for unsigned types. > Ack. > > * previously supplied to rte_event_dev_configure(). > > + * > > + * For @ref RTE_SCHED_TYPE_ATOMIC, this field is used to identify a > > + * flow context for atomicity, such that events from each individual flow > > + * will only be scheduled to one port at a time. > > flow_id alone doesn't identify an atomic flow. It's queue_id + flow_id. I'm > not sure I think "flow context" adds much, unless it's defined somewhere. > Sounds like some assumed implementation detail. > Removing the word context, and adding that it identifies a flow "within a queue and priority level", to make it clear that it's just not the flow_id involved here, as you say. > > + * > > + * 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 SW or event adapter use, > > "SW" -> "application" > Ack. > > + * and is unused 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 SW or event adapter use, > > + * and is unused in scheduling decisions. > > "unused" -> "is not considered"? > Ack. > > */ > > uint8_t op:2; > > - /**< The type of event enqueue operation - new/forward/ > > - * etc.This field is not preserved across an instance > > + /**< The type of event enqueue operation - new/forward/ etc. > > + * > > + * This field is *not* preserved across an instance > > * and is undefined on dequeue. > > Maybe you should use "undefined" rather than "implementation dependent", or > change this instance of undefined to implementation dependent. Now two > different terms are used for the same thing. > Using implementation dependent. Ideally, I think we should update all drivers to set this to "FORWARD" by default on dequeue, but for now it's "implementation dependent". > > - * @see RTE_EVENT_OP_NEW, (RTE_EVENT_OP_*) > > + * > > + * @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. Zero on dequeue. > > + */ > > Why say they should be zero on dequeue? Doesn't this defeat the purpose of > having reserved bits, for future use? With you suggested wording, you can't > use these bits without breaking the ABI. Good point. Removing the dequeue value bit. > > > 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 supported. > > "supported" -> "configured" > Ack. > > + * For queues where only a single scheduling type is available, > > + * this field must be set to match the configured scheduling type. > > + * > > Why is the API/event device asking this of the application? > Historical reasons. I agree that it shouldn't, this should just be marked as ignored on fixed-type queues, but the spec up till now says it must match and some drivers do check this. Once we update the drivers to stop checking then we can change the spec without affecting apps. > > + * 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(). + * [0, @ref > > rte_event_dev_config.nb_event_queues - 1] 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. + * @ref > > RTE_EVENT_DEV_CAP_EVENT_QOS capability. + * Ignored > > otherwise. + * + * This > > field is preserved between enqueue and dequeue. > > Is the normalized or unnormalized value that is preserved? > Very good point. It's the normalized & then denormalised version that is guaranteed to be preserved, I suspect. SW eventdevs probably preserve as-is, but HW eventdevs may lose precision. Rather than making this "implementation defined" or "not preserved" which would be annoying for apps, I think, I'm going to document this as "preserved, but with possible loss of precision". > > */ > > uint8_t impl_opaque; > > /**< Implementation specific opaque value. > > Maybe you can also fix "implementation" here to be something more specific. > Implementation, of what? > > "Event device implementation" or just "event device". > "Opaque field for event device use" > > + * > > * An implementation may use this field to hold > > * implementation specific value to share between > > * dequeue and enqueue operation. > > + * > > * The application should 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 > > Should it be mentioned that impl_opaque is ignored by the event device for > NEW events? > Added in V3. > > */ > > }; > > }; > > -- > > 2.40.1 > >