Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/136322/?format=api
{ "id": 136322, "url": "http://patches.dpdk.org/api/patches/136322/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20240202123953.77166-4-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-4-bruce.richardson@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20240202123953.77166-4-bruce.richardson@intel.com", "date": "2024-02-02T12:39:45", "name": "[v3,03/11] eventdev: update documentation on device capability flags", "commit_ref": null, "pull_url": null, "state": "changes-requested", "archived": true, "hash": "e11e111b16a36e66eb12913cf69c7fb2b67cf3b4", "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-4-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/136322/comments/", "check": "success", "checks": "http://patches.dpdk.org/api/patches/136322/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 0014543A4F;\n\tFri, 2 Feb 2024 13:40:46 +0100 (CET)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 2418142E5E;\n\tFri, 2 Feb 2024 13:40:39 +0100 (CET)", "from mgamail.intel.com (mgamail.intel.com [192.198.163.18])\n by mails.dpdk.org (Postfix) with ESMTP id AF92542E63\n for <dev@dpdk.org>; Fri, 2 Feb 2024 13:40:36 +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:40:36 -0800", "from silpixa00401385.ir.intel.com ([10.237.214.38])\n by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:34 -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=1706877637; x=1738413637;\n h=from:to:cc:subject:date:message-id:in-reply-to:\n references:mime-version:content-transfer-encoding;\n bh=DzYCMLXxu3B262mm4OlS1C0hzLeOmXkEAfiIghGFbSk=;\n b=e8lhCCJVxuQXj3NB3Re6js9pyXOzHkOJmy5WTIwacvmEp/Hrs6JEF6Kg\n ZoFSswR1XaenkA3yQlsFClPHmNrohLqXVPMoyFHAQM1d9nqYqg7sSEFYF\n KKL4cOSbXPyReGagO9saAPWWpu7eAMYRRuaGc61xOQkFKcYPa7X4M5hZP\n OUeaDUASuXWUreZSFg5KP1X5jY1LXCUP+1/PXktOdKLgq++GWj+JXtPwu\n NjU1MOHudDHGyhIsSBZ8Xl+mvpFycsnCBHEFn/Un6Y5WIdK9k5vRGoUCo\n zCKqox4z8luGowb1MTIEHZGWn5IE0yFVe0lm50fYdGqKQ98AxF+oj+eej w==;", "X-IronPort-AV": [ "E=McAfee;i=\"6600,9927,10971\"; a=\"54349\"", "E=Sophos;i=\"6.05,238,1701158400\";\n d=\"scan'208\";a=\"54349\"", "E=Sophos;i=\"6.05,238,1701158400\";\n d=\"scan'208\";a=\"347559\"" ], "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 03/11] eventdev: update documentation on device capability\n flags", "Date": "Fri, 2 Feb 2024 12:39:45 +0000", "Message-Id": "<20240202123953.77166-4-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": "Update the device capability docs, to:\n\n* include more cross-references\n* split longer text into paragraphs, in most cases with each flag having\n a single-line summary at the start of the doc block\n* general comment rewording and clarification as appropriate\n\nSigned-off-by: Bruce Richardson <bruce.richardson@intel.com>\n---\nV3: Updated following feedback from Mattias\n---\n lib/eventdev/rte_eventdev.h | 130 +++++++++++++++++++++++++-----------\n 1 file changed, 92 insertions(+), 38 deletions(-)", "diff": "diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h\nindex 37493464f9..a33024479d 100644\n--- a/lib/eventdev/rte_eventdev.h\n+++ b/lib/eventdev/rte_eventdev.h\n@@ -253,143 +253,197 @@ struct rte_event;\n /* Event device capability bitmap flags */\n #define RTE_EVENT_DEV_CAP_QUEUE_QOS (1ULL << 0)\n /**< Event scheduling prioritization is based on the priority and weight\n- * associated with each event queue. Events from a queue with highest priority\n- * is scheduled first. If the queues are of same priority, weight of the queues\n+ * associated with each event queue.\n+ *\n+ * Events from a queue with highest priority\n+ * are scheduled first. If the queues are of same priority, weight of the queues\n * are considered to select a queue in a weighted round robin fashion.\n * Subsequent dequeue calls from an event port could see events from the same\n * event queue, if the queue is configured with an affinity count. Affinity\n * count is the number of subsequent dequeue calls, in which an event port\n * should use the same event queue if the queue is non-empty\n *\n+ * NOTE: A device may use both queue prioritization and event prioritization\n+ * (@ref RTE_EVENT_DEV_CAP_EVENT_QOS capability) when making packet scheduling decisions.\n+ *\n * @see rte_event_queue_setup(), rte_event_queue_attr_set()\n */\n #define RTE_EVENT_DEV_CAP_EVENT_QOS (1ULL << 1)\n /**< Event scheduling prioritization is based on the priority associated with\n- * each event. Priority of each event is supplied in *rte_event* structure\n+ * each event.\n+ *\n+ * Priority of each event is supplied in *rte_event* structure\n * on each enqueue operation.\n+ * If this capability is not set, the priority field of the event structure\n+ * is ignored for each event.\n *\n+ * NOTE: A device may use both queue prioritization (@ref RTE_EVENT_DEV_CAP_QUEUE_QOS capability)\n+ * and event prioritization when making packet scheduling decisions.\n+\n * @see rte_event_enqueue_burst()\n */\n #define RTE_EVENT_DEV_CAP_DISTRIBUTED_SCHED (1ULL << 2)\n /**< Event device operates in distributed scheduling mode.\n+ *\n * In distributed scheduling mode, event scheduling happens in HW or\n- * rte_event_dequeue_burst() or the combination of these two.\n+ * rte_event_dequeue_burst() / rte_event_enqueue_burst() or the combination of these two.\n * If the flag is not set then eventdev is centralized and thus needs a\n * dedicated service core that acts as a scheduling thread .\n *\n- * @see rte_event_dequeue_burst()\n+ * @see rte_event_dev_service_id_get\n */\n #define RTE_EVENT_DEV_CAP_QUEUE_ALL_TYPES (1ULL << 3)\n /**< Event device is capable of enqueuing events of any type to any queue.\n- * If this capability is not set, the queue only supports events of the\n- * *RTE_SCHED_TYPE_* type that it was created with.\n *\n- * @see RTE_SCHED_TYPE_* values\n+ * If this capability is not set, each queue only supports events of the\n+ * *RTE_SCHED_TYPE_* type that it was created with.\n+ * The behaviour when events of other scheduling types are sent to the queue is\n+ * currently undefined.\n+ *\n+ * @see rte_event_enqueue_burst\n+ * @see RTE_SCHED_TYPE_ATOMIC RTE_SCHED_TYPE_ORDERED RTE_SCHED_TYPE_PARALLEL\n */\n #define RTE_EVENT_DEV_CAP_BURST_MODE (1ULL << 4)\n /**< Event device is capable of operating in burst mode for enqueue(forward,\n- * release) and dequeue operation. If this capability is not set, application\n- * still uses the rte_event_dequeue_burst() and rte_event_enqueue_burst() but\n- * PMD accepts only one event at a time.\n+ * release) and dequeue operation.\n+ *\n+ * If this capability is not set, application\n+ * can still use the rte_event_dequeue_burst() and rte_event_enqueue_burst() but\n+ * PMD accepts or returns only one event at a time.\n *\n * @see rte_event_dequeue_burst() rte_event_enqueue_burst()\n */\n #define RTE_EVENT_DEV_CAP_IMPLICIT_RELEASE_DISABLE (1ULL << 5)\n /**< Event device ports support disabling the implicit release feature, in\n * which the port will release all unreleased events in its dequeue operation.\n+ *\n * If this capability is set and the port is configured with implicit release\n * disabled, the application is responsible for explicitly releasing events\n- * using either the RTE_EVENT_OP_FORWARD or the RTE_EVENT_OP_RELEASE event\n+ * using either the @ref RTE_EVENT_OP_FORWARD or the @ref RTE_EVENT_OP_RELEASE event\n * enqueue operations.\n *\n * @see rte_event_dequeue_burst() rte_event_enqueue_burst()\n */\n \n #define RTE_EVENT_DEV_CAP_NONSEQ_MODE (1ULL << 6)\n-/**< Event device is capable of operating in none sequential mode. The path\n- * of the event is not necessary to be sequential. Application can change\n- * the path of event at runtime. If the flag is not set, then event each event\n- * will follow a path from queue 0 to queue 1 to queue 2 etc. If the flag is\n- * set, events may be sent to queues in any order. If the flag is not set, the\n- * eventdev will return an error when the application enqueues an event for a\n+/**< Event device is capable of operating in non-sequential mode.\n+ *\n+ * The path of the event is not necessary to be sequential. Application can change\n+ * the path of event at runtime and events may be sent to queues in any order.\n+ *\n+ * If the flag is not set, then event each event will follow a path from queue 0\n+ * to queue 1 to queue 2 etc.\n+ * The eventdev will return an error when the application enqueues an event for a\n * qid which is not the next in the sequence.\n */\n \n #define RTE_EVENT_DEV_CAP_RUNTIME_PORT_LINK (1ULL << 7)\n-/**< Event device is capable of configuring the queue/port link at runtime.\n+/**< Event device is capable of reconfiguring the queue/port link at runtime.\n+ *\n * If the flag is not set, the eventdev queue/port link is only can be\n- * configured during initialization.\n+ * configured during initialization, or by stopping the device and\n+ * then later restarting it after reconfiguration.\n+ *\n+ * @see rte_event_port_link rte_event_port_unlink\n */\n \n #define RTE_EVENT_DEV_CAP_MULTIPLE_QUEUE_PORT (1ULL << 8)\n-/**< Event device is capable of setting up the link between multiple queue\n- * with single port. If the flag is not set, the eventdev can only map a\n- * single queue to each port or map a single queue to many port.\n+/**< Event device is capable of setting up links between multiple queues and a single port.\n+ *\n+ * If the flag is not set, each port may only be linked to a single queue, and\n+ * so can only receive events from that queue.\n+ * However, each queue may be linked to multiple ports.\n+ *\n+ * @see rte_event_port_link\n */\n \n #define RTE_EVENT_DEV_CAP_CARRY_FLOW_ID (1ULL << 9)\n-/**< Event device preserves the flow ID from the enqueued\n- * event to the dequeued event if the flag is set. Otherwise,\n- * the content of this field is implementation dependent.\n+/**< Event device preserves the flow ID from the enqueued event to the dequeued event.\n+ *\n+ * If this flag is not set,\n+ * the content of the flow-id field in dequeued events is implementation dependent.\n+ *\n+ * @see rte_event_dequeue_burst\n */\n \n #define RTE_EVENT_DEV_CAP_MAINTENANCE_FREE (1ULL << 10)\n /**< Event device *does not* require calls to rte_event_maintain().\n+ *\n * An event device that does not set this flag requires calls to\n * rte_event_maintain() during periods when neither\n * rte_event_dequeue_burst() nor rte_event_enqueue_burst() are called\n * on a port. This will allow the event device to perform internal\n * processing, such as flushing buffered events, return credits to a\n * global pool, or process signaling related to load balancing.\n+ *\n+ * @see rte_event_maintain\n */\n \n #define RTE_EVENT_DEV_CAP_RUNTIME_QUEUE_ATTR (1ULL << 11)\n /**< Event device is capable of changing the queue attributes at runtime i.e\n- * after rte_event_queue_setup() or rte_event_start() call sequence. If this\n- * flag is not set, eventdev queue attributes can only be configured during\n+ * after rte_event_queue_setup() or rte_event_dev_start() call sequence.\n+ *\n+ * If this flag is not set, event queue attributes can only be configured during\n * rte_event_queue_setup().\n+ *\n+ * @see rte_event_queue_setup\n */\n \n #define RTE_EVENT_DEV_CAP_PROFILE_LINK (1ULL << 12)\n-/**< Event device is capable of supporting multiple link profiles per event port\n- * i.e., the value of `rte_event_dev_info::max_profiles_per_port` is greater\n- * than one.\n+/**< Event device is capable of supporting multiple link profiles per event port.\n+ *\n+ *\n+ * When set, the value of `rte_event_dev_info::max_profiles_per_port` is greater\n+ * than one, and multiple profiles may be configured and then switched at runtime.\n+ * If not set, only a single profile may be configured, which may itself be\n+ * runtime adjustable (if @ref RTE_EVENT_DEV_CAP_RUNTIME_PORT_LINK is set).\n+ *\n+ * @see rte_event_port_profile_links_set rte_event_port_profile_links_get\n+ * @see rte_event_port_profile_switch\n+ * @see RTE_EVENT_DEV_CAP_RUNTIME_PORT_LINK\n */\n \n /* Event device priority levels */\n #define RTE_EVENT_DEV_PRIORITY_HIGHEST 0\n-/**< Highest priority expressed across eventdev subsystem\n+/**< Highest priority level for events and queues.\n+ *\n * @see rte_event_queue_setup(), rte_event_enqueue_burst()\n * @see rte_event_port_link()\n */\n #define RTE_EVENT_DEV_PRIORITY_NORMAL 128\n-/**< Normal priority expressed across eventdev subsystem\n+/**< Normal priority level for events and queues.\n+ *\n * @see rte_event_queue_setup(), rte_event_enqueue_burst()\n * @see rte_event_port_link()\n */\n #define RTE_EVENT_DEV_PRIORITY_LOWEST 255\n-/**< Lowest priority expressed across eventdev subsystem\n+/**< Lowest priority level for events and queues.\n+ *\n * @see rte_event_queue_setup(), rte_event_enqueue_burst()\n * @see rte_event_port_link()\n */\n \n /* Event queue scheduling weights */\n #define RTE_EVENT_QUEUE_WEIGHT_HIGHEST 255\n-/**< Highest weight of an event queue\n+/**< Highest weight of an event queue.\n+ *\n * @see rte_event_queue_attr_get(), rte_event_queue_attr_set()\n */\n #define RTE_EVENT_QUEUE_WEIGHT_LOWEST 0\n-/**< Lowest weight of an event queue\n+/**< Lowest weight of an event queue.\n+ *\n * @see rte_event_queue_attr_get(), rte_event_queue_attr_set()\n */\n \n /* Event queue scheduling affinity */\n #define RTE_EVENT_QUEUE_AFFINITY_HIGHEST 255\n-/**< Highest scheduling affinity of an event queue\n+/**< Highest scheduling affinity of an event queue.\n+ *\n * @see rte_event_queue_attr_get(), rte_event_queue_attr_set()\n */\n #define RTE_EVENT_QUEUE_AFFINITY_LOWEST 0\n-/**< Lowest scheduling affinity of an event queue\n+/**< Lowest scheduling affinity of an event queue.\n+ *\n * @see rte_event_queue_attr_get(), rte_event_queue_attr_set()\n */\n \n", "prefixes": [ "v3", "03/11" ] }