Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/136329/?format=api
{ "id": 136329, "url": "http://patches.dpdk.org/api/patches/136329/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20240202123953.77166-11-bruce.richardson@intel.com/", "project": { "id": 1, "url": "http://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20240202123953.77166-11-bruce.richardson@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20240202123953.77166-11-bruce.richardson@intel.com", "date": "2024-02-02T12:39:52", "name": "[v3,10/11] eventdev: clarify docs on event object fields and op types", "commit_ref": null, "pull_url": null, "state": "changes-requested", "archived": true, "hash": "508abf233f9313ae2963e39f276e27f80dd07abc", "submitter": { "id": 20, "url": "http://patches.dpdk.org/api/people/20/?format=api", "name": "Bruce Richardson", "email": "bruce.richardson@intel.com" }, "delegate": { "id": 310, "url": "http://patches.dpdk.org/api/users/310/?format=api", "username": "jerin", "first_name": "Jerin", "last_name": "Jacob", "email": "jerinj@marvell.com" }, "mbox": "http://patches.dpdk.org/project/dpdk/patch/20240202123953.77166-11-bruce.richardson@intel.com/mbox/", "series": [ { "id": 30988, "url": "http://patches.dpdk.org/api/series/30988/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=30988", "date": "2024-02-02T12:39:42", "name": "improve eventdev API specification/documentation", "version": 3, "mbox": "http://patches.dpdk.org/series/30988/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/136329/comments/", "check": "success", "checks": "http://patches.dpdk.org/api/patches/136329/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "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])\n\tby inbox.dpdk.org (Postfix) with ESMTP id 5E61643A4F;\n\tFri, 2 Feb 2024 13:41:42 +0100 (CET)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 32F3042EA4;\n\tFri, 2 Feb 2024 13:41:07 +0100 (CET)", "from mgamail.intel.com (mgamail.intel.com [192.198.163.18])\n by mails.dpdk.org (Postfix) with ESMTP id 922F3402E8\n for <dev@dpdk.org>; Fri, 2 Feb 2024 13:41:05 +0100 (CET)", "from fmviesa006.fm.intel.com ([10.60.135.146])\n by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;\n 02 Feb 2024 04:41:01 -0800", "from silpixa00401385.ir.intel.com ([10.237.214.38])\n by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:59 -0800" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple;\n d=intel.com; i=@intel.com; q=dns/txt; s=Intel;\n t=1706877666; x=1738413666;\n h=from:to:cc:subject:date:message-id:in-reply-to:\n references:mime-version:content-transfer-encoding;\n bh=0lQxTjmfd7B8O0fajP3oZ69CTv13Dg6NOW2tNvKejJo=;\n b=CzCo3EjgzwKpuEpHeVDjEwb/CiKHAzlrQUUdOLjDDQtHRUv67+rKEkA6\n f7MJ1WvHxX+qNR2Jngu7gid1Io1VejnQZZWRoa57PqoFf4cC1GdqvwwCj\n dc6s6x2aQ34T6WGK8kfCoQlsi99eXdCrQTsnC8Y4PuXgAZylqXlK9wUKg\n Z6downqtrBqPUNrQR5Ri6MLzy7RqgLAaI2gPpcvmSKrzhq0157PbPy4D6\n cXN8JMiFL2/Vym3gfi8Pa7lJvd8cXmytQ+b3s/2HWYsP0cMYXsSuSTNJu\n 8asTWb6TjhlciG2JsJnAErzwz2y0uL0RXtw36hTA1j/Q6BtJbPvI/JjhM Q==;", "X-IronPort-AV": [ "E=McAfee;i=\"6600,9927,10971\"; a=\"54490\"", "E=Sophos;i=\"6.05,238,1701158400\";\n d=\"scan'208\";a=\"54490\"", "E=Sophos;i=\"6.05,238,1701158400\";\n d=\"scan'208\";a=\"347666\"" ], "X-ExtLoop1": "1", "From": "Bruce Richardson <bruce.richardson@intel.com>", "To": "dev@dpdk.org,\n\tjerinj@marvell.com,\n\tmattias.ronnblom@ericsson.com", "Cc": "abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com,\n hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com,\n Bruce Richardson <bruce.richardson@intel.com>", "Subject": "[PATCH v3 10/11] eventdev: clarify docs on event object fields and op\n types", "Date": "Fri, 2 Feb 2024 12:39:52 +0000", "Message-Id": "<20240202123953.77166-11-bruce.richardson@intel.com>", "X-Mailer": "git-send-email 2.40.1", "In-Reply-To": "<20240202123953.77166-1-bruce.richardson@intel.com>", "References": "<20240119174346.108905-1-bruce.richardson@intel.com>\n <20240202123953.77166-1-bruce.richardson@intel.com>", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org" }, "content": "Clarify the meaning of the NEW, FORWARD and RELEASE event types.\nFor the fields in \"rte_event\" struct, enhance the comments on each to\nclarify the field's use, and whether it is preserved between enqueue and\ndequeue, and it's role, if any, in scheduling.\n\nSigned-off-by: Bruce Richardson <bruce.richardson@intel.com>\n---\nV3: updates following review\n---\n lib/eventdev/rte_eventdev.h | 161 +++++++++++++++++++++++++-----------\n 1 file changed, 111 insertions(+), 50 deletions(-)", "diff": "diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h\nindex 8d72765ae7..58219e027e 100644\n--- a/lib/eventdev/rte_eventdev.h\n+++ b/lib/eventdev/rte_eventdev.h\n@@ -1463,47 +1463,54 @@ struct rte_event_vector {\n \n /* Event enqueue operations */\n #define RTE_EVENT_OP_NEW 0\n-/**< The event producers use this operation to inject a new event to the\n- * event device.\n+/**< The @ref rte_event.op field must be set to this operation type to inject a new event,\n+ * i.e. one not previously dequeued, into the event device, to be scheduled\n+ * for processing.\n */\n #define RTE_EVENT_OP_FORWARD 1\n-/**< The CPU use this operation to forward the event to different event queue or\n- * change to new application specific flow or schedule type to enable\n- * pipelining.\n+/**< The application must set the @ref rte_event.op field to this operation type to return a\n+ * previously dequeued event to the event device to be scheduled for further processing.\n *\n- * This operation must only be enqueued to the same port that the\n+ * This event *must* be enqueued to the same port that the\n * event to be forwarded was dequeued from.\n+ *\n+ * The event's fields, including (but not limited to) flow_id, scheduling type,\n+ * destination queue, and event payload e.g. mbuf pointer, may all be updated as\n+ * desired by the application, but the @ref rte_event.impl_opaque field must\n+ * be kept to the same value as was present when the event was dequeued.\n */\n #define RTE_EVENT_OP_RELEASE 2\n /**< Release the flow context associated with the schedule type.\n *\n- * If current flow's scheduler type method is *RTE_SCHED_TYPE_ATOMIC*\n- * then this function hints the scheduler that the user has completed critical\n- * section processing in the current atomic context.\n- * The scheduler is now allowed to schedule events from the same flow from\n- * an event queue to another port. However, the context may be still held\n- * until the next rte_event_dequeue_burst() call, this call allows but does not\n- * force the scheduler to release the context early.\n- *\n- * Early atomic context release may increase parallelism and thus system\n+ * If current flow's scheduler type method is @ref RTE_SCHED_TYPE_ATOMIC\n+ * then this operation type hints the scheduler that the user has completed critical\n+ * section processing for this event in the current atomic context, and that the\n+ * scheduler may unlock any atomic locks held for this event.\n+ * If this is the last event from an atomic flow, i.e. all flow locks are released,\n+ * the scheduler is now allowed to schedule events from that flow from to another port.\n+ * However, the atomic locks may be still held until the next rte_event_dequeue_burst()\n+ * call; enqueuing an event with opt type @ref RTE_EVENT_OP_RELEASE allows,\n+ * but does not force, the scheduler to release the atomic locks early.\n+ *\n+ * Early atomic lock release may increase parallelism and thus system\n * performance, but the user needs to design carefully the split into critical\n * vs non-critical sections.\n *\n- * If current flow's scheduler type method is *RTE_SCHED_TYPE_ORDERED*\n- * then this function hints the scheduler that the user has done all that need\n- * to maintain event order in the current ordered context.\n- * The scheduler is allowed to release the ordered context of this port and\n- * avoid reordering any following enqueues.\n- *\n- * Early ordered context release may increase parallelism and thus system\n- * performance.\n+ * If current flow's scheduler type method is @ref RTE_SCHED_TYPE_ORDERED\n+ * then this operation type informs the scheduler that the current event has\n+ * completed processing and will not be returned to the scheduler, i.e.\n+ * it has been dropped, and so the reordering context for that event\n+ * should be considered filled.\n *\n- * If current flow's scheduler type method is *RTE_SCHED_TYPE_PARALLEL*\n- * or no scheduling context is held then this function may be an NOOP,\n- * depending on the implementation.\n+ * Events with this operation type must only be enqueued to the same port that the\n+ * event to be released was dequeued from. The @ref rte_event.impl_opaque\n+ * field in the release event must have the same value as that in the original dequeued event.\n *\n- * This operation must only be enqueued to the same port that the\n- * event to be released was dequeued from.\n+ * If a dequeued event is re-enqueued with operation type of @ref RTE_EVENT_OP_RELEASE,\n+ * then any subsequent enqueue of that event - or a copy of it - must be done as event of type\n+ * @ref RTE_EVENT_OP_NEW, not @ref RTE_EVENT_OP_FORWARD. This is because any context for\n+ * the originally dequeued event, i.e. atomic locks, or reorder buffer entries, will have\n+ * been removed or invalidated by the release operation.\n */\n \n /**\n@@ -1517,56 +1524,110 @@ struct rte_event {\n \t\t/** Event attributes for dequeue or enqueue operation */\n \t\tstruct {\n \t\t\tuint32_t flow_id:20;\n-\t\t\t/**< Targeted flow identifier for the enqueue and\n-\t\t\t * dequeue operation.\n-\t\t\t * The value must be in the range of\n-\t\t\t * [0, nb_event_queue_flows - 1] which\n-\t\t\t * previously supplied to rte_event_dev_configure().\n+\t\t\t/**< Target flow identifier for the enqueue and dequeue operation.\n+\t\t\t *\n+\t\t\t * For @ref RTE_SCHED_TYPE_ATOMIC, this field is used to identify a\n+\t\t\t * flow for atomicity within a queue & priority level, such that events\n+\t\t\t * from each individual flow will only be scheduled to one port at a time.\n+\t\t\t *\n+\t\t\t * This field is preserved between enqueue and dequeue when\n+\t\t\t * a device reports the @ref RTE_EVENT_DEV_CAP_CARRY_FLOW_ID\n+\t\t\t * capability. Otherwise the value is implementation dependent\n+\t\t\t * on dequeue.\n \t\t\t */\n \t\t\tuint32_t sub_event_type:8;\n \t\t\t/**< Sub-event types based on the event source.\n+\t\t\t *\n+\t\t\t * This field is preserved between enqueue and dequeue.\n+\t\t\t * This field is for application or event adapter use,\n+\t\t\t * and is not considered in scheduling decisions.\n+\t\t\t *\n \t\t\t * @see RTE_EVENT_TYPE_CPU\n \t\t\t */\n \t\t\tuint32_t event_type:4;\n-\t\t\t/**< Event type to classify the event source.\n-\t\t\t * @see RTE_EVENT_TYPE_ETHDEV, (RTE_EVENT_TYPE_*)\n+\t\t\t/**< Event type to classify the event source. (RTE_EVENT_TYPE_*)\n+\t\t\t *\n+\t\t\t * This field is preserved between enqueue and dequeue\n+\t\t\t * This field is for application or event adapter use,\n+\t\t\t * and is not considered in scheduling decisions.\n \t\t\t */\n \t\t\tuint8_t op:2;\n-\t\t\t/**< The type of event enqueue operation - new/forward/\n-\t\t\t * etc.This field is not preserved across an instance\n-\t\t\t * and is undefined on dequeue.\n-\t\t\t * @see RTE_EVENT_OP_NEW, (RTE_EVENT_OP_*)\n+\t\t\t/**< The type of event enqueue operation - new/forward/ etc.\n+\t\t\t *\n+\t\t\t * This field is *not* preserved across an instance\n+\t\t\t * and is implementation dependent on dequeue.\n+\t\t\t *\n+\t\t\t * @see RTE_EVENT_OP_NEW\n+\t\t\t * @see RTE_EVENT_OP_FORWARD\n+\t\t\t * @see RTE_EVENT_OP_RELEASE\n \t\t\t */\n \t\t\tuint8_t rsvd:4;\n-\t\t\t/**< Reserved for future use */\n+\t\t\t/**< Reserved for future use.\n+\t\t\t *\n+\t\t\t * Should be set to zero on enqueue.\n+\t\t\t */\n \t\t\tuint8_t sched_type:2;\n \t\t\t/**< Scheduler synchronization type (RTE_SCHED_TYPE_*)\n \t\t\t * associated with flow id on a given event queue\n \t\t\t * for the enqueue and dequeue operation.\n+\t\t\t *\n+\t\t\t * This field is used to determine the scheduling type\n+\t\t\t * for events sent to queues where @ref RTE_EVENT_QUEUE_CFG_ALL_TYPES\n+\t\t\t * is configured.\n+\t\t\t * For queues where only a single scheduling type is available,\n+\t\t\t * this field must be set to match the configured scheduling type.\n+\t\t\t *\n+\t\t\t * This field is preserved between enqueue and dequeue.\n+\t\t\t *\n+\t\t\t * @see RTE_SCHED_TYPE_ORDERED\n+\t\t\t * @see RTE_SCHED_TYPE_ATOMIC\n+\t\t\t * @see RTE_SCHED_TYPE_PARALLEL\n \t\t\t */\n \t\t\tuint8_t queue_id;\n \t\t\t/**< Targeted event queue identifier for the enqueue or\n \t\t\t * dequeue operation.\n-\t\t\t * The value must be in the range of\n-\t\t\t * [0, nb_event_queues - 1] which previously supplied to\n-\t\t\t * rte_event_dev_configure().\n+\t\t\t * The value must be less than @ref rte_event_dev_config.nb_event_queues\n+\t\t\t * which was previously supplied to rte_event_dev_configure().\n+\t\t\t *\n+\t\t\t * This field is preserved between enqueue on dequeue.\n \t\t\t */\n \t\t\tuint8_t priority;\n \t\t\t/**< Event priority relative to other events in the\n \t\t\t * event queue. The requested priority should in the\n-\t\t\t * range of [RTE_EVENT_DEV_PRIORITY_HIGHEST,\n-\t\t\t * RTE_EVENT_DEV_PRIORITY_LOWEST].\n+\t\t\t * range of [@ref RTE_EVENT_DEV_PRIORITY_HIGHEST,\n+\t\t\t * @ref RTE_EVENT_DEV_PRIORITY_LOWEST].\n+\t\t\t *\n \t\t\t * The implementation shall normalize the requested\n \t\t\t * priority to supported priority value.\n-\t\t\t * Valid when the device has\n-\t\t\t * RTE_EVENT_DEV_CAP_EVENT_QOS capability.\n+\t\t\t * [For devices with where the supported priority range is a power-of-2, the\n+\t\t\t * normalization will be done via bit-shifting, so only the highest\n+\t\t\t * log2(num_priorities) bits will be used by the event device]\n+\t\t\t *\n+\t\t\t * Valid when the device has @ref RTE_EVENT_DEV_CAP_EVENT_QOS capability\n+\t\t\t * and this field is preserved between enqueue and dequeue,\n+\t\t\t * though with possible loss of precision due to normalization and\n+\t\t\t * subsequent de-normalization. (For example, if a device only supports 8\n+\t\t\t * priority levels, only the high 3 bits of this field will be\n+\t\t\t * used by that device, and hence only the value of those 3 bits are\n+\t\t\t * guaranteed to be preserved between enqueue and dequeue.)\n+\t\t\t *\n+\t\t\t * Ignored when device does not support @ref RTE_EVENT_DEV_CAP_EVENT_QOS\n+\t\t\t * capability, and it is implementation dependent if this field is preserved\n+\t\t\t * between enqueue and dequeue.\n \t\t\t */\n \t\t\tuint8_t impl_opaque;\n-\t\t\t/**< Implementation specific opaque value.\n-\t\t\t * An implementation may use this field to hold\n+\t\t\t/**< Opaque field for event device use.\n+\t\t\t *\n+\t\t\t * An event driver implementation may use this field to hold an\n \t\t\t * implementation specific value to share between\n \t\t\t * dequeue and enqueue operation.\n-\t\t\t * The application should not modify this field.\n+\t\t\t *\n+\t\t\t * The application most not modify this field.\n+\t\t\t * Its value is implementation dependent on dequeue,\n+\t\t\t * and must be returned unmodified on enqueue when\n+\t\t\t * op type is @ref RTE_EVENT_OP_FORWARD or @ref RTE_EVENT_OP_RELEASE.\n+\t\t\t * This field is ignored on events with op type\n+\t\t\t * @ref RTE_EVENT_OP_NEW.\n \t\t\t */\n \t\t};\n \t};\n", "prefixes": [ "v3", "10/11" ] }