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 4620A439A6; Tue, 23 Jan 2024 11:10:11 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id DDBBA402BD; Tue, 23 Jan 2024 11:10:10 +0100 (CET) Received: from mail.lysator.liu.se (mail.lysator.liu.se [130.236.254.3]) by mails.dpdk.org (Postfix) with ESMTP id DA640400D7 for ; Tue, 23 Jan 2024 11:10:09 +0100 (CET) Received: from mail.lysator.liu.se (localhost [127.0.0.1]) by mail.lysator.liu.se (Postfix) with ESMTP id 8E2AD18F7E for ; Tue, 23 Jan 2024 11:10:09 +0100 (CET) Received: by mail.lysator.liu.se (Postfix, from userid 1004) id 8125619094; Tue, 23 Jan 2024 11:10:09 +0100 (CET) X-Spam-Checker-Version: SpamAssassin 4.0.0 (2022-12-13) on hermod.lysator.liu.se X-Spam-Level: X-Spam-Status: No, score=-1.4 required=5.0 tests=ALL_TRUSTED,AWL, T_SCC_BODY_TEXT_LINE autolearn=disabled version=4.0.0 X-Spam-Score: -1.4 Received: from [192.168.1.59] (h-62-63-215-114.A163.priv.bahnhof.se [62.63.215.114]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mail.lysator.liu.se (Postfix) with ESMTPSA id B05F319035; Tue, 23 Jan 2024 11:10:07 +0100 (CET) Message-ID: <6366688f-6ae5-44ca-bee7-e085a235548f@lysator.liu.se> Date: Tue, 23 Jan 2024 11:10:07 +0100 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH v2 09/11] eventdev: improve doxygen comments for control APIs Content-Language: en-US To: Bruce Richardson , 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 References: <20240118134557.73172-1-bruce.richardson@intel.com> <20240119174346.108905-1-bruce.richardson@intel.com> <20240119174346.108905-10-bruce.richardson@intel.com> From: =?UTF-8?Q?Mattias_R=C3=B6nnblom?= In-Reply-To: <20240119174346.108905-10-bruce.richardson@intel.com> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Virus-Scanned: ClamAV using ClamSMTP 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 On 2024-01-19 18:43, Bruce Richardson wrote: > 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 "." missing. > */ > #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(). Does the range need to be mentioned everywhere? Seems like it should be pretty opaque to the app. > * @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 3 x "." > */ > int > rte_event_dev_close(uint8_t dev_id);