From patchwork Fri Feb 2 12:39:50 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 136327 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 54E2843A4F; Fri, 2 Feb 2024 13:41:26 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 4FCA142EA0; Fri, 2 Feb 2024 13:40:57 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id DF6D742E8B for ; Fri, 2 Feb 2024 13:40:54 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706877655; x=1738413655; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=NPSSjXz5I2AgI19Rp1SjE5YBkkLBsA82iqVj1WGlXmU=; b=meyCYD78kLewTiMKSKPivZrRSAY7eAKjtZ3e3iYxZMct+en2U9jLNPwy ais0c+OVsc1I9sk3k2QmZidH38DRj5h+PCW2OY3p9qaITHG4B5Ar4j32D irGuwLems2mjhU87q9JG/VehjOhvRc4a+wD4aIphce5xJD+qZxWz+ktay MK0lk/wcP/CBHI+72Ej38PFhtYv1JFe0PeIjGcm55MrFwQ0urU55qnmOk 5FszGP/OEgFfGJPQ110Y07Rc8M/4FNtYEOIlrX0bGHdrgLg76PeAhzz6H inGSv826Szj4JXWgzfuzGhPr+QX1TB1O0CSgiN7BZm1qY//3cHgiYtEqz g==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="54461" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="54461" Received: from fmviesa006.fm.intel.com ([10.60.135.146]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 04:40:54 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="347622" Received: from silpixa00401385.ir.intel.com ([10.237.214.38]) by fmviesa006.fm.intel.com with ESMTP; 02 Feb 2024 04:40:52 -0800 From: Bruce Richardson To: dev@dpdk.org, jerinj@marvell.com, mattias.ronnblom@ericsson.com Cc: abdullah.sevincer@intel.com, sachin.saxena@oss.nxp.com, hemant.agrawal@nxp.com, pbhagavatula@marvell.com, pravin.pathak@intel.com, Bruce Richardson Subject: [PATCH v3 08/11] eventdev: improve doxygen comments for control APIs Date: Fri, 2 Feb 2024 12:39:50 +0000 Message-Id: <20240202123953.77166-9-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> <20240202123953.77166-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 --- V3: add missing "." on end of sentences/lines. --- lib/eventdev/rte_eventdev.h | 47 +++++++++++++++++++++++-------------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index e2923a69fb..a7d8c28015 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -1151,19 +1151,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 @@ -1171,17 +1173,18 @@ 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 less than + * @ref rte_event_dev_config.nb_event_ports 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 * * @return - * - 0: Successfully returned value - * - (-EINVAL) Invalid device, port or attr_id, or attr_value was NULL + * - 0: Successfully returned value. + * - (-EINVAL) Invalid device, port or attr_id, or attr_value was NULL. */ int rte_event_port_attr_get(uint8_t dev_id, uint8_t port_id, uint32_t attr_id, @@ -1190,17 +1193,19 @@ 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. * * @param dev_id - * Event device identifier + * Event device identifier. * @return * - 0: Success, device started. - * - -ESTALE : Not all ports of the device are configured + * - -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. */ int @@ -1242,18 +1247,22 @@ 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. * * @return * - 0 on success. - * - -EINVAL if *dev_id* is invalid + * - -EINVAL if *dev_id* is invalid. * * @see rte_event_dev_stop() */ @@ -1264,12 +1273,14 @@ int rte_event_dev_stop_flush_callback_register(uint8_t dev_id, * Close an event device. The device cannot be restarted! * * @param dev_id - * Event device identifier + * Event device identifier. * * @return * - 0 on successfully closing device - * - <0 on failure to close device - * - (-EAGAIN) if device is busy + * - <0 on failure to close device. + * - -EINVAL - invalid device id. + * - -ENOTSUP - operation not supported for this device. + * - -EAGAIN - device is busy. */ int rte_event_dev_close(uint8_t dev_id);