From patchwork Fri Jan 19 17:43:44 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 136001 X-Patchwork-Delegate: jerinj@marvell.com Return-Path: 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]) by inbox.dpdk.org (Postfix) with ESMTP id 707FC43901; Fri, 19 Jan 2024 18:45:10 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 440F042DF9; Fri, 19 Jan 2024 18:44:24 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.12]) by mails.dpdk.org (Postfix) with ESMTP id 3334142DF0 for ; Fri, 19 Jan 2024 18:44:22 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1705686262; x=1737222262; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=qAoPoc77mPbZe//oBkOrCaX/GLEDYqz1OCUco46eQwg=; b=bEFRyavhSD/8SFQwLnI9Jir7/KRcJ8LYF4oga7IocoP79rakaI4HiPwQ u7Cfp2h0ynu2mvUtwS7YXwCB0pVbhAxvvijBQw6GVuL9hKsRDiPmZ5b6s cbhoRowLJOe/Xhkx9dhkiyITW/K809nTQcZVFOhND9272YGrhUmsfeqHd 6SEmPQrQS59FV8zu3rA4qkIXhUWk2Hub1RMZfSYmQT5Lm65jjWLrzDVjY UenE4GkndsL+lzkFPHKjVBQ5BF0Goofw6H23Dj8P+nu5mpZAN8mkF4OWe 4J0i8BHT5h4C8GPeqw60a+FduSJ3mG5ZJOEO/2VaSeRphC7S3EsBoaI2Q A==; X-IronPort-AV: E=McAfee;i="6600,9927,10957"; a="683754" X-IronPort-AV: E=Sophos;i="6.05,204,1701158400"; d="scan'208";a="683754" Received: from orsmga006.jf.intel.com ([10.7.209.51]) by fmvoesa106.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 19 Jan 2024 09:44:22 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10957"; a="761177801" X-IronPort-AV: E=Sophos;i="6.05,204,1701158400"; d="scan'208";a="761177801" Received: from silpixa00400957.ir.intel.com (HELO silpixa00401385.ir.intel.com) ([10.237.214.26]) by orsmga006.jf.intel.com with ESMTP; 19 Jan 2024 09:44:18 -0800 From: Bruce Richardson To: dev@dpdk.org Cc: jerinj@marvell.com, mattias.ronnblom@ericsson.com, abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v2 09/11] eventdev: improve doxygen comments for control APIs Date: Fri, 19 Jan 2024 17:43:44 +0000 Message-Id: <20240119174346.108905-10-bruce.richardson@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240119174346.108905-1-bruce.richardson@intel.com> References: <20240118134557.73172-1-bruce.richardson@intel.com> <20240119174346.108905-1-bruce.richardson@intel.com> MIME-Version: 1.0 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 The doxygen comments for the port attributes, start and stop (and related functions) are improved. Signed-off-by: Bruce Richardson --- lib/eventdev/rte_eventdev.h | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index 1fda8a5a13..2c6576e921 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -1117,19 +1117,21 @@ rte_event_port_quiesce(uint8_t dev_id, uint8_t port_id, rte_eventdev_port_flush_t release_cb, void *args); /** - * The queue depth of the port on the enqueue side + * Port attribute id for the maximum size of a burst enqueue operation supported on a port */ #define RTE_EVENT_PORT_ATTR_ENQ_DEPTH 0 /** - * The queue depth of the port on the dequeue side + * Port attribute id for the maximum size of a dequeue burst which can be returned from a port */ #define RTE_EVENT_PORT_ATTR_DEQ_DEPTH 1 /** - * The new event threshold of the port + * Port attribute id for the new event threshold of the port. + * Once the number of events in the system exceeds this threshold, the enqueue of NEW-type + * events will fail. */ #define RTE_EVENT_PORT_ATTR_NEW_EVENT_THRESHOLD 2 /** - * The implicit release disable attribute of the port + * Port attribute id for the implicit release disable attribute of the port */ #define RTE_EVENT_PORT_ATTR_IMPLICIT_RELEASE_DISABLE 3 @@ -1137,11 +1139,13 @@ rte_event_port_quiesce(uint8_t dev_id, uint8_t port_id, * Get an attribute from a port. * * @param dev_id - * Eventdev id + * The identifier of the device. * @param port_id - * Eventdev port id + * The index of the event port to query. The value must be in the range + * [0, @ref rte_event_dev_config.nb_event_ports - 1] + * previously supplied to rte_event_dev_configure(). * @param attr_id - * The attribute ID to retrieve + * The attribute ID to retrieve (RTE_EVENT_PORT_ATTR_*) * @param[out] attr_value * A pointer that will be filled in with the attribute value if successful * @@ -1156,8 +1160,8 @@ rte_event_port_attr_get(uint8_t dev_id, uint8_t port_id, uint32_t attr_id, /** * Start an event device. * - * The device start step is the last one and consists of setting the event - * queues to start accepting the events and schedules to event ports. + * The device start step is the last one in device setup, and enables the event + * ports and queues to start accepting events and scheduling them to event ports. * * On success, all basic functions exported by the API (event enqueue, * event dequeue and so on) can be invoked. @@ -1166,6 +1170,8 @@ rte_event_port_attr_get(uint8_t dev_id, uint8_t port_id, uint32_t attr_id, * Event device identifier * @return * - 0: Success, device started. + * - -EINVAL: Invalid device id provided + * - -ENOTSUP: Device does not support this operation. * - -ESTALE : Not all ports of the device are configured * - -ENOLINK: Not all queues are linked, which could lead to deadlock. */ @@ -1208,12 +1214,16 @@ typedef void (*rte_eventdev_stop_flush_t)(uint8_t dev_id, * callback function must be registered in every process that can call * rte_event_dev_stop(). * + * Only one callback function may be registered. Each new call replaces + * the existing registered callback function with the new function passed in. + * * To unregister a callback, call this function with a NULL callback pointer. * * @param dev_id * The identifier of the device. * @param callback - * Callback function invoked once per flushed event. + * Callback function to be invoked once per flushed event. + * Pass NULL to unset any previously-registered callback function. * @param userdata * Argument supplied to callback. * @@ -1235,7 +1245,9 @@ int rte_event_dev_stop_flush_callback_register(uint8_t dev_id, * @return * - 0 on successfully closing device * - <0 on failure to close device - * - (-EAGAIN) if device is busy + * - -EINVAL - invalid device id + * - -ENOTSUP - operation not supported for this device + * - -EAGAIN - device is busy */ int rte_event_dev_close(uint8_t dev_id);