From patchwork Fri Jun 21 02:32:46 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Nandini Persad X-Patchwork-Id: 141464 X-Patchwork-Delegate: thomas@monjalon.net 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 0C9B6454B2; Fri, 21 Jun 2024 04:33:06 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id F24AA40265; Fri, 21 Jun 2024 04:33:05 +0200 (CEST) Received: from mail-oi1-f177.google.com (mail-oi1-f177.google.com [209.85.167.177]) by mails.dpdk.org (Postfix) with ESMTP id EFF6B4025E for ; Fri, 21 Jun 2024 04:33:03 +0200 (CEST) Received: by mail-oi1-f177.google.com with SMTP id 5614622812f47-3d361cf5755so887494b6e.2 for ; Thu, 20 Jun 2024 19:33:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1718937183; x=1719541983; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=YVBa7D8i6YtKq0cNiJGcnYiCxhtVL+0owcbRAnwS2XE=; b=KIsg64H9AfXU9hU8r2j9IKLW7Pdam7WoIPEHQ7XfLoYqHAtyJtLXJNY2Jq7Ax4kr5D eoYeAU1JKjf0Y7HXAbrpkTfw+YtsoQv/WdlvSPxBTHq8rTF4hJ5TdOwv4BFjtHyh8xkb UJBIPxtPO2PuhuZuHSAAXuk/7PGPS3198h504uZohZkp6XXUYkU9xZ6MnURlbiJLIXr9 0GlpE9FteUgn0QrfmwnHX0r2SOzYHEyKJRZcUdUKhw76A5g8hlJYC5/nxS8Y4Gz9vqXj wfcwpvXV/PKiwanN7T+Q5+nXF1fSUtDthwTUDGTukjxWQpMIcYFTvXiL3PIhrdedLxzX 1GgA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718937183; x=1719541983; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=YVBa7D8i6YtKq0cNiJGcnYiCxhtVL+0owcbRAnwS2XE=; b=uYkBrxXZX4P9sL5L+WvRNtNPpQKXwfD15nMNxn9s3U3CiEDlr3eZ27ukuSkCW6iD81 xv7wCHKSXJlfrkJaBjYcEtoQUq/KxAEaUYdLNbM4EbEmjg7HAtcOENz0+nDT41Gox6r6 HK9r7pIxoYmT7mUh185SFh5LnCc6eAYqSiHLavLOKLDtQQdyF0DD7kHH0wcRiVk9gAiA zctoqQGcOEuAtwXsmKLa1PBtNYNiwzeiEM1c/1WChdILDdYl9P4FCn23nHhoNGxUMT9t EUHvOwaWYge5EmLAPc/+pYWzYUDGVNY66ZCdI/su4eqzBxNt/8a/sIJB/I+0Z+5LPKGi 94sA== X-Gm-Message-State: AOJu0Yych9FKTfaDIXpk6LoQuGcXK2rFAm9E9S4F8W8pbDNybPH5Dwih aIFDQZPFScIulGHWKFoYA+Ip6OXEmdH4TLJNa8tyGgX5LuWrJvpihLvLwr7r X-Google-Smtp-Source: AGHT+IE+ywqWeTV0ivT2fmCPBp5wdwcw8hPupQCI9a5MFmbhAQjyVeQm4Y8AJ/rMeQmnGVfAA4EbGg== X-Received: by 2002:a05:6808:f04:b0:3d2:4f9f:f5c5 with SMTP id 5614622812f47-3d51baf718cmr8084108b6e.59.1718937182245; Thu, 20 Jun 2024 19:33:02 -0700 (PDT) Received: from localhost.localdomain (syn-076-032-089-124.res.spectrum.com. [76.32.89.124]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-7065124df73sm334482b3a.110.2024.06.20.19.33.01 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Jun 2024 19:33:01 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Subject: [PATCH v2 1/9] doc: reword pmd section in prog guide Date: Thu, 20 Jun 2024 19:32:46 -0700 Message-Id: <20240621023254.4258-1-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240513155911.31872-1-nandinipersad361@gmail.com> References: <20240513155911.31872-1-nandinipersad361@gmail.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 I made edits for syntax/grammar the PMD section of the prog guide. Signed-off-by: Nandini Persad Acked-by: Stephen Hemminger --- doc/guides/prog_guide/poll_mode_drv.rst | 151 ++++++++++++------------ 1 file changed, 73 insertions(+), 78 deletions(-) diff --git a/doc/guides/prog_guide/poll_mode_drv.rst b/doc/guides/prog_guide/poll_mode_drv.rst index 5008b41c60..360af20900 100644 --- a/doc/guides/prog_guide/poll_mode_drv.rst +++ b/doc/guides/prog_guide/poll_mode_drv.rst @@ -6,25 +6,24 @@ Poll Mode Driver ================ -The DPDK includes 1 Gigabit, 10 Gigabit and 40 Gigabit and para virtualized virtio Poll Mode Drivers. +The DPDK includes 1 Gigabit, 10 Gigabit, 40 Gigabit and para virtualized virtio Poll Mode Drivers. -A Poll Mode Driver (PMD) consists of APIs, provided through the BSD driver running in user space, -to configure the devices and their respective queues. +A Poll Mode Driver (PMD) consists of APIs (provided through the BSD driver running in user space) to configure the devices and their respective queues. In addition, a PMD accesses the RX and TX descriptors directly without any interrupts (with the exception of Link Status Change interrupts) to quickly receive, process and deliver packets in the user's application. -This section describes the requirements of the PMDs, -their global design principles and proposes a high-level architecture and a generic external API for the Ethernet PMDs. +This section describes the requirements of the PMDs and +their global design principles. It also proposes a high-level architecture and a generic external API for the Ethernet PMDs. Requirements and Assumptions ---------------------------- The DPDK environment for packet processing applications allows for two models, run-to-completion and pipe-line: -* In the *run-to-completion* model, a specific port's RX descriptor ring is polled for packets through an API. - Packets are then processed on the same core and placed on a port's TX descriptor ring through an API for transmission. +* In the *run-to-completion* model, a specific port's Rx descriptor ring is polled for packets through an API. + Packets are then processed on the same core and placed on a port's Tx descriptor ring through an API for transmission. -* In the *pipe-line* model, one core polls one or more port's RX descriptor ring through an API. +* In the *pipe-line* model, one core polls one or more port's Rx descriptor ring through an API. Packets are received and passed to another core via a ring. The other core continues to process the packet which then may be placed on a port's TX descriptor ring through an API for transmission. @@ -50,14 +49,14 @@ The loop for packet processing includes the following steps: * Retrieve the received packet from the packet queue -* Process the received packet, up to its retransmission if forwarded +* Process the received packet up to its retransmission if forwarded To avoid any unnecessary interrupt processing overhead, the execution environment must not use any asynchronous notification mechanisms. Whenever needed and appropriate, asynchronous communication should be introduced as much as possible through the use of rings. Avoiding lock contention is a key issue in a multi-core environment. -To address this issue, PMDs are designed to work with per-core private resources as much as possible. -For example, a PMD maintains a separate transmit queue per-core, per-port, if the PMD is not ``RTE_ETH_TX_OFFLOAD_MT_LOCKFREE`` capable. +To address this issue, PMDs are designed to work with per core private resources as much as possible. +For example, a PMD maintains a separate transmit queue per core, per port, if the PMD is not ``RTE_ETH_TX_OFFLOAD_MT_LOCKFREE`` capable. In the same way, every receive queue of a port is assigned to and polled by a single logical core (lcore). To comply with Non-Uniform Memory Access (NUMA), memory management is designed to assign to each logical core @@ -101,9 +100,9 @@ However, an rte_eth_tx_burst function is effectively implemented by the PMD to m * Apply burst-oriented software optimization techniques to remove operations that would otherwise be unavoidable, such as ring index wrap back management. -Burst-oriented functions are also introduced via the API for services that are intensively used by the PMD. +Burst-oriented functions are also introduced via the API for services that are extensively used by the PMD. This applies in particular to buffer allocators used to populate NIC rings, which provide functions to allocate/free several buffers at a time. -For example, an mbuf_multiple_alloc function returning an array of pointers to rte_mbuf buffers which speeds up the receive poll function of the PMD when +An example of this would be an mbuf_multiple_alloc function returning an array of pointers to rte_mbuf buffers which speeds up the receive poll function of the PMD when replenishing multiple descriptors of the receive ring. Logical Cores, Memory and NIC Queues Relationships @@ -111,7 +110,7 @@ Logical Cores, Memory and NIC Queues Relationships The DPDK supports NUMA allowing for better performance when a processor's logical cores and interfaces utilize its local memory. Therefore, mbuf allocation associated with local PCIe* interfaces should be allocated from memory pools created in the local memory. -The buffers should, if possible, remain on the local processor to obtain the best performance results and RX and TX buffer descriptors +The buffers should, if possible, remain on the local processor to obtain the best performance results and Rx and Tx buffer descriptors should be populated with mbufs allocated from a mempool allocated from local memory. The run-to-completion model also performs better if packet or data manipulation is in local memory instead of a remote processors memory. @@ -120,12 +119,11 @@ This is also true for the pipe-line model provided all logical cores used are lo Multiple logical cores should never share receive or transmit queues for interfaces since this would require global locks and hinder performance. If the PMD is ``RTE_ETH_TX_OFFLOAD_MT_LOCKFREE`` capable, multiple threads can invoke ``rte_eth_tx_burst()`` -concurrently on the same tx queue without SW lock. This PMD feature found in some NICs and useful in the following use cases: +concurrently on the same Tx queue without an SW lock. This PMD feature found in some NICs is useful for: -* Remove explicit spinlock in some applications where lcores are not mapped to Tx queues with 1:1 relation. +* Removing explicit spinlock in some applications where lcores are not mapped to Tx queues with 1:1 relation. -* In the eventdev use case, avoid dedicating a separate TX core for transmitting and thus - enables more scaling as all workers can send the packets. +* Enabling greater scalability by removing the requirement to have a dedicated Tx core See `Hardware Offload`_ for ``RTE_ETH_TX_OFFLOAD_MT_LOCKFREE`` capability probing details. @@ -135,8 +133,8 @@ Device Identification, Ownership and Configuration Device Identification ~~~~~~~~~~~~~~~~~~~~~ -Each NIC port is uniquely designated by its (bus/bridge, device, function) PCI -identifiers assigned by the PCI probing/enumeration function executed at DPDK initialization. +Each NIC port is uniquely designated by its PCI +identifiers (bus/bridge, device, function) assigned by the PCI probing/enumeration function executed at DPDK initialization. Based on their PCI identifier, NIC ports are assigned two other identifiers: * A port index used to designate the NIC port in all functions exported by the PMD API. @@ -149,14 +147,13 @@ Port Ownership The Ethernet devices ports can be owned by a single DPDK entity (application, library, PMD, process, etc). The ownership mechanism is controlled by ethdev APIs and allows to set/remove/get a port owner by DPDK entities. -It prevents Ethernet ports to be managed by different entities. +This prevents Ethernet ports from being managed by different entities. .. note:: - It is the DPDK entity responsibility to set the port owner before using it and to manage the port usage synchronization between different threads or processes. + It is the DPDK entity responsibility to set the port owner before using the port and to manage the port usage synchronization between different threads or processes. -It is recommended to set port ownership early, -like during the probing notification ``RTE_ETH_EVENT_NEW``. +It is recommended to set port ownership early. For instance, during the probing notification ``RTE_ETH_EVENT_NEW``. Device Configuration ~~~~~~~~~~~~~~~~~~~~ @@ -165,7 +162,7 @@ The configuration of each NIC port includes the following operations: * Allocate PCI resources -* Reset the hardware (issue a Global Reset) to a well-known default state +* Reset the hardware to a well-known default state (issue a Global Reset) * Set up the PHY and the link @@ -174,7 +171,7 @@ The configuration of each NIC port includes the following operations: The PMD API must also export functions to start/stop the all-multicast feature of a port and functions to set/unset the port in promiscuous mode. Some hardware offload features must be individually configured at port initialization through specific configuration parameters. -This is the case for the Receive Side Scaling (RSS) and Data Center Bridging (DCB) features for example. +This is the case for the Receive Side Scaling (RSS) and Data Center Bridging (DCB) features. On-the-Fly Configuration ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -210,7 +207,7 @@ Each transmit queue is independently configured with the following information: * The *minimum* transmit packets to free threshold (tx_free_thresh). When the number of descriptors used to transmit packets exceeds this threshold, the network adaptor should be checked to see if it has written back descriptors. - A value of 0 can be passed during the TX queue configuration to indicate the default value should be used. + A value of 0 can be passed during the Tx queue configuration to indicate the default value should be used. The default value for tx_free_thresh is 32. This ensures that the PMD does not search for completed descriptors until at least 32 have been processed by the NIC for this queue. @@ -222,7 +219,7 @@ Each transmit queue is independently configured with the following information: A value of 0 can be passed during the TX queue configuration to indicate that the default value should be used. The default value for tx_rs_thresh is 32. This ensures that at least 32 descriptors are used before the network adapter writes back the most recently used descriptor. - This saves upstream PCIe* bandwidth resulting from TX descriptor write-backs. + This saves upstream PCIe* bandwidth resulting from Tx descriptor write-backs. It is important to note that the TX Write-back threshold (TX wthresh) should be set to 0 when tx_rs_thresh is greater than 1. Refer to the Intel® 82599 10 Gigabit Ethernet Controller Datasheet for more details. @@ -244,7 +241,7 @@ One descriptor in the TX ring is used as a sentinel to avoid a hardware race con .. note:: - When configuring for DCB operation, at port initialization, both the number of transmit queues and the number of receive queues must be set to 128. + When configuring for DCB operation at port initialization, both the number of transmit queues and the number of receive queues must be set to 128. Free Tx mbuf on Demand ~~~~~~~~~~~~~~~~~~~~~~ @@ -265,7 +262,7 @@ There are two scenarios when an application may want the mbuf released immediate One option is to make a copy of the packet or a copy of the header portion that needs to be manipulated. A second option is to transmit the packet and then poll the ``rte_eth_tx_done_cleanup()`` API until the reference count on the packet is decremented. - Then the same packet can be transmitted to the next destination interface. + Then, the same packet can be transmitted to the next destination interface. The application is still responsible for managing any packet manipulations needed between the different destination interfaces, but a packet copy can be avoided. This API is independent of whether the packet was transmitted or dropped, @@ -288,13 +285,13 @@ Hardware Offload Depending on driver capabilities advertised by ``rte_eth_dev_info_get()``, the PMD may support hardware offloading feature like checksumming, TCP segmentation, VLAN insertion or -lockfree multithreaded TX burst on the same TX queue. +lockfree multithreaded Tx burst on the same Tx queue. The support of these offload features implies the addition of dedicated status bit(s) and value field(s) into the rte_mbuf data structure, along with their appropriate handling by the receive/transmit functions exported by each PMD. The list of flags and their precise meaning is -described in the mbuf API documentation and in the in :ref:`Mbuf Library +described in the mbuf API documentation and in the :ref:`Mbuf Library `, section "Meta Information". Per-Port and Per-Queue Offloads @@ -303,14 +300,14 @@ Per-Port and Per-Queue Offloads In the DPDK offload API, offloads are divided into per-port and per-queue offloads as follows: * A per-queue offloading can be enabled on a queue and disabled on another queue at the same time. -* A pure per-port offload is the one supported by device but not per-queue type. -* A pure per-port offloading can't be enabled on a queue and disabled on another queue at the same time. +* A pure per-port offload is supported by a device but not per-queue type. +* A pure per-port offloading cannot be enabled on a queue and disabled on another queue at the same time. * A pure per-port offloading must be enabled or disabled on all queues at the same time. -* Any offloading is per-queue or pure per-port type, but can't be both types at same devices. +* Offloading is per-queue or pure per-port type, but cannot be both types on the same devices. * Port capabilities = per-queue capabilities + pure per-port capabilities. * Any supported offloading can be enabled on all queues. -The different offloads capabilities can be queried using ``rte_eth_dev_info_get()``. +The different offload capabilities can be queried using ``rte_eth_dev_info_get()``. The ``dev_info->[rt]x_queue_offload_capa`` returned from ``rte_eth_dev_info_get()`` includes all per-queue offloading capabilities. The ``dev_info->[rt]x_offload_capa`` returned from ``rte_eth_dev_info_get()`` includes all pure per-port and per-queue offloading capabilities. Supported offloads can be either per-port or per-queue. @@ -329,8 +326,8 @@ per-port type and no matter whether it is set or cleared in If a per-queue offloading hasn't been enabled in ``rte_eth_dev_configure()``, it can be enabled or disabled in ``rte_eth_[rt]x_queue_setup()`` for individual queue. A newly added offloads in ``[rt]x_conf->offloads`` to ``rte_eth_[rt]x_queue_setup()`` input by application -is the one which hasn't been enabled in ``rte_eth_dev_configure()`` and is requested to be enabled -in ``rte_eth_[rt]x_queue_setup()``. It must be per-queue type, otherwise trigger an error log. +is the one that hasn't been enabled in ``rte_eth_dev_configure()`` and is requested to be enabled +in ``rte_eth_[rt]x_queue_setup()``. It must be per-queue type, otherwise an error log will be triggered. Poll Mode Driver API -------------------- @@ -340,8 +337,8 @@ Generalities By default, all functions exported by a PMD are lock-free functions that are assumed not to be invoked in parallel on different logical cores to work on the same target object. -For instance, a PMD receive function cannot be invoked in parallel on two logical cores to poll the same RX queue of the same port. -Of course, this function can be invoked in parallel by different logical cores on different RX queues. +For instance, a PMD receive function cannot be invoked in parallel on two logical cores to poll the same Rx queue of the same port. +This function can be invoked in parallel by different logical cores on different Rx queues. It is the responsibility of the upper-level application to enforce this rule. If needed, parallel accesses by multiple logical cores to shared queues can be explicitly protected by dedicated inline lock-aware functions @@ -357,7 +354,7 @@ The rte_mbuf data structure includes specific fields to represent, in a generic For an input packet, most fields of the rte_mbuf structure are filled in by the PMD receive function with the information contained in the receive descriptor. Conversely, for output packets, most fields of rte_mbuf structures are used by the PMD transmit function to initialize transmit descriptors. -The mbuf structure is fully described in the :ref:`Mbuf Library ` chapter. +The mbuf structure is described in depth in the :ref:`Mbuf Library ` chapter. Ethernet Device API ~~~~~~~~~~~~~~~~~~~ @@ -370,12 +367,12 @@ Ethernet Device Standard Device Arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Standard Ethernet device arguments allow for a set of commonly used arguments/ -parameters which are applicable to all Ethernet devices to be available to for -specification of specific device and for passing common configuration +parameters applicable to all Ethernet devices. These arguments/parameters are available for +specification of specific devices and passing common configuration parameters to those ports. -* ``representor`` for a device which supports the creation of representor ports - this argument allows user to specify which switch ports to enable port +* Use ``representor`` for a device which supports the creation of representor ports. + This argument allows user to specify which switch ports to enable port representors for:: -a DBDF,representor=vf0 @@ -392,7 +389,7 @@ parameters to those ports. -a DBDF,representor=[pf[0-1],pf2vf[0-2],pf3[3,5-8]] (Multiple representors in one device argument can be represented as a list) -Note: PMDs are not required to support the standard device arguments and users +Note: PMDs are not required to support the standard device arguments. Users should consult the relevant PMD documentation to see support devargs. Extended Statistics API @@ -402,9 +399,9 @@ The extended statistics API allows a PMD to expose all statistics that are available to it, including statistics that are unique to the device. Each statistic has three properties ``name``, ``id`` and ``value``: -* ``name``: A human readable string formatted by the scheme detailed below. +* ``name``: A human-readable string formatted by the scheme detailed below. * ``id``: An integer that represents only that statistic. -* ``value``: A unsigned 64-bit integer that is the value of the statistic. +* ``value``: An unsigned 64-bit integer that is the value of the statistic. Note that extended statistic identifiers are driver-specific, and hence might not be the same for different ports. @@ -439,7 +436,7 @@ associated with the receive side of the NIC. The second component ``packets`` indicates that the unit of measure is packets. A more complicated example: ``tx_size_128_to_255_packets``. In this example, -``tx`` indicates transmission, ``size`` is the first detail, ``128`` etc are +``tx`` indicates transmission, ``size`` is the first detail, ``128`` etc., are more details, and ``packets`` indicates that this is a packet counter. Some additions in the metadata scheme are as follows: @@ -466,8 +463,8 @@ lookup of specific statistics. Performant lookup means two things; The API ensures these requirements are met by mapping the ``name`` of the statistic to a unique ``id``, which is used as a key for lookup in the fast-path. The API allows applications to request an array of ``id`` values, so that the -PMD only performs the required calculations. Expected usage is that the -application scans the ``name`` of each statistic, and caches the ``id`` +PMD only performs the required calculations. The expected usage is that the +application scans the ``name`` of each statistic and caches the ``id`` if it has an interest in that statistic. On the fast-path, the integer can be used to retrieve the actual ``value`` of the statistic that the ``id`` represents. @@ -486,7 +483,7 @@ statistics. * ``rte_eth_xstats_get_by_id()``: Fills in an array of ``uint64_t`` values with matching the provided ``ids`` array. If the ``ids`` array is NULL, it - returns all statistics that are available. + returns all available statistics. Application Usage @@ -496,10 +493,10 @@ Imagine an application that wants to view the dropped packet count. If no packets are dropped, the application does not read any other metrics for performance reasons. If packets are dropped, the application has a particular set of statistics that it requests. This "set" of statistics allows the app to -decide what next steps to perform. The following code-snippets show how the +decide what next steps to perform. The following code snippets show how the xstats API can be used to achieve this goal. -First step is to get all statistics names and list them: +The first step is to get all statistics names and list them: .. code-block:: c @@ -545,7 +542,7 @@ First step is to get all statistics names and list them: The application has access to the names of all of the statistics that the PMD exposes. The application can decide which statistics are of interest, cache the -ids of those statistics by looking up the name as follows: +IDs of those statistics by looking up the name as follows: .. code-block:: c @@ -564,8 +561,7 @@ ids of those statistics by looking up the name as follows: The API provides flexibility to the application so that it can look up multiple statistics using an array containing multiple ``id`` numbers. This reduces the -function call overhead of retrieving statistics, and makes lookup of multiple -statistics simpler for the application. +function call overhead of retrieving statistics and simplifies the application's lookup of multiple statistics. .. code-block:: c @@ -585,8 +581,8 @@ statistics simpler for the application. This array lookup API for xstats allows the application create multiple "groups" of statistics, and look up the values of those IDs using a single API -call. As an end result, the application is able to achieve its goal of -monitoring a single statistic ("rx_errors" in this case), and if that shows +call. As an end result, the application can achieve its goal of +monitoring a single statistic (in this case,"rx_errors"). If that shows packets being dropped, it can easily retrieve a "set" of statistics using the IDs array parameter to ``rte_eth_xstats_get_by_id`` function. @@ -597,23 +593,23 @@ NIC Reset API int rte_eth_dev_reset(uint16_t port_id); -Sometimes a port has to be reset passively. For example when a PF is +There are times when a port has to be reset passively. For example, when a PF is reset, all its VFs should also be reset by the application to make them -consistent with the PF. A DPDK application also can call this function -to trigger a port reset. Normally, a DPDK application would invokes this +consistent with the PF. A DPDK application can also call this function +to trigger a port reset. Normally, a DPDK application would invoke this function when an RTE_ETH_EVENT_INTR_RESET event is detected. -It is the duty of the PMD to trigger RTE_ETH_EVENT_INTR_RESET events and -the application should register a callback function to handle these +The PMD's duty is to trigger RTE_ETH_EVENT_INTR_RESET events. +The application should register a callback function to handle these events. When a PMD needs to trigger a reset, it can trigger an RTE_ETH_EVENT_INTR_RESET event. On receiving an RTE_ETH_EVENT_INTR_RESET -event, applications can handle it as follows: Stop working queues, stop +event, applications can do as follows: Stop working queues, stop calling Rx and Tx functions, and then call rte_eth_dev_reset(). For thread safety all these operations should be called from the same thread. For example when PF is reset, the PF sends a message to notify VFs of -this event and also trigger an interrupt to VFs. Then in the interrupt -service routine the VFs detects this notification message and calls +this event and also trigger an interrupt to VFs. Then, in the interrupt +service routine, the VFs detects this notification message and calls rte_eth_dev_callback_process(dev, RTE_ETH_EVENT_INTR_RESET, NULL). This means that a PF reset triggers an RTE_ETH_EVENT_INTR_RESET event within VFs. The function rte_eth_dev_callback_process() will @@ -621,13 +617,12 @@ call the registered callback function. The callback function can trigger the application to handle all operations the VF reset requires including stopping Rx/Tx queues and calling rte_eth_dev_reset(). -The rte_eth_dev_reset() itself is a generic function which only does -some hardware reset operations through calling dev_unint() and -dev_init(), and itself does not handle synchronization, which is handled +The rte_eth_dev_reset() is a generic function that only does hardware reset operations through calling dev_unint() and +dev_init(). It does not handle synchronization, which is handled by application. The PMD itself should not call rte_eth_dev_reset(). The PMD can trigger -the application to handle reset event. It is duty of application to +the application to handle reset event. It is duty of the application to handle all synchronization before it calls rte_eth_dev_reset(). The above error handling mode is known as ``RTE_ETH_ERROR_HANDLE_MODE_PASSIVE``. @@ -635,15 +630,15 @@ The above error handling mode is known as ``RTE_ETH_ERROR_HANDLE_MODE_PASSIVE``. Proactive Error Handling Mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This mode is known as ``RTE_ETH_ERROR_HANDLE_MODE_PROACTIVE``, -different from the application invokes recovery in PASSIVE mode, -the PMD automatically recovers from error in PROACTIVE mode, +This mode is known as ``RTE_ETH_ERROR_HANDLE_MODE_PROACTIVE``, which is +different from the application invokes recovery in PASSIVE mode. +The PMD automatically recovers from error in PROACTIVE mode, and only a small amount of work is required for the application. During error detection and automatic recovery, the PMD sets the data path pointers to dummy functions (which will prevent the crash), -and also make sure the control path operations fail with a return code ``-EBUSY``. +and ensures sure the control path operations fail with a return code ``-EBUSY``. Because the PMD recovers automatically, the application can only sense that the data flow is disconnected for a while @@ -655,9 +650,9 @@ three events are available: ``RTE_ETH_EVENT_ERR_RECOVERING`` Notify the application that an error is detected - and the recovery is being started. + and the recovery is beginning. Upon receiving the event, the application should not invoke - any control path function until receiving + any control path function until receiving the ``RTE_ETH_EVENT_RECOVERY_SUCCESS`` or ``RTE_ETH_EVENT_RECOVERY_FAILED`` event. .. note:: @@ -667,7 +662,7 @@ three events are available: because a larger error may occur during the recovery. ``RTE_ETH_EVENT_RECOVERY_SUCCESS`` - Notify the application that the recovery from error is successful, + Notify the application that the recovery from the error was successful, the PMD already re-configures the port, and the effect is the same as a restart operation. From patchwork Fri Jun 21 02:32:47 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nandini Persad X-Patchwork-Id: 141465 X-Patchwork-Delegate: thomas@monjalon.net 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 88974454B2; Fri, 21 Jun 2024 04:33:22 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7D57942E7A; Fri, 21 Jun 2024 04:33:22 +0200 (CEST) Received: from mail-pf1-f182.google.com (mail-pf1-f182.google.com [209.85.210.182]) by mails.dpdk.org (Postfix) with ESMTP id 4A98F42E7A for ; Fri, 21 Jun 2024 04:33:20 +0200 (CEST) Received: by mail-pf1-f182.google.com with SMTP id d2e1a72fcca58-705bf368037so1394202b3a.0 for ; Thu, 20 Jun 2024 19:33:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1718937199; x=1719541999; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=hG5jPfxCs2cqf2u0yQ4c5/Wr1lNC/AZ4J8oIgNAwgow=; b=AAQMwy1T+tgKb063i2mwJ3qJhDyRATBM1kA0iKMT1cn/i7Ico3jPRYeuUw2pd0IAPe yooMMWQeMFNkDYnurs7lDwO3WUxYVbxHOrNDxQA/FZagGy5zk+36a+KPR/lqR2epeZ3a HEvY506tUO41BeFcjbWAjx0CyqyB9fYA079u02SRH7AOB+jxfvy4uQlYUPUDekGym/5O yHiKfaKQcm5/q0I+OdB1qTdY0UgGdz+YWxcnddx7VVaSmwUuM+ocOrNBZPKHrndUDv3d 16j8sJMNOgRqck4oAjCh1x/oR2adNchfb8U2c8ghXTbkZsHsdDwc2q6LInyHiCCf9wt1 wzgA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718937199; x=1719541999; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=hG5jPfxCs2cqf2u0yQ4c5/Wr1lNC/AZ4J8oIgNAwgow=; b=seca2uyI6KxPJvGnGj4wekC6uhdPY99vAayN5u9G141lElI+91f57pMUilXUELp6vd gcBA4tlwiL0Xs6oIbzmpYEby6wiOEFZCS3fUzgNUmqKkAbheJLvLgTvfC6fBgZ+zobOA z5awfY+tuYygLpCsuZrwOQvUPNOE7kjyO087AUxrNnezmfCyc8EPFFk+6rRyNnonZ3vB Jga5or8OIrcaIKAD5ZOp1fZaowyaJB84X8vEN+fmiWY+gWhFK5aOR1h6Rh1b2UBiAKRB 4YuKFam5col9WF4dCtS6NsqUIvJRF5ZgfAore7ytPhl6R/IOTdiDDr+ZgJCHQZBR7T+I 9g4Q== X-Gm-Message-State: AOJu0YyzYMwYvjTGTXKecrlUjjcFfN4/J5I1vBXzsa39yr/Idic6Pshl bF7R4A7p9k0JCRk4e+1AETDiPd0z03xHI6rf9gx5y81y2vcPZ1GqyrEpK96d X-Google-Smtp-Source: AGHT+IHDQjv2lqMGwSwNgl4UW0Oy2YtpE2GLxnyqSg4ux4+ZgKvznx6ukeXylQFx9PRZkfvdXTNmVA== X-Received: by 2002:a05:6a00:a93:b0:705:c273:d19 with SMTP id d2e1a72fcca58-70629c43067mr9174173b3a.12.1718937198980; Thu, 20 Jun 2024 19:33:18 -0700 (PDT) Received: from localhost.localdomain (syn-076-032-089-124.res.spectrum.com. [76.32.89.124]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-7065124df73sm334482b3a.110.2024.06.20.19.33.18 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Jun 2024 19:33:18 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Subject: [PATCH v2 2/9] doc: reword argparse section in prog guide Date: Thu, 20 Jun 2024 19:32:47 -0700 Message-Id: <20240621023254.4258-2-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240621023254.4258-1-nandinipersad361@gmail.com> References: <20240513155911.31872-1-nandinipersad361@gmail.com> <20240621023254.4258-1-nandinipersad361@gmail.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 I have made small edits for syntax in this section. Signed-off-by: Nandini Persad Acked-by: Stephen Hemminger --- doc/guides/prog_guide/argparse_lib.rst | 75 +++++++++++++------------- 1 file changed, 38 insertions(+), 37 deletions(-) diff --git a/doc/guides/prog_guide/argparse_lib.rst b/doc/guides/prog_guide/argparse_lib.rst index a6ac11b1c0..1acde60861 100644 --- a/doc/guides/prog_guide/argparse_lib.rst +++ b/doc/guides/prog_guide/argparse_lib.rst @@ -4,30 +4,31 @@ Argparse Library ================ -The argparse library provides argument parsing functionality, -this library makes it easy to write user-friendly command-line program. +The argparse library provides argument parsing functionality and makes it easy to write user-friendly command-line programming. Features and Capabilities ------------------------- -- Support parsing optional argument (which could take with no-value, - required-value and optional-value). +- Supports parsing of optional arguments (which can contain no-value, + required-value and optional-values). -- Support parsing positional argument (which must take with required-value). +- Supports parsing of positional arguments (which must contain required-values). -- Support automatic generate usage information. +- Supports automatic generation of usage information. -- Support issue errors when provide with invalid arguments. +- Provides issue errors when an argument is invalid + +- Supports parsing arguments in two ways: -- Support parsing argument by two ways: #. autosave: used for parsing known value types; #. callback: will invoke user callback to parse. + Usage Guide ----------- -The following code demonstrates how to use: +The following code demonstrates how to use the following: .. code-block:: C @@ -89,12 +90,12 @@ The following code demonstrates how to use: ... } -In this example, the arguments which start with a hyphen (-) are optional -arguments (they're "--aaa"/"--bbb"/"--ccc"/"--ddd"/"--eee"/"--fff"); and the -arguments which don't start with a hyphen (-) are positional arguments -(they're "ooo"/"ppp"). +In this example, the arguments thhat start with a hyphen (-) are optional +arguments ("--aaa"/"--bbb"/"--ccc"/"--ddd"/"--eee"/"--fff"). +The arguments that do not start with a hyphen (-) are positional arguments +("ooo"/"ppp"). -Every argument must be set whether to carry a value (one of +Every argument must set whether it carries a value (one of ``RTE_ARGPARSE_ARG_NO_VALUE``, ``RTE_ARGPARSE_ARG_REQUIRED_VALUE`` and ``RTE_ARGPARSE_ARG_OPTIONAL_VALUE``). @@ -105,26 +106,26 @@ Every argument must be set whether to carry a value (one of User Input Requirements ~~~~~~~~~~~~~~~~~~~~~~~ -For optional arguments which take no-value, +For optional arguments which have no-value, the following mode is supported (take above "--aaa" as an example): - The single mode: "--aaa" or "-a". -For optional arguments which take required-value, +For optional arguments which have required-value, the following two modes are supported (take above "--bbb" as an example): - The kv mode: "--bbb=1234" or "-b=1234". - The split mode: "--bbb 1234" or "-b 1234". -For optional arguments which take optional-value, +For optional arguments which have optional-value, the following two modes are supported (take above "--ccc" as an example): - The single mode: "--ccc" or "-c". - The kv mode: "--ccc=123" or "-c=123". -For positional arguments which must take required-value, +For positional arguments which must have required-value, their values are parsing in the order defined. .. note:: @@ -132,15 +133,15 @@ their values are parsing in the order defined. The compact mode is not supported. Take above "-a" and "-d" as an example, don't support "-ad" input. -Parsing by autosave way -~~~~~~~~~~~~~~~~~~~~~~~ +Parsing the Autosave Method +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Argument of known value type (e.g. ``RTE_ARGPARSE_ARG_VALUE_INT``) -could be parsed using this autosave way, -and its result will save in the ``val_saver`` field. +Arguments of a known value type (e.g. ``RTE_ARGPARSE_ARG_VALUE_INT``) +can be parsed using the autosave method, +The result will save in the ``val_saver`` field. In the above example, the arguments "--aaa"/"--bbb"/"--ccc" and "ooo" -both use this way, the parsing is as follows: +both use this method. The parsing is as follows: - For argument "--aaa", it is configured as no-value, so the ``aaa_val`` will be set to ``val_set`` field @@ -150,28 +151,28 @@ both use this way, the parsing is as follows: so the ``bbb_val`` will be set to user input's value (e.g. will be set to 1234 with input "--bbb 1234"). -- For argument "--ccc", it is configured as optional-value, - if user only input "--ccc" then the ``ccc_val`` will be set to ``val_set`` field +- For argument "--ccc", it is configured as optional-value. + If user only input "--ccc", then the ``ccc_val`` will be set to ``val_set`` field which is 200 in the above example; - if user input "--ccc=123", then the ``ccc_val`` will be set to 123. + If user input "--ccc=123", then the ``ccc_val`` will be set to 123. - For argument "ooo", it is positional argument, the ``ooo_val`` will be set to user input's value. -Parsing by callback way -~~~~~~~~~~~~~~~~~~~~~~~ +Parsing by Callback Method +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -It could also choose to use callback to parse, -just define a unique index for the argument -and make the ``val_save`` field to be NULL also zero value-type. +You may choose to use the callback method to parse. +To do so, define a unique index for the argument +and make the ``val_save`` field to be NULL as a zero value-type. -In the above example, the arguments "--ddd"/"--eee"/"--fff" and "ppp" both use this way. +In the above example, the arguments "--ddd"/"--eee"/"--fff" and "ppp" both use this method. -Multiple times argument +Multiple Times Argument ~~~~~~~~~~~~~~~~~~~~~~~ -If want to support the ability to enter the same argument multiple times, -then should mark ``RTE_ARGPARSE_ARG_SUPPORT_MULTI`` in the ``flags`` field. +If you want to support the ability to enter the same argument multiple times, +then you should mark ``RTE_ARGPARSE_ARG_SUPPORT_MULTI`` in the ``flags`` field. For example: .. code-block:: C @@ -182,5 +183,5 @@ Then the user input could contain multiple "--xyz" arguments. .. note:: - The multiple times argument only support with optional argument + The multiple times argument is only supported with optional argument and must be parsed by callback way. From patchwork Fri Jun 21 02:32:48 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nandini Persad X-Patchwork-Id: 141466 X-Patchwork-Delegate: thomas@monjalon.net 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 9E640454B2; Fri, 21 Jun 2024 04:33:27 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 8D8EA42E8F; Fri, 21 Jun 2024 04:33:27 +0200 (CEST) Received: from mail-oi1-f178.google.com (mail-oi1-f178.google.com [209.85.167.178]) by mails.dpdk.org (Postfix) with ESMTP id 5767642E8F for ; Fri, 21 Jun 2024 04:33:25 +0200 (CEST) Received: by mail-oi1-f178.google.com with SMTP id 5614622812f47-3c9c36db8eeso782360b6e.0 for ; Thu, 20 Jun 2024 19:33:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1718937204; x=1719542004; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=dfhcmhfGolSCM2wg3cPwl/FtSZxe2Df+dnNfG00WhVQ=; b=c60HY+yPTKlOKgAXrZ9RABnZDxJXJ9R8IatS6ua9vDHBXPM/89edwjLQoF05oNgEB1 CcpumuWKFHCQ316pvuXQXeEG3Xae1zIcclNMesFEMtg9lHJZwYtsrb+98VUqPGSfJjMf pFegc1H2ov275C696oizqCAM3dTR11hvGmBjXfVwDkrsEEIWFEekYOM5xs/w2ppJmcA2 s+PpFee0ue9dAIk4frZu4tukIuO9vHaRujHtFcbvnMY5AqOZ+/XskKKO3Ikw5A9LGEGz P4I1Sc9JhI5r8LeHABr1zqO/3BJ0vF6PViHf8tggVrXOW6GjPwGdBNgop/jHJF2vTaHz 9SPQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718937204; x=1719542004; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=dfhcmhfGolSCM2wg3cPwl/FtSZxe2Df+dnNfG00WhVQ=; b=N/Pgt3dAA17Tk0eJlsrUGyQzU3LfcngU+rjYOYYtBL7Xpg9KXgMP+So5q9bSk6Zyyy Soc1zT7dfjRKBoGA9eZp8IK5CYGG8Qujcqu/erLUaxBAmMwgwIXqKRv+BK42VX7/+ZIK y2uZ1QIWMNTV93F0uEYNqJNcpTIJc3yhHu0WuVM16v0IifOUHVJAm/AUuWnyZZs9ukLs M7zX2En509Bwy7m+pR73P5jwPvQmNgB1r5ZuGRqxPuqT8lu1WOvtQwU1v3oPsYdMCdyx QP+ILTeFmE0ixMmLJBKLcyMVx8wYV+G1vZpGWDYA0XE3U8iDl1EAr5BoGyHftUaQeL5i 9obQ== X-Gm-Message-State: AOJu0Yx+FXttMIGNmsWV4LTWWRh6keJHxE063mLVVHsZY5re/jOWXVO3 0XMWzQI3TICDqPSpnJGci08G1V5J4u4qAlyeeC+78JUaKV+tJ3dNY6To2jmK X-Google-Smtp-Source: AGHT+IHez5n3nBt2diE11RGl+VUbw7lxrnceSGyPfETbgU1+A1zlml6DAp0JblFMLp+EeA/h9DEUHA== X-Received: by 2002:a05:6808:f07:b0:3d2:21a7:8629 with SMTP id 5614622812f47-3d51bac4b56mr7798605b6e.41.1718937202598; Thu, 20 Jun 2024 19:33:22 -0700 (PDT) Received: from localhost.localdomain (syn-076-032-089-124.res.spectrum.com. [76.32.89.124]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-7065124df73sm334482b3a.110.2024.06.20.19.33.21 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Jun 2024 19:33:22 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Subject: [PATCH v2 3/9] doc: reword design section in contributors guidelines Date: Thu, 20 Jun 2024 19:32:48 -0700 Message-Id: <20240621023254.4258-3-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240621023254.4258-1-nandinipersad361@gmail.com> References: <20240513155911.31872-1-nandinipersad361@gmail.com> <20240621023254.4258-1-nandinipersad361@gmail.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 Minor editing was made for grammar and syntax of design section. Signed-off-by: Nandini Persad --- .mailmap | 1 + doc/guides/contributing/design.rst | 86 +++++++++++++++--------------- doc/guides/linux_gsg/sys_reqs.rst | 2 +- 3 files changed, 45 insertions(+), 44 deletions(-) diff --git a/.mailmap b/.mailmap index 66ebc20666..7d4929c5d1 100644 --- a/.mailmap +++ b/.mailmap @@ -1002,6 +1002,7 @@ Naga Suresh Somarowthu Nalla Pradeep Na Na Nan Chen +Nandini Persad Nannan Lu Nan Zhou Narcisa Vasile diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst index b724177ba1..3d1f5aeb91 100644 --- a/doc/guides/contributing/design.rst +++ b/doc/guides/contributing/design.rst @@ -1,6 +1,7 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright 2018 The DPDK contributors + Design ====== @@ -8,22 +9,26 @@ Design Environment or Architecture-specific Sources -------------------------------------------- -In DPDK and DPDK applications, some code is specific to an architecture (i686, x86_64) or to an executive environment (freebsd or linux) and so on. -As far as is possible, all such instances of architecture or env-specific code should be provided via standard APIs in the EAL. +In DPDK and DPDK applications, some code is architecture-specific (i686, x86_64) or environment-specific (FreeBsd or Linux, etc.). +When feasible, such instances of architecture or env-specific code should be provided via standard APIs in the EAL. + +By convention, a file is specific if the directory is indicated. Otherwise, it is common. -By convention, a file is common if it is not located in a directory indicating that it is specific. -For instance, a file located in a subdir of "x86_64" directory is specific to this architecture. +For example: + +A file located in a subdir of "x86_64" directory is specific to this architecture. A file located in a subdir of "linux" is specific to this execution environment. .. note:: Code in DPDK libraries and applications should be generic. - The correct location for architecture or executive environment specific code is in the EAL. + The correct location for architecture or executive environment-specific code is in the EAL. + +When necessary, there are several ways to handle specific code: -When absolutely necessary, there are several ways to handle specific code: -* Use a ``#ifdef`` with a build definition macro in the C code. - This can be done when the differences are small and they can be embedded in the same C file: +* When the differences are small and they can be embedded in the same C file, use a ``#ifdef`` with a build definition macro in the C code. + .. code-block:: c @@ -33,9 +38,9 @@ When absolutely necessary, there are several ways to handle specific code: titi(); #endif -* Use build definition macros and conditions in the Meson build file. This is done when the differences are more significant. - In this case, the code is split into two separate files that are architecture or environment specific. - This should only apply inside the EAL library. + +* When the differences are more significant, use build definition macros and conditions in the Meson build file. In this case, the code is split into two separate files that are architecture or environment specific. This should only apply inside the EAL library. + Per Architecture Sources ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -43,7 +48,8 @@ Per Architecture Sources The following macro options can be used: * ``RTE_ARCH`` is a string that contains the name of the architecture. -* ``RTE_ARCH_I686``, ``RTE_ARCH_X86_64``, ``RTE_ARCH_X86_X32``, ``RTE_ARCH_PPC_64``, ``RTE_ARCH_RISCV``, ``RTE_ARCH_LOONGARCH``, ``RTE_ARCH_ARM``, ``RTE_ARCH_ARMv7`` or ``RTE_ARCH_ARM64`` are defined only if we are building for those architectures. +* ``RTE_ARCH_I686``, ``RTE_ARCH_X86_64``, ``RTE_ARCH_X86_X32``, ``RTE_ARCH_PPC_64``, ``RTE_ARCH_RISCV``, ``RTE_ARCH_LOONGARCH``, ``RTE_ARCH_ARM``, ``RTE_ARCH_ARMv7`` or ``RTE_ARCH_ARM64`` are defined when building for these architectures. + Per Execution Environment Sources ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -51,30 +57,22 @@ Per Execution Environment Sources The following macro options can be used: * ``RTE_EXEC_ENV`` is a string that contains the name of the executive environment. -* ``RTE_EXEC_ENV_FREEBSD``, ``RTE_EXEC_ENV_LINUX`` or ``RTE_EXEC_ENV_WINDOWS`` are defined only if we are building for this execution environment. +* ``RTE_EXEC_ENV_FREEBSD``, ``RTE_EXEC_ENV_LINUX`` or ``RTE_EXEC_ENV_WINDOWS`` are defined only when building for this execution environment. + Mbuf features ------------- -The ``rte_mbuf`` structure must be kept small (128 bytes). - -In order to add new features without wasting buffer space for unused features, -some fields and flags can be registered dynamically in a shared area. -The "dynamic" mbuf area is the default choice for the new features. +A designated area in mbuf stores "dynamically" registered fields and flags. It is the default choice for accommodating new features. The "dynamic" area consumes the remaining space in the mbuf, indicating that it's being efficiently utilized. However, the ``rte_mbuf`` structure must be kept small (128 bytes). -The "dynamic" area is eating the remaining space in mbuf, -and some existing "static" fields may need to become "dynamic". - -Adding a new static field or flag must be an exception matching many criteria -like (non exhaustive): wide usage, performance, size. +As more features are added, the space for existinG=g "static" fields (fields that are allocated statically) may need to be reconsidered and possibly converted to "dynamic" allocation. Adding a new static field or flag should be an exception. It must meet specific criteria including widespread usage, performance impact, and size considerations. Before adding a new static feature, it must be justified by its necessity and its impact on the system's efficiency. Runtime Information - Logging, Tracing and Telemetry ---------------------------------------------------- -It is often desirable to provide information to the end-user -as to what is happening to the application at runtime. -DPDK provides a number of built-in mechanisms to provide this introspection: +The end user may inquire as to what is happening to the application at runtime. +DPDK provides several built-in mechanisms to provide these insights: * :ref:`Logging ` * :doc:`Tracing <../prog_guide/trace_lib>` @@ -82,11 +80,11 @@ DPDK provides a number of built-in mechanisms to provide this introspection: Each of these has its own strengths and suitabilities for use within DPDK components. -Below are some guidelines for when each should be used: +Here are guidelines for when each mechanism should be used: * For reporting error conditions, or other abnormal runtime issues, *logging* should be used. - Depending on the severity of the issue, the appropriate log level, for example, - ``ERROR``, ``WARNING`` or ``NOTICE``, should be used. + For example, depending on the severity of the issue, the appropriate log level, + ``ERROR``, ``WARNING`` or ``NOTICE`` should be used. .. note:: @@ -96,24 +94,24 @@ Below are some guidelines for when each should be used: * For component initialization, or other cases where a path through the code is only likely to be taken once, - either *logging* at ``DEBUG`` level or *tracing* may be used, or potentially both. + either *logging* at ``DEBUG`` level or *tracing* may be used, or both. In the latter case, tracing can provide basic information as to the code path taken, with debug-level logging providing additional details on internal state, - not possible to emit via tracing. + which is not possible to emit via tracing. * For a component's data-path, where a path is to be taken multiple times within a short timeframe, *tracing* should be used. Since DPDK tracing uses `Common Trace Format `_ for its tracing logs, post-analysis can be done using a range of external tools. -* For numerical or statistical data generated by a component, for example, per-packet statistics, +* For numerical or statistical data generated by a component, such as per-packet statistics, *telemetry* should be used. -* For any data where the data may need to be gathered at any point in the execution - to help assess the state of the application component, - for example, core configuration, device information, *telemetry* should be used. +* For any data that may need to be gathered at any point during the execution + to help assess the state of the application component (for example, core configuration, device information) *telemetry* should be used. Telemetry callbacks should not modify any program state, but be "read-only". + Many libraries also include a ``rte__dump()`` function as part of their API, writing verbose internal details to a given file-handle. New libraries are encouraged to provide such functions where it makes sense to do so, @@ -135,13 +133,12 @@ requirements for preventing ABI changes when implementing statistics. Mechanism to allow the application to turn library statistics on and off ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Having runtime support for enabling/disabling library statistics is recommended, -as build-time options should be avoided. However, if build-time options are used, -for example as in the table library, the options can be set using c_args. -When this flag is set, all the counters supported by current library are +Having runtime support for enabling/disabling library statistics is recommended +as build-time options should be avoided. However, if build-time options are used, as in the table library, the options can be set using c_args. +When this flag is set, all the counters supported by the current library are collected for all the instances of every object type provided by the library. When this flag is cleared, none of the counters supported by the current library -are collected for any instance of any object type provided by the library: +are collected for any instance of any object type provided by the library. Prevention of ABI changes due to library statistics support @@ -165,8 +162,8 @@ Motivation to allow the application to turn library statistics on and off It is highly recommended that each library provides statistics counters to allow an application to monitor the library-level run-time events. Typical counters -are: number of packets received/dropped/transmitted, number of buffers -allocated/freed, number of occurrences for specific events, etc. +are: the number of packets received/dropped/transmitted, the number of buffers +allocated/freed, the number of occurrences for specific events, etc. However, the resources consumed for library-level statistics counter collection have to be spent out of the application budget and the counters collected by @@ -198,6 +195,7 @@ applications: the application may decide to turn the collection of statistics counters off for Library X and on for Library Y. + The statistics collection consumes a certain amount of CPU resources (cycles, cache bandwidth, memory bandwidth, etc) that depends on: @@ -218,6 +216,7 @@ cache bandwidth, memory bandwidth, etc) that depends on: validated for header integrity, counting the number of bits set in a bitmask might be needed. + PF and VF Considerations ------------------------ @@ -229,5 +228,6 @@ Developers should work with the Linux Kernel community to get the required functionality upstream. PF functionality should only be added to DPDK for testing and prototyping purposes while the kernel work is ongoing. It should also be marked with an "EXPERIMENTAL" tag. If the functionality isn't -upstreamable then a case can be made to maintain the PF functionality in DPDK +upstreamable, then a case can be made to maintain the PF functionality in DPDK without the EXPERIMENTAL tag. + diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst index 13be715933..0569c5cae6 100644 --- a/doc/guides/linux_gsg/sys_reqs.rst +++ b/doc/guides/linux_gsg/sys_reqs.rst @@ -99,7 +99,7 @@ e.g. :doc:`../nics/index` Running DPDK Applications ------------------------- -To run a DPDK application, some customization may be required on the target machine. +To run a DPDK application, customization may be required on the target machine. System Software ~~~~~~~~~~~~~~~ From patchwork Fri Jun 21 02:32:49 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nandini Persad X-Patchwork-Id: 141467 X-Patchwork-Delegate: thomas@monjalon.net 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 4B366454B2; Fri, 21 Jun 2024 04:33:34 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id C437A42E98; Fri, 21 Jun 2024 04:33:28 +0200 (CEST) Received: from mail-pf1-f179.google.com (mail-pf1-f179.google.com [209.85.210.179]) by mails.dpdk.org (Postfix) with ESMTP id 0486342E8F for ; Fri, 21 Jun 2024 04:33:26 +0200 (CEST) Received: by mail-pf1-f179.google.com with SMTP id d2e1a72fcca58-705cffc5bcfso1566494b3a.3 for ; Thu, 20 Jun 2024 19:33:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1718937205; x=1719542005; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=b9Z2YzdZ6Bt6BPGLubiBI/QfGdFA7MvR6ptVRJQekWA=; b=CGHIqhDUGIMreUcVvCpbeH+N19UHnA1QPsxvFRp6/nefj3va+TGKBqyro9/m+whX2+ tE0Q9HsRJoyoSoF6nHcCM6TW4FThUkEWw5U9GXu6wQk+/Ogi+D5NJEr4x5wsIUGvyv6Y 9IMvqHvg27px1pEx+B6oaTPaQ0OXk5ht/CPLb0SPDT+TPXMmlB7M5vGQ+i/1vDYTI9tU mLZYnOosn7RQRiZMCaoNpfrTAe73QqcYOEzMoe7chDaqpfLFsfYA/kBpOzWCIBCWlTgY IyK8DUSj8qL9CYWAmL7+OtKgeb1wHmy+jEQkTqW0ts3yL/6pI0Uv7qJVrtsxcbkaokeh OMFQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718937205; x=1719542005; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=b9Z2YzdZ6Bt6BPGLubiBI/QfGdFA7MvR6ptVRJQekWA=; b=v51+qjmuR3ec3CrodbLoxq4pxmEDObVPsi7CYZsXG7gzUhSPUyv4zJbBF5aAXCR7iV 9/r0NzvrnVUdPwrLAxw6DWkcD9nznMSWlrCh3AkMZzFd4ISHS7j54flq22VrlDr95AaF 2Cae/92425o/QT17iEMVaYnxcbHTxzGn3umb7uhQRGycid7WIgkScPknUtq+7jUkQXhO yoE23jijCHfHCRqsC7n58rFaA/vG/EOBEsLfxjJLE/V/hjHZTOULes5ViKP8uisKlZUE 0glbtsElYIy9Gtsfd+3di0aKYcNsOpcnvbZgHWjjm/XlJWw2YdbvAv4JqwSuEq7wgmFv WHJg== X-Gm-Message-State: AOJu0Yy4gesZwOZpIYW7uMd03B7fgYYTgyjf2c80JM7SyM5LZgy76kla p/7MfnKbq/AbiQziOM/9R9BSBttulpX/pyIPVWx23SyFuU08DzU53zTa9xyO X-Google-Smtp-Source: AGHT+IGrYXw6K2H293z6aPIgdcVAYLW40bDG5Tk7Ji/mY3Lmy19dfLFonYTcODXlKvJ8e8EY9F+76g== X-Received: by 2002:a05:6a20:6da5:b0:1bc:c4d1:7810 with SMTP id adf61e73a8af0-1bcc4d17871mr5629149637.29.1718937204857; Thu, 20 Jun 2024 19:33:24 -0700 (PDT) Received: from localhost.localdomain (syn-076-032-089-124.res.spectrum.com. [76.32.89.124]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-7065124df73sm334482b3a.110.2024.06.20.19.33.24 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Jun 2024 19:33:24 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Subject: [PATCH v2 4/9] doc: reword service cores section in prog guide Date: Thu, 20 Jun 2024 19:32:49 -0700 Message-Id: <20240621023254.4258-4-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240621023254.4258-1-nandinipersad361@gmail.com> References: <20240513155911.31872-1-nandinipersad361@gmail.com> <20240621023254.4258-1-nandinipersad361@gmail.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 I've made minor syntax changes to section 8 of programmer's guide, service cores. Signed-off-by: Nandini Persad Acked-by: Stephen Hemminger --- doc/guides/prog_guide/service_cores.rst | 32 ++++++++++++------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/guides/prog_guide/service_cores.rst b/doc/guides/prog_guide/service_cores.rst index d4e6c3d6e6..59da3964bf 100644 --- a/doc/guides/prog_guide/service_cores.rst +++ b/doc/guides/prog_guide/service_cores.rst @@ -4,38 +4,38 @@ Service Cores ============= -DPDK has a concept known as service cores, which enables a dynamic way of -performing work on DPDK lcores. Service core support is built into the EAL, and -an API is provided to optionally allow applications to control how the service +DPDK has a concept known as service cores. Service cores enable a dynamic way of +performing work on DPDK lcores. Service core support is built into the EAL. +An API is provided to give you the option of allowing applications to control how the service cores are used at runtime. -The service cores concept is built up out of services (components of DPDK that +The service cores concept is built out of services (components of DPDK that require CPU cycles to operate) and service cores (DPDK lcores, tasked with running services). The power of the service core concept is that the mapping -between service cores and services can be configured to abstract away the +between service cores and services can be configured to simplify the difference between platforms and environments. -For example, the Eventdev has hardware and software PMDs. Of these the software +For example, the Eventdev has hardware and software PMDs. Of these the software, PMD requires an lcore to perform the scheduling operations, while the hardware PMD does not. With service cores, the application would not directly notice -that the scheduling is done in software. +that the scheduling is done in the software. For detailed information about the service core API, please refer to the docs. Service Core Initialization ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are two methods to having service cores in a DPDK application, either by +There are two methods to having service cores in a DPDK application: by using the service coremask, or by dynamically adding cores using the API. -The simpler of the two is to pass the `-s` coremask argument to EAL, which will -take any cores available in the main DPDK coremask, and if the bits are also set -in the service coremask the cores become service-cores instead of DPDK +The simpler of the two is to pass the `-s` coremask argument to the EAL, which will +take any cores available in the main DPDK coremask. If the bits are also set +in the service coremask, the cores become service-cores instead of DPDK application lcores. Enabling Services on Cores ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Each registered service can be individually mapped to a service core, or set of +Each registered service can be individually mapped to a service core, or a set of service cores. Enabling a service on a particular core means that the lcore in question will run the service. Disabling that core on the service stops the lcore in question from running the service. @@ -48,8 +48,8 @@ function to run the service. Service Core Statistics ~~~~~~~~~~~~~~~~~~~~~~~ -The service core library is capable of collecting runtime statistics like number -of calls to a specific service, and number of cycles used by the service. The +The service core library is capable of collecting runtime statistics like the number +of calls to a specific service, and the number of cycles used by the service. The cycle count collection is dynamically configurable, allowing any application to profile the services running on the system at any time. @@ -58,9 +58,9 @@ Service Core Tracing The service core library is instrumented with tracepoints using the DPDK Trace Library. These tracepoints allow you to track the service and logical cores -state. To activate tracing when launching a DPDK program it is necessary to use the +state. To activate tracing when launching a DPDK program, it is necessary to use the ``--trace`` option to specify a regular expression to select which tracepoints -to enable. Here is an example if you want to only specify service core tracing:: +to enable. Here is an example if you want to specify only service core tracing:: ./dpdk/examples/service_cores/build/service_cores --trace="lib.eal.thread*" --trace="lib.eal.service*" From patchwork Fri Jun 21 02:32:50 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nandini Persad X-Patchwork-Id: 141468 X-Patchwork-Delegate: thomas@monjalon.net 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 7D343454B2; Fri, 21 Jun 2024 04:33:43 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 4A4B442EAB; Fri, 21 Jun 2024 04:33:30 +0200 (CEST) Received: from mail-oa1-f42.google.com (mail-oa1-f42.google.com [209.85.160.42]) by mails.dpdk.org (Postfix) with ESMTP id 1023B42E92 for ; Fri, 21 Jun 2024 04:33:28 +0200 (CEST) Received: by mail-oa1-f42.google.com with SMTP id 586e51a60fabf-2598a57b2c1so793567fac.0 for ; Thu, 20 Jun 2024 19:33:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1718937207; x=1719542007; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=PHVNW4mnJ5LGFWkoMSG2ZReJQsaezFvbg5mMljcs8GQ=; b=I8J7kwVyt+7adlnrQ6nJhmTAzX0BFPyKlG3NaenU9V+By3XGSOvHFXRXUZ0vy3z3jn PvQWChww51+BEY7RF532KXRlyYGDjK96vUl8Ril3ORcP4VsUF4D9ZzseSefhPJktaR96 RLm4KemiNOOysUgTbrqkzKLlOaR9JcJs2RpfKS9tOKaQs4uBSj5J0QcLM6JnVa9L0KRN W+AEE2a/rXekrr9l3Frf3at58YO6nYf8a3ochCsZ6boPgQNR6FGlj97Rme1m2b0q3f23 qC52jNlIsD308wJxAySEjWUaB4pIk0Sta1O5Rdc0aY/C4JVANhJwsD6tyigw2Xyq79wH cdWg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718937207; x=1719542007; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=PHVNW4mnJ5LGFWkoMSG2ZReJQsaezFvbg5mMljcs8GQ=; b=ulJ1T+ocRZsXVo/DasZ/GnWRAakfKRA1xqZNh/vLaItt7rOlCTh0TQNqIDjPuF9Rt7 QcCNsY6OS7babMAUMbdZJVwNJWYFndB5W5iv2pdkFa2h4VuOymxv72mg/2PRyCHrLsmF bQ22RR2XYhAUjl0gzzQBA9/Cdvt9ksciP294XU/qglmCgOVBgRLQ2815Ixa4I+arVPeS NutmiY7uSrgOrYPoRdvQNynycXE2BrqTCXdIFYTX6i7PT7Glxk9xMKqvaXg6Oa4q+3Lv 6WdvFU3fHzLty8q2EtICm+XJgG67uZLAFOfIpGo0NjW+AVL7F/emqFNvb2DKM1XcOzcz sUYQ== X-Gm-Message-State: AOJu0YxnMPXA2QaB3q4ChAjYrQJmRYLkwvdZQ5EVjm6pnznH3JzfPRLA N2s0U3GGbHIO4KeDmn3dXsJ1jfiAkPoAkzwUWIRP8wi2VkuJ8oDrbLttinoa X-Google-Smtp-Source: AGHT+IGwexV2hHyJ2BGSbmvXpBR3M1FMKPkldtpcJxEP98wvisUuxW2i1sSMMh5RjLRw9rGa5FYnZQ== X-Received: by 2002:a05:6870:5490:b0:259:8156:c08f with SMTP id 586e51a60fabf-25c9498ecafmr7780322fac.15.1718937207071; Thu, 20 Jun 2024 19:33:27 -0700 (PDT) Received: from localhost.localdomain (syn-076-032-089-124.res.spectrum.com. [76.32.89.124]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-7065124df73sm334482b3a.110.2024.06.20.19.33.26 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Jun 2024 19:33:26 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Subject: [PATCH v2 5/9] doc: reword trace library section in prog guide Date: Thu, 20 Jun 2024 19:32:50 -0700 Message-Id: <20240621023254.4258-5-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240621023254.4258-1-nandinipersad361@gmail.com> References: <20240513155911.31872-1-nandinipersad361@gmail.com> <20240621023254.4258-1-nandinipersad361@gmail.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 Minor syntax edits were made to sect the trace library section of prog guide. Signed-off-by: Nandini Persad Acked-by: Stephen Hemminger --- doc/guides/prog_guide/trace_lib.rst | 50 ++++++++++++++--------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/doc/guides/prog_guide/trace_lib.rst b/doc/guides/prog_guide/trace_lib.rst index d9b17abe90..e2983017d8 100644 --- a/doc/guides/prog_guide/trace_lib.rst +++ b/doc/guides/prog_guide/trace_lib.rst @@ -14,29 +14,29 @@ When recording, specific instrumentation points placed in the software source code generate events that are saved on a giant tape: a trace file. The trace file then later can be opened in *trace viewers* to visualize and analyze the trace events with timestamps and multi-core views. -Such a mechanism will be useful for resolving a wide range of problems such as -multi-core synchronization issues, latency measurements, finding out the -post analysis information like CPU idle time, etc that would otherwise be -extremely challenging to get. +This mechanism will be useful for resolving a wide range of problems such as +multi-core synchronization issues, latency measurements, and finding +post analysis information like CPU idle time, etc., that would otherwise be +extremely challenging to gather. Tracing is often compared to *logging*. However, tracers and loggers are two -different tools, serving two different purposes. -Tracers are designed to record much lower-level events that occur much more +different tools serving two different purposes. +Tracers are designed to record much lower-level events that occur more frequently than log messages, often in the range of thousands per second, with very little execution overhead. Logging is more appropriate for a very high-level analysis of less frequent events: user accesses, exceptional conditions (errors and warnings, for -example), database transactions, instant messaging communications, and such. +example), database transactions, instant messaging communications, etc. Simply put, logging is one of the many use cases that can be satisfied with tracing. DPDK tracing library features ----------------------------- -- A framework to add tracepoints in control and fast path APIs with minimum +- Provides framework to add tracepoints in control and fast path APIs with minimum impact on performance. Typical trace overhead is ~20 cycles and instrumentation overhead is 1 cycle. -- Enable and disable the tracepoints at runtime. +- Enable and disable tracepoints at runtime. - Save the trace buffer to the filesystem at any point in time. - Support ``overwrite`` and ``discard`` trace mode operations. - String-based tracepoint object lookup. @@ -47,7 +47,7 @@ DPDK tracing library features For detailed information, refer to `Common Trace Format `_. -How to add a tracepoint? +How to add a Tracepoint ------------------------ This section steps you through the details of adding a simple tracepoint. @@ -67,14 +67,14 @@ Create the tracepoint header file rte_trace_point_emit_string(str); ) -The above macro creates ``app_trace_string`` tracepoint. +The above macro creates the ``app_trace_string`` tracepoint. The user can choose any name for the tracepoint. However, when adding a tracepoint in the DPDK library, the ``rte__trace_[_]`` naming convention must be followed. The examples are ``rte_eal_trace_generic_str``, ``rte_mempool_trace_create``. -The ``RTE_TRACE_POINT`` macro expands from above definition as the following +The ``RTE_TRACE_POINT`` macro expands from the above definition as the following function template: .. code-block:: c @@ -91,7 +91,7 @@ The consumer of this tracepoint can invoke ``app_trace_string(const char *str)`` to emit the trace event to the trace buffer. -Register the tracepoint +Register the Tracepoint ~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: c @@ -122,40 +122,40 @@ convention. The ``RTE_TRACE_POINT_REGISTER`` defines the placeholder for the ``rte_trace_point_t`` tracepoint object. - For generic tracepoint or for tracepoint used in public header files, + For a generic tracepoint or for the tracepoint used in public header files, the user must export a ``__`` symbol in the library ``.map`` file for this tracepoint - to be used out of the library, in shared builds. + to be used out of the library in shared builds. For example, ``__app_trace_string`` will be the exported symbol in the above example. -Fast path tracepoint +Fast Path Tracepoint -------------------- In order to avoid performance impact in fast path code, the library introduced ``RTE_TRACE_POINT_FP``. When adding the tracepoint in fast path code, the user must use ``RTE_TRACE_POINT_FP`` instead of ``RTE_TRACE_POINT``. -``RTE_TRACE_POINT_FP`` is compiled out by default and it can be enabled using +``RTE_TRACE_POINT_FP`` is compiled by default and can be enabled using the ``enable_trace_fp`` option for meson build. -Event record mode +Event Record Mode ----------------- -Event record mode is an attribute of trace buffers. Trace library exposes the +Event record mode is an attribute of trace buffers. The trace library exposes the following modes: Overwrite - When the trace buffer is full, new trace events overwrites the existing + When the trace buffer is full, new trace events overwrite the existing captured events in the trace buffer. Discard When the trace buffer is full, new trace events will be discarded. -The mode can be configured either using EAL command line parameter -``--trace-mode`` on application boot up or use ``rte_trace_mode_set()`` API to +The mode can be configured either using the EAL command line parameter +``--trace-mode`` on application boot up or use the ``rte_trace_mode_set()`` API to configure at runtime. -Trace file location +Trace File Location ------------------- On ``rte_trace_save()`` or ``rte_eal_cleanup()`` invocation, the library saves @@ -167,7 +167,7 @@ option. For more information, refer to :doc:`../linux_gsg/linux_eal_parameters` for trace EAL command line options. -View and analyze the recorded events +View and Analyze Recorded Events ------------------------------------ Once the trace directory is available, the user can view/inspect the recorded @@ -176,7 +176,7 @@ events. There are many tools you can use to read DPDK traces: #. ``babeltrace`` is a command-line utility that converts trace formats; it - supports the format that DPDK trace library produces, CTF, as well as a + supports the format that the DPDK trace library produces, CTF, as well as a basic text output that can be grep'ed. The babeltrace command is part of the Open Source Babeltrace project. From patchwork Fri Jun 21 02:32:51 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nandini Persad X-Patchwork-Id: 141469 X-Patchwork-Delegate: thomas@monjalon.net 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 6774F454B2; Fri, 21 Jun 2024 04:33:51 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A39D242E9F; Fri, 21 Jun 2024 04:33:32 +0200 (CEST) Received: from mail-oa1-f44.google.com (mail-oa1-f44.google.com [209.85.160.44]) by mails.dpdk.org (Postfix) with ESMTP id 06E1A42EB0 for ; Fri, 21 Jun 2024 04:33:30 +0200 (CEST) Received: by mail-oa1-f44.google.com with SMTP id 586e51a60fabf-24542b8607fso826425fac.1 for ; Thu, 20 Jun 2024 19:33:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1718937210; x=1719542010; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=DEDpIKooXOiOxB99sjlNJWL+PC7EgeRPd6x9nu20yWg=; b=Gvb7uaTS5JAgUkqf68NE2F0JaZN0KbNSBFO7evUB3Pe0275tS4xr0j00aYCei2UPIq 6hD/eEn6xdTgOyVO3m1uKKeIpsrC0vuXmV5YPyVtU0VqHFRQTfc4sKTzDIMqwiYkw0N/ HDQ/RQlm1kY/+ULp4hlqodnvz1+lY9Y2AkUEW8TjZqv1AQ9Y/DwkSSE6IR0OApuGEjNK KNslGvw9sTOMerO11VSRU5icwbFY4JyjFobE/oR0LodfiK1IlLnn+0iC4EwtVqBFzJth iVQQJ1ZcoVSXcxOBEc4VqFYFLUG0waHWS2viZ1A6UAE+MZaXaEob2Jo7TSWGFwGx7gOe Obxg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718937210; x=1719542010; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=DEDpIKooXOiOxB99sjlNJWL+PC7EgeRPd6x9nu20yWg=; b=hPhXbM1h1cFuxTw2ci+WW6fomuKcWq5K1wVuVkwDYV41YryRY1A3egaP+l2niZ6/3A hMVzdYEwHfBWQ3Kar2qURVm370zWefSVlp4bKt8q5ayNccsnK8+g0J0ZptdF7z+r7oMn TnV30oAarvFYVFJXa+rXaefXzLBPvYEYV1R4IZiPGQE0ywo3bTE7dUsm2kbQe9ebqF2M e/nNJgz31c2zIY8v0gxiX2Y3Z+kEDDCfPBzOnewhW/jVTIrT5NefItt+/MGOYNNtI3Gz p62USHI27Reqrg8zx7PEl2I2UQY9CWAIAPqG8ph8k0MKwRYhgUaapHaZdBdF8EmWvmvr MX1w== X-Gm-Message-State: AOJu0Yw+RLRGz7rkVqhnm+0vB+K9ry5JfS5BybAo/qVj2WSHaepjYXDU FlCYz68t44X03NZUvU8BLR32AJ2m4SKabjFDatxxBvaq8e1m7wfhCBDJ/WJX X-Google-Smtp-Source: AGHT+IGYdbpZMBDak9kUwpmwbSgfuylY5BtSCp7amlC83a/dxCyDpukqk17stv8quw9SL6lqmShcCw== X-Received: by 2002:a05:6870:6586:b0:25b:5032:25c4 with SMTP id 586e51a60fabf-25c94db976fmr8119300fac.54.1718937209728; Thu, 20 Jun 2024 19:33:29 -0700 (PDT) Received: from localhost.localdomain (syn-076-032-089-124.res.spectrum.com. [76.32.89.124]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-7065124df73sm334482b3a.110.2024.06.20.19.33.28 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Jun 2024 19:33:29 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Subject: [PATCH v2 6/9] doc: reword log library section in prog guide Date: Thu, 20 Jun 2024 19:32:51 -0700 Message-Id: <20240621023254.4258-6-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240621023254.4258-1-nandinipersad361@gmail.com> References: <20240513155911.31872-1-nandinipersad361@gmail.com> <20240621023254.4258-1-nandinipersad361@gmail.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 Minor changes made for syntax in the log library section and 7.1 section of the programmer's guide. A couple sentences at the end of the trace library section were also edited. Signed-off-by: Nandini Persad Acked-by: Stephen Hemminger --- doc/guides/prog_guide/cmdline.rst | 24 +++++++++++----------- doc/guides/prog_guide/log_lib.rst | 32 ++++++++++++++--------------- doc/guides/prog_guide/trace_lib.rst | 22 ++++++++++---------- 3 files changed, 39 insertions(+), 39 deletions(-) diff --git a/doc/guides/prog_guide/cmdline.rst b/doc/guides/prog_guide/cmdline.rst index e20281ceb5..6b10ab6c99 100644 --- a/doc/guides/prog_guide/cmdline.rst +++ b/doc/guides/prog_guide/cmdline.rst @@ -5,8 +5,8 @@ Command-line Library ==================== Since its earliest versions, DPDK has included a command-line library - -primarily for internal use by, for example, ``dpdk-testpmd`` and the ``dpdk-test`` binaries, -but the library is also exported on install and can be used by any end application. +primarily for internal use by, for example, ``dpdk-testpmd`` and the ``dpdk-test`` binaries. +However, the library is also exported on install and can be used by any end application. This chapter covers the basics of the command-line library and how to use it in an application. Library Features @@ -18,7 +18,7 @@ The DPDK command-line library supports the following features: * Ability to read and process commands taken from an input file, e.g. startup script -* Parameterized commands able to take multiple parameters with different datatypes: +* Parameterized commands that can take multiple parameters with different datatypes: * Strings * Signed/unsigned 16/32/64-bit integers @@ -56,7 +56,7 @@ Creating a Command List File The ``dpdk-cmdline-gen.py`` script takes as input a list of commands to be used by the application. While these can be piped to it via standard input, using a list file is probably best. -The format of the list file must be: +The format of the list file must follow these requirements: * Comment lines start with '#' as first non-whitespace character @@ -75,7 +75,7 @@ The format of the list file must be: * ``dst_ip6`` * Variable fields, which take their values from a list of options, - have the comma-separated option list placed in braces, rather than a the type name. + have the comma-separated option list placed in braces, rather than by the type name. For example, * ``<(rx,tx,rxtx)>mode`` @@ -127,13 +127,13 @@ and the callback stubs will be written to an equivalent ".c" file. Providing the Function Callbacks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -As discussed above, the script output is a header file, containing structure definitions, -but the callback functions themselves obviously have to be provided by the user. -These callback functions must be provided as non-static functions in a C file, +As discussed above, the script output is a header file containing structure definitions, +but the callback functions must be provided by the user. +These callback functions must be provided as non-static functions in a C file and named ``cmd__parsed``. The function prototypes can be seen in the generated output header. -The "cmdname" part of the function name is built up by combining the non-variable initial tokens in the command. +The "cmdname" part of the function name is built by combining the non-variable initial tokens in the command. So, given the commands in our worked example below: ``quit`` and ``show port stats ``, the callback functions would be: @@ -151,11 +151,11 @@ the callback functions would be: ... } -These functions must be provided by the developer, but, as stated above, +These functions must be provided by the developer. However, as stated above, stub functions may be generated by the script automatically using the ``--stubs`` parameter. The same "cmdname" stem is used in the naming of the generated structures too. -To get at the results structure for each command above, +To get to the results structure for each command above, the ``parsed_result`` parameter should be cast to ``struct cmd_quit_result`` or ``struct cmd_show_port_stats_result`` respectively. @@ -179,7 +179,7 @@ To integrate the script output with the application, we must ``#include`` the generated header into our applications C file, and then have the command-line created via either ``cmdline_new`` or ``cmdline_stdin_new``. The first parameter to the function call should be the context array in the generated header file, -``ctx`` by default. (Modifiable via script parameter). +``ctx`` by default (Modifiable via script parameter). The callback functions may be in this same file, or in a separate one - they just need to be available to the linker at build-time. diff --git a/doc/guides/prog_guide/log_lib.rst b/doc/guides/prog_guide/log_lib.rst index ff9d1b54a2..05f032dfad 100644 --- a/doc/guides/prog_guide/log_lib.rst +++ b/doc/guides/prog_guide/log_lib.rst @@ -5,7 +5,7 @@ Log Library =========== The DPDK Log library provides the logging functionality for other DPDK libraries and drivers. -By default, in a Linux application, logs are sent to syslog and also to the console. +By default, in a Linux application, logs are sent to syslog and the console. On FreeBSD and Windows applications, logs are sent only to the console. However, the log function can be overridden by the user to use a different logging mechanism. @@ -26,14 +26,14 @@ These levels, specified in ``rte_log.h`` are (from most to least important): At runtime, only messages of a configured level or above (i.e. of higher importance) will be emitted by the application to the log output. -That level can be configured either by the application calling the relevant APIs from the logging library, +That level can be configured either by the application calling relevant APIs from the logging library, or by the user passing the ``--log-level`` parameter to the EAL via the application. Setting Global Log Level ~~~~~~~~~~~~~~~~~~~~~~~~ To adjust the global log level for an application, -just pass a numeric level or a level name to the ``--log-level`` EAL parameter. +pass a numeric level or a level name to the ``--log-level`` EAL parameter. For example:: /path/to/app --log-level=error @@ -47,9 +47,9 @@ Within an application, the log level can be similarly set using the ``rte_log_se Setting Log Level for a Component ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In some cases, for example, for debugging purposes, -it may be desirable to increase or decrease the log level for only a specific component, or set of components. -To facilitate this, the ``--log-level`` argument also accepts an, optionally wildcarded, component name, +In some cases (such as debugging purposes), +you may want to increase or decrease the log level for only a specific component or set of components. +To facilitate this, the ``--log-level`` argument also accepts an optionally wildcarded component name, along with the desired level for that component. For example:: @@ -57,13 +57,13 @@ For example:: /path/to/app --log-level=lib.*:warning -Within an application, the same result can be got using the ``rte_log_set_level_pattern()`` or ``rte_log_set_level_regex()`` APIs. +Within an application, you can achieve the same result using the ``rte_log_set_level_pattern()`` or ``rte_log_set_level_regex()`` APIs. Using Logging APIs to Generate Log Messages ------------------------------------------- -To output log messages, ``rte_log()`` API function should be used. -As well as the log message, ``rte_log()`` takes two additional parameters: +To output log messages, the ``rte_log()`` API function should be used, +as well as the log message, ``rte_log()`` which takes two additional parameters: * The log level * The log component type @@ -73,16 +73,16 @@ The component type is a unique id that identifies the particular DPDK component To get this id, each component needs to register itself at startup, using the macro ``RTE_LOG_REGISTER_DEFAULT``. This macro takes two parameters, with the second being the default log level for the component. -The first parameter, called "type", the name of the "logtype", or "component type" variable used in the component. -This variable will be defined by the macro, and should be passed as the second parameter in calls to ``rte_log()``. +The first parameter, called "type", is the name of the "logtype", or "component type" variable used in the component. +This variable will be defined by the macro and should be passed as the second parameter in calls to ``rte_log()``. In general, most DPDK components define their own logging macros to simplify the calls to the log APIs. They do this by: * Hiding the component type parameter inside the macro so it never needs to be passed explicitly. * Using the log-level definitions given in ``rte_log.h`` to allow short textual names to be used in - place of the numeric log levels. + place of numeric log levels. -The following code is taken from ``rte_cfgfile.c`` and shows the log registration, +The following code is taken from ``rte_cfgfile.c`` and shows the log registration and subsequent definition of a shortcut logging macro. It can be used as a template for any new components using DPDK logging. @@ -97,10 +97,10 @@ It can be used as a template for any new components using DPDK logging. it should be placed near the top of the C file using it. If not, the logtype variable should be defined as an "extern int" near the top of the file. - Similarly, if logging is to be done by multiple files in a component, - only one file should register the logtype via the macro, + Similarly, if logging will be done by multiple files in a component, + only one file should register the logtype via the macro and the logtype should be defined as an "extern int" in a common header file. - Any component-specific logging macro should similarly be defined in that header. + Any component-specific logging macro should be similarly defined in that header. Throughout the cfgfile library, all logging calls are therefore of the form: diff --git a/doc/guides/prog_guide/trace_lib.rst b/doc/guides/prog_guide/trace_lib.rst index e2983017d8..4177f8ba15 100644 --- a/doc/guides/prog_guide/trace_lib.rst +++ b/doc/guides/prog_guide/trace_lib.rst @@ -195,12 +195,12 @@ to babeltrace with no options:: all their events, merging them in chronological order. You can pipe the output of the babeltrace into a tool like grep(1) for further -filtering. Below example grep the events for ``ethdev`` only:: +filtering. Here's an example of how you grep the events for ``ethdev`` only:: babeltrace /tmp/my-dpdk-trace | grep ethdev You can pipe the output of babeltrace into a tool like wc(1) to count the -recorded events. Below example count the number of ``ethdev`` events:: +recorded events. Below is an example of counting the number of ``ethdev`` events:: babeltrace /tmp/my-dpdk-trace | grep ethdev | wc --lines @@ -210,14 +210,14 @@ Use the tracecompass GUI tool ``Tracecompass`` is another tool to view/analyze the DPDK traces which gives a graphical view of events. Like ``babeltrace``, tracecompass also provides an interface to search for a particular event. -To use ``tracecompass``, following are the minimum required steps: +To use ``tracecompass``, the following are the minimum required steps: - Install ``tracecompass`` to the localhost. Variants are available for Linux, Windows, and OS-X. - Launch ``tracecompass`` which will open a graphical window with trace management interfaces. -- Open a trace using ``File->Open Trace`` option and select metadata file which - is to be viewed/analyzed. +- Open a trace using the ``File->Open Trace`` option and select the metadata file which + will be viewed/analyzed. For more details, refer `Trace Compass `_. @@ -225,7 +225,7 @@ For more details, refer Quick start ----------- -This section steps you through the details of generating trace and viewing it. +This section steps you through the details of generating the trace and viewing it. - Start the dpdk-test:: @@ -238,8 +238,8 @@ This section steps you through the details of generating trace and viewing it. Implementation details ---------------------- -As DPDK trace library is designed to generate traces that uses ``Common Trace -Format (CTF)``. ``CTF`` specification consists of the following units to create +As the DPDK trace library is designed to generate traces that use the ``Common Trace +Format (CTF)``. ``CTF`` specification and consists of the following units to create a trace. - ``Stream`` Sequence of packets. @@ -249,7 +249,7 @@ a trace. For detailed information, refer to `Common Trace Format `_. -The implementation details broadly divided into the following areas: +Implementation details are broadly divided into the following areas: Trace metadata creation ~~~~~~~~~~~~~~~~~~~~~~~ @@ -277,7 +277,7 @@ per thread to enable lock less trace-emit function. For non lcore threads, the trace memory is allocated on the first trace emission. -For lcore threads, if trace points are enabled through a EAL option, the trace +For lcore threads, if trace points are enabled through an EAL option, the trace memory is allocated when the threads are known of DPDK (``rte_eal_init`` for EAL lcores, ``rte_thread_register`` for non-EAL lcores). Otherwise, when trace points are enabled later in the life of the application, @@ -348,7 +348,7 @@ trace.header | timestamp [47:0] | +----------------------+ -The trace header is 64 bits, it consists of 48 bits of timestamp and 16 bits +The trace header is 64 bits. It consists of 48 bits of timestamp and 16 bits event ID. The ``packet.header`` and ``packet.context`` will be written in the slow path From patchwork Fri Jun 21 02:32:52 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nandini Persad X-Patchwork-Id: 141470 X-Patchwork-Delegate: thomas@monjalon.net 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 8CF57454B2; Fri, 21 Jun 2024 04:33:58 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id F39A342EB5; Fri, 21 Jun 2024 04:33:36 +0200 (CEST) Received: from mail-pf1-f173.google.com (mail-pf1-f173.google.com [209.85.210.173]) by mails.dpdk.org (Postfix) with ESMTP id A233242EA3 for ; Fri, 21 Jun 2024 04:33:33 +0200 (CEST) Received: by mail-pf1-f173.google.com with SMTP id d2e1a72fcca58-706354409e1so1414347b3a.2 for ; Thu, 20 Jun 2024 19:33:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1718937212; x=1719542012; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=iRj6alim9AuWlP/nQ0tlPjMEdRHBzcnYZDfbrYPWw4M=; b=fNTru6p6fSlr9BdgO/oywLLJdVleqKc6w/JwOR3qK0/IYMqFTDfhMA1NgKlmiipzCr /zxu880lFog4BstlfTajheSx/QDOyxUbGdU0g1iiZchaTjhaB/krYDaBprBWC7xVoI1c hqHVaE0CFFc5ohnQCq5hpNQE9bwNqgvbckY/oclCrYznDhqxg/a+NHHXAlPechAz0X0T 9cPKth6XLrb+pQEWdvKoQFPSyn+LPFugLTnckrabxkvAkXUE66zLg7Bkz60fNdhik120 AVtXXg1PPEpNEgGnV7tzq/r9N1cIBpVlpn6ijpvszyonpid7AG67e5YNXN6A24Z7hmGX JZDA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718937212; x=1719542012; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=iRj6alim9AuWlP/nQ0tlPjMEdRHBzcnYZDfbrYPWw4M=; b=g1UBVU3wwFrHUes6gRFlleX7LHHKOW81pnrPXYxj/uIeDytdX1A9EZw6aRrKRGDOER epwU1XbeuiIj3K3DH9GWFKmdnqt8E3Ir8mIJ0mhjJNifT72xhNVcf5QyFR4rzSHY7v/p 9G1F0eYY2cQ9p5xhg8UVyfgU+6uttw37u0iW8BQatS4zjwtjsArJ/c837PPAvqQZl/rU YZ/5V2954osiCOMesaqg/OE8fx5zP8dUExclSsCg0ZI9ehYQailoodU5TnDtcJeRd9ga 2FeNPmFYdRhi2KjMy4dFIN8YA8JSwcmMkTaqoG3a2TZVH20h6ERIgLNwYeoQc0zafsea tecQ== X-Gm-Message-State: AOJu0YwPwFdauyg5TkE27GOaxhkGywA5LmlZerjjZw1DG9TsH0PCMsnA STDe/htOHxqxt/v5+v/8+PfgYV2Wbo2D4zg+H6B9KAgB7zM8zOvqHtCjTO4k X-Google-Smtp-Source: AGHT+IEaM80CsLu1/94vXz03JGHuhxZ9NfRhg7ZlZaa01Yn8/uEThHbDzzOknQ7Ux4WlgLl9zhi3vg== X-Received: by 2002:a05:6a00:2e95:b0:705:a171:b994 with SMTP id d2e1a72fcca58-70629cf92d5mr8803862b3a.32.1718937212341; Thu, 20 Jun 2024 19:33:32 -0700 (PDT) Received: from localhost.localdomain (syn-076-032-089-124.res.spectrum.com. [76.32.89.124]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-7065124df73sm334482b3a.110.2024.06.20.19.33.31 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Jun 2024 19:33:32 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Subject: [PATCH v2 7/9] doc: reword cmdline section in prog guide Date: Thu, 20 Jun 2024 19:32:52 -0700 Message-Id: <20240621023254.4258-7-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240621023254.4258-1-nandinipersad361@gmail.com> References: <20240513155911.31872-1-nandinipersad361@gmail.com> <20240621023254.4258-1-nandinipersad361@gmail.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 Minor syntax edits made to the cmdline section. Signed-off-by: Nandini Persad Acked-by: Stephen Hemminger --- doc/guides/prog_guide/cmdline.rst | 34 +++++++++++++++---------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/doc/guides/prog_guide/cmdline.rst b/doc/guides/prog_guide/cmdline.rst index 6b10ab6c99..8aa1ef180b 100644 --- a/doc/guides/prog_guide/cmdline.rst +++ b/doc/guides/prog_guide/cmdline.rst @@ -62,7 +62,7 @@ The format of the list file must follow these requirements: * One command per line -* Variable fields are prefixed by the type-name in angle-brackets, for example: +* Variable fields are prefixed by the type-name in angle-brackets. For example: * ``message`` @@ -75,7 +75,7 @@ The format of the list file must follow these requirements: * ``dst_ip6`` * Variable fields, which take their values from a list of options, - have the comma-separated option list placed in braces, rather than by the type name. + have the comma-separated option list placed in braces rather than by the type name. For example, * ``<(rx,tx,rxtx)>mode`` @@ -112,7 +112,7 @@ The generated content includes: * A command-line context array definition, suitable for passing to ``cmdline_new`` -If so desired, the script can also output function stubs for the callback functions for each command. +If needed, the script can also output function stubs for the callback functions for each command. This behaviour is triggered by passing the ``--stubs`` flag to the script. In this case, an output file must be provided with a filename ending in ".h", and the callback stubs will be written to an equivalent ".c" file. @@ -120,7 +120,7 @@ and the callback stubs will be written to an equivalent ".c" file. .. note:: The stubs are written to a separate file, - to allow continuous use of the script to regenerate the command-line header, + to allow continuous use of the script to regenerate the command-line header without overwriting any code the user has added to the callback functions. This makes it easy to incrementally add new commands to an existing application. @@ -154,7 +154,7 @@ the callback functions would be: These functions must be provided by the developer. However, as stated above, stub functions may be generated by the script automatically using the ``--stubs`` parameter. -The same "cmdname" stem is used in the naming of the generated structures too. +The same "cmdname" stem is used in the naming of the generated structures as well. To get to the results structure for each command above, the ``parsed_result`` parameter should be cast to ``struct cmd_quit_result`` or ``struct cmd_show_port_stats_result`` respectively. @@ -176,13 +176,12 @@ Integrating with the Application ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To integrate the script output with the application, -we must ``#include`` the generated header into our applications C file, +we must ``#include`` the generated header into our application's C file, and then have the command-line created via either ``cmdline_new`` or ``cmdline_stdin_new``. The first parameter to the function call should be the context array in the generated header file, ``ctx`` by default (Modifiable via script parameter). -The callback functions may be in this same file, or in a separate one - -they just need to be available to the linker at build-time. +The callback functions may be in the same or separate file, as long as they are available to the linker at build-time. Limitations of the Script Approach ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -242,19 +241,19 @@ The resulting struct looks like: As before, we choose names to match the tokens in the command. Since our numeric parameter is a 16-bit value, we use ``uint16_t`` type for it. -Any of the standard sized integer types can be used as parameters, depending on the desired result. +Any of the standard-sized integer types can be used as parameters depending on the desired result. Beyond the standard integer types, -the library also allows variable parameters to be of a number of other types, +the library also allows variable parameters to be of a number of other types as called out in the feature list above. * For variable string parameters, the type should be ``cmdline_fixed_string_t`` - the same as for fixed tokens, but these will be initialized differently (as described below). -* For ethernet addresses use type ``struct rte_ether_addr`` +* For ethernet addresses, use type ``struct rte_ether_addr`` -* For IP addresses use type ``cmdline_ipaddr_t`` +* For IP addresses, use type ``cmdline_ipaddr_t`` Providing Field Initializers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -267,6 +266,7 @@ For fixed string tokens, like "quit", "show" and "port", the initializer will be static cmdline_parse_token_string_t cmd_quit_quit_tok = TOKEN_STRING_INITIALIZER(struct cmd_quit_result, quit, "quit"); + The convention for naming used here is to include the base name of the overall result structure - ``cmd_quit`` in this case, as well as the name of the field within that structure - ``quit`` in this case, followed by ``_tok``. @@ -311,8 +311,8 @@ The callback function should have type: where the first parameter is a pointer to the result structure defined above, the second parameter is the command-line instance, and the final parameter is a user-defined pointer provided when we associate the callback with the command. -Most callback functions only use the first parameter, or none at all, -but the additional two parameters provide some extra flexibility, +Most callback functions only use the first parameter or none at all, +but the additional two parameters provide some extra flexibility to allow the callback to work with non-global state in your application. For our two example commands, the relevant callback functions would look very similar in definition. @@ -341,7 +341,7 @@ Associating Callback and Command The ``cmdline_parse_inst_t`` type defines a "parse instance", i.e. a sequence of tokens to be matched and then an associated function to be called. -Also included in the instance type are a field for help text for the command, +Also included in the instance type are a field for help text for the command and any additional user-defined parameter to be passed to the callback functions referenced above. For example, for our simple "quit" command: @@ -362,8 +362,8 @@ then set the user-defined parameter to NULL, provide a help message to be given, on request, to the user explaining the command, before finally listing out the single token to be matched for this command instance. -For our second, port stats, example, -as well as making things a little more complicated by having multiple tokens to be matched, +For our second "port stats" example, +as well as making things more complex by having multiple tokens to be matched, we can also demonstrate passing in a parameter to the function. Let us suppose that our application does not always use all the ports available to it, but instead only uses a subset of the ports, stored in an array called ``active_ports``. From patchwork Fri Jun 21 02:32:53 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nandini Persad X-Patchwork-Id: 141471 X-Patchwork-Delegate: thomas@monjalon.net 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 901DA454B2; Fri, 21 Jun 2024 04:34:05 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 0972842EBD; Fri, 21 Jun 2024 04:33:39 +0200 (CEST) Received: from mail-pf1-f176.google.com (mail-pf1-f176.google.com [209.85.210.176]) by mails.dpdk.org (Postfix) with ESMTP id 317F242EB4 for ; Fri, 21 Jun 2024 04:33:36 +0200 (CEST) Received: by mail-pf1-f176.google.com with SMTP id d2e1a72fcca58-705c739b878so2114761b3a.1 for ; Thu, 20 Jun 2024 19:33:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1718937215; x=1719542015; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=nSHAkYRqu1xy5FbsqsBZDDpNRs9947vCPWN8oWMaLR8=; b=W7s/UHcwxLmM4Y2IRQqndb6HNBtUeVEFRxnM8ZX85aZbBxuzAiWjebQP3Yh6Ii0v2l HfQEfXNiw/t5Hvt5RGYLszxhDC/41kudr27WxU3D4mR+DGZP3VWRS/GxIFfSBj5TAfyt uMOLLRcPVXGPgG9zbRn7tS9BU5G3dlJfl799O2zUg5fbidMYjxgBWPJS4zwC0R+r+hJr 84Z8otZ39s0qqTPfLWds7KmyHLzPHz3fVmDgoNzxwmf7jdxoU4vZki0Fi5eIprGReG+1 F8pBIbLJ0S47IIwtiIKytIZUzkdDvvWHxbk9Jr6zZY5eL4aENPPNwLYtqu6EKl4O6VPg 5AnA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718937215; x=1719542015; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=nSHAkYRqu1xy5FbsqsBZDDpNRs9947vCPWN8oWMaLR8=; b=kNklRpDaRrdwH8pXFeSkPloqbmrBxAVi+QoBc2mPP+EZ1P1GXKhX/Abj0pQGsMklin HLKS+DpExHqu5epc7Ek6Gxa4pj9Xrr4ypGyhG43AZb7pgWCK4HmNagg09LEOaEDOaHjr WO1dGCM3IqwkzJV6h1+ah4s4JbQ8YZVuoD4YNo7T8M6cIok68s5GEk7UAE4h8g/1cKsR iZMapaha0izUBxo+JImYqhsy6M+DbPGQ+HsFE8NdsOe1qchF1KheHIB6Sr+xmkMEN9eB eGrEkdrXmNFSTCJYUsjUmCDUgKBD4e41moFYTbXaf9x8tstaE8tGMQkEG9h49wDuMwyH 8B/w== X-Gm-Message-State: AOJu0YzzqQpe5miUvKBM37O6nEZ8BZhLE9kyKFHMFo9f86/M5HNvhpMf YbuA0V4LjS3LWaIt3TQxpeX8V4Lt8dhCE8GEkW9qE2mAI+9lsCXFUYnR1bds X-Google-Smtp-Source: AGHT+IEsQHDp84cHpbQhPwr3QBSANqt3UdvsuT9v7YDiw4piNzih0TaGNV5eHxtI5OXaghPRYqibFA== X-Received: by 2002:a05:6a20:1a9d:b0:1bc:ad1e:2e6f with SMTP id adf61e73a8af0-1bcba15b446mr9088324637.9.1718937215096; Thu, 20 Jun 2024 19:33:35 -0700 (PDT) Received: from localhost.localdomain (syn-076-032-089-124.res.spectrum.com. [76.32.89.124]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-7065124df73sm334482b3a.110.2024.06.20.19.33.34 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Jun 2024 19:33:34 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Subject: [PATCH v2 8/9] doc: reword stack library section in prog guide Date: Thu, 20 Jun 2024 19:32:53 -0700 Message-Id: <20240621023254.4258-8-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240621023254.4258-1-nandinipersad361@gmail.com> References: <20240513155911.31872-1-nandinipersad361@gmail.com> <20240621023254.4258-1-nandinipersad361@gmail.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 Minor changes made to wording of the stack library section in prog guide. Signed-off-by: Nandini Persad Acked-by: Stephen Hemminger --- doc/guides/prog_guide/stack_lib.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/guides/prog_guide/stack_lib.rst b/doc/guides/prog_guide/stack_lib.rst index 975d3ad796..a51df60d13 100644 --- a/doc/guides/prog_guide/stack_lib.rst +++ b/doc/guides/prog_guide/stack_lib.rst @@ -44,8 +44,8 @@ Lock-free Stack The lock-free stack consists of a linked list of elements, each containing a data pointer and a next pointer, and an atomic stack depth counter. The -lock-free property means that multiple threads can push and pop simultaneously, -and one thread being preempted/delayed in a push or pop operation will not +lock-free property means that multiple threads can push and pop simultaneously. +One thread being preempted/delayed in a push or pop operation will not impede the forward progress of any other thread. The lock-free push operation enqueues a linked list of pointers by pointing the From patchwork Fri Jun 21 02:32:54 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nandini Persad X-Patchwork-Id: 141472 X-Patchwork-Delegate: thomas@monjalon.net 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 C9A3B454B2; Fri, 21 Jun 2024 04:34:14 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id BBE2C42EB4; Fri, 21 Jun 2024 04:33:41 +0200 (CEST) Received: from mail-pg1-f172.google.com (mail-pg1-f172.google.com [209.85.215.172]) by mails.dpdk.org (Postfix) with ESMTP id 73C9E42ECC for ; Fri, 21 Jun 2024 04:33:40 +0200 (CEST) Received: by mail-pg1-f172.google.com with SMTP id 41be03b00d2f7-707040e3018so1094855a12.1 for ; Thu, 20 Jun 2024 19:33:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1718937219; x=1719542019; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=23sti7takF/Vv5vwBLCh4oszsWaDxCMzjvNiozb9dsQ=; b=XEHu0fK9fYziM4Lxm87ZbtlOxJ3us3zZdRcBTlBR/hMsr8SYgBMpXqpihXgh+MCm9X CCbwY4MhycVDSd67U9rLa2fz/4T3Owr1GaovbOTiclHi6Vwz61k/itlZOhMOnvj7YHH2 u1AswR3t0qN6LpslUKb72ahVr06kG6yERN5ReDUUioOmgZ38pG5hWCZkAPhb3RySfCOy WGLGVsdCEKhjKz/y6mdTRbSwTJ1qVEFmgQASCtfwLIS2U67FU1w4yZf5CBsRdmEeb/9G rbwUUMQB3syHX2CQ5atCaRsBABrp3m37Kp6O6+YgHTm4xNCceId+89B2sRdeBegaR8xn Z7hg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718937219; x=1719542019; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=23sti7takF/Vv5vwBLCh4oszsWaDxCMzjvNiozb9dsQ=; b=UKVdnbvRoOmGvvyksQ7DQ42vNhom6IDAW2dzR/Rx+ZWf4zq6WYgdsIS7rQrLkUfusu a24wOT7gnXMOo3YiXv4FL8OHe/t8m8FQdqm5DclEPbjNNBIw9Rc9t9MmPWFNhDq7acRq 97llURebyF2RdrVGDVBpZpc2rlZYrEaeexIN2zrLJx6cNnwXNxCx7SnaLxhu0YGctIsu 3FycA+ZuPoqTr/ODuM5Hchj9dxOA7SGG/oiZIU2EDuMn3O524PhpfH1Dw2ju/UvvcZNu vME6D9KKwhPEhTfYk9guCVq/o0frElKceBCpOu8HcoqEjTtGASYCpDVDDmKK342Qf3tr okDA== X-Gm-Message-State: AOJu0YxqYvlgcFhxWQkCTt8zWcI3LdkOAFIPUseDHkg6iP0dKELeKVa5 Rg5W1xj7iliTWEyHVDKWdOYYzhEc7a+YU5rQTwDCOVPpXiPBZgofvJa/t1Xj X-Google-Smtp-Source: AGHT+IFb57esAFuBmNF/XZdVglm6tc0qDK2AvXbUJKT0hiK/TG/KzSUQnQCz1WTYi2r9pmAk1BljUA== X-Received: by 2002:a05:6a20:1909:b0:1b8:a3f5:3557 with SMTP id adf61e73a8af0-1bcbb41ce74mr7363027637.24.1718937219254; Thu, 20 Jun 2024 19:33:39 -0700 (PDT) Received: from localhost.localdomain (syn-076-032-089-124.res.spectrum.com. [76.32.89.124]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-7065124df73sm334482b3a.110.2024.06.20.19.33.38 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Jun 2024 19:33:38 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Subject: [PATCH v2 9/9] doc: reword rcu library section in prog guide Date: Thu, 20 Jun 2024 19:32:54 -0700 Message-Id: <20240621023254.4258-9-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240621023254.4258-1-nandinipersad361@gmail.com> References: <20240513155911.31872-1-nandinipersad361@gmail.com> <20240621023254.4258-1-nandinipersad361@gmail.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 Simple syntax changes made to the rcu library section in programmer's guide. Signed-off-by: Nandini Persad Acked-by: Stephen Hemminger --- doc/guides/prog_guide/rcu_lib.rst | 77 ++++++++++++++++--------------- 1 file changed, 40 insertions(+), 37 deletions(-) diff --git a/doc/guides/prog_guide/rcu_lib.rst b/doc/guides/prog_guide/rcu_lib.rst index d0aef3bc16..c7ae349184 100644 --- a/doc/guides/prog_guide/rcu_lib.rst +++ b/doc/guides/prog_guide/rcu_lib.rst @@ -8,17 +8,17 @@ RCU Library Lockless data structures provide scalability and determinism. They enable use cases where locking may not be allowed -(for example real-time applications). +(for example, real-time applications). In the following sections, the term "memory" refers to memory allocated by typical APIs like malloc() or anything that is representative of -memory, for example an index of a free element array. +memory. An example of this is an index of a free element array. Since these data structures are lockless, the writers and readers are accessing the data structures concurrently. Hence, while removing an element from a data structure, the writers cannot return the memory -to the allocator, without knowing that the readers are not -referencing that element/memory anymore. Hence, it is required to +to the allocator without knowing that the readers are not +referencing that element/memory anymore. Therefore, it is required to separate the operation of removing an element into two steps: #. Delete: in this step, the writer removes the reference to the element from @@ -64,19 +64,19 @@ quiescent state. Reader thread 3 was not accessing D1 when the delete operation happened. So, reader thread 3 will not have a reference to the deleted entry. -It can be noted that, the critical sections for D2 is a quiescent state -for D1. i.e. for a given data structure Dx, any point in the thread execution -that does not reference Dx is a quiescent state. +Note that the critical sections for D2 is a quiescent state +for D1 (i.e. for a given data structure Dx, any point in the thread execution +that does not reference Dx is a quiescent state). Since memory is not freed immediately, there might be a need for -provisioning of additional memory, depending on the application requirements. +provisioning additional memory depending on the application requirements. Factors affecting the RCU mechanism ----------------------------------- It is important to make sure that this library keeps the overhead of -identifying the end of grace period and subsequent freeing of memory, -to a minimum. The following paras explain how grace period and critical +identifying the end of grace period and subsequent freeing of memory +to a minimum. The following paragraphs explain how grace period and critical section affect this overhead. The writer has to poll the readers to identify the end of grace period. @@ -119,14 +119,14 @@ How to use this library The application must allocate memory and initialize a QS variable. Applications can call ``rte_rcu_qsbr_get_memsize()`` to calculate the size -of memory to allocate. This API takes a maximum number of reader threads, -using this variable, as a parameter. +of memory to allocate. This API takes a maximum number of reader threads +using this variable as a parameter. Further, the application can initialize a QS variable using the API ``rte_rcu_qsbr_init()``. Each reader thread is assumed to have a unique thread ID. Currently, the -management of the thread ID (for example allocation/free) is left to the +management of the thread ID (for example, allocation/free) is left to the application. The thread ID should be in the range of 0 to maximum number of threads provided while creating the QS variable. The application could also use ``lcore_id`` as the thread ID where applicable. @@ -134,13 +134,13 @@ The application could also use ``lcore_id`` as the thread ID where applicable. The ``rte_rcu_qsbr_thread_register()`` API will register a reader thread to report its quiescent state. This can be called from a reader thread. A control plane thread can also call this on behalf of a reader thread. -The reader thread must call ``rte_rcu_qsbr_thread_online()`` API to start +The reader thread must call the ``rte_rcu_qsbr_thread_online()`` API to start reporting its quiescent state. Some of the use cases might require the reader threads to make blocking API -calls (for example while using eventdev APIs). The writer thread should not +calls (for example, while using eventdev APIs). The writer thread should not wait for such reader threads to enter quiescent state. The reader thread must -call ``rte_rcu_qsbr_thread_offline()`` API, before calling blocking APIs. It +call ``rte_rcu_qsbr_thread_offline()`` API before calling blocking APIs. It can call ``rte_rcu_qsbr_thread_online()`` API once the blocking API call returns. @@ -149,13 +149,13 @@ state by calling the API ``rte_rcu_qsbr_start()``. It is possible for multiple writer threads to query the quiescent state status simultaneously. Hence, ``rte_rcu_qsbr_start()`` returns a token to each caller. -The writer thread must call ``rte_rcu_qsbr_check()`` API with the token to -get the current quiescent state status. Option to block till all the reader +The writer thread must call the ``rte_rcu_qsbr_check()`` API with the token to +get the current quiescent state status. The option to block till all the reader threads enter the quiescent state is provided. If this API indicates that all the reader threads have entered the quiescent state, the application can free the deleted entry. -The APIs ``rte_rcu_qsbr_start()`` and ``rte_rcu_qsbr_check()`` are lock free. +The APIs ``rte_rcu_qsbr_start()`` and ``rte_rcu_qsbr_check()`` are lock-free. Hence, they can be called concurrently from multiple writers even while running as worker threads. @@ -173,7 +173,7 @@ polls till all the readers enter the quiescent state or go offline. This API does not allow the writer to do useful work while waiting and introduces additional memory accesses due to continuous polling. However, the application does not have to store the token or the reference to the deleted resource. The -resource can be freed immediately after ``rte_rcu_qsbr_synchronize()`` API +resource can be freed immediately after the ``rte_rcu_qsbr_synchronize()`` API returns. The reader thread must call ``rte_rcu_qsbr_thread_offline()`` and @@ -181,9 +181,9 @@ The reader thread must call ``rte_rcu_qsbr_thread_offline()`` and quiescent state. The ``rte_rcu_qsbr_check()`` API will not wait for this reader thread to report the quiescent state status anymore. -The reader threads should call ``rte_rcu_qsbr_quiescent()`` API to indicate that +The reader threads should call the ``rte_rcu_qsbr_quiescent()`` API to indicate that they entered a quiescent state. This API checks if a writer has triggered a -quiescent state query and update the state accordingly. +quiescent state query and updates the state accordingly. The ``rte_rcu_qsbr_lock()`` and ``rte_rcu_qsbr_unlock()`` are empty functions. However, these APIs can aid in debugging issues. One can mark the access to @@ -203,40 +203,43 @@ the application. When a writer deletes an entry from a data structure, the write There are several APIs provided to help with this process. The writer can create a FIFO to store the references to deleted resources using ``rte_rcu_qsbr_dq_create()``. The resources can be enqueued to this FIFO using ``rte_rcu_qsbr_dq_enqueue()``. -If the FIFO is full, ``rte_rcu_qsbr_dq_enqueue`` will reclaim the resources before enqueuing. It will also reclaim resources on regular basis to keep the FIFO from growing too large. If the writer runs out of resources, the writer can call ``rte_rcu_qsbr_dq_reclaim`` API to reclaim resources. ``rte_rcu_qsbr_dq_delete`` is provided to reclaim any remaining resources and free the FIFO while shutting down. +If the FIFO is full, ``rte_rcu_qsbr_dq_enqueue`` will reclaim the resources before enqueuing. +It will also reclaim resources on regular basis to keep the FIFO from growing too large. If the writer runs out of resources, the writer can call ``rte_rcu_qsbr_dq_reclaim`` API to reclaim resources. ``rte_rcu_qsbr_dq_delete`` is provided to reclaim any remaining resources and free the FIFO while shutting down. However, if this resource reclamation process were to be integrated in lock-free data structure libraries, it -hides this complexity from the application and makes it easier for the application to adopt lock-free algorithms. The following paragraphs discuss how the reclamation process can be integrated in DPDK libraries. +hides this complexity from the application and makes it easier for the application to adopt lock-free algorithms. + +The following paragraphs discuss how the reclamation process can be integrated in DPDK libraries. In any DPDK application, the resource reclamation process using QSBR can be split into 4 parts: #. Initialization #. Quiescent State Reporting -#. Reclaiming Resources +#. Reclaiming Resources* #. Shutdown The design proposed here assigns different parts of this process to client libraries and applications. The term 'client library' refers to lock-free data structure libraries such at rte_hash, rte_lpm etc. in DPDK or similar libraries outside of DPDK. The term 'application' refers to the packet processing application that makes use of DPDK such as L3 Forwarding example application, OVS, VPP etc.. -The application has to handle 'Initialization' and 'Quiescent State Reporting'. So, +The application must handle 'Initialization' and 'Quiescent State Reporting'. Therefore, the application: -* the application has to create the RCU variable and register the reader threads to report their quiescent state. -* the application has to register the same RCU variable with the client library. -* reader threads in the application have to report the quiescent state. This allows for the application to control the length of the critical section/how frequently the application wants to report the quiescent state. +* Must create the RCU variable and register the reader threads to report their quiescent state. +* Must register the same RCU variable with the client library. +* Note that reader threads in the application have to report the quiescent state. This allows for the application to control the length of the critical section/how frequently the application wants to report the quiescent state. -The client library will handle 'Reclaiming Resources' part of the process. The +The client library will handle the 'Reclaiming Resources' part of the process. The client libraries will make use of the writer thread context to execute the memory -reclamation algorithm. So, +reclamation algorithm. So, the client library should: -* client library should provide an API to register a RCU variable that it will use. It should call ``rte_rcu_qsbr_dq_create()`` to create the FIFO to store the references to deleted entries. -* client library should use ``rte_rcu_qsbr_dq_enqueue`` to enqueue the deleted resources on the FIFO and start the grace period. -* if the library runs out of resources while adding entries, it should call ``rte_rcu_qsbr_dq_reclaim`` to reclaim the resources and try the resource allocation again. +* Provide an API to register a RCU variable that it will use. It should call ``rte_rcu_qsbr_dq_create()`` to create the FIFO to store the references to deleted entries. +* Use ``rte_rcu_qsbr_dq_enqueue`` to enqueue the deleted resources on the FIFO and start the grace period. +* Note that if the library runs out of resources while adding entries, it should call ``rte_rcu_qsbr_dq_reclaim`` to reclaim the resources and try the resource allocation again. The 'Shutdown' process needs to be shared between the application and the -client library. +client library. Note that: -* the application should make sure that the reader threads are not using the shared data structure, unregister the reader threads from the QSBR variable before calling the client library's shutdown function. +* The application should make sure that the reader threads are not using the shared data structure, unregister the reader threads from the QSBR variable before calling the client library's shutdown function. -* client library should call ``rte_rcu_qsbr_dq_delete`` to reclaim any remaining resources and free the FIFO. +* The client library should call ``rte_rcu_qsbr_dq_delete`` to reclaim any remaining resources and free the FIFO. Integrating the resource reclamation with client libraries removes the burden from the application and makes it easy to use lock-free algorithms.