X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fsample_app_ug%2Fl2_forward_real_virtual.rst;h=671d0c7c19d4f4a54d405cf31bcdcd2d4b15c203;hb=9eb974221f44cf210fe5d883bdccfcb48de75fc6;hp=9334e75927a32bfb105af6d3a5c85f041513129e;hpb=4a22e6ee3d2f8be8afd5b374a8916e232ab7fe97;p=dpdk.git diff --git a/doc/guides/sample_app_ug/l2_forward_real_virtual.rst b/doc/guides/sample_app_ug/l2_forward_real_virtual.rst index 9334e75927..671d0c7c19 100644 --- a/doc/guides/sample_app_ug/l2_forward_real_virtual.rst +++ b/doc/guides/sample_app_ug/l2_forward_real_virtual.rst @@ -1,32 +1,7 @@ -.. BSD LICENSE - Copyright(c) 2010-2014 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. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. + +.. _l2_fwd_app_real_and_virtual: L2 Forwarding Sample Application (in Real and Virtualized Environments) ======================================================================= @@ -48,17 +23,14 @@ performs L2 forwarding for each packet that is received on an RX_PORT. The destination port is the adjacent port from the enabled portmask, that is, 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: +Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows: * The source MAC address is replaced by the TX_PORT MAC address * The destination MAC address is replaced by 02:00:00:00:00:TX_PORT_ID -This application can be used to benchmark performance using a traffic-generator, as shown in the :numref:`figure_l2_fwd_benchmark_setup`. - -The application can also be used in a virtualized environment as shown in :numref:`figure_l2_fwd_virtenv_benchmark_setup`. - -The L2 Forwarding application can also be used as a starting point for developing a new application based on the DPDK. +This application can be used to benchmark performance using a traffic-generator, as shown in the :numref:`figure_l2_fwd_benchmark_setup`, +or in a virtualized environment as shown in :numref:`figure_l2_fwd_virtenv_benchmark_setup`. .. _figure_l2_fwd_benchmark_setup: @@ -66,13 +38,24 @@ The L2 Forwarding application can also be used as a starting point for developin Performance Benchmark Setup (Basic Environment) - .. _figure_l2_fwd_virtenv_benchmark_setup: .. figure:: img/l2_fwd_virtenv_benchmark_setup.* Performance Benchmark Setup (Virtualized Environment) +This application may be used for basic VM to VM communication as shown in :numref:`figure_l2_fwd_vm2vm`, +when MAC addresses updating is disabled. + +.. _figure_l2_fwd_vm2vm: + +.. figure:: img/l2_fwd_vm2vm.* + + Virtual Machine to Virtual Machine communication. + +The L2 Forwarding application can also be used as a starting point for developing a new application based on the DPDK. + +.. _l2_fwd_vf_setup: Virtual Function Setup Instructions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -97,25 +80,9 @@ in this case enabling a total of four Virtual Functions. Compiling the Application ------------------------- -#. Go to the example directory: +To compile the sample application see :doc:`compiling`. - .. code-block:: console - - export RTE_SDK=/path/to/rte_sdk cd ${RTE_SDK}/examples/l2fwd - -#. Set the target (a default target is used if not specified). For example: - - .. code-block:: console - - export RTE_TARGET=x86_64-native-linuxapp-gcc - - *See the DPDK Getting Started Guide* for possible RTE_TARGET values. - -#. Build the application: - - .. code-block:: console - - make +The application is located in the ``l2fwd`` sub-directory. Running the Application ----------------------- @@ -124,7 +91,7 @@ The application requires a number of command line options: .. code-block:: console - ./build/l2fwd [EAL options] -- -p PORTMASK [-q NQ] + ./build/l2fwd [EAL options] -- -p PORTMASK [-q NQ] --[no-]mac-updating where, @@ -132,11 +99,14 @@ where, * q NQ: A number of queues (=ports) per lcore (default is 1) -To run the application in linuxapp environment with 4 lcores, 16 ports and 8 RX queues per lcore, issue the command: +* --[no-]mac-updating: Enable or disable MAC addresses updating (enabled by default). + +To run the application in linux environment with 4 lcores, 16 ports and 8 RX queues per lcore and MAC address +updating enabled, issue the command: .. code-block:: console - $ ./build/l2fwd -c f -n 4 -- -q 8 -p ffff + $ ./build/l2fwd -l 0-3 -n 4 -- -q 8 -p ffff Refer to the *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options. @@ -146,11 +116,13 @@ Explanation The following sections provide some explanation of the code. +.. _l2_fwd_app_cmd_arguments: + Command Line Arguments ~~~~~~~~~~~~~~~~~~~~~~ The L2 Forwarding sample application takes specific parameters, -in addition to Environment Abstraction Layer (EAL) arguments (see Section 9.3). +in addition to Environment Abstraction Layer (EAL) arguments. The preferred way to parse parameters is to use the getopt() function, since it is part of a well-defined and portable library. @@ -178,6 +150,8 @@ This is done at the beginning of the main() function: if (ret < 0) rte_exit(EXIT_FAILURE, "Invalid L2FWD arguments\n"); +.. _l2_fwd_app_mbuf_init: + Mbuf Pool Initialization ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -189,31 +163,27 @@ and the application to store network packet data: /* create the mbuf pool */ - l2fwd_pktmbuf_pool = rte_mempool_create("mbuf_pool", NB_MBUF, MBUF_SIZE, 32, sizeof(struct rte_pktmbuf_pool_private), - rte_pktmbuf_pool_init, NULL, rte_pktmbuf_init, NULL, SOCKET0, 0); + l2fwd_pktmbuf_pool = rte_pktmbuf_pool_create("mbuf_pool", NB_MBUF, + MEMPOOL_CACHE_SIZE, 0, RTE_MBUF_DEFAULT_BUF_SIZE, + rte_socket_id()); if (l2fwd_pktmbuf_pool == NULL) rte_panic("Cannot init mbuf pool\n"); The rte_mempool is a generic structure used to handle pools of objects. -In this case, it is necessary to create a pool that will be used by the driver, -which expects to have some reserved space in the mempool structure, -sizeof(struct rte_pktmbuf_pool_private) bytes. -The number of allocated pkt mbufs is NB_MBUF, with a size of MBUF_SIZE each. +In this case, it is necessary to create a pool that will be used by the driver. +The number of allocated pkt mbufs is NB_MBUF, with a data room size of +RTE_MBUF_DEFAULT_BUF_SIZE each. A per-lcore cache of 32 mbufs is kept. The memory is allocated in NUMA socket 0, but it is possible to extend this code to allocate one mbuf pool per socket. -Two callback pointers are also given to the rte_mempool_create() function: +The rte_pktmbuf_pool_create() function uses the default mbuf pool and mbuf +initializers, respectively rte_pktmbuf_pool_init() and rte_pktmbuf_init(). +An advanced application may want to use the mempool API to create the +mbuf pool with more control. -* The first callback pointer is to rte_pktmbuf_pool_init() and is used - to initialize the private data of the mempool, which is needed by the driver. - This function is provided by the mbuf API, but can be copied and extended by the developer. - -* The second callback pointer given to rte_mempool_create() is the mbuf initializer. - The default is used, that is, rte_pktmbuf_init(), which is provided in the rte_mbuf library. - If a more complex application wants to extend the rte_pktmbuf structure for its own needs, - a new function derived from rte_pktmbuf_init( ) can be created. +.. _l2_fwd_app_dvr_init: Driver Initialization ~~~~~~~~~~~~~~~~~~~~~ @@ -224,17 +194,6 @@ in the *DPDK Programmer's Guide* - Rel 1.4 EAR and the *DPDK API Reference*. .. code-block:: c - if (rte_eal_pci_probe() < 0) - rte_exit(EXIT_FAILURE, "Cannot probe PCI\n"); - - nb_ports = rte_eth_dev_count(); - - if (nb_ports == 0) - rte_exit(EXIT_FAILURE, "No Ethernet ports - bye\n"); - - if (nb_ports > RTE_MAX_ETHPORTS) - nb_ports = RTE_MAX_ETHPORTS; - /* reset l2fwd_dst_ports */ for (portid = 0; portid < RTE_MAX_ETHPORTS; portid++) @@ -246,7 +205,7 @@ in the *DPDK Programmer's Guide* - Rel 1.4 EAR and the *DPDK API Reference*. * Each logical core is assigned a dedicated TX queue on each port. */ - for (portid = 0; portid < nb_ports; portid++) { + RTE_ETH_FOREACH_DEV(portid) { /* skip ports that are not enabled */ if ((l2fwd_enabled_port_mask & (1 << portid)) == 0) @@ -264,12 +223,6 @@ in the *DPDK Programmer's Guide* - Rel 1.4 EAR and the *DPDK API Reference*. rte_eth_dev_info_get((uint8_t) portid, &dev_info); } -Observe that: - -* rte_igb_pmd_init_all() simultaneously registers the driver as a PCI driver and as an Ethernet* Poll Mode Driver. - -* rte_eal_pci_probe() parses the devices on the PCI bus and initializes recognized devices. - The next step is to configure the RX and TX queues. For each port, there is only one RX queue (only one lcore is able to poll a given port). The number of TX queues depends on the number of available lcores. @@ -283,24 +236,7 @@ The rte_eth_dev_configure() function is used to configure the number of queues f "err=%d, port=%u\n", ret, portid); -The global configuration is stored in a static structure: - -.. code-block:: c - - static const struct rte_eth_conf port_conf = { - .rxmode = { - .split_hdr_size = 0, - .header_split = 0, /**< Header Split disabled */ - .hw_ip_checksum = 0, /**< IP checksum offload disabled */ - .hw_vlan_filter = 0, /**< VLAN filtering disabled */ - .jumbo_frame = 0, /**< Jumbo Frame Support disabled */ - .hw_strip_crc= 0, /**< CRC stripped by hardware */ - }, - - .txmode = { - .mq_mode = ETH_DCB_NONE - }, - }; +.. _l2_fwd_app_rx_init: RX Queue Initialization ~~~~~~~~~~~~~~~~~~~~~~~ @@ -334,19 +270,9 @@ The list of queues that must be polled for a given lcore is stored in a private struct lcore_queue_conf lcore_queue_conf[RTE_MAX_LCORE]; The values n_rx_port and rx_port_list[] are used in the main packet processing loop -(see Section 9.4.6 "Receive, Process and Transmit Packets" later in this chapter). - -The global configuration for the RX queues is stored in a static structure: +(see :ref:`l2_fwd_app_rx_tx_packets`). -.. code-block:: c - - static const struct rte_eth_rxconf rx_conf = { - .rx_thresh = { - .pthresh = RX_PTHRESH, - .hthresh = RX_HTHRESH, - .wthresh = RX_WTHRESH, - }, - }; +.. _l2_fwd_app_tx_init: TX Queue Initialization ~~~~~~~~~~~~~~~~~~~~~~~ @@ -376,6 +302,8 @@ The global configuration for TX queues is stored in a static structure: .tx_free_thresh = RTE_TEST_TX_DESC_DEFAULT + 1, /* disable feature */ }; +.. _l2_fwd_app_rx_tx_packets: + Receive, Process and Transmit Packets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -402,7 +330,8 @@ Packets are read in a burst of size MAX_PKT_BURST. The rte_eth_rx_burst() function writes the mbuf pointers in a local table and returns the number of available mbufs in the table. Then, each mbuf in the table is processed by the l2fwd_simple_forward() function. -The processing is very simple: process the TX port from the RX port, then replace the source and destination MAC addresses. +The processing is very simple: process the TX port from the RX port, then replace the source and destination MAC addresses if MAC +addresses updating is enabled. .. note:: @@ -417,13 +346,13 @@ Naturally, the number of ports in the portmask must be even, otherwise, the appl static void l2fwd_simple_forward(struct rte_mbuf *m, unsigned portid) { - struct ether_hdr *eth; + struct rte_ether_hdr *eth; void *tmp; unsigned dst_port; dst_port = l2fwd_dst_ports[portid]; - eth = rte_pktmbuf_mtod(m, struct ether_hdr *); + eth = rte_pktmbuf_mtod(m, struct rte_ether_hdr *); /* 02:00:00:00:00:xx */ @@ -433,7 +362,7 @@ Naturally, the number of ports in the portmask must be even, otherwise, the appl /* src addr */ - ether_addr_copy(&l2fwd_ports_eth_addr[dst_port], ð->s_addr); + rte_ether_addr_copy(&l2fwd_ports_eth_addr[dst_port], ð->s_addr); l2fwd_send_packet(m, (uint8_t) dst_port); } @@ -456,10 +385,10 @@ If the table is full, the whole packets table is transmitted using the l2fwd_sen /* Send the packet on an output interface */ static int - l2fwd_send_packet(struct rte_mbuf *m, uint8_t port) + l2fwd_send_packet(struct rte_mbuf *m, uint16_t port) { unsigned lcore_id, len; - struct lcore_queue_conf \*qconf; + struct lcore_queue_conf *qconf; lcore_id = rte_lcore_id(); qconf = &lcore_queue_conf[lcore_id];