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 E8C44439A6; Tue, 23 Jan 2024 10:40:31 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7FDF6402C5; Tue, 23 Jan 2024 10:40:31 +0100 (CET) Received: from mail.lysator.liu.se (mail.lysator.liu.se [130.236.254.3]) by mails.dpdk.org (Postfix) with ESMTP id E8763402BD for ; Tue, 23 Jan 2024 10:40:29 +0100 (CET) Received: from mail.lysator.liu.se (localhost [127.0.0.1]) by mail.lysator.liu.se (Postfix) with ESMTP id 943B618E07 for ; Tue, 23 Jan 2024 10:40:29 +0100 (CET) Received: by mail.lysator.liu.se (Postfix, from userid 1004) id 71C2718E06; Tue, 23 Jan 2024 10:40:29 +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.5 required=5.0 tests=ALL_TRUSTED,AWL, T_SCC_BODY_TEXT_LINE autolearn=disabled version=4.0.0 X-Spam-Score: -1.5 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 C456518D96; Tue, 23 Jan 2024 10:40:27 +0100 (CET) Message-ID: Date: Tue, 23 Jan 2024 10:40:27 +0100 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH v2 05/11] eventdev: improve function documentation for query fns 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-6-bruce.richardson@intel.com> From: =?UTF-8?Q?Mattias_R=C3=B6nnblom?= In-Reply-To: <20240119174346.108905-6-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: > General improvements to the doxygen docs for eventdev functions for > querying basic information: > * number of devices > * id for a particular device > * socket id of device > * capability information for a device > > Signed-off-by: Bruce Richardson > --- > lib/eventdev/rte_eventdev.h | 22 +++++++++++++--------- > 1 file changed, 13 insertions(+), 9 deletions(-) > > diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h > index 872f241df2..c57c93a22e 100644 > --- a/lib/eventdev/rte_eventdev.h > +++ b/lib/eventdev/rte_eventdev.h > @@ -440,8 +440,7 @@ struct rte_event; > */ > > /** > - * Get the total number of event devices that have been successfully > - * initialised. > + * Get the total number of event devices available for application use. Does "for application use" add information? If they aren't for application use, I would argue such are "unavailable". "Get the total number of available event devices" or just "Get the total number of event devices". > * > * @return > * The total number of usable event devices. > @@ -456,8 +455,10 @@ rte_event_dev_count(void); > * Event device name to select the event device identifier. > * > * @return > - * Returns event device identifier on success. > - * - <0: Failure to find named event device. > + * Event device identifier (dev_id >= 0) on success. > + * Negative error code on failure: > + * - -EINVAL - input name parameter is invalid > + * - -ENODEV - no event device found with that name "."? > */ > int > rte_event_dev_get_dev_id(const char *name); > @@ -470,7 +471,8 @@ rte_event_dev_get_dev_id(const char *name); > * @return > * The NUMA socket id to which the device is connected or > * a default of zero if the socket could not be determined. > - * -(-EINVAL) dev_id value is out of range. > + * -EINVAL on error, where the given dev_id value does not > + * correspond to any event device. > */ > int > rte_event_dev_socket_id(uint8_t dev_id); > @@ -539,18 +541,20 @@ struct rte_event_dev_info { > }; > > /** > - * Retrieve the contextual information of an event device. > + * Retrieve details of an event device's capabilities and configuration limits. > * > * @param dev_id > * The identifier of the device. > * > * @param[out] dev_info > * A pointer to a structure of type *rte_event_dev_info* to be filled with the > - * contextual information of the device. > + * information about the device's capabilities. > * > * @return > - * - 0: Success, driver updates the contextual information of the event device > - * - <0: Error code returned by the driver info get function. > + * - 0: Success, information about the event device is present in dev_info. > + * - <0: Failure, error code returned by the function. > + * - -EINVAL - invalid input parameters, e.g. incorrect device id > + * - -ENOTSUP - device does not support returning capabilities information > */ > int > rte_event_dev_info_get(uint8_t dev_id, struct rte_event_dev_info *dev_info);