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 BBF5143BE1; Mon, 26 Feb 2024 07:52:39 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 928D6402BA; Mon, 26 Feb 2024 07:52:39 +0100 (CET) Received: from mx0b-0016f401.pphosted.com (mx0b-0016f401.pphosted.com [67.231.156.173]) by mails.dpdk.org (Postfix) with ESMTP id EC14B40144 for ; Mon, 26 Feb 2024 07:52:37 +0100 (CET) Received: from pps.filterd (m0045851.ppops.net [127.0.0.1]) by mx0b-0016f401.pphosted.com (8.17.1.24/8.17.1.24) with ESMTP id 41Q6jG9b005140; Sun, 25 Feb 2024 22:52:37 -0800 Received: from nam11-dm6-obe.outbound.protection.outlook.com (mail-dm6nam11lp2168.outbound.protection.outlook.com [104.47.57.168]) by mx0b-0016f401.pphosted.com (PPS) with ESMTPS id 3wfgun3yn9-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Sun, 25 Feb 2024 22:52:37 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=ntofl3zL+SF2PoBk+T9jSiJwOpVq9DEuNSqiTLUBDI+cx2NZN2gDi3te+bKizE3aE9MS8RZI0E7KcZd+ikEWn+BMoolmcd71WCOKLo3h6G8ydBYtaT4GdsJBYyB218WgGWxocv954//F7VMqwU/12H5U2g8NiaQKHq83T06CT7FYVgOX2OG0jjituTq4HwBehRuIaT+dQyiq9zLo2X/KE7bvytqszU5LMbNqhJt5lncD2o5+Ep8ETb0sYZoFaYKIOUeSrQuUVKQ+Ji1mySIUe8z1NquLUglic+CCCIN2FSN9XLRQ+Lrul4worQZaqYBxLyquTSVAMXqdYyez5PHZzg== 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=Wkes00uO9PULnEaVvcfS1udNCOGQJIXqusqxXdWrQLI=; b=aq2+9mdTf4w+Dv+wfysLG/lvyJGYj+PRAk+CPn/S4L13maQfejIb3TROBGLTm404VSGV724D4tVwDzLG1pOdg412Wuh8w2PCEH8L0TBM4/yE0rliQzcQvQTxInBiLm5KwwE6HbHW2KIJ/9HF4KWRPiLpW7+c+xPr5AcFO0bsCfT1KrMPCmAk4QPBW+/S9LWgj00FhsGKvXHIVOWmcbfEkRIT8Ts/rfJqP/mZUZjAyh6VPOjYAECwX4gA8DFyfnr+UxDj8BZH6KOFMyrtUVFoaysq0wVwRikUAZjbK237+R/d43/sybEAu0zLgX8yKJ1M2oSIjr/pnlGS3H056rDGyw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=marvell.com; dmarc=pass action=none header.from=marvell.com; dkim=pass header.d=marvell.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=marvell.onmicrosoft.com; s=selector1-marvell-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=Wkes00uO9PULnEaVvcfS1udNCOGQJIXqusqxXdWrQLI=; b=UyevAtmLmIe+LzUnNZZXxM+QPFYEPihMXDVD1V1Vq7x+Xv2YfZ8dMRZcSGNFD5z89CAqx9T4uZrBcJbsS2BSJ2PqXVd1GPw7aDrGH3AA7gW2rzyWjcDDZBwINwmAP07ZpPRjsMqpzLIegkqpZCJ9475xsuDh2akG77aAXKc74Lk= Received: from PH0PR18MB4086.namprd18.prod.outlook.com (2603:10b6:510:3::9) by MN2PR18MB3461.namprd18.prod.outlook.com (2603:10b6:208:26f::19) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7316.34; Mon, 26 Feb 2024 06:52:34 +0000 Received: from PH0PR18MB4086.namprd18.prod.outlook.com ([fe80::baf5:a4b6:7776:10f4]) by PH0PR18MB4086.namprd18.prod.outlook.com ([fe80::baf5:a4b6:7776:10f4%6]) with mapi id 15.20.7316.034; Mon, 26 Feb 2024 06:52:33 +0000 From: Pavan Nikhilesh Bhagavatula To: Bruce Richardson , "dev@dpdk.org" , Jerin Jacob , "mattias.ronnblom@ericsson.com" Subject: RE: [EXT] [PATCH v4 10/12] eventdev: clarify docs on event object fields and op types Thread-Topic: [EXT] [PATCH v4 10/12] eventdev: clarify docs on event object fields and op types Thread-Index: AQHaZLFyP1DsaYRiAk2GakgfsyiXOLEcN1RQ Date: Mon, 26 Feb 2024 06:52:33 +0000 Message-ID: References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240221103221.933238-1-bruce.richardson@intel.com> <20240221103221.933238-11-bruce.richardson@intel.com> In-Reply-To: <20240221103221.933238-11-bruce.richardson@intel.com> Accept-Language: en-US, en-IN Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-ms-publictraffictype: Email x-ms-traffictypediagnostic: PH0PR18MB4086:EE_|MN2PR18MB3461:EE_ x-ms-office365-filtering-correlation-id: 6f11305f-040a-4bf0-9aa6-08dc36978282 x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: fZp2126cG9Qtx8hMgdzGD6PeU6nXoNFjfJMwZbalGjV2PP3cSRYvQHM5xLUKs0Ui02B+pOvJHckC+6oaLu8o8rEeVsDmUhEA3WBaFdZ3h9ylDglz6DUYwp6lWAo4r2sRX/u4CxoZkhmk+aGfwFJGC5O/yT/F//kEdVDrp9S8z5aaoLgr6nIwrmz6umPH+jbkoz7vKR1+8/j2sXuOAZhiK5b+fk2XRoP8ktOj6uatntxwrp1otCwEmskpTUeAmEs1JURmX8w9qVqsmJ+hsRm2u9tCBVlJsv1tY5BfGPag8Wdezm67j9esvtO1hUySvvWwSm1BeEWELXBcgTxIgI6mrp0T463+/+3auYd2D1eoVMtfVC2Vs3IW0VfCnhhmcjhD9k2AKJRdu+Tjv+eG9ZNwjbaJTXo9MYd7uqQGnUdibpKp5bvZDhNdbSBQkrDd/be8s0HVrpM96ZqcWhLNDmFIGGo9vkcDJoE9MS8x9H2qHW3yyPrJxWVAOx/IHG47n39jwrkUulONrfprLxnp5PwolzTJpHaV/2SYtSb0p9CORKEKQASfl9x0cwjHxjnAt+4Jnv4cZZCvDIy/Z8OqAMh2FhIS7G+t4q2+dJ+kDMKgCf2VvEpeorF3NyVLJlOZHUm60q9BIiRGUqyRDtvPbdvtiS7/gyLeuEYSjxxI2+xLDNp+NcAVVKJ9bQ2Mzez/SO7L+UsIOne9Cnls1YW+zCCf4vBjglIH4WjI6K7xSQhiiYE= x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:PH0PR18MB4086.namprd18.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230031)(38070700009); DIR:OUT; SFP:1102; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: =?us-ascii?Q?vJi7p4UbgHtjb4UufN36mN0rvfGlr4qKdAvvqqPuyFhRIMMbQxrqdDBAUjaP?= =?us-ascii?Q?RbuGVkFc+CMhQ6b5703mPjfZZOqyQxxcmuHLqA1+85XyRXBM4ErSmRcXTn0p?= =?us-ascii?Q?61vemQSQRlyKSXt60HTy7/DZlySPsG2DnF7QzpAyp2+MNRvY8Gou4BxzHrx+?= =?us-ascii?Q?xrPNPp71p37gwFtnxw7NxIyE+IRhXA3pOBza/UiKNWO/X6YlZIUe3Cmt0lDJ?= =?us-ascii?Q?sC5e/xa4DLbE+CUlUSf7u0SwDyeBM03TVK3HVmNUCqmQlw52VsRxN4RPpQGU?= =?us-ascii?Q?iM+dUXcI8tkXkb6+F9gqHm8M2ILrdJfFO5FDG70HDrh6A5lVJIBNn1TmzGjP?= =?us-ascii?Q?vNgEEgLQb4yMRv5RFUYKgxE9rCjSTKZkRhElpt3v7KWwCL1b7ncJqVAvhwiA?= =?us-ascii?Q?EbYqiOhnWQABkDiNxi8jazwqXGwF9qZDN54CWEDpHbTQyhr6YySVrUgqbWHs?= =?us-ascii?Q?vLCda2U7lNc78oJS+1iuFbNPDyyiYcvSaqD48Wb61od/VLWAeyVtRWqa5vYI?= =?us-ascii?Q?mLHCk1hvGq6yf6Ue9tyrN5Lt1yYfgjsCR1J4N7t5ImlzgNSCZ5IfmIx4qqEg?= =?us-ascii?Q?iNa9pkhclcyKPpBmn8mK4HDBcbeDsuhJfWQLiPHCvQPtQ+PE7NLuMtFTbbIo?= =?us-ascii?Q?rrv70OieqxvwAtNoVRFUd1P6zGCNC6ykaX9ddtxls+hYF6BGGG45u63VEGF5?= =?us-ascii?Q?JcZEVwW8+U/i/WIshvKguRjyrYGMK8wTisVzrlx+tYuUmZgIYFmVtNTvrEHg?= =?us-ascii?Q?0lWnaROdv5OMDIEqCJ8cxESmpdDfgZw1YpU0QRN5Le6r1/NZ7IhM8VmWUthZ?= =?us-ascii?Q?dITGtqMuOkZg6TpoKfqT+2lwiCr070FDMHFFFAiSALRVrqURIEMFTM7sz/ce?= =?us-ascii?Q?KmR5m2v8f2DS2J0C9qwtNQC/SVRO6Ql+LhCo9nN81xS84OGIBW2jb0gzuh7z?= =?us-ascii?Q?dtP1/Fcfm2AutgvQbSJBbMcuV+0M3rWix+Ps1niuDyelnyh53wOmWwTcxt/z?= =?us-ascii?Q?el+GtuqJJ8Hn2nXu/SCmCQYrZGq9D6hz4nmwtut5cp+JqNHiU2Y2+zU2mPZW?= =?us-ascii?Q?at5xKkiILwZvW2zDxViOvkrFJKP34jw8HueHM06MVWdpsEwkR8E+IyPuuKkC?= =?us-ascii?Q?Pb/eIsIwJOa+6H+GlIyKPk1ndVW1nD3ZWPIk2mwkb3dF4G51q6JHnCSL5GCO?= =?us-ascii?Q?v/f/CNP9LZM/07gGLD0apNiQEbPxD+vz6FqOrdWLZvPtCn0/v0pQNrwab/iW?= =?us-ascii?Q?eaCBahqndCGfImEUA3PJnwYp1LFq/AWKcqIEZgzgAjNAghYS1r6M1Pr0BT++?= =?us-ascii?Q?97zNS7nj0dQpPs+UaAvKUL0D5hudtex9i20/dYZybKM6UAZecrkYVBhNKQxF?= =?us-ascii?Q?vtN16vlW/O3qQowssnen9fk78IJrhaoNKVUo7UNqKTgtzjavHlgc+wHJ6xn6?= =?us-ascii?Q?qzKsAiWtRQMaro+28e0JqPTKwOsSTCuAgVVOT3ENpYBDx7wH0cgpo+0Tz2d+?= =?us-ascii?Q?qmJ/ke01Hd8gVnTLAJo9xate6DPddTIuWL67vdvQp6UPwuDu2FxCmtH25u4F?= =?us-ascii?Q?pd4RlGN5WWFZv1rB/vv3mbfVaXeF68XNEHNbI49I?= Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-OriginatorOrg: marvell.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: PH0PR18MB4086.namprd18.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 6f11305f-040a-4bf0-9aa6-08dc36978282 X-MS-Exchange-CrossTenant-originalarrivaltime: 26 Feb 2024 06:52:33.7279 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 70e1fb47-1155-421d-87fc-2e58f638b6e0 X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: evV1Mx6cHgJk1EfGDw8Wygb9bxrVEsd/7HmEPvTRokv8xUsIPsLoyU/P8KmF84NDBg8KczvoEioX5EiuZSKsEAoYlQW6A4DJ9ltrpGendjQ= X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR18MB3461 X-Proofpoint-ORIG-GUID: U9U4el-nsXnshNRPpmQTUNQedxNzSHE8 X-Proofpoint-GUID: U9U4el-nsXnshNRPpmQTUNQedxNzSHE8 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.272,Aquarius:18.0.1011,Hydra:6.0.619,FMLib:17.11.176.26 definitions=2024-02-26_03,2024-02-23_01,2023-05-22_02 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 > 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. >=20 > Signed-off-by: Bruce Richardson Acked-by: Pavan Nikhilesh > --- > V4: reworked following review by Jerin > V3: updates following review > --- > lib/eventdev/rte_eventdev.h | 161 +++++++++++++++++++++++++----------- > 1 file changed, 111 insertions(+), 50 deletions(-) >=20 > diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h > index 6d881bd665..7e7e275620 100644 > --- a/lib/eventdev/rte_eventdev.h > +++ b/lib/eventdev/rte_eventdev.h > @@ -1515,47 +1515,55 @@ struct rte_event_vector { >=20 > /* Event enqueue operations */ > #define RTE_EVENT_OP_NEW 0 > -/**< The event producers use this operation to inject a new event to the > - * event device. > +/**< The @ref rte_event.op field must be set to this operation type to i= nject a > new event, > + * i.e. one not previously dequeued, into the event device, to be schedu= led > + * for processing. > */ > #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. > +/**< The application must set the @ref rte_event.op field to this operat= ion > type to return a > + * previously dequeued event to the event device to be scheduled for fur= ther > processing. > * > - * 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. > + * > + * The event's fields, including (but not limited to) flow_id, schedulin= g type, > + * destination queue, and event payload e.g. mbuf pointer, may all be > updated as > + * desired by the application, but the @ref rte_event.impl_opaque field = must > + * 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* > - * then this function hints the scheduler that the user has completed cr= itical > - * section processing in the current atomic context. > - * The scheduler is now allowed to schedule events from the same flow fr= om > - * an event queue to another port. However, the context may be still hel= d > - * until the next rte_event_dequeue_burst() call, this call allows but d= oes not > - * force the scheduler to release the context early. > - * > - * Early atomic context release may increase parallelism and thus system > + * If current flow's scheduler type method is @ref RTE_SCHED_TYPE_ATOMIC > + * then this operation type hints the scheduler that the user has comple= ted > critical > + * section processing for this event in the current atomic context, and = that the > + * scheduler may unlock any atomic locks held for this event. > + * If this is the last event from an atomic flow, i.e. all flow locks ar= e released > + * (see @ref RTE_SCHED_TYPE_ATOMIC for details), the scheduler is now > allowed to > + * schedule events from that flow from to another port. > + * However, the atomic locks may be still held until the next > rte_event_dequeue_burst() > + * call; enqueuing an event with opt type @ref RTE_EVENT_OP_RELEASE is a > hint only, > + * allowing the scheduler to release the atomic locks early, but not req= uiring it > to do so. > + * > + * Early atomic lock release may increase parallelism and thus system > * performance, but the user needs to design carefully the split into cr= itical > * 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 tha= t 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 syste= m > - * performance. > + * If current flow's scheduler type method is @ref > RTE_SCHED_TYPE_ORDERED > + * then this operation type 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* > - * or no scheduling context is held then this function may be an NOOP, > - * depending on the implementation. > + * Events with this operation type must only be enqueued to the same por= t > that the > + * event to be released was dequeued from. The @ref > rte_event.impl_opaque > + * field in the release event must have the same value as that in the or= iginal > dequeued event. > * > - * This operation must only be enqueued to the same port that the > - * event to be released was dequeued from. > + * If a dequeued event is re-enqueued with operation type of @ref > RTE_EVENT_OP_RELEASE, > + * then any subsequent enqueue of that event - or a copy of it - must be > done as event of type > + * @ref RTE_EVENT_OP_NEW, not @ref RTE_EVENT_OP_FORWARD. This is > because any context for > + * the originally dequeued event, i.e. atomic locks, or reorder buffer e= ntries, > will have > + * been removed or invalidated by the release operation. > */ >=20 > /** > @@ -1569,56 +1577,109 @@ struct rte_event { > /** Event attributes for dequeue or enqueue operation */ > struct { > uint32_t flow_id:20; > - /**< Targeted flow identifier for the enqueue and > - * dequeue operation. > - * The value must be in the range of > - * [0, nb_event_queue_flows - 1] which > - * previously supplied to rte_event_dev_configure(). > + /**< Target flow identifier for the enqueue and > dequeue operation. > + * > + * For @ref RTE_SCHED_TYPE_ATOMIC, this field is > used to identify a > + * flow for atomicity within a queue & priority level, > such that events > + * from each individual flow will only be scheduled to > one port at a time. > + * > + * 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. > + * > * @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 > */ > uint8_t op:2; > - /**< The type of event enqueue operation - > new/forward/ > - * etc.This field is not preserved across an instance > - * and is undefined on dequeue. > - * @see RTE_EVENT_OP_NEW, (RTE_EVENT_OP_*) > + /**< The type of event enqueue operation - > new/forward/ etc. > + * > + * This field is *not* preserved across an instance > + * and is implementation dependent on dequeue. > + * > + * @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 when initializing event > structures. > + * > + * When forwarding or releasing existing events > dequeued from the scheduler, > + * this field can be ignored. > + */ > 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 configured. > + * For queues where only a single scheduling type is > available, > + * this field must be set to match the configured > scheduling type. > + * > + * 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(). > + * The value must be less than @ref > rte_event_dev_config.nb_event_queues > + * 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. > + * [For devices with where the supported priority > range is a power-of-2, the > + * normalization will be done via bit-shifting, so only > the highest > + * log2(num_priorities) bits will be used by the event > device] > + * > + * Valid when the device has @ref > RTE_EVENT_DEV_CAP_EVENT_QOS capability > + * and this field is preserved between enqueue and > dequeue, > + * though with possible loss of precision due to > normalization and > + * subsequent de-normalization. (For example, if a > device only supports 8 > + * priority levels, only the high 3 bits of this field will be > + * used by that device, and hence only the value of > those 3 bits are > + * guaranteed to be preserved between enqueue and > dequeue.) > + * > + * Ignored when device does not support @ref > RTE_EVENT_DEV_CAP_EVENT_QOS > + * capability, and it is implementation dependent if this > field is preserved > + * between enqueue and dequeue. > */ > uint8_t impl_opaque; > - /**< Implementation specific opaque value. > - * An implementation may use this field to hold > + /**< Opaque field for event device use. > + * > + * An event driver implementation may use this field > to hold an > * implementation specific value to share between > * dequeue and enqueue operation. > - * The application should not modify this field. > + * > + * The application must 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. > + * This field is ignored on events with op type > + * @ref RTE_EVENT_OP_NEW. > */ > }; > }; > -- > 2.40.1