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 365C643A40; Wed, 7 Feb 2024 11:15:06 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id EF8B040279; Wed, 7 Feb 2024 11:15:05 +0100 (CET) Received: from mail-qk1-f174.google.com (mail-qk1-f174.google.com [209.85.222.174]) by mails.dpdk.org (Postfix) with ESMTP id 9B56C4021D for ; Wed, 7 Feb 2024 11:15:04 +0100 (CET) Received: by mail-qk1-f174.google.com with SMTP id af79cd13be357-783fa618997so24704885a.0 for ; Wed, 07 Feb 2024 02:15:04 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1707300904; x=1707905704; darn=dpdk.org; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=gdMU7gs07c8NglIatmoDdTb0n4edkhIVyIt2ntGiFzI=; b=lR3XIHCMGNxTfy5dLhRpXzNFqta2QjPkMTrhtcC/Tn43YNoHSG6a/mrULmU5zFEBRl EMTMT+F1yafg4yxjXCvfMi8A+3eU9DDQig8GZOU9xkqNyhef4tSA1rFIZ9RvzvgeVGEi zA+Rxruc4gFVe5oClZB9UfuNnUQp5XmwVZRrUBeTCDS3fe5XvjekR0LwHnjGcc+pm6p0 5JieMFa8a/8IPmDv85fXodNXwrjzby2Qjsi/0zYxtPWCatlLc5lgWG8n3UC8hqPwvKEz NyZ9PNv6vp7esUaAsjd12/2Bi+JoOHUk/qM3HWASl+n7YqlNDncXPJovGgeUFDBpRmKM NXtw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1707300904; x=1707905704; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=gdMU7gs07c8NglIatmoDdTb0n4edkhIVyIt2ntGiFzI=; b=LO/p+JzEPsBSPgWRKwCDAGEA93sbcmm/Ej2uRShdXqpE3L4OqoRb2PMYizIwmMEFO1 udjctF+x3IijuYI7izd+Oy1QP55shNf5zYqR+hann600480nHSYU+B+Uv2xeXbul9qOC 26I33jMJd91Ck/mUqWfjZhCsTGdq4r3KtARxKadHG82LWRReMHy2UlSxfqze5DO/1N9I k/AixrZZH+isGyn098yagXcTBGuIrJqXXjoCVc7yc2m8KZULETUT2392ePp7g5tcQs9K FMHytToOk49Z0ILQxZetgKJknOEJlZ153md1fVx0gp9tzs7ys/z9tK2axqJe+VFIoPZB Gi4w== X-Gm-Message-State: AOJu0Yyom4HqsGT+bV8+Rnt4PNU9aACIYrgyial0SW7h6VjKwtugxj43 pcI1kSQCy0QErZBjJwFKAAQE71MUcwKz/cdRJen9E3G5gscLzz4MGZAjInzFsPy9YQ0JNXA2XIc KSgT/6yhKUOvCjC6NB0301UMoyzU= X-Google-Smtp-Source: AGHT+IGp7IR1O6b13IAUEk0ZIUcEOM3SjD/yWp4su8k2sKH6xy6poP3ntIpmeeeUqB1qHVcVQpZZlxVLMGbV8hXPGeI= X-Received: by 2002:a05:620a:2792:b0:785:9402:5536 with SMTP id g18-20020a05620a279200b0078594025536mr4238238qkp.24.1707300903769; Wed, 07 Feb 2024 02:15:03 -0800 (PST) MIME-Version: 1.0 References: <20240119174346.108905-1-bruce.richardson@intel.com> <20240202123953.77166-1-bruce.richardson@intel.com> <20240202123953.77166-2-bruce.richardson@intel.com> In-Reply-To: <20240202123953.77166-2-bruce.richardson@intel.com> From: Jerin Jacob Date: Wed, 7 Feb 2024 15:44:37 +0530 Message-ID: Subject: Re: [PATCH v3 01/11] eventdev: improve doxygen introduction text To: Bruce Richardson Cc: dev@dpdk.org, 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 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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 Fri, Feb 2, 2024 at 7:29=E2=80=AFPM Bruce Richardson wrote: > > Make some textual improvements to the introduction to eventdev and event > devices in the eventdev header file. This text appears in the doxygen > output for the header file, and introduces the key concepts, for > example: events, event devices, queues, ports and scheduling. > > This patch makes the following improvements: > * small textual fixups, e.g. correcting use of singular/plural > * rewrites of some sentences to improve clarity > * using doxygen markdown to split the whole large block up into > sections, thereby making it easier to read. > > No large-scale changes are made, and blocks are not reordered > > Signed-off-by: Bruce Richardson Thanks Bruce, While you are cleaning up, Please add following or similar change to fix for not properly parsing the struct rte_event_vector. i.e it is coming as global variables in html files. l[dpdk.org] $ git diff diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h index e31c927905..ce4a195a8f 100644 --- a/lib/eventdev/rte_eventdev.h +++ b/lib/eventdev/rte_eventdev.h @@ -1309,9 +1309,9 @@ struct rte_event_vector { */ struct { uint16_t port; - /* Ethernet device port id. */ + /**< Ethernet device port id. */ uint16_t queue; - /* Ethernet device queue id. */ + /**< Ethernet device queue id. */ }; }; /**< Union to hold common attributes of the vector array. */ @@ -1340,7 +1340,11 @@ struct rte_event_vector { * vector array can be an array of mbufs or pointers or opaque u64 * values. */ +#ifndef __DOXYGEN__ } __rte_aligned(16); +#else +}; +#endif /* Scheduler type definitions */ #define RTE_SCHED_TYPE_ORDERED 0 > > --- > V3: reworked following feedback from Mattias > --- > lib/eventdev/rte_eventdev.h | 132 ++++++++++++++++++++++-------------- > 1 file changed, 81 insertions(+), 51 deletions(-) > > diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h > index ec9b02455d..a741832e8e 100644 > --- a/lib/eventdev/rte_eventdev.h > +++ b/lib/eventdev/rte_eventdev.h > @@ -12,25 +12,33 @@ > * @file > * > * RTE Event Device API > + * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > * > - * In a polling model, lcores poll ethdev ports and associated rx queues > - * directly to look for packet. In an event driven model, by contrast, l= cores > - * call the scheduler that selects packets for them based on programmer > - * specified criteria. Eventdev library adds support for event driven > - * programming model, which offer applications automatic multicore scali= ng, > - * dynamic load balancing, pipelining, packet ingress order maintenance = and > - * synchronization services to simplify application packet processing. > + * In a traditional run-to-completion application model, lcores pick up = packets Can we keep it is as poll mode instead of run-to-completion as event mode a= lso supports run to completion by having dequuee() and then Tx. > + * from Ethdev ports and associated RX queues, run the packet processing= to completion, > + * and enqueue the completed packets to a TX queue. NIC-level receive-si= de scaling (RSS) > + * may be used to balance the load across multiple CPU cores. > + * > + * In contrast, in an event-driver model, as supported by this "eventdev= " library, > + * incoming packets are fed into an event device, which schedules those = packets across packets -> events. We may need to bring in Rx adapter if the event is packe= t. > + * the available lcores, in accordance with its configuration. > + * This event-driven programming model offers applications automatic mul= ticore scaling, > + * dynamic load balancing, pipelining, packet order maintenance, synchro= nization, > + * and prioritization/quality of service. > * > * The Event Device API is composed of two parts: > * > * - The application-oriented Event API that includes functions to setup > * an event device (configure it, setup its queues, ports and start it= ), to > - * establish the link between queues to port and to receive events, an= d so on. > + * establish the links between queues and ports to receive events, and= so on. > * > * - The driver-oriented Event API that exports a function allowing > - * an event poll Mode Driver (PMD) to simultaneously register itself a= s > + * an event poll Mode Driver (PMD) to register itself as > * an event device driver. > * > + * Application-oriented Event API > + * ------------------------------ > + * > * Event device components: > * > * +-----------------+ > @@ -75,27 +83,39 @@ > * | = | > * +---------------------------------------------------------= --+ > * > - * Event device: A hardware or software-based event scheduler. > + * **Event device**: A hardware or software-based event scheduler. > * > - * Event: A unit of scheduling that encapsulates a packet or other datat= ype > - * like SW generated event from the CPU, Crypto work completion notifica= tion, > - * Timer expiry event notification etc as well as metadata. > - * The metadata includes flow ID, scheduling type, event priority, event= _type, > - * sub_event_type etc. > + * **Event**: Represents an item of work and is the smallest unit of sch= eduling. > + * An event carries metadata, such as queue ID, scheduling type, and eve= nt priority, > + * and data such as one or more packets or other kinds of buffers. > + * Some examples of events are: > + * - a software-generated item of work originating from a lcore, lcore. > + * perhaps carrying a packet to be processed, processed. > + * - a crypto work completion notification notification. > + * - a timer expiry notification. > * > - * Event queue: A queue containing events that are scheduled by the even= t dev. > + * **Event queue**: A queue containing events that are scheduled by the = event device. Shouldn't we add "to be" or so? i.e A queue containing events that are to be scheduled by the event device. > * An event queue contains events of different flows associated with sch= eduling > * types, such as atomic, ordered, or parallel. > + * Each event given to an event device must have a valid event queue id = field in the metadata, > + * to specify on which event queue in the device the event must be place= d, > + * for later scheduling. > * > - * Event port: An application's interface into the event dev for enqueue= and > + * **Event port**: An application's interface into the event dev for enq= ueue and > * dequeue operations. Each event port can be linked with one or more > * event queues for dequeue operations. > - * > - * By default, all the functions of the Event Device API exported by a P= MD > - * are lock-free functions which assume to not be invoked in parallel on > - * different logical cores to work on the same target object. For instan= ce, > - * the dequeue function of a PMD cannot be invoked in parallel on two lo= gical > - * cores to operates on same event port. Of course, this function > + * Enqueue and dequeue from a port is not thread-safe, and the expected = use-case is > + * that each port is polled by only a single lcore. [If this is not the = case, > + * a suitable synchronization mechanism should be used to prevent simult= aneous > + * access from multiple lcores.] > + * To schedule events to an lcore, the event device will schedule them t= o the event port(s) > + * being polled by that lcore. > + * > + * *NOTE*: By default, all the functions of the Event Device API exporte= d by a PMD > + * are non-thread-safe functions, which must not be invoked on the same = object in parallel on > + * different logical cores. > + * For instance, the dequeue function of a PMD cannot be invoked in para= llel on two logical > + * cores to operate on same event port. Of course, this function > * can be invoked in parallel by different logical cores on different po= rts. > * It is the responsibility of the upper level application to enforce th= is rule. > * > @@ -107,22 +127,19 @@ > * > * Event devices are dynamically registered during the PCI/SoC device pr= obing > * phase performed at EAL initialization time. > - * When an Event device is being probed, a *rte_event_dev* structure and > - * a new device identifier are allocated for that device. Then, the > - * event_dev_init() function supplied by the Event driver matching the p= robed > - * device is invoked to properly initialize the device. > + * When an Event device is being probed, an *rte_event_dev* structure is= allocated > + * for it and the event_dev_init() function supplied by the Event driver > + * is invoked to properly initialize the device. > * > - * The role of the device init function consists of resetting the hardwa= re or > - * software event driver implementations. > + * The role of the device init function is to reset the device hardware = or > + * to initialize the software event driver implementation. > * > - * If the device init operation is successful, the correspondence betwee= n > - * the device identifier assigned to the new device and its associated > - * *rte_event_dev* structure is effectively registered. > - * Otherwise, both the *rte_event_dev* structure and the device identifi= er are > - * freed. > + * If the device init operation is successful, the device is assigned a = device > + * id (dev_id) for application use. > + * Otherwise, the *rte_event_dev* structure is freed. > * > * The functions exported by the application Event API to setup a device > - * designated by its device identifier must be invoked in the following = order: > + * must be invoked in the following order: > * - rte_event_dev_configure() > * - rte_event_queue_setup() > * - rte_event_port_setup() > @@ -130,10 +147,15 @@ > * - rte_event_dev_start() > * > * Then, the application can invoke, in any order, the functions > - * exported by the Event API to schedule events, dequeue events, enqueue= events, > - * change event queue(s) to event port [un]link establishment and so on. > - * > - * Application may use rte_event_[queue/port]_default_conf_get() to get = the > + * exported by the Event API to dequeue events, enqueue events, > + * and link and unlink event queue(s) to event ports. > + * > + * Before configuring a device, an application should call rte_event_dev= _info_get() > + * to determine the capabilities of the event device, and any queue or p= ort > + * limits of that device. The parameters set in the various device confi= guration > + * structures may need to be adjusted based on the max values provided i= n the > + * device information structure returned from the info_get API. Can we add full name of info_get()?