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 3027E45AE0; Tue, 8 Oct 2024 05:34:08 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id B9976400D7; Tue, 8 Oct 2024 05:34:07 +0200 (CEST) Received: from szxga05-in.huawei.com (szxga05-in.huawei.com [45.249.212.191]) by mails.dpdk.org (Postfix) with ESMTP id 53EA54003C for ; Tue, 8 Oct 2024 05:34:05 +0200 (CEST) Received: from mail.maildlp.com (unknown [172.19.88.163]) by szxga05-in.huawei.com (SkyGuard) with ESMTP id 4XN1jg0ftfz1HKgF; Tue, 8 Oct 2024 11:29:59 +0800 (CST) Received: from dggpeml500024.china.huawei.com (unknown [7.185.36.10]) by mail.maildlp.com (Postfix) with ESMTPS id 6682818002B; Tue, 8 Oct 2024 11:34:03 +0800 (CST) Received: from [10.67.121.161] (10.67.121.161) by dggpeml500024.china.huawei.com (7.185.36.10) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2507.39; Tue, 8 Oct 2024 11:34:03 +0800 Message-ID: Date: Tue, 8 Oct 2024 11:34:02 +0800 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH v2] doc: reword sample app guides To: Nandini Persad , Thomas Monjalon , Ferruh Yigit , Andrew Rybchenko , Kevin Laatz , Bruce Richardson , Ori Kam , Konstantin Ananyev , John McNamara CC: References: <20241006234517.55303-1-nandinipersad361@gmail.com> Content-Language: en-US From: fengchengwen In-Reply-To: <20241006234517.55303-1-nandinipersad361@gmail.com> Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 7bit X-Originating-IP: [10.67.121.161] X-ClientProxiedBy: dggems702-chm.china.huawei.com (10.3.19.179) To dggpeml500024.china.huawei.com (7.185.36.10) 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 Hi Nandini, For dma.rst, there are two minor comments, with that fixed, please add: Acked-by: Chengwen Feng Thanks On 2024/10/7 7:45, Nandini Persad wrote: > 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/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 Refer to the "Direct Memory Access (DMA) Device 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()``. a comma should place after "After that" > > > .. 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 ...