From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 75CBDA6A for ; Mon, 2 Mar 2015 20:02:40 +0100 (CET) Received: from orsmga002.jf.intel.com ([10.7.209.21]) by orsmga103.jf.intel.com with ESMTP; 02 Mar 2015 11:00:16 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.09,676,1418112000"; d="scan'208";a="692857024" Received: from irsmsx152.ger.corp.intel.com ([163.33.192.66]) by orsmga002.jf.intel.com with ESMTP; 02 Mar 2015 11:02:37 -0800 Received: from irsmsx109.ger.corp.intel.com ([169.254.13.103]) by IRSMSX152.ger.corp.intel.com ([169.254.6.205]) with mapi id 14.03.0195.001; Mon, 2 Mar 2015 19:02:33 +0000 From: "Butler, Siobhan A" To: "Mcnamara, John" , "dev@dpdk.org" Thread-Topic: [dpdk-dev] [PATCH 3/3] doc: add docs for the rxtx_callbacks sample app Thread-Index: AQHQUTPvBW0MxjQGs0GW1CewgC4fOJ0JlHBQ Date: Mon, 2 Mar 2015 19:02:33 +0000 Message-ID: <0C5AFCA4B3408848ADF2A3073F7D8CC86D51AA17@IRSMSX109.ger.corp.intel.com> References: <1424893562-8740-1-git-send-email-john.mcnamara@intel.com> <1424893562-8740-4-git-send-email-john.mcnamara@intel.com> In-Reply-To: <1424893562-8740-4-git-send-email-john.mcnamara@intel.com> Accept-Language: en-IE, en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-originating-ip: [163.33.239.181] Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Subject: Re: [dpdk-dev] [PATCH 3/3] doc: add docs for the rxtx_callbacks sample app X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 02 Mar 2015 19:02:41 -0000 > -----Original Message----- > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of John McNamara > Sent: Wednesday, February 25, 2015 7:46 PM > To: dev@dpdk.org > Subject: [dpdk-dev] [PATCH 3/3] doc: add docs for the rxtx_callbacks samp= le > app >=20 > Added a sample application guide for the rxtx_callbacks app. >=20 > Signed-off-by: John McNamara > --- > MAINTAINERS | 1 + > doc/guides/sample_app_ug/index.rst | 1 + > doc/guides/sample_app_ug/rxtx_callbacks.rst | 251 > +++++++++++++++++++++++++++ > 3 files changed, 253 insertions(+), 0 deletions(-) create mode 100644 > doc/guides/sample_app_ug/rxtx_callbacks.rst >=20 > diff --git a/MAINTAINERS b/MAINTAINERS > index 86c1c6b..2ddb312 100644 > --- a/MAINTAINERS > +++ b/MAINTAINERS > @@ -443,6 +443,7 @@ F: doc/guides/sample_app_ug/quota_watermark.rst > M: Bruce Richardson > M: John McNamara > F: examples/rxtx_callbacks/ > +F: doc/guides/sample_app_ug/rxtx_callbacks.rst >=20 > M: Bruce Richardson > M: John McNamara diff --git > a/doc/guides/sample_app_ug/index.rst > b/doc/guides/sample_app_ug/index.rst > index 4e9d59b..4a86459 100644 > --- a/doc/guides/sample_app_ug/index.rst > +++ b/doc/guides/sample_app_ug/index.rst > @@ -44,6 +44,7 @@ Sample Applications User Guide > exception_path > hello_world > skeleton > + rxtx_callbacks > ip_frag > ipv4_multicast > ip_reassembly > diff --git a/doc/guides/sample_app_ug/rxtx_callbacks.rst > b/doc/guides/sample_app_ug/rxtx_callbacks.rst > new file mode 100644 > index 0000000..9df57ed > --- /dev/null > +++ b/doc/guides/sample_app_ug/rxtx_callbacks.rst > @@ -0,0 +1,251 @@ > +.. BSD LICENSE > + Copyright(c) 2015 Intel Corporation. All rights reserved. > + All rights reserved. > + > + Redistribution and use in source and binary forms, with or without > + modification, are permitted provided that the following conditions > + are met: > + > + * Redistributions of source code must retain the above copyright > + notice, this list of conditions and the following disclaimer. > + * Redistributions in binary form must reproduce the above copyright > + notice, this list of conditions and the following disclaimer in > + the documentation and/or other materials provided with the > + distribution. > + * Neither the name of Intel Corporation nor the names of its > + contributors may be used to endorse or promote products derived > + from this software without specific prior written permission. > + > + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND > CONTRIBUTORS > + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT > NOT > + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND > FITNESS FOR > + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE > COPYRIGHT > + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, > INCIDENTAL, > + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT > NOT > + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS > OF USE, > + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED > AND ON ANY > + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT > + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF > THE USE > + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH > DAMAGE. > + > + > +RX/TX Callbacks Sample Application > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +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 with= in > the application. > + > +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. > + > + > +Compiling the Application > +------------------------- > + > +To compile the application export the path to the DPDK source tree and > +go to the example directory: > + > +.. code-block:: console > + > + export RTE_SDK=3D/path/to/rte_sdk > + > + cd ${RTE_SDK}/examples/rxtx_callbacks > + > + > +Set the target, for example: > + > +.. code-block:: console > + > + export RTE_TARGET=3Dx86_64-native-linuxapp-gcc > + > +See the *DPDK Getting Started* Guide for possible ``RTE_TARGET`` values. > + > +The callbacks feature requires that the > +``CONFIG_RTE_ETHDEV_RXTX_CALLBACKS`` > +setting is on in the ``config/common_`` config file that applies to the > +target. This is generally on by default: > + > +.. code-block:: console > + > + CONFIG_RTE_ETHDEV_RXTX_CALLBACKS=3Dy > + > +Build the application as follows: > + > +.. code-block:: console > + > + make > + > + > +Running the Application > +----------------------- > + > +To run the example in a ``linuxapp`` environment: > + > +.. code-block:: console > + > + ./build/rxtx_callbacks -c 2 -n 4 > + > +Refer to *DPDK Getting Started Guide* for general information on > +running applications and the Environment Abstraction Layer (EAL) options= . > + > + > + > +Explanation > +----------- > + > +The ``rxtx_callbacks`` application is mainly a simple forwarding > +application based on the :doc:`skeleton`. See that section of the > +documentation for more details of the forwarding part of the application= . > + > +The sections below explain the additional RX/TX callback code. > + > + > +The Main Function > +~~~~~~~~~~~~~~~~~ > + > +The ``main()`` function performs the application initialization and > +calls the execution threads for each lcore. This function is > +effectively identical to the ``main()`` function explained in :doc:`skel= eton`. > + > +The ``lcore_main()`` function is also identical. > + > +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 main functional part of the port initialization is shown below with > +comments: > + > +.. code-block:: c > + > + static inline int > + port_init(uint8_t port, struct rte_mempool *mbuf_pool) > + { > + struct rte_eth_conf port_conf =3D port_conf_default; > + const uint16_t rx_rings =3D 1, tx_rings =3D 1; > + struct ether_addr addr; > + int retval; > + uint16_t q; > + > + if (port >=3D rte_eth_dev_count()) > + return -1; > + > + /* Configure the Ethernet device. */ > + retval =3D rte_eth_dev_configure(port, rx_rings, tx_rings, &port= _conf); > + if (retval !=3D 0) > + return retval; > + > + /* Allocate and set up 1 RX queue per Ethernet port. */ > + for (q =3D 0; q < rx_rings; q++) { > + retval =3D rte_eth_rx_queue_setup(port, q, RX_RING_SIZE, > + rte_eth_dev_socket_id(port), NULL, mbuf_pool); > + if (retval < 0) > + return retval; > + } > + > + /* Allocate and set up 1 TX queue per Ethernet port. */ > + for (q =3D 0; q < tx_rings; q++) { > + retval =3D rte_eth_tx_queue_setup(port, q, TX_RING_SIZE, > + rte_eth_dev_socket_id(port), NULL); > + if (retval < 0) > + return retval; > + } > + > + /* Start the Ethernet port. */ > + retval =3D rte_eth_dev_start(port); > + if (retval < 0) > + return retval; > + > + /* Enable RX in promiscuous mode for the Ethernet device. */ > + rte_eth_promiscuous_enable(port); > + > + > + /* Add the callbacks for RX and TX.*/ > + rte_eth_add_rx_callback(port, 0, add_timestamps, NULL); > + rte_eth_add_tx_callback(port, 0, calc_latency, NULL); > + > + return 0; > + } > + > + > +The RX and TX callbacks are added to the ports/queues as function pointe= rs: > + > +.. code-block:: c > + > + rte_eth_add_rx_callback(port, 0, add_timestamps, NULL); > + rte_eth_add_tx_callback(port, 0, calc_latency, NULL); > + > +More than one callback can be added and additional information can be > +passed to callback function pointers as a ``void*``. In the examples > +above ``NULL`` is used. > + > +The ``add_timestamps()`` and ``calc_latency()`` functions are explained > below. > + > + > +The add_timestamps() Callback > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +The ``add_timestamps()`` callback is added to the RX port and is > +applied to all packets received: > + > +.. code-block:: c > + > + static uint16_t > + add_timestamps(uint8_t port __rte_unused, uint16_t qidx > __rte_unused, > + struct rte_mbuf **pkts, uint16_t nb_pkts, void *_ __rte_unus= ed) > + { > + unsigned i; > + uint64_t now =3D rte_rdtsc(); > + > + for (i =3D 0; i < nb_pkts; i++) > + pkts[i]->udata64 =3D now; > + > + return nb_pkts; > + } > + > +The DPDK function ``rte_rdtsc()`` is used to add a cycle count > +timestamp to each packet (see the *cycles* section of the *DPDK API > +Documentation* for details). > + > + > +The calc_latency() Callback > +~~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +The ``calc_latency()`` callback is added to the TX port and is applied > +to all packets prior to transmission: > + > +.. code-block:: c > + > + static uint16_t > + calc_latency(uint8_t port __rte_unused, uint16_t qidx __rte_unused, > + struct rte_mbuf **pkts, uint16_t nb_pkts, void *_ __rte_unus= ed) > + { > + uint64_t cycles =3D 0; > + uint64_t now =3D rte_rdtsc(); > + unsigned i; > + > + for (i =3D 0; i < nb_pkts; i++) > + cycles +=3D now - pkts[i]->udata64; > + > + latency_numbers.total_cycles +=3D cycles; > + latency_numbers.total_pkts +=3D nb_pkts; > + > + if (latency_numbers.total_pkts > (100 * 1000 * 1000ULL)) { > + printf("Latency =3D %"PRIu64" cycles\n", > + latency_numbers.total_cycles / > + latency_numbers.total_pkts); > + > + latency_numbers.total_cycles =3D latency_numbers.total_pkts = =3D 0; > + } > + > + return nb_pkts; > + } > + > +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 are reset. > -- > 1.7.4.1 Acked-by: Siobhan Butler