From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 5083745ACE; Mon, 7 Oct 2024 01:45:33 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 3111D40A67; Mon, 7 Oct 2024 01:45:33 +0200 (CEST) Received: from mail-pl1-f177.google.com (mail-pl1-f177.google.com [209.85.214.177]) by mails.dpdk.org (Postfix) with ESMTP id 7DD3540265 for ; Mon, 7 Oct 2024 01:45:30 +0200 (CEST) Received: by mail-pl1-f177.google.com with SMTP id d9443c01a7336-20b01da232aso29508565ad.1 for ; Sun, 06 Oct 2024 16:45:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1728258330; x=1728863130; darn=dpdk.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=pElV6j2q57yRgzJ19zKDKx8aX67I5ZR985oj3e+tsyQ=; b=DGIlup8eKwsjcNmKMKVkbO2jgzWSiIUZwlb9bA0yok56PXV+KzCJBpX5IdiDgCjYf/ +jx2AHlkkm1pjeulSbOiz5nyNQ6LkqQfjOro2MJg0XkrSO+sIPcnP7ssyWw6nAKQspG1 76b7fiSj9P7H4YvOLXDoaCp9vVNjJHZ2YiVggEV3qI6jhbl4NuZMK9DN3e0VHiJx+DSX 6ByrInfZXskPmkpq3m37Y/F3VGvs44L9dthrF1hMJGQRh8r9shx9zP0pW39PTjy8zBCZ 4+sWWIBPxMuByG41f+wlIJnCNyMLKE4Z2V6HbQlT7VL4ggLhkgYCNhN9Hn+d5hKHUyak Tg0g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1728258330; x=1728863130; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=pElV6j2q57yRgzJ19zKDKx8aX67I5ZR985oj3e+tsyQ=; b=OWJxqQuSgkaU21DXnIxkms+nmGlwFrXk9Q+MBsmgnobznqPV7sjtQXWG/ZGJLbr2iZ qxTxYv53waPn01YzPlsQLQD66/nuzlPQjBhUrzt+cZBWnCRFi3xxJDCSpHwGMgRYMMeG ojLTnjBnPN0i5NMTCRUFZw2Goe7lJHpWY1u6tMFGxmJFCf89HIwu0BQbX5wBQht7ysef 8gw61tUGFxElfAG2ycm3bf28STlydJQ3TJ2sZSHE9fKpn+UG6tftdYQJex2fQvlPlc16 3Z582ei24fHP5KrTlsdDTSkV5SqrArceliDKc6MlQOIsH/nhpjtsdKtdMr2a9nTVxf6v 9LAw== X-Gm-Message-State: AOJu0Yyc2SfNeK/DFznmeVoYulFpCl2TAtdbXM+k6X/MV2KYUohz6slV 2++YiRZWU1vjNKbhdPD+F0whL6XESqBvu0Hx/HF1otPcM97ms5KU X-Google-Smtp-Source: AGHT+IEOIbi9qndW3i3/6ZAxw15n4G6gGq6dGraVQUs9aj1QekJFu4CaKgngXK5JWPCmTK0LyTgsYA== X-Received: by 2002:a17:903:2349:b0:20b:a9b2:b558 with SMTP id d9443c01a7336-20be199e341mr205093305ad.28.1728258328107; Sun, 06 Oct 2024 16:45:28 -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 d9443c01a7336-20c13930872sm29400085ad.172.2024.10.06.16.45.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 06 Oct 2024 16:45:27 -0700 (PDT) From: Nandini Persad To: Thomas Monjalon , Ferruh Yigit , Andrew Rybchenko , Chengwen Feng , Kevin Laatz , Bruce Richardson , Ori Kam , Konstantin Ananyev , John McNamara Cc: dev@dpdk.org Subject: [PATCH v2] doc: reword sample app guides Date: Sun, 6 Oct 2024 16:45:17 -0700 Message-Id: <20241006234517.55303-1-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit 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 reviewed these sections for grammar/clarity and made small modifications to the formatting of sections to adhere to a template which will create uniformality in the sample application user guides overall. Signed-off-by: Nandini Persad --- .../prog_guide/switch_representation.rst | 18 +++--- .../traffic_metering_and_policing.rst | 4 +- doc/guides/sample_app_ug/cmd_line.rst | 24 ++++---- doc/guides/sample_app_ug/dma.rst | 38 ++++++------- doc/guides/sample_app_ug/ethtool.rst | 13 +++-- doc/guides/sample_app_ug/flow_filtering.rst | 50 +++++++++-------- doc/guides/sample_app_ug/hello_world.rst | 6 +- doc/guides/sample_app_ug/intro.rst | 20 +++---- doc/guides/sample_app_ug/ip_frag.rst | 11 ++-- doc/guides/sample_app_ug/ip_reassembly.rst | 38 +++++++------ doc/guides/sample_app_ug/ipv4_multicast.rst | 39 ++++++------- doc/guides/sample_app_ug/keep_alive.rst | 10 ++-- .../sample_app_ug/l2_forward_crypto.rst | 29 +++++----- .../sample_app_ug/l2_forward_job_stats.rst | 56 +++++++++++-------- doc/guides/sample_app_ug/rxtx_callbacks.rst | 21 ++++--- doc/guides/sample_app_ug/skeleton.rst | 30 +++++----- 16 files changed, 223 insertions(+), 184 deletions(-) diff --git a/doc/guides/prog_guide/switch_representation.rst b/doc/guides/prog_guide/switch_representation.rst index 46e0ca85a5..98c2830b03 100644 --- a/doc/guides/prog_guide/switch_representation.rst +++ b/doc/guides/prog_guide/switch_representation.rst @@ -15,8 +15,8 @@ Network adapters with multiple physical ports and/or SR-IOV capabilities usually support the offload of traffic steering rules between their virtual functions (VFs), sub functions (SFs), physical functions (PFs) and ports. -Like for standard Ethernet switches, this involves a combination of -automatic MAC learning and manual configuration. For most purposes it is +For standard Ethernet switches, this involves a combination of +automatic MAC learning and manual configuration. For most purposes, it is managed by the host system and fully transparent to users and applications. On the other hand, applications typically found on hypervisors that process @@ -26,23 +26,23 @@ according on their own criteria. Without a standard software interface to manage traffic steering rules between VFs, SFs, PFs and the various physical ports of a given device, applications cannot take advantage of these offloads; software processing is -mandatory even for traffic which ends up re-injected into the device it +mandatory, even for traffic, which ends up re-injected into the device it originates from. This document describes how such steering rules can be configured through the DPDK flow API (**rte_flow**), with emphasis on the SR-IOV use case -(PF/VF steering) using a single physical port for clarity, however the same +(PF/VF steering) using a single physical port for clarity. However, the same logic applies to any number of ports without necessarily involving SR-IOV. Sub Function ------------ -Besides SR-IOV, Sub function is a portion of the PCI device, a SF netdev -has its own dedicated queues(txq, rxq). A SF netdev supports E-Switch +Besides SR-IOV, Sub function is a portion of the PCI device and a SF netdev +has its own dedicated queues (txq, rxq). A SF netdev supports E-Switch representation offload similar to existing PF and VF representors. A SF shares PCI level resources with other SFs and/or with its parent PCI function. -Sub function is created on-demand, coexists with VFs. Number of SFs is +Sub function is created on-demand and coexists with VFs. The number of SFs is limited by hardware resources. Port Representors @@ -80,7 +80,7 @@ thought as a software "patch panel" front-end for applications. -a pci:dbdf,representor=[pf[0-1],pf2vf[0-2],pf3[3,5]] - As virtual devices, they may be more limited than their physical - counterparts, for instance by exposing only a subset of device + counterparts. For instance, by exposing only a subset of device configuration callbacks and/or by not necessarily having Rx/Tx capability. - Among other things, they can be used to assign MAC addresses to the @@ -100,7 +100,7 @@ thought as a software "patch panel" front-end for applications. - The device or group relationship of ports can be discovered using the switch ``domain_id`` field within the devices switch information structure. By - default the switch ``domain_id`` of a port will be + default, the switch ``domain_id`` of a port will be ``RTE_ETH_DEV_SWITCH_DOMAIN_ID_INVALID`` to indicate that the port doesn't support the concept of a switch domain, but ports which do support the concept will be allocated a unique switch ``domain_id``, ports within the same switch diff --git a/doc/guides/prog_guide/traffic_metering_and_policing.rst b/doc/guides/prog_guide/traffic_metering_and_policing.rst index 2e8f419f97..d288dc0f9f 100644 --- a/doc/guides/prog_guide/traffic_metering_and_policing.rst +++ b/doc/guides/prog_guide/traffic_metering_and_policing.rst @@ -48,7 +48,7 @@ red) based on the previous history for this flow as maintained by the MTR object. The policer can do nothing, override the color the packet or drop the packet. Statistics counters are maintained for MTR object, as configured. -The processing done for each input packet hitting an MTR object is: +The processing for each input packet hitting an MTR object is: * Traffic metering: The packet is assigned a color (the meter output color) based on the previous traffic history reflected in the current state of the @@ -118,7 +118,7 @@ Protocol based input color selection ------------------------------------ The API supports selecting the input color based on the packet content. -Following is the API usage model for the same. +The following is the API usage model for the same purpose. #. Probe the protocol based input color selection device capabilities using the following parameters with ``rte_mtr_capabilities_get()`` API. diff --git a/doc/guides/sample_app_ug/cmd_line.rst b/doc/guides/sample_app_ug/cmd_line.rst index 6655b1e5a7..72ce5fc27f 100644 --- a/doc/guides/sample_app_ug/cmd_line.rst +++ b/doc/guides/sample_app_ug/cmd_line.rst @@ -13,7 +13,7 @@ Overview The Command Line sample application is a simple application that demonstrates the use of the command line interface in the DPDK. This application is a readline-like interface that can be used -to debug a DPDK application, in a Linux* application environment. +to debug a DPDK application in a Linux* application environment. .. note:: @@ -22,10 +22,13 @@ to debug a DPDK application, in a Linux* application environment. See also the "rte_cmdline library should not be used in production code due to limited testing" item in the "Known Issues" section of the Release Notes. -The Command Line sample application supports some of the features of the GNU readline library such as, completion, -cut/paste and some other special bindings that make configuration and debug faster and easier. +The Command Line sample application supports some of the features of +the GNU readline library such as completion, cut/paste and other +special bindings that make configuration and debug faster and easier. + +The application shows how the rte_cmdline application can be extended +to handle a list of objects. -The application shows how the rte_cmdline application can be extended to handle a list of objects. There are three simple commands: * add obj_name IP: Add a new object with an IP/IPv6 address associated to it. @@ -48,7 +51,7 @@ The application is located in the ``cmd_line`` sub-directory. Running the Application ----------------------- -To run the application in linux environment, issue the following command: +To run the application in a linux environment, issue the following command: .. code-block:: console @@ -60,7 +63,7 @@ and the Environment Abstraction Layer (EAL) options. Explanation ----------- -The following sections provide some explanation of the code. +The following sections provide explanation of the code. EAL Initialization and cmdline Start ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -73,7 +76,7 @@ This is achieved as follows: :start-after: Initialization of the Environment Abstraction Layer (EAL). 8< :end-before: >8 End of initialization of Environment Abstraction Layer (EAL). -Then, a new command line object is created and started to interact with the user through the console: +Then, a new command line object is created and starts to interact with the user through the console: .. literalinclude:: ../../../examples/cmdline/main.c :language: c @@ -81,13 +84,14 @@ Then, a new command line object is created and started to interact with the user :end-before: >8 End of creating a new command line object. :dedent: 1 -The cmd line_interact() function returns when the user types **Ctrl-d** and in this case, -the application exits. +The cmd line_interact() function returns when the user types **Ctrl-d** and, +in this case, the application exits. Defining a cmdline Context ~~~~~~~~~~~~~~~~~~~~~~~~~~ -A cmdline context is a list of commands that are listed in a NULL-terminated table, for example: +A cmdline context is a list of commands that are listed in a NULL-terminated table. +For example: .. literalinclude:: ../../../examples/cmdline/commands.c :language: c diff --git a/doc/guides/sample_app_ug/dma.rst b/doc/guides/sample_app_ug/dma.rst index 2765895564..701d09d1b3 100644 --- a/doc/guides/sample_app_ug/dma.rst +++ b/doc/guides/sample_app_ug/dma.rst @@ -10,10 +10,10 @@ Overview -------- This sample is intended as a demonstration of the basic components of a DPDK -forwarding application and example of how to use the DMAdev API to make a packet +forwarding application and an example of how to use the DMAdev API to make a packet copy application. -Also while forwarding, the MAC addresses are affected as follows: +Also, while forwarding, the MAC addresses are affected as follows: * The source MAC address is replaced by the TX port MAC address @@ -27,7 +27,7 @@ received/send packets and packets dropped or failed to copy. Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. The application is located in the ``dma`` sub-directory. @@ -38,7 +38,7 @@ Running the Application In order to run the hardware copy application, the copying device needs to be bound to user-space IO driver. -Refer to the "DMAdev library" chapter in the "Programmers guide" for information +Refer to the "DMAdev library" chapter in the Programmer's guide for information on using the library. The application requires a number of command line options: @@ -70,11 +70,11 @@ where, * i SI: set the interval, in second, between statistics prints (default is 1) -The application can be launched in various configurations depending on +The application can be launched in various configurations depending on the provided parameters. The app can use up to 2 lcores: one of them receives incoming traffic and makes a copy of each packet. The second lcore then -updates MAC address and sends the copy. If one lcore per port is used, -both operations are done sequentially. For each configuration an additional +updates the MAC address and sends the copy. If one lcore per port is used, +both operations are done sequentially. For each configuration, an additional lcore is needed since the main lcore does not handle traffic but is responsible for configuration, statistics printing and safe shutdown of all ports and devices. @@ -159,7 +159,7 @@ multiple DMA channels per port: :end-before: >8 End of configuring port to use RSS for multiple RX queues. :dedent: 1 -For this example the ports are set up with the number of Rx queues provided +For this example, the ports are set up with the number of Rx queues provided with -q option and 1 Tx queue using the ``rte_eth_rx_queue_setup()`` and ``rte_eth_tx_queue_setup()`` functions. @@ -172,7 +172,7 @@ The Ethernet port is then started: :dedent: 1 -Finally the Rx port is set in promiscuous mode: +Finally, the Rx port is set in promiscuous mode: .. literalinclude:: ../../../examples/dma/dmafwd.c :language: c @@ -181,7 +181,7 @@ Finally the Rx port is set in promiscuous mode: :dedent: 1 -After that each port application assigns resources needed. +After that, each port application assigns resources needed. .. literalinclude:: ../../../examples/dma/dmafwd.c :language: c @@ -224,7 +224,7 @@ using ``rte_dma_start()`` function. Each of the above operations is done in If initialization is successful, memory for hardware device statistics is allocated. -Finally ``main()`` function starts all packet handling lcores and starts +Finally, the ``main()`` function starts all packet handling lcores and starts printing stats in a loop on the main lcore. The application can be interrupted and closed using ``Ctrl-C``. The main lcore waits for all worker lcores to finish, deallocates resources and exits. @@ -273,13 +273,13 @@ packet using ``pktmbuf_sw_copy()`` function and enqueue them to an rte_ring: :dedent: 0 The packets are received in burst mode using ``rte_eth_rx_burst()`` -function. When using hardware copy mode the packets are enqueued in +function. When using hardware copy mode the packets are enqueued in the copying device's buffer using ``dma_enqueue_packets()`` which calls ``rte_dma_copy()``. When all received packets are in the -buffer the copy operations are started by calling ``rte_dma_submit()``. +buffer, the copy operations are started by calling ``rte_dma_submit()``. Function ``rte_dma_copy()`` operates on physical address of the packet. Structure ``rte_mbuf`` contains only physical address to -start of the data buffer (``buf_iova``). Thus the ``rte_pktmbuf_iova()`` API is +start of the data buffer (``buf_iova``). Thus, the ``rte_pktmbuf_iova()`` API is used to get the address of the start of the data within the mbuf. .. literalinclude:: ../../../examples/dma/dmafwd.c @@ -291,11 +291,11 @@ used to get the address of the start of the data within the mbuf. Once the copies have been completed (this includes gathering the completions in HW copy mode), the copied packets are enqueued to the ``rx_to_tx_ring``, which -is used to pass the packets to the TX function. +is used to pass the packets to the Tx function. All completed copies are processed by ``dma_tx_port()`` function. This function -dequeues copied packets from the ``rx_to_tx_ring``. Then each packet MAC address is changed -if it was enabled. After that copies are sent in burst mode using ``rte_eth_tx_burst()``. +dequeues copied packets from the ``rx_to_tx_ring``. Then, each packet MAC address is changed +if it was enabled. After that. copies are sent in burst mode using ``rte_eth_tx_burst()``. .. literalinclude:: ../../../examples/dma/dmafwd.c @@ -307,7 +307,7 @@ if it was enabled. After that copies are sent in burst mode using ``rte_eth_tx_b The Packet Copying Functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In order to perform SW packet copy, there are user-defined functions to first copy +In order to perform SW packet copy, there are user-defined functions to the first copy the packet metadata (``pktmbuf_metadata_copy()``) and then the packet data (``pktmbuf_sw_copy()``): @@ -321,5 +321,5 @@ The metadata in this example is copied from ``rx_descriptor_fields1`` marker of ``rte_mbuf`` struct up to ``buf_len`` member. In order to understand why software packet copying is done as shown -above please refer to the "Mbuf Library" section of the +above, please refer to the "Mbuf Library" section of the *DPDK Programmer's Guide*. diff --git a/doc/guides/sample_app_ug/ethtool.rst b/doc/guides/sample_app_ug/ethtool.rst index 159e9e0639..433175368b 100644 --- a/doc/guides/sample_app_ug/ethtool.rst +++ b/doc/guides/sample_app_ug/ethtool.rst @@ -4,6 +4,12 @@ Ethtool Sample Application ========================== +This chapter describes the Ethrool sample application that +is part of the Data Plane Development Kit (DPDK). + +Overview +-------- + The Ethtool sample application shows an implementation of an ethtool-like API and provides a console environment that allows its use to query and change Ethernet card parameters. The sample @@ -30,17 +36,14 @@ Refer to the *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options. -Using the application ---------------------- - The application is console-driven using the cmdline DPDK interface: .. code-block:: console EthApp> -From this interface the available commands and descriptions of what -they do as follows: +From this interface, the available commands and descriptions of what +they do are as follows: * ``drvinfo``: Print driver info * ``eeprom``: Dump EEPROM to file diff --git a/doc/guides/sample_app_ug/flow_filtering.rst b/doc/guides/sample_app_ug/flow_filtering.rst index 8cac2f8a8f..2cf7973852 100644 --- a/doc/guides/sample_app_ug/flow_filtering.rst +++ b/doc/guides/sample_app_ug/flow_filtering.rst @@ -4,16 +4,20 @@ Basic RTE Flow Filtering Sample Application =========================================== -The Basic RTE flow filtering sample application is a simple example of a + +Overview +-------- + +The Basic RTE flow filtering sample application is a simple example of creating a RTE flow rule. -It is intended as a demonstration of the basic components RTE flow rules. +It demonstrates the basic components of RTE flow rules. Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. Running the Application @@ -33,7 +37,7 @@ Explanation ----------- The example is built from 2 files, -``main.c`` which holds the example logic and ``flow_blocks.c`` that holds the +``main.c`` which holds the example logic and ``flow_blocks.c`` holds the implementation for building the flow rule. The following sections provide an explanation of the main components of the @@ -49,7 +53,7 @@ The Main Function The ``main()`` function located in ``main.c`` file performs the initialization and runs the main loop function. -The first task is to initialize the Environment Abstraction Layer (EAL). The +The first task is to initialize the Environment Abstraction Layer (EAL). The ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()`` function. The value returned is the number of parsed arguments: @@ -90,8 +94,8 @@ following code: :end-before: >8 End of creating flow for send packet with. :dedent: 1 -In the last part the application is ready to launch the -``main_loop()`` function. Which is explained below. +In the last part, the application is ready to launch the +``main_loop()`` function, which is explained below. .. literalinclude:: ../../../examples/flow_filtering/main.c @@ -100,8 +104,9 @@ In the last part the application is ready to launch the :end-before: >8 End of launching main_loop(). :dedent: 1 -The Port Initialization Function -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Port Initialization Function +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The main functional part of the port initialization used in the flow filtering application is shown below: @@ -120,7 +125,7 @@ The Ethernet port is configured with default settings using the :end-before: >8 End of ethernet port configured with default settings. :dedent: 1 -For this example we are configuring number of rx and tx queues that are connected +For this example, we are configuring a number of Rx and Tx queues that are connected to a single port. .. literalinclude:: ../../../examples/flow_filtering/main.c @@ -129,8 +134,8 @@ to a single port. :end-before: >8 End of Configuring RX and TX queues connected to single port. :dedent: 1 -In the next step we create and apply the flow rule. which is to send packets -with destination ip equals to 192.168.1.1 to queue number 1. The detail +In the next step, we create and apply the flow rule to send packets +with destination IP equal to 192.168.1.1 to queue number 1. A detailed explanation of the ``generate_ipv4_flow()`` appears later in this document: .. literalinclude:: ../../../examples/flow_filtering/main.c @@ -159,8 +164,8 @@ The last step is to start the port. The main_loop function ~~~~~~~~~~~~~~~~~~~~~~ -As we saw above the ``main()`` function calls an application function to handle -the main loop. For the flow filtering application the main_loop function +As we saw above, the ``main()`` function calls an application function to handle +the main loop. For the flow filtering application, the main_loop function looks like the following: .. literalinclude:: ../../../examples/flow_filtering/main.c @@ -169,7 +174,7 @@ looks like the following: :end-before: >8 End of reading the packets from all queues. The main work of the application is reading the packets from all -queues and printing for each packet the destination queue: +queues and printing each packet from the destination queue: .. literalinclude:: ../../../examples/flow_filtering/main.c :language: c @@ -178,9 +183,10 @@ queues and printing for each packet the destination queue: The forwarding loop can be interrupted and the application closed using -``Ctrl-C``. Which results in closing the port and the device using +``Ctrl-C`` which results in closing the port and the device using ``rte_eth_dev_stop`` and ``rte_eth_dev_close`` + The generate_ipv4_flow function ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -200,7 +206,7 @@ The first part of the function is declaring the structures that will be used. :end-before: >8 End of declaring structs being used. :dedent: 1 -The following part create the flow attributes, in our case ingress. +The following part creates the flow attributes. In this case, ingress. .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c :language: c @@ -209,7 +215,7 @@ The following part create the flow attributes, in our case ingress. :dedent: 1 The third part defines the action to be taken when a packet matches -the rule. In this case send the packet to queue. +the rule. In this case, send the packet to queue. .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c :language: c @@ -217,10 +223,10 @@ the rule. In this case send the packet to queue. :end-before: >8 End of setting the rule attribute. The fourth part is responsible for creating the pattern and is built from -number of steps. In each step we build one level of the pattern starting with +number of steps. In each step, we build one level of the pattern starting with the lowest one. -Setting the first level of the pattern ETH: +Set the first level of the pattern ETH: .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c :language: c @@ -228,7 +234,7 @@ Setting the first level of the pattern ETH: :end-before: >8 End of setting the first level of the pattern. :dedent: 1 -Setting the second level of the pattern IP: +Set the second level of the pattern IP: .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c :language: c @@ -236,7 +242,7 @@ Setting the second level of the pattern IP: :end-before: >8 End of setting the second level of the pattern. :dedent: 1 -Closing the pattern part. +Close the pattern part: .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c :language: c diff --git a/doc/guides/sample_app_ug/hello_world.rst b/doc/guides/sample_app_ug/hello_world.rst index c4db52c6a1..f4f83efac4 100644 --- a/doc/guides/sample_app_ug/hello_world.rst +++ b/doc/guides/sample_app_ug/hello_world.rst @@ -4,6 +4,10 @@ Hello World Sample Application ============================== + +Overview +-------- + The Hello World sample application is an example of the simplest DPDK application that can be written. The application simply prints an "helloworld" message on every enabled lcore. @@ -29,7 +33,7 @@ and the Environment Abstraction Layer (EAL) options. Explanation ----------- -The following sections provide some explanation of code. +The following sections provide an explanation of the code required to start and use the application. EAL Initialization ~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/sample_app_ug/intro.rst b/doc/guides/sample_app_ug/intro.rst index e765f1fd6b..41378118bc 100644 --- a/doc/guides/sample_app_ug/intro.rst +++ b/doc/guides/sample_app_ug/intro.rst @@ -4,9 +4,9 @@ Introduction to the DPDK Sample Applications ============================================ -The DPDK Sample Applications are small standalone applications which +The DPDK Sample Applications are small standalone applications that demonstrate various features of DPDK. They can be considered as a cookbook of -DPDK features. Users interested in getting started with DPDK can take the +DPDK features. Users interested in getting started with DPDK can take the applications, try out the features, and then extend them to fit their needs. @@ -14,7 +14,7 @@ Running Sample Applications --------------------------- Some sample applications may have their own command-line parameters described in -their respective guides, however all of them also share the same EAL parameters. +their respective guides. However, they all also share the same EAL parameters. Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>` or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for a list of available EAL command-line options. @@ -24,16 +24,16 @@ The DPDK Sample Applications ---------------------------- There are many sample applications available in the examples directory of DPDK. -These examples range from simple to reasonably complex but most are designed +These examples range from simple to reasonably complex, but most are designed to demonstrate one particular feature of DPDK. Some of the more interesting examples are highlighted below. * :doc:`Hello World`: As with most introductions to a - programming framework a good place to start is with the Hello World + programming framework, a good place to start is with the Hello World application. The Hello World example sets up the DPDK Environment Abstraction Layer (EAL), and prints a simple "Hello World" message to each of the DPDK - enabled cores. This application doesn't do any packet forwarding but it is a + enabled cores. This application doesn't do any packet forwarding, but it is a good way to test if the DPDK environment is compiled and set up properly. * :doc:`Basic Forwarding/Skeleton Application`: The Basic @@ -72,19 +72,19 @@ examples are highlighted below. * :doc:`RX/TX callbacks Application`: The RX/TX callbacks sample application is a packet forwarding application that - demonstrates the use of user defined callbacks on received and transmitted + demonstrates the use of user-defined callbacks on received and transmitted packets. The application calculates the latency of a packet between RX (packet arrival) and TX (packet transmission) by adding callbacks to the RX and TX packet processing functions. * :doc:`IPsec Security Gateway`: The IPsec Security - Gateway application is minimal example of something closer to a real world + Gateway application is a minimal example of something close to a real world example. This is also a good example of an application using the DPDK Cryptodev framework. * :doc:`Precision Time Protocol (PTP) client`: The PTP client is another minimal implementation of a real world application. - In this case the application is a PTP client that communicates with a PTP + In this case, the application is a PTP client that communicates with a PTP master clock to synchronize time on a Network Interface Card (NIC) using the IEEE1588 protocol. @@ -93,4 +93,4 @@ examples are highlighted below. There are many more examples shown in the following chapters. Each of the documented sample applications show how to compile, configure and run the -application as well as explaining the main functionality of the code. +application, as well as explaining the main functionality of the code. diff --git a/doc/guides/sample_app_ug/ip_frag.rst b/doc/guides/sample_app_ug/ip_frag.rst index 5fdeb2a84e..39e3f6b1dd 100644 --- a/doc/guides/sample_app_ug/ip_frag.rst +++ b/doc/guides/sample_app_ug/ip_frag.rst @@ -25,17 +25,18 @@ There are three key differences from the L2 Forwarding sample application: * The third difference is that the application differentiates between IP and non-IP traffic by means of offload flags. -The Longest Prefix Match (LPM for IPv4, LPM6 for IPv6) table is used to store/lookup an outgoing port number, -associated with that IP address. +The Longest Prefix Match (LPM for IPv4, LPM6 for IPv6) table is used to store/lookup an +outgoing port number associated with that IP address. Any unmatched packets are forwarded to the originating port. By default, input frame sizes up to 9.5 KB are supported. -Before forwarding, the input IP packet is fragmented to fit into the "standard" Ethernet* v2 MTU (1500 bytes). +Before forwarding, the input IP packet is fragmented to fit into the "standard" Ethernet* +v2 MTU (1500 bytes). Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. The application is located in the ``ip_fragmentation`` sub-directory. @@ -46,7 +47,7 @@ The LPM object is created and loaded with the pre-configured entries read from global l3fwd_ipv4_route_array and l3fwd_ipv6_route_array tables. For each input packet, the packet forwarding decision (that is, the identification of the output interface for the packet) is taken as a result of LPM lookup. -If the IP packet size is greater than default output MTU, +If the IP packet size is greater than the default output MTU, then the input packet is fragmented and several fragments are sent via the output interface. Application usage: diff --git a/doc/guides/sample_app_ug/ip_reassembly.rst b/doc/guides/sample_app_ug/ip_reassembly.rst index 5280bf4ea0..a15d6751fb 100644 --- a/doc/guides/sample_app_ug/ip_reassembly.rst +++ b/doc/guides/sample_app_ug/ip_reassembly.rst @@ -30,7 +30,7 @@ associated with that IPv4 address. Any unmatched packets are forwarded to the or Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. The application is located in the ``ip_reassembly`` sub-directory. @@ -57,7 +57,7 @@ where: then they are considered as invalid and will be dropped. Valid range is 1ms - 3600s. Default value: 1s. -To run the example in linux environment with 2 lcores (2,4) over 2 ports(0,2) with 1 RX queue per lcore: +To run the example in a linux environment with 2 lcores (2,4) over 2 ports(0,2) with 1 RX queue per lcore: .. code-block:: console @@ -88,7 +88,7 @@ To run the example in linux environment with 2 lcores (2,4) over 2 ports(0,2) wi IP_RSMBL: entering main loop on lcore 2 IP_RSMBL: -- lcoreid=2 portid=0 -To run the example in linux environment with 1 lcore (4) over 2 ports(0,2) with 2 RX queues per lcore: +To run the example in a linux environment with 1 lcore (4) over 2 ports(0,2) with 2 RX queues per lcore: .. code-block:: console @@ -100,7 +100,7 @@ l3fwd_ipv4_route_array and/or l3fwd_ipv6_route_array table. Please note that in order to test this application, the traffic generator should be generating valid fragmented IP packets. For IPv6, the only supported case is when no other extension headers other than -fragment extension header are present in the packet. +the fragment extension header are present in the packet. The default l3fwd_ipv4_route_array table is: @@ -123,19 +123,21 @@ once all the fragments are collected. Explanation ----------- -The following sections provide some explanation of the sample application code. -As mentioned in the overview section, the initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`. +The following sections provide in-depth explanation of the sample application code. +As mentioned in the overview section, the initialization and run-time paths are very +similar to those of the :doc:`l2_forward_real_virtual`. The following sections describe aspects that are specific to the IP reassemble sample application. IPv4 Fragment Table Initialization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This application uses the rte_ip_frag library. Please refer to Programmer's Guide for more detailed explanation of how to use this library. -Fragment table maintains information about already received fragments of the packet. +This application uses the rte_ip_frag library. Please refer to Programmer's Guide for more +detailed explanation of how to use this library. +The Fragment table maintains information about already received fragments of the packet. Each IP packet is uniquely identified by triple , , . -To avoid lock contention, each RX queue has its own Fragment Table, -e.g. the application can't handle the situation when different fragments of the same packet arrive through different RX queues. -Each table entry can hold information about packet consisting of up to RTE_LIBRTE_IP_FRAG_MAX_FRAGS fragments. +To avoid lock contention, each RX queue has its own Fragment Table. The application +cannot handle when different fragments of the same packet arrive through different Rx queues. +Each table entry can hold information about packets consisting of up to RTE_LIBRTE_IP_FRAG_MAX_FRAGS fragments. .. literalinclude:: ../../../examples/ip_reassembly/main.c :language: c @@ -147,10 +149,10 @@ Mempools Initialization ~~~~~~~~~~~~~~~~~~~~~~~ The reassembly application demands a lot of mbuf's to be allocated. -At any given time up to (2 \* max_flow_num \* RTE_LIBRTE_IP_FRAG_MAX_FRAGS \* ) -can be stored inside Fragment Table waiting for remaining fragments. -To keep mempool size under reasonable limits and to avoid situation when one RX queue can starve other queues, -each RX queue uses its own mempool. +At any given time, up to (2 \* max_flow_num \* RTE_LIBRTE_IP_FRAG_MAX_FRAGS \* ) +can be stored inside the Fragment Table waiting for remaining fragments. +To keep mempool size under reasonable limits and to avoid a situation when one Rx queue can starve other queues, +each Rx queue uses its own mempool. .. literalinclude:: ../../../examples/ip_reassembly/main.c :language: c @@ -164,9 +166,9 @@ Packet Reassembly and Forwarding For each input packet, the packet forwarding operation is done by the l3fwd_simple_forward() function. If the packet is an IPv4 or IPv6 fragment, then it calls rte_ipv4_reassemble_packet() for IPv4 packets, or rte_ipv6_reassemble_packet() for IPv6 packets. -These functions either return a pointer to valid mbuf that contains reassembled packet, +These functions either return a pointer to a valid mbuf that contains a reassembled packet, or NULL (if the packet can't be reassembled for some reason). -Then l3fwd_simple_forward() continues with the code for the packet forwarding decision +Then, l3fwd_simple_forward() continues with the code for the packet forwarding decision (that is, the identification of the output interface for the packet) and actual transmit of the packet. @@ -204,5 +206,5 @@ This macro is disabled by default, but it can be enabled by modifying the approp in ``config/rte_config.h``. To make ip_reassembly print the statistics to the standard output, the user must send either an USR1, INT or TERM signal to the process. -For all of these signals, the ip_reassembly process prints Fragment table statistics for each RX queue, +For all of these signals, the ip_reassembly process prints Fragment table statistics for each Rx queue, plus the INT and TERM will cause process termination as usual. diff --git a/doc/guides/sample_app_ug/ipv4_multicast.rst b/doc/guides/sample_app_ug/ipv4_multicast.rst index b8d0b1429a..23843a1a4f 100644 --- a/doc/guides/sample_app_ug/ipv4_multicast.rst +++ b/doc/guides/sample_app_ug/ipv4_multicast.rst @@ -21,7 +21,7 @@ There are two key differences from the L2 Forwarding sample application: * The forwarding decision is taken based on information read from the input packet's IPv4 header. The lookup method is the Four-byte Key (FBK) hash-based method. -The lookup table is composed of pairs of destination IPv4 address (the FBK) +The lookup table is composed of pairs of destination IPv4 addresses (the FBK) and a port mask associated with that IPv4 address. By default, the following IP addresses and their respective port masks are added: @@ -38,14 +38,15 @@ By default, the following IP addresses and their respective port masks are added For convenience and simplicity, this sample application does not take IANA-assigned multicast addresses into account, but instead equates the last four bytes of the multicast group (that is, the last four bytes of the destination IP address) -with the mask of ports to multicast packets to. +with the mask of ports to multicast packets. + Also, the application does not consider the Ethernet addresses; it looks only at the IPv4 destination address for any given packet. Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. The application is located in the ``ipv4_multicast`` sub-directory. @@ -91,7 +92,7 @@ and the Environment Abstraction Layer (EAL) options. Explanation ----------- -The following sections provide some explanation of the code. +The following sections explain the code needed for this sample application. As mentioned in the overview section, the initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`. The following sections describe aspects that are specific to the IPv4 Multicast sample application. @@ -109,8 +110,8 @@ Memory pools for indirect buffers are initialized differently from the memory po :end-before: >8 End of create mbuf pools. :dedent: 1 -The reason for this is because indirect buffers are not supposed to hold any packet data and -therefore can be initialized with lower amount of reserved memory for each buffer. +The reason for this is that indirect buffers are not supposed to hold any packet data and +therefore can be initialized with the lower amount of reserved memory for each buffer. Hash Initialization ~~~~~~~~~~~~~~~~~~~ @@ -143,7 +144,7 @@ if the routing table has any ports assigned to the destination address: :end-before: >8 End of valid multicast address check. :dedent: 1 -Then, the number of ports in the destination portmask is calculated with the help of the bitcnt() function: +Next, the number of ports in the destination portmask is calculated with the help of the bitcnt() function: .. literalinclude:: ../../../examples/ipv4_multicast/main.c :language: c @@ -170,7 +171,7 @@ with the Ethernet address 01:00:5e:00:00:00, as per RFC 1112: :start-after: Construct Ethernet multicast address from IPv4 multicast Address. 8< :end-before: >8 End of Construction of multicast address from IPv4 multicast address. -Then, packets are dispatched to the destination ports according to the portmask associated with a multicast group: +Packets are then dispatched to the destination ports according to the portmask associated with a multicast group: .. literalinclude:: ../../../examples/ipv4_multicast/main.c :language: c @@ -188,36 +189,36 @@ The actual packet transmission is done in the mcast_send_pkt() function: Buffer Cloning ~~~~~~~~~~~~~~ -This is the most important part of the application since it demonstrates the use of zero- copy buffer cloning. -There are two approaches for creating the outgoing packet and although both are based on the data zero-copy idea, -there are some differences in the detail. +This is the most important part of the application since it demonstrates the use of zero-copy buffer cloning. +There are two approaches for creating the outgoing packet. Although both are based on the data zero-copy idea, +there are some differences in the details. -The first approach creates a clone of the input packet, for example, +The first approach creates a clone of the input packet. for example, walk though all segments of the input packet and for each of segment, create a new buffer and attach that new buffer to the segment (refer to rte_pktmbuf_clone() in the rte_mbuf library for more details). A new buffer is then allocated for the packet header and is prepended to the cloned buffer. -The second approach does not make a clone, it just increments the reference counter for all input packet segment, +The second approach does not make a clone. It simply increments the reference counter for all input packet segments, allocates a new buffer for the packet header and prepends it to the input packet. Basically, the first approach reuses only the input packet's data, but creates its own copy of packet's metadata. The second approach reuses both input packet's data and metadata. -The advantage of first approach is that each outgoing packet has its own copy of the metadata, +The advantage of the first approach is that each outgoing packet has its own copy of the metadata, so we can safely modify the data pointer of the input packet. That allows us to skip creation if the output packet is for the last destination port -and instead modify input packet's header in place. +and, instead, modify the input packet's header in place. For example, for N destination ports, we need to invoke mcast_out_pkt() (N-1) times. -The advantage of the second approach is that there is less work to be done for each outgoing packet, -that is, the "clone" operation is skipped completely. +The advantage of the second approach is that there is less work to be done for each outgoing packet. +The "clone" operation is skipped completely. However, there is a price to pay. -The input packet's metadata must remain intact, so for N destination ports, +The input packet's metadata must remain intact. For N destination ports, we need to invoke mcast_out_pkt() (N) times. Therefore, for a small number of outgoing ports (and segments in the input packet), -first approach is faster. +the first approach is faster. As the number of outgoing ports (and/or input segments) grows, the second approach becomes more preferable. Depending on the number of segments or the number of ports in the outgoing portmask, diff --git a/doc/guides/sample_app_ug/keep_alive.rst b/doc/guides/sample_app_ug/keep_alive.rst index a907ff36a1..79bdc531aa 100644 --- a/doc/guides/sample_app_ug/keep_alive.rst +++ b/doc/guides/sample_app_ug/keep_alive.rst @@ -38,7 +38,7 @@ of the L2 forwarding application. Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. The application is located in the ``l2fwd_keep_alive`` sub-directory. @@ -78,7 +78,7 @@ options. Explanation ----------- -The following sections provide some explanation of the +The following sections provide explanation of the Keep-Alive/'Liveliness' conceptual scheme. As mentioned in the overview section, the initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`. @@ -89,10 +89,10 @@ The Keep-Alive/'Liveliness' conceptual scheme: * DPDK Cores respond to the keep-alive agent. -* If keep-alive agent detects time-outs, it notifies the +* If a keep-alive agent detects time-outs, it notifies the fault management entity through a callback function. -The following sections provide some explanation of the code aspects +The following sections provide explanation of the code aspects that are specific to the Keep Alive sample application. The keepalive functionality is initialized with a struct @@ -114,7 +114,7 @@ is configured to run every check_period milliseconds. :end-before: >8 End of issuing the pings keepalive_dispatch_pings(). :dedent: 2 -The rest of the initialization and run-time path follows +The rest of the initialization and run-time paths follow the same paths as the L2 forwarding application. The only addition to the main processing loop is the mark alive functionality and the example random failures. diff --git a/doc/guides/sample_app_ug/l2_forward_crypto.rst b/doc/guides/sample_app_ug/l2_forward_crypto.rst index ce49eab96f..c9226ce578 100644 --- a/doc/guides/sample_app_ug/l2_forward_crypto.rst +++ b/doc/guides/sample_app_ug/l2_forward_crypto.rst @@ -6,20 +6,21 @@ L2 Forwarding with Crypto Sample Application ============================================ -The L2 Forwarding with Crypto (l2fwd-crypto) sample application is a simple example of packet processing using -the Data Plane Development Kit (DPDK), in conjunction with the Cryptodev library. +The L2 Forwarding with Crypto (l2fwd-crypto) sample application is a simple example +of packet processing using the Data Plane Development Kit (DPDK) in conjunction with +the Cryptodev library. Overview -------- The L2 Forwarding with Crypto sample application performs a crypto operation (cipher/hash) -specified by the user from command line (or using the default values), +specified by the user from the command line (or using the default values), with a crypto device capable of doing that operation, for each packet that is received on an RX_PORT and performs L2 forwarding. -The destination port is the adjacent port from the enabled portmask, that is, -if the first four ports are enabled (portmask 0xf), +The destination port is the adjacent port from the enabled portmask. +If the first four ports are enabled (portmask 0xf), ports 0 and 1 forward into each other, and ports 2 and 3 forward into each other. -Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows: +If the MAC addresses updating is enabled, the MAC addresses are affected as follows: * The source MAC address is replaced by the TX_PORT MAC address @@ -28,7 +29,7 @@ Also, if MAC addresses updating is enabled, the MAC addresses are affected as fo Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. The application is located in the ``l2fwd-crypt`` sub-directory. @@ -161,7 +162,7 @@ the specified crypto operation are available on application initialization. This means that HW crypto device/s must be bound to a DPDK driver or a SW crypto device/s (virtual crypto PMD) must be created (using --vdev). -To run the application in linux environment with 2 lcores, 2 ports and 2 crypto devices, issue the command: +To run the application in Linux environment with 2 lcores, 2 ports and 2 crypto devices, issue the command: .. code-block:: console @@ -199,12 +200,12 @@ from reception until transmission. Encryption flow through the L2 Forwarding with Crypto Application -The following sections provide some explanation of the application. +The following sections provide explanation of the application. Crypto operation specification ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -All the packets received in all the ports get transformed by the crypto device/s +All the packets received in all the ports get transformed by the crypto devices (ciphering and/or authentication). The crypto operation to be performed on the packet is parsed from the command line. (Go to "Running the Application" section for all the options.) @@ -228,16 +229,16 @@ There are two methods to pass keys, IV and ADD from the command line: --cipher_key_random_size 16 **Note**: - If full key is passed (first method) and the size is passed as well (second method), + If the full key is passed (first method) and the size is passed as well (second method), the latter will be ignored. -Size of these keys are checked (regardless the method), before starting the app, +The size of these keys are checked (regardless of the method) before starting the app, to make sure that it is supported by the crypto devices. Crypto device initialization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once the encryption operation is defined, crypto devices are initialized. +Once the encryption operation is defined, the crypto devices are initialized. The crypto devices must be either bound to a DPDK driver (if they are physical devices) or created using the EAL option --vdev (if they are virtual devices), when running the application. @@ -278,7 +279,7 @@ Session creation ~~~~~~~~~~~~~~~~ The crypto operation has a crypto session associated to it, which contains -information such as the transform chain to perform (e.g. ciphering then hashing), +information such as the transform chain to perform (e.g. ciphering then hashing) pointers to the keys, lengths... etc. This session is created and is later attached to the crypto operation: diff --git a/doc/guides/sample_app_ug/l2_forward_job_stats.rst b/doc/guides/sample_app_ug/l2_forward_job_stats.rst index 349ad56ec6..f90da8ee6c 100644 --- a/doc/guides/sample_app_ug/l2_forward_job_stats.rst +++ b/doc/guides/sample_app_ug/l2_forward_job_stats.rst @@ -19,10 +19,11 @@ Overview The L2 Forwarding sample application, which can operate in real and virtualized environments, performs L2 forwarding for each packet that is received. -The destination port is the adjacent port from the enabled portmask, that is, -if the first four ports are enabled (portmask 0xf), +The destination port is the adjacent port from the enabled portmask +if: the first four ports are enabled (portmask 0xf), ports 1 and 2 forward into each other, and ports 3 and 4 forward into each other. -Also, the MAC addresses are affected as follows: + +The MAC addresses are affected as follows: * The source MAC address is replaced by the TX port MAC address @@ -51,8 +52,8 @@ Virtual Function Setup Instructions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This application can use the virtual function available in the system and -therefore can be used in a virtual machine without passing through -the whole Network Device into a guest machine in a virtualized scenario. +can be used in a virtual machine without passing through +the whole Network Device into a guest machine when in a virtualized scenario. The virtual functions can be enabled in the host machine or the hypervisor with the respective physical function driver. For example, in a Linux* host machine, it is possible to enable a virtual function using the following command: @@ -65,15 +66,17 @@ This command enables two Virtual Functions on each of Physical Function of the N with two physical ports in the PCI configuration space. It is important to note that enabled Virtual Function 0 and 2 would belong to Physical Function 0 and Virtual Function 1 and 3 would belong to Physical Function 1, -in this case enabling a total of four Virtual Functions. +enabling a total of four Virtual Functions (in this case). + Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. The application is located in the ``l2fwd-jobstats`` sub-directory. + Running the Application ----------------------- @@ -91,8 +94,8 @@ where, * l: Use locale thousands separator when formatting big numbers. -To run the application in linux environment with 4 lcores, 16 ports, 8 RX queues per lcore and -thousands separator printing, issue the command: +To run the application in a linux environment with 4 lcores, 16 ports, 8 RX queues per lcore and +thousands separator printing, issue the command: .. code-block:: console @@ -101,22 +104,24 @@ thousands separator printing, issue the command: Refer to the *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options. + Explanation ----------- -The following sections provide some explanation of the code. +The following sections provide explanation of the code. + Command Line Arguments ~~~~~~~~~~~~~~~~~~~~~~ -The L2 Forwarding sample application takes specific parameters, +The L2 Forwarding sample application takes specific parameters in addition to Environment Abstraction Layer (EAL) arguments (see `Running the Application`_). The preferred way to parse parameters is to use the getopt() function, since it is part of a well-defined and portable library. The parsing of arguments is done in the l2fwd_parse_args() function. -The method of argument parsing is not described here. +This method of argument parsing is not described here. Refer to the *glibc getopt(3)* man page for details. EAL arguments are parsed first, then application-specific arguments. @@ -255,7 +260,7 @@ Main loop ~~~~~~~~~ The forwarding path is reworked comparing to original L2 Forwarding application. -In the l2fwd_main_loop() function three loops are placed. +In the l2fwd_main_loop() function, three loops are placed. .. literalinclude:: ../../../examples/l2fwd-jobstats/main.c :language: c @@ -263,15 +268,20 @@ In the l2fwd_main_loop() function three loops are placed. :end-before: >8 End of minimize impact of stats reading. :dedent: 1 -First infinite for loop is to minimize impact of stats reading. Lock is only locked/unlocked when asked. +The first infinite for loop is to minimize impact of stats reading. Lock is only locked/unlocked +when asked. + +Second inner while loop do the whole jobs management. When any job is ready, +the use rte_timer_manage() is used to call the job handler. -Second inner while loop do the whole jobs management. When any job is ready, the use rte_timer_manage() is used to call the job handler. -In this place functions l2fwd_fwd_job() and l2fwd_flush_job() are called when needed. -Then rte_jobstats_context_finish() is called to mark loop end - no other jobs are ready to execute. By this time stats are ready to be read +In this place, functions l2fwd_fwd_job() and l2fwd_flush_job() are called when needed. +Then, rte_jobstats_context_finish() is called to mark loop end - no other jobs are ready to execute. +By this time, stats are ready to be read and if stats_read_pending is set, loop breaks allowing stats to be read. -Third do-while loop is the idle job (idle stats counter). Its only purpose is monitoring if any job is ready or stats job read is pending -for this lcore. Statistics from this part of code is considered as the headroom available for additional processing. +Third do-while loop is the idle job (idle stats counter). Its only purpose is monitoring if any job is +ready or stats job read is pending for this lcore. Statistics from this part of the code is considered as +the headroom available for additional processing. Receive, Process and Transmit Packets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -291,7 +301,7 @@ The processing is very simple: process the TX port from the RX port, then replac The rte_eth_rx_burst() function writes the mbuf pointers in a local table and returns the number of available mbufs in the table. -After first read second try is issued. +After first read, a second try is issued. .. literalinclude:: ../../../examples/l2fwd-jobstats/main.c :language: c @@ -299,7 +309,7 @@ After first read second try is issued. :end-before: >8 End of read second try. :dedent: 1 -This second read is important to give job stats library a feedback how many packets was processed. +This second read is important to give the job stats library feedback of how many packets were processed. .. literalinclude:: ../../../examples/l2fwd-jobstats/main.c :language: c @@ -307,8 +317,8 @@ This second read is important to give job stats library a feedback how many pack :end-before: >8 End of adjust period time in which we are running. :dedent: 1 -To maximize performance exactly MAX_PKT_BURST is expected (the target value) to be read for each l2fwd_fwd_job() call. -If total_nb_rx is smaller than target value job->period will be increased. If it is greater the period will be decreased. +To maximize performance, exactly MAX_PKT_BURST is expected (the target value) to be read for each l2fwd_fwd_job() call. +If total_nb_rx is smaller than target value job->period will be increased. If it is greater, the period will be decreased. .. note:: diff --git a/doc/guides/sample_app_ug/rxtx_callbacks.rst b/doc/guides/sample_app_ug/rxtx_callbacks.rst index f06c5c866a..ddec20cf69 100644 --- a/doc/guides/sample_app_ug/rxtx_callbacks.rst +++ b/doc/guides/sample_app_ug/rxtx_callbacks.rst @@ -4,24 +4,29 @@ RX/TX Callbacks Sample Application ================================== + +Overview +-------- + The RX/TX Callbacks sample application is a packet forwarding application that demonstrates the use of user defined callbacks on received and transmitted packets. The application performs a simple latency check, using callbacks, to -determine the time packets spend within the application. +determine the time that packets spend within the application. -In the sample application a user defined callback is applied to all received +In the sample application, a user defined callback is applied to all received packets to add a timestamp. A separate callback is applied to all packets -prior to transmission to calculate the elapsed time, in CPU cycles. +prior to transmission to calculate the elapsed time in CPU cycles. If hardware timestamping is supported by the NIC, the sample application will -also display the average latency since the packet was timestamped in hardware, +also display the average latency. The packet was timestamped in hardware on top of the latency since the packet was received and processed by the RX callback. + Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. The application is located in the ``rxtx_callbacks`` sub-directory. @@ -66,8 +71,8 @@ The main difference is in the user defined ``port_init()`` function where the callbacks are added. This is explained in the next section: -The Port Initialization Function -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The Port Initialization Function +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The main functional part of the port initialization is shown below with comments: @@ -122,5 +127,5 @@ packets prior to transmission: The ``calc_latency()`` function accumulates the total number of packets and the total number of cycles used. Once more than 100 million packets have been -transmitted the average cycle count per packet is printed out and the counters +transmitted, the average cycle count per packet is printed out and the counters are reset. diff --git a/doc/guides/sample_app_ug/skeleton.rst b/doc/guides/sample_app_ug/skeleton.rst index 08ddd7aa59..cb7ff6da4b 100644 --- a/doc/guides/sample_app_ug/skeleton.rst +++ b/doc/guides/sample_app_ug/skeleton.rst @@ -7,14 +7,17 @@ Basic Forwarding Sample Application The Basic Forwarding sample application is a simple *skeleton* example of a forwarding application. -It is intended as a demonstration of the basic components of a DPDK forwarding -application. For more detailed implementations see the L2 and L3 forwarding +Overview +-------- + +This application demonstrates the basic components of a DPDK forwarding +application. For more detailed implementations, see the L2 and L3 forwarding sample applications. Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. The application is located in the ``skeleton`` sub-directory. @@ -28,7 +31,7 @@ To run the example in a ``linux`` environment: .//examples/dpdk-skeleton -l 1 -n 4 Refer to *DPDK Getting Started Guide* for general information on running -applications and the Environment Abstraction Layer (EAL) options. +applications and Environment Abstraction Layer (EAL) options. Explanation @@ -47,8 +50,8 @@ The Main Function The ``main()`` function performs the initialization and calls the execution threads for each lcore. -The first task is to initialize the Environment Abstraction Layer (EAL). The -``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()`` +The first task is to initialize the Environment Abstraction Layer (EAL). +The ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()`` function. The value returned is the number of parsed arguments: .. literalinclude:: ../../../examples/skeleton/basicfwd.c @@ -80,7 +83,7 @@ The ``main()`` function also initializes all the ports using the user defined :dedent: 1 Once the initialization is complete, the application is ready to launch a -function on an lcore. In this example ``lcore_main()`` is called on a single +function on an lcore. In this example, ``lcore_main()`` is called on a single lcore. @@ -93,9 +96,8 @@ lcore. The ``lcore_main()`` function is explained below. - -The Port Initialization Function -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The Port Initialization Function +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The main functional part of the port initialization used in the Basic Forwarding application is shown below: @@ -108,7 +110,7 @@ Forwarding application is shown below: The Ethernet ports are configured with default settings using the ``rte_eth_dev_configure()`` function. -For this example the ports are set up with 1 RX and 1 TX queue using the +In this example, the ports are set up with 1 RX and 1 TX queue using the ``rte_eth_rx_queue_setup()`` and ``rte_eth_tx_queue_setup()`` functions. The Ethernet port is then started: @@ -120,7 +122,7 @@ The Ethernet port is then started: :dedent: 1 -Finally the RX port is set in promiscuous mode: +Finally, the RX port is set in promiscuous mode: .. literalinclude:: ../../../examples/skeleton/basicfwd.c :language: c @@ -132,8 +134,8 @@ Finally the RX port is set in promiscuous mode: The Lcores Main ~~~~~~~~~~~~~~~ -As we saw above the ``main()`` function calls an application function on the -available lcores. For the Basic Forwarding application the lcore function +As we saw above, the ``main()`` function calls an application function on the +available lcores. For the Basic Forwarding application, the lcore function looks like the following: .. literalinclude:: ../../../examples/skeleton/basicfwd.c -- 2.34.1