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 B92EA43BE1; Mon, 26 Feb 2024 07:44:21 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A742D402BA; Mon, 26 Feb 2024 07:44:21 +0100 (CET) Received: from mx0b-0016f401.pphosted.com (mx0a-0016f401.pphosted.com [67.231.148.174]) by mails.dpdk.org (Postfix) with ESMTP id E4D6240144 for ; Mon, 26 Feb 2024 07:44:19 +0100 (CET) Received: from pps.filterd (m0045849.ppops.net [127.0.0.1]) by mx0a-0016f401.pphosted.com (8.17.1.24/8.17.1.24) with ESMTP id 41Q6ctc3024112; Sun, 25 Feb 2024 22:44:19 -0800 Received: from nam11-bn8-obe.outbound.protection.outlook.com (mail-bn8nam11lp2168.outbound.protection.outlook.com [104.47.58.168]) by mx0a-0016f401.pphosted.com (PPS) with ESMTPS id 3wfepr49jh-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Sun, 25 Feb 2024 22:44:18 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=BbwuJcRMkzpNnyBUGVQkvpD5e33CZVMdV4wnq7TXN/cOyfqRKFWGpfiGVSEUwQ/dVlD0MkjF/VWVFc4fsoKBXfxu4l7703DN8vg0xmAEuBzR2Eyz9Rlu32i7IAMck7MA/guF2mge3426zcqFJ9GkPWsvQLEggqD3rWPXv7DT1RuMwltpn9yEV/7z/EcdsivcGlZVF8GFb8HsuCc/euhQrSr+hXjfImG8+LeEwTFPulvzdBjrTZ76iQjm8L/oyzkNkL3zre32XVj4xdtOB/t09+pX0N3fzX/6Bf4E6ptT571Q7JMgPdff57sRlcYI8mnLhF7Bn3bN+w+hv4Va1flNJQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=kkUVPeMLqUeG6fMAwiohALC3cGmUj5LpD1kEVW3QT28=; b=aFtja9WtmKi4S7HiGstvREyZfFtmo5omBAxf7xhsRMcXTNYnk+9IIsuHZ7wMsSVcOuuc8C/tYbUseZ8T7Wc6FHg8tY7vGnUNWj10FdLCdVLd+WGaVaRD3rIVVeMwFLJrBhl6PvDWvjagSZ1QuAX58kqnjmMdcdg9qTJW5njRhbty0qBxMImzKaAR5KpoHQIVmZN+o/joQUPtZb1+f7cXbKLWERMJvTtYLk0BRjeEbv9Fa9vIa735yQjGy2dQYYC1olv1AReBmNv54K54wvVCTxW4HnayCItXol5usWLYElb0Vrn/7xz1sAN3xu2kBWVaNZMGzd4Y77g/fTOFMhuKvw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=marvell.com; dmarc=pass action=none header.from=marvell.com; dkim=pass header.d=marvell.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=marvell.onmicrosoft.com; s=selector1-marvell-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=kkUVPeMLqUeG6fMAwiohALC3cGmUj5LpD1kEVW3QT28=; b=g9erZNcPmNke3efZFFEAteJFl9pNlrvjG4WAXemqq9zuOmDMnHV29EKUkoViHBkZro0WgTkDS/nUOARR5oDwb90vch0L7VftDH4gFKNVRS8THFW51zi/6ZdSQXbCNxN8AX7AONqYb96Vih/PxYYohMHg7A1AxGxmhbx41CJ99rU= Received: from PH0PR18MB4086.namprd18.prod.outlook.com (2603:10b6:510:3::9) by PH0PR18MB3831.namprd18.prod.outlook.com (2603:10b6:510:22::16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7316.34; Mon, 26 Feb 2024 06:44:16 +0000 Received: from PH0PR18MB4086.namprd18.prod.outlook.com ([fe80::baf5:a4b6:7776:10f4]) by PH0PR18MB4086.namprd18.prod.outlook.com ([fe80::baf5:a4b6:7776:10f4%6]) with mapi id 15.20.7316.034; Mon, 26 Feb 2024 06:44:16 +0000 From: Pavan Nikhilesh Bhagavatula To: Bruce Richardson , "dev@dpdk.org" , Jerin Jacob , "mattias.ronnblom@ericsson.com" Subject: RE: [EXT] [PATCH v4 08/12] eventdev: improve doxygen comments for control APIs Thread-Topic: [EXT] [PATCH v4 08/12] eventdev: improve doxygen comments for control APIs Thread-Index: AQHaZLFo/NOdLvc/WEyiH9byV54c37EcNPVw Date: Mon, 26 Feb 2024 06:44:16 +0000 Message-ID: References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240221103221.933238-1-bruce.richardson@intel.com> <20240221103221.933238-9-bruce.richardson@intel.com> In-Reply-To: <20240221103221.933238-9-bruce.richardson@intel.com> Accept-Language: en-US, en-IN Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-ms-publictraffictype: Email x-ms-traffictypediagnostic: PH0PR18MB4086:EE_|PH0PR18MB3831:EE_ x-ms-office365-filtering-correlation-id: acdbe4c3-dfe4-4e7d-4f9b-08dc36965a29 x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: xS/MbXnWDiMZwJyktRfCP2WIxwHXD07iur7mK0OWuqDz2859yvz4+48RkCIP5JFw0JQ5Q3zoEdEQh+IEBZ2sSILgvFrsQH7tUr7a8pTHdkqeIQ0w1wZADURVPNTizXBCUEIgG0BEDmV+kzsI3zgECLviJ5gOc3eY7FVm5e22sF/eqOOq+R3HmQUI5U+MbqvXOLMDqgY5/BSIhueubqZrBNlbXQ7IMi8bkKZyBAFGIH0/D2kUj7+tXRNTHfIpH1VKaxzQfxYGiBnJ59h43CDQM9el8GcEl/RZa9OxfD4wx2u1f4j0GRVxS6AAtBPL9n+V5q/amhvnGQekEVSvX1EIQGnOO7z3S9/cCSHp7ZWe05hAjtS9Ja9U7FMM4d9L9RL2RBA7pntnkbeB7SedzHkhdEHviCpjtopkp/0WF3aj9vSSnfvarp/Nlkqd3KyKQ7/XJsYSxwxju8BNiUtnOmpu/jKXAiL3XF9SbGDzk/Rs7e7Zj7ujAENVDf5dNWMMJVRdIJCO2UJaDTh/8I4EJpucX23eLO/UNdoJDCh2rZS90s4/ENwV/unJom3IkT4vZ2eUrvcvDxxoix82ytA5d4xcaNopkKXUxnKyYLS/kzdDWLhV3UWzgoZrGw8F3xmNahoU23KMOSfryDko9/V4Ymgd4tQsDXfXrZcy9j7Au3kiX2zrUmkhyX2fqQVi2PddSmIIx7h1ZXXQkuvEcbGQ7pKcGHUyJMwGCfQafmDK8KBmxVs= x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:PH0PR18MB4086.namprd18.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230031)(38070700009); DIR:OUT; SFP:1102; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: =?us-ascii?Q?zvysAdr0eDmFHZ9Ol7pjc/vOmnfRoHGQ3JA/n+LzJRvhxgrBPSGPJbLP2mmK?= =?us-ascii?Q?llQVRWMjKqtnYXWsfA1A7Kq8TnBJ+DeNjyrMdLd1htREfF36/DhhYQ3HRDY5?= =?us-ascii?Q?zHLKwNAC5NfkPO5lBxHjqAl/hWM9YAMp3nSRqF2VC/ieFpky080pWrFNfy8b?= =?us-ascii?Q?mVTdlu567Wt03DvJFBow9WXJh4dhV/omYzv6GDqwjVTL8PquigBnE99mNv9a?= =?us-ascii?Q?NrAjIcjXVnackSsyDBIG4RsZpsj3ZFIvEmA0/ZrXoZJ1QPdwF36NV/FtnDHs?= =?us-ascii?Q?bZgIivYLVMg3US0GYiA07Mpq28VaMdKg1eT03erS5+W7V2+5DiJ+MSvwV0A1?= =?us-ascii?Q?yjQM89PIOtIfQscdWzwinf5taG3BsPNJ8YFvu+Zh2SE3cTjRJ5McpKKBnIPK?= =?us-ascii?Q?pTiLV2YVcD2aLzWUr7XMLwSqC1TNBh1q+3EDun5EJ33qBbY0Pj9eacfPzERe?= =?us-ascii?Q?QFirX3X/wB1ThcyywW282QdCN1d05BusoJSrGFekyzz8MGw/p/xidqtMn6ZP?= =?us-ascii?Q?c5VHp97q0oOtatT8pMnt2O/r2BHGPFzoQ/W7C969wi+XCUIKKaJOS3agYM0w?= =?us-ascii?Q?2dkMiRbXOP2r6No3U3tg/PMMQj+8KwKv9I6b62SrBQzyEnxkLwMZLQCKNpZA?= =?us-ascii?Q?jrt7vHOMQss/xlNIB9MXdUwAXPEynGhX9buDjqaYvUTyiLi6BTsrBqgf6q1T?= =?us-ascii?Q?eYQdnUtWrswxL70w+hWTgFL4gJGfpQtOGscpGN0TKqmDb55WdZGGn25pfyln?= =?us-ascii?Q?r/rFyQdE1bnIE1Z8bheCr14B/m1NJrS6HxQlF2CHQoP2SHdLdhc0VBZDOI+F?= =?us-ascii?Q?MNlj+UNa3AQ+w4X+rA8OhFrroUnkISudSyHi7uahhrvnm2JG7Bc3trqK6aWd?= =?us-ascii?Q?NfPBhITwXlDyYvmrgm18hJqXVaeOO9MNynFrkfbKfjyaH0CsETPGo8B+NGCX?= =?us-ascii?Q?X0OK9GSWaXN5fbxVY1ujMSNw1q15EZzOXJLkUIE7253tp4+YWBtemQi2iigS?= =?us-ascii?Q?yqhZPrzCYSxV8EAJPncL8rkvrVFnG/vo5ydY8LDxetC1TVMFlpVyVx6uSUY1?= =?us-ascii?Q?vHcvqdSPZMqehs41678SoH3osSDYSJUVbfkCSTdRBL+PtyQKXLP9VZrkb4Ht?= =?us-ascii?Q?SqW2dTQyy5ajEbsK7LrnpSpQG+sRi0C5ISa42q/gINVkb+FlJIg+NxnZDeHW?= =?us-ascii?Q?FPQVfb9b4TMK9WAT3Jd59KZwnTjoL2Wu632qCsCVys+rtz6CMRoNqphCm9CM?= =?us-ascii?Q?VnOITbgL3wjVrPfyNdHiBIfm2oHUnLkkMsYv511iXM6S1DeVUgn91Pd+wJVD?= =?us-ascii?Q?Zpml4RxBEqPbOLQvfHB2WJfKyTxEpOdGVpVyC0El29AFKDf2u7ByAHKCyLEw?= =?us-ascii?Q?CqH1H11g0LGixKKompsBDnSSbbgB6WsM43EYwsMLtlnI84b9HLSxwXcbJrtn?= =?us-ascii?Q?mowQ1+YveGU9JPOkZMN0fhBQXOLKpQD0vtuYYTIkZprUp2jLy2WfFYYCvBiy?= =?us-ascii?Q?otvG+wU1AMr+xwKQuULF8WxvtKZDwRd1Nh8zbRALxneXiaC3pYqWaCMeQ18V?= =?us-ascii?Q?hD6mwxSafApqr37bEKrTeX2kxVh5hoFzck73+G1y?= Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-OriginatorOrg: marvell.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: PH0PR18MB4086.namprd18.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: acdbe4c3-dfe4-4e7d-4f9b-08dc36965a29 X-MS-Exchange-CrossTenant-originalarrivaltime: 26 Feb 2024 06:44:16.5360 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 70e1fb47-1155-421d-87fc-2e58f638b6e0 X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: lMJNUIHQoZhAHklnB7E0nTPDNM58q1NYhR4aP2Jch3pJMBf16GbTZZICLYtmHz2WoRCVk/yftR1pb9fK1objSkFWaU8QrnRO4EY9/VTHpIs= X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH0PR18MB3831 X-Proofpoint-ORIG-GUID: DTNFdQWfF2ZSCZSwj6UBE8onLN-juU87 X-Proofpoint-GUID: DTNFdQWfF2ZSCZSwj6UBE8onLN-juU87 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.272,Aquarius:18.0.1011,Hydra:6.0.619,FMLib:17.11.176.26 definitions=2024-02-26_03,2024-02-23_01,2023-05-22_02 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. >=20 > Signed-off-by: Bruce Richardson Acked-by: Pavan Nikhilesh >=20 > --- > V3: add missing "." on end of sentences/lines. > --- > lib/eventdev/rte_eventdev.h | 47 +++++++++++++++++++++++-------------- > 1 file changed, 29 insertions(+), 18 deletions(-) >=20 > diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h > index e38354cedd..72814719b2 100644 > --- a/lib/eventdev/rte_eventdev.h > +++ b/lib/eventdev/rte_eventdev.h > @@ -1201,19 +1201,21 @@ rte_event_port_quiesce(uint8_t dev_id, uint8_t > port_id, > rte_eventdev_port_flush_t release_cb, void *args); >=20 > /** > - * 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 b= e > 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 p= ort. > */ > #define RTE_EVENT_PORT_ATTR_IMPLICIT_RELEASE_DISABLE 3 >=20 > @@ -1221,17 +1223,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 succes= sful > * > * @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_i= d, > @@ -1240,17 +1243,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 eve= nt > - * queues to start accepting the events and schedules to event ports. > + * The device start step is the last one in device setup, and enables th= e event > + * ports and queues to start accepting events and scheduling them to eve= nt > 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 > @@ -1292,18 +1297,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 passe= d in. > + * > * To unregister a callback, call this function with a NULL callback poi= nter. > * > * @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() > */ > @@ -1314,12 +1323,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); > -- > 2.40.1