I revised these sections mostly for grammar and clarity. Signed-off-by: Nandini Persad <nandinipersad...@gmail.com> --- doc/guides/sample_app_ug/l2_forward_cat.rst | 24 +++-- doc/guides/sample_app_ug/l2_forward_event.rst | 96 +++++++++---------- .../sample_app_ug/l2_forward_macsec.rst | 8 +- .../sample_app_ug/l2_forward_real_virtual.rst | 49 +++++----- doc/guides/sample_app_ug/l3_forward.rst | 29 +++--- doc/guides/sample_app_ug/l3_forward_graph.rst | 12 +-- .../sample_app_ug/l3_forward_power_man.rst | 10 +- doc/guides/sample_app_ug/link_status_intr.rst | 9 +- doc/guides/sample_app_ug/server_node_efd.rst | 12 +-- 9 files changed, 128 insertions(+), 121 deletions(-)
diff --git a/doc/guides/sample_app_ug/l2_forward_cat.rst b/doc/guides/sample_app_ug/l2_forward_cat.rst index 51621b692f..ab38d99821 100644 --- a/doc/guides/sample_app_ug/l2_forward_cat.rst +++ b/doc/guides/sample_app_ug/l2_forward_cat.rst @@ -4,19 +4,23 @@ L2 Forwarding Sample Application with Cache Allocation Technology (CAT) ======================================================================= -Basic Forwarding sample application is a simple *skeleton* example of +The Basic Forwarding sample application is a *skeleton* example of a forwarding application. It has been extended to make use of CAT via extended command line options and linking against the libpqos library. -It is intended as a demonstration of the basic components of a DPDK forwarding -application and use of the libpqos library to program CAT. -For more detailed implementations see the L2 and L3 forwarding +Overview +-------- + +This app is intended as a demonstration of the basic components of a DPDK forwarding +application and use of the libpqos library to the program CAT. +For more detailed implementations, see the L2 and L3 forwarding sample applications. CAT and Code Data Prioritization (CDP) features allow management of the CPU's last level cache. CAT introduces classes of service (COS) that are essentially bitmasks. In current CAT implementations, a bit in a COS bitmask corresponds to one cache way in last level cache. + A CPU core is always assigned to one of the CAT classes. By programming CPU core assignment and COS bitmasks, applications can be given exclusive, shared, or mixed access to the CPU's last level cache. @@ -29,7 +33,7 @@ By default, after reset, all CPU cores are assigned to COS 0 and all classes are programmed to allow fill into all cache ways. CDP is off by default. -For more information about CAT please see: +For more information about CAT, please see: * https://github.com/01org/intel-cmt-cat @@ -57,7 +61,7 @@ To compile the application, export the path to PQoS lib: export CFLAGS=-I/path/to/intel-cmt-cat/include export LDFLAGS=-L/path/to/intel-cmt-cat/lib -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. The application is located in the ``l2fwd-cat`` sub-directory. @@ -71,13 +75,13 @@ To run the example in a ``linux`` environment and enable CAT on cpus 0-2: ./<build_dir>/examples/dpdk-l2fwd-cat -l 1 -n 4 -- --l3ca="0x3@(0-2)" -or to enable CAT and CDP on cpus 1,3: +Or to enable CAT and CDP on cpus 1,3: .. code-block:: console ./<build_dir>/examples/dpdk-l2fwd-cat -l 1 -n 4 -- --l3ca="(0x00C00,0x00300)@(1,3)" -If CDP is not supported it will fail with following error message: +If CDP is not supported, it will fail with following error message: .. code-block:: console @@ -191,8 +195,8 @@ function. The value returned is the number of parsed arguments: ``cat_init()`` is a wrapper function which parses the command, validates the requested parameters and configures CAT accordingly. -Parsing of command line arguments is done in ``parse_args(...)``. -libpqos is then initialized with the ``pqos_init(...)`` call. Next, libpqos is +The parsing of command line arguments is done in ``parse_args(...)``. +Libpqos is then initialized with the ``pqos_init(...)`` call. Next, libpqos is queried for system CPU information and L3CA capabilities via ``pqos_cap_get(...)`` and ``pqos_cap_get_type(..., PQOS_CAP_TYPE_L3CA, ...)`` calls. When all capability and topology information is collected, the requested diff --git a/doc/guides/sample_app_ug/l2_forward_event.rst b/doc/guides/sample_app_ug/l2_forward_event.rst index 904f6f1a4a..4c9cac871e 100644 --- a/doc/guides/sample_app_ug/l2_forward_event.rst +++ b/doc/guides/sample_app_ug/l2_forward_event.rst @@ -6,24 +6,24 @@ L2 Forwarding Eventdev Sample Application ========================================= -The L2 Forwarding eventdev sample application is a simple example of packet -processing using the Data Plane Development Kit (DPDK) to demonstrate usage of -poll and event mode packet I/O mechanism. +The L2 Forwarding eventdev sample application is an example of packet +processing using the Data Plane Development Kit (DPDK) to demonstrate the usage of +the poll and event mode packet I/O mechanism. Overview -------- -The L2 Forwarding eventdev sample application, performs L2 forwarding for each +The L2 Forwarding eventdev sample application 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=0x0f), +from the enabled portmask if the first four ports are enabled (portmask=0x0f), ports 1 and 2 forward into each other, and ports 3 and 4 forward into each other. -Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows: +Also, if MAC address 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 -Application receives packets from RX_PORT using below mentioned methods: +Application receives packets from RX_PORT using these methods: * Poll mode @@ -41,7 +41,7 @@ as shown in the :numref:`figure_l2fwd_event_benchmark_setup`. 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-event`` sub-directory. @@ -79,7 +79,7 @@ where, * --event-vector-tmo: Max timeout to form vector in nanoseconds if event vectorization is enabled. -Sample usage commands are given below to run the application into different mode: +Sample usage commands are given below to run the application into different modes: Poll mode with 4 lcores, 16 ports and 8 RX queues per lcore and MAC address updating enabled, issue the command: @@ -88,7 +88,7 @@ issue the command: ./<build_dir>/examples/dpdk-l2fwd-event -l 0-3 -n 4 -- -q 8 -p ffff --mode=poll -Eventdev mode with 4 lcores, 16 ports , sched method ordered and MAC address updating enabled, +Eventdev mode with 4 lcores, 16 ports, schedule method ordered and MAC address updating enabled, issue the command: .. code-block:: console @@ -102,17 +102,17 @@ or ./<build_dir>/examples/dpdk-l2fwd-event -l 0-3 -n 4 -- -q 8 -p ffff --mode=eventdev --eventq-sched=ordered Refer to the *DPDK Getting Started Guide* for general information on running -applications and the Environment Abstraction Layer (EAL) options. +applications and Environment Abstraction Layer (EAL) options. -To run application with S/W scheduler, it uses following DPDK services: +To run the application with S/W scheduler, it uses following DPDK services: * Software scheduler * Rx adapter service function * Tx adapter service function -Application needs service cores to run above mentioned services. Service cores +The application needs service cores to run the above mentioned services. Service cores must be provided as EAL parameters along with the --vdev=event_sw0 to enable S/W -scheduler. Following is the sample command: +scheduler. The following is the sample command: .. code-block:: console @@ -121,24 +121,24 @@ scheduler. Following is the sample command: Explanation ----------- -The following sections provide some explanation of the code. +The following sections provide an explanation of the code. .. _l2_fwd_event_app_cmd_arguments: Command Line Arguments ~~~~~~~~~~~~~~~~~~~~~~ -The L2 Forwarding eventdev sample application takes specific parameters, -in addition to Environment Abstraction Layer (EAL) arguments. -The preferred way to parse parameters is to use the getopt() function, +The L2 Forwarding eventdev sample application takes specific parameters +and 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. -The parsing of arguments is done in the **l2fwd_parse_args()** function for non +The parsing of arguments is done in the **l2fwd_parse_args()** function for non- eventdev parameters and in **parse_eventdev_args()** for eventdev parameters. -The method of argument parsing is not described here. Refer to the -*glibc getopt(3)* man page for details. +This method of argument parsing is not described here. Refer to the +*glibc getopt(3)* main page for details. -EAL arguments are parsed first, then application-specific arguments. +EAL arguments are parsed first, then application-specific arguments follow. This is done at the beginning of the main() function and eventdev parameters are parsed in eventdev_resource_setup() function during eventdev setup: @@ -181,7 +181,7 @@ Driver Initialization The main part of the code in the main() function relates to the initialization of the driver. To fully understand this code, it is recommended to study the -chapters that related to the Poll Mode and Event mode Driver in the +chapters related to the Poll Mode and Event mode Driver in the *DPDK Programmer's Guide* - Rel 1.4 EAR and the *DPDK API Reference*. .. literalinclude:: ../../../examples/l2fwd-event/main.c @@ -234,7 +234,7 @@ loop (see :ref:`l2_fwd_event_app_rx_tx_packets`). TX Queue Initialization ~~~~~~~~~~~~~~~~~~~~~~~ -Each lcore should be able to transmit on any port. For every port, a single TX +Each lcore should be able to transmit on any port. For each port, a single TX queue is initialized. .. literalinclude:: ../../../examples/l2fwd-event/l2fwd_common.c @@ -243,7 +243,7 @@ queue is initialized. :end-before: >8 End of init one TX queue on each port. :dedent: 2 -To configure eventdev support, application setups following components: +To configure eventdev support, the application sets up following components: * Event dev * Event queue @@ -257,7 +257,7 @@ Event device Initialization ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Application can use either H/W or S/W based event device scheduler implementation and supports single instance of event device. It configures event -device as per below configuration +device as per the following configuration: .. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event_generic.c :language: c @@ -265,8 +265,8 @@ device as per below configuration :end-before: >8 End of configuration event device as per below configuration. :dedent: 1 -In case of S/W scheduler, application runs eventdev scheduler service on service -core. Application retrieves service id and finds the best possible service core to +In case of S/W scheduler, the application runs eventdev the scheduler service on the service +core. The application retrieves the service id and finds the best possible service core to run S/W scheduler. .. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event.c @@ -278,7 +278,7 @@ run S/W scheduler. Event queue Initialization ~~~~~~~~~~~~~~~~~~~~~~~~~~ Each Ethernet device is assigned a dedicated event queue which will be linked -to all available event ports i.e. each lcore can dequeue packets from any of the +to all available event ports, i.e. each lcore can dequeue packets from any of the Ethernet ports. .. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event_generic.c @@ -295,7 +295,7 @@ Tx adapter service function for enqueue operation. Event port Initialization ~~~~~~~~~~~~~~~~~~~~~~~~~ Each worker thread is assigned a dedicated event port for enq/deq operations -to/from an event device. All event ports are linked with all available event +to/from an event device. All event ports are linked to all available event queues. .. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event_generic.c @@ -304,8 +304,8 @@ queues. :end-before: >8 End of event port initialization. :dedent: 1 -In case of S/W scheduler, an extra event port is created by DPDK library which -is retrieved by the application and same will be used by Tx adapter service. +In case of S/W scheduler, an extra event port is created by the DPDK library which +is retrieved by the application. It will be used by Tx adapter service. .. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event_generic.c :language: c @@ -327,9 +327,9 @@ connected via Tx adapter. :dedent: 1 For S/W scheduler instead of dedicated adapters, common Rx/Tx adapters are -configured which will be shared among all the Ethernet ports. Also DPDK library -need service cores to run internal services for Rx/Tx adapters. Application gets -service id for Rx/Tx adapters and after successful setup it runs the services +configured which will be shared among all the Ethernet ports. Also, the DPDK library +needs service cores to run internal services for Rx/Tx adapters. The application gets a +service id for Rx/Tx adapters. After a successful setup, it runs the services on dedicated service cores. .. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event.c @@ -358,18 +358,18 @@ 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 if MAC addresses updating +then replace the source and destination MAC addresses if MAC address updating is enabled. During the initialization process, a static array of destination ports -(l2fwd_dst_ports[]) is filled such that for each source port, a destination port +(l2fwd_dst_ports[]) is filled so that for each source port, a destination port is assigned that is either the next or previous enabled port from the portmask. -If number of ports are odd in portmask then packet from last port will be +If the number of ports are odd in portmask, then the packet from the last port will be forwarded to first port i.e. if portmask=0x07, then forwarding will take place like p0--->p1, p1--->p2, p2--->p0. -Also to optimize enqueue operation, l2fwd_simple_forward() stores incoming mbufs -up to MAX_PKT_BURST. Once it reaches up to limit, all packets are transmitted to +Also, to optimize enqueue operation, l2fwd_simple_forward() stores incoming mbufs +up to MAX_PKT_BURST. Once it reaches the limit, all packets are transmitted to destination ports. .. literalinclude:: ../../../examples/l2fwd/main.c @@ -383,14 +383,14 @@ the rte_eth_tx_buffer() function directly from the main loop to send all the received packets on the same TX port, using the burst-oriented send function, which is more efficient. -However, in real-life applications (such as, L3 routing), +However, in real-life applications (such as L3 routing), packet N is not necessarily forwarded on the same port as packet N-1. -The application is implemented to illustrate that, so the same approach can be +The application is implemented to illustrate so the same approach can be reused in a more complex application. To ensure that no packets remain in the tables, each lcore does a draining of TX queue in its main loop. This technique introduces some latency when there are -not many packets to send, however it improves performance: +not many packets to send. However, it improves performance: .. literalinclude:: ../../../examples/l2fwd-event/l2fwd_poll.c :language: c @@ -408,25 +408,25 @@ packets from the event ports. This is done using the following code: :dedent: 2 -Before reading packets, deq_len is fetched to ensure correct allowed deq length +Before reading packets, deq_len is fetched to ensure the correct allowed deq length by the eventdev. The rte_event_dequeue_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_eventdev_forward() function. 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 +then replace the source and destination MAC addresses if MAC address updating is enabled. During the initialization process, a static array of destination ports -(l2fwd_dst_ports[]) is filled such that for each source port, a destination port +(l2fwd_dst_ports[]) is filled so that for each source port, a destination port is assigned that is either the next or previous enabled port from the portmask. If number of ports are odd in portmask then packet from last port will be forwarded to first port i.e. if portmask=0x07, then forwarding will take place like p0--->p1, p1--->p2, p2--->p0. -l2fwd_eventdev_forward() does not stores incoming mbufs. Packet will forwarded -be to destination ports via Tx adapter or generic event dev enqueue API +l2fwd_eventdev_forward() does not stores incoming mbufs. The packet will forwarded +to destination ports via Tx adapter or generic event dev enqueue API depending H/W or S/W scheduler is used. .. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event.c diff --git a/doc/guides/sample_app_ug/l2_forward_macsec.rst b/doc/guides/sample_app_ug/l2_forward_macsec.rst index 15dd57cfed..5ae27ff2de 100644 --- a/doc/guides/sample_app_ug/l2_forward_macsec.rst +++ b/doc/guides/sample_app_ug/l2_forward_macsec.rst @@ -4,8 +4,8 @@ L2 Forwarding MACsec Sample Application ======================================= -The L2 forwarding MACsec application is a simple example of packet processing -using the Data Plane Development Kit (DPDK) which encrypt/decrypt packets +The L2 forwarding MACsec application is an example of packet processing +using the Data Plane Development Kit (DPDK) to encrypt/decrypt packets based on rte_security MACsec sessions. Overview @@ -15,7 +15,7 @@ The L2 forwarding MACsec application performs L2 forwarding for each packet that is received on an Rx port after encrypting/decrypting the packets based on rte_security sessions using inline protocol mode. -The destination port is the adjacent port from the enabled portmask, that is, +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. @@ -24,7 +24,7 @@ This application can be used to benchmark performance using a traffic-generator. 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-macsec`` sub-directory. 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 aeeda7059c..8154ce4a49 100644 --- a/doc/guides/sample_app_ug/l2_forward_real_virtual.rst +++ b/doc/guides/sample_app_ug/l2_forward_real_virtual.rst @@ -6,9 +6,10 @@ L2 Forwarding Sample Application (in Real and Virtualized Environments) ======================================================================= -The L2 Forwarding sample application is a simple example of packet processing using -the Data Plane Development Kit (DPDK) which -also takes advantage of Single Root I/O Virtualization (SR-IOV) features in a virtualized environment. +The L2 Forwarding sample application is an example of packet processing using +the Data Plane Development Kit (DPDK). +It also takes advantage of Single Root I/O Virtualization (SR-IOV) features in a +virtualized environment. .. note:: @@ -20,10 +21,10 @@ Overview The L2 Forwarding sample application, which can operate in real and virtualized environments, 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), +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, if MAC addresses updating is enabled, the MAC addresses are affected as follows: +Also, if MAC address updating is enabled, the MAC addresses are affected as follows: * The source MAC address is replaced by the TX_PORT MAC address @@ -75,12 +76,12 @@ 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. +in this case, enabling a total of four Virtual Functions. 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`` sub-directory. @@ -133,21 +134,21 @@ 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. .. _l2_fwd_app_cmd_arguments: Command Line Arguments ~~~~~~~~~~~~~~~~~~~~~~ -The L2 Forwarding sample application takes specific parameters, -in addition to Environment Abstraction Layer (EAL) arguments. -The preferred way to parse parameters is to use the getopt() function, +The L2 Forwarding sample application takes specific parameters +and 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. The parsing of arguments is done in the l2fwd_parse_args() function. -The method of argument parsing is not described here. -Refer to the *glibc getopt(3)* man page for details. +This method of argument parsing is not described here. +Refer to the *glibc getopt(3)* main page for details. EAL arguments are parsed first, then application-specific arguments. This is done at the beginning of the main() function: @@ -192,7 +193,7 @@ Driver Initialization ~~~~~~~~~~~~~~~~~~~~~ The main part of the code in the main() function relates to the initialization of the driver. -To fully understand this code, it is recommended to study the chapters that related to the Poll Mode Driver +To fully understand this code, it is recommended to study the chapters related to the Poll Mode Driver in the *DPDK Programmer's Guide* - Rel 1.4 EAR and the *DPDK API Reference*. .. literalinclude:: ../../../examples/l2fwd/main.c @@ -217,7 +218,7 @@ The rte_eth_dev_configure() function is used to configure the number of queues f RX Queue Initialization ~~~~~~~~~~~~~~~~~~~~~~~ -The application uses one lcore to poll one or several ports, depending on the -q option, +The application uses one lcore to poll one or several ports depending on the -q option, which specifies the number of queues per lcore. For example, if the user specifies -q 4, the application is able to poll four ports with one lcore. @@ -245,7 +246,7 @@ The values n_rx_port and rx_port_list[] are used in the main packet processing l TX Queue Initialization ~~~~~~~~~~~~~~~~~~~~~~~ -Each lcore should be able to transmit on any port. For every port, a single TX queue is initialized. +Each lcore should be able to transmit on any port. For each port, a single TX queue is initialized. .. literalinclude:: ../../../examples/l2fwd/main.c :language: c @@ -272,7 +273,7 @@ The rte_eth_rx_burst() function writes the mbuf pointers in a local table and re 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 if MAC -addresses updating is enabled. +address updating is enabled. .. note:: @@ -280,7 +281,7 @@ addresses updating is enabled. During the initialization process, a static array of destination ports (l2fwd_dst_ports[]) is filled such that for each source port, a destination port is assigned that is either the next or previous enabled port from the portmask. -Naturally, the number of ports in the portmask must be even, otherwise, the application exits. +Naturally, the number of ports in the portmask must be even. Otherwise, the application exits. .. literalinclude:: ../../../examples/l2fwd/main.c :language: c @@ -288,15 +289,15 @@ Naturally, the number of ports in the portmask must be even, otherwise, the appl :end-before: >8 End of simple forward. -Then, the packet is sent using the l2fwd_send_packet (m, dst_port) function. +At this point, the packet is sent using the l2fwd_send_packet (m, dst_port) function. For this test application, the processing is exactly the same for all packets arriving on the same RX port. Therefore, it would have been possible to call the l2fwd_send_burst() function directly from the main loop to send all the received packets on the same TX port, using the burst-oriented send function, which is more efficient. -However, in real-life applications (such as, L3 routing), +However, in real-life applications (such as L3 routing), packet N is not necessarily forwarded on the same port as packet N-1. -The application is implemented to illustrate that, so the same approach can be reused in a more complex application. +The application is implemented to illustrate this so the same approach can be reused in a more complex application. The l2fwd_send_packet() function stores the packet in a per-lcore and per-txport table. If the table is full, the whole packets table is transmitted using the l2fwd_send_burst() function: @@ -307,8 +308,8 @@ If the table is full, the whole packets table is transmitted using the l2fwd_sen :end-before: >8 End of Enqueuing packets for TX. To ensure that no packets remain in the tables, each lcore does a draining of TX queue in its main loop. -This technique introduces some latency when there are not many packets to send, -however it improves performance: +This technique introduces some latency when there are not many packets to send. +However it improves performance: .. literalinclude:: ../../../examples/l2fwd/main.c :language: c diff --git a/doc/guides/sample_app_ug/l3_forward.rst b/doc/guides/sample_app_ug/l3_forward.rst index 1cc2c1dd1d..95a3bfc114 100644 --- a/doc/guides/sample_app_ug/l3_forward.rst +++ b/doc/guides/sample_app_ug/l3_forward.rst @@ -4,8 +4,8 @@ L3 Forwarding Sample Application ================================ -The L3 Forwarding application is a simple example of packet processing using -DPDK to demonstrate usage of poll and event mode packet I/O mechanism. +The L3 Forwarding application is an example of packet processing using +DPDK to demonstrate the usage of poll and event mode packet I/O mechanism. The application performs L3 forwarding. Overview @@ -16,7 +16,7 @@ to implement packet forwarding using poll or event mode PMDs for packet I/O. The initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual` and :doc:`l2_forward_event`. The main difference from the L2 Forwarding sample application is that optionally -packet can be Rx/Tx from/to eventdev instead of port directly and forwarding +the packet can be Rx/Tx from/to eventdev instead of to port directly. The forwarding decision is made based on information read from the input packet. Eventdev can optionally use S/W or H/W (if supported by platform) scheduler @@ -58,12 +58,12 @@ a source port, a destination port and a protocol identifier. In the sample application, hash-based, LPM-based, FIB-based and ACL-based forwarding supports both IPv4 and IPv6. -During the initialization phase route rules for IPv4 and IPv6 are read from rule files. +During the initialization, phase route rules for IPv4 and IPv6 are read from rule files. 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 ``l3fwd`` sub-directory. @@ -184,8 +184,8 @@ In this command: * The -rule_ipv6 option specifies the reading of IPv6 rules sets from the rule_ipv6.cfg file. -To use eventdev mode with sync method **ordered** on above mentioned environment, -Following is the sample command: +To use eventdev mode with sync method **ordered** on the above environment, +the following is the sample command: .. code-block:: console @@ -213,16 +213,16 @@ If application uses S/W scheduler, it uses following DPDK services: * Rx adapter service function * Tx adapter service function -Application needs service cores to run above mentioned services. Service cores +The application needs service cores to run the above mentioned services. Service cores must be provided as EAL parameters along with the --vdev=event_sw0 to enable S/W -scheduler. Following is the sample command: +scheduler. The following is the sample command: .. code-block:: console ./<build_dir>/examples/dpdk-l3fwd -l 0-7 -s 0xf0000 -n 4 --vdev event_sw0 -- -p 0x3 --mode=eventdev --eventq-sched=ordered --rule_ipv4="rule_ipv4.cfg" --rule_ipv6="rule_ipv6.cfg" In case of eventdev mode, *--config* option is not used for ethernet port -configuration. Instead each ethernet port will be configured with mentioned +configuration. Instead, each ethernet port will be configured with this setup: * Single Rx/Tx queue @@ -239,7 +239,7 @@ the Environment Abstraction Layer (EAL) options. Explanation ----------- -The following sections provide some explanation of the sample application code. As mentioned in the overview section, +The following sections provide 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` and :doc:`l2_forward_event`. The following sections describe aspects that are specific to the L3 Forwarding sample application. @@ -293,12 +293,12 @@ IPv4 addresses are specified in CIDR format as specified in RFC 4632. For LPM/FIB/ACL they consist of the dot notation for the address and a prefix length separated by '/'. For example, 192.168.0.34/32, where the address is 192.168.0.34 and the prefix length is 32. -For EM they consist of just the dot notation for the address and no prefix length. +For EM, they consist of just the dot notation for the address and no prefix length. For example, 192.168.0.34, where the Address is 192.168.0.34. EM also includes ports which are specified as a single number which represents a single port. The application parses the rules from the file, -it ignores empty and comment lines, +it ignores empty and comment lines and parses and validates the rules it reads. If errors are detected, the application exits with messages to identify the errors encountered. @@ -476,5 +476,6 @@ can be found in the sample app code. Eventdev Driver Initialization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Eventdev driver initialization is same as L2 forwarding eventdev application. + +Eventdev driver initialization is the same as L2 forwarding eventdev application. Refer :doc:`l2_forward_event` for more details. diff --git a/doc/guides/sample_app_ug/l3_forward_graph.rst b/doc/guides/sample_app_ug/l3_forward_graph.rst index eb56f9b94a..37f063dad3 100644 --- a/doc/guides/sample_app_ug/l3_forward_graph.rst +++ b/doc/guides/sample_app_ug/l3_forward_graph.rst @@ -4,7 +4,7 @@ L3 Forwarding Graph Sample Application ====================================== -The L3 Forwarding Graph application is a simple example of packet processing +The L3 Forwarding Graph application is an example of packet processing using the DPDK Graph framework. The application performs L3 forwarding using Graph framework and nodes written for graph framework. @@ -22,7 +22,7 @@ and configuration per lcore. Run-time path is main thing that differs from L3 forwarding sample application. Difference is that forwarding logic starting from Rx, followed by LPM lookup, TTL update and finally Tx is implemented inside graph nodes. These nodes are -interconnected in graph framework. Application main loop needs to walk over +interconnected in graph framework. The application main loop needs to walk over graph using ``rte_graph_walk()`` with graph objects created one per worker lcore. The lookup method is as per implementation of ``ip4_lookup``/``ip6_lookup`` graph node. @@ -38,7 +38,7 @@ In the sample application, IPv4 and IPv6 forwarding is supported. 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 ``l3fwd-graph`` sub-directory. @@ -181,7 +181,7 @@ specific graph object. Graph Initialization ~~~~~~~~~~~~~~~~~~~~ -Now a graph needs to be created with a specific set of nodes for every lcore. +Now, a graph needs to be created with a specific set of nodes for every lcore. A graph object returned after graph creation is a per lcore object and cannot be shared between lcores. Since ``ethdev_tx-X`` node is per port node, it can be associated with all the graphs created as all the lcores should have @@ -226,8 +226,8 @@ Packet Forwarding using Graph Walk ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Now that all the device configurations are done, graph creations are done and -forwarding data is updated with nodes, worker lcores will be launched with graph -main loop. Graph main loop is very simple in the sense that it needs to +forwarding data is updated with nodes, worker lcores will be launched with the graph +main loop.The graph main loop is very simple in the sense that it needs to continuously call a non-blocking API ``rte_graph_walk()`` with it's lcore specific graph object that was already created. diff --git a/doc/guides/sample_app_ug/l3_forward_power_man.rst b/doc/guides/sample_app_ug/l3_forward_power_man.rst index 4a6f33bf4f..98b0ce5aa9 100644 --- a/doc/guides/sample_app_ug/l3_forward_power_man.rst +++ b/doc/guides/sample_app_ug/l3_forward_power_man.rst @@ -8,7 +8,7 @@ Introduction ------------ The L3 Forwarding with Power Management application is an example of power-aware packet processing using the DPDK. -The application is based on existing L3 Forwarding sample application, +The application is based on the existing L3 Forwarding sample application, with the power management algorithms to control the P-states and C-states of the Intel processor via a power management library. @@ -77,7 +77,7 @@ instead of always running to the C0 state waiting for packets. 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 ``l3fwd-power`` sub-directory. @@ -127,7 +127,7 @@ The L3fwd-power example reuses the L3fwd command line options. Explanation ----------- -The following sections provide some explanation of the sample application code. +The following sections provide explanation of the sample application code. As mentioned in the overview section, the initialization and run-time paths are identical to those of the L3 forwarding application. The following sections describe aspects that are specific to the L3 Forwarding with Power Management sample application. @@ -239,7 +239,7 @@ in order to avoid a potential performance impact. Telemetry Mode -------------- -The telemetry mode support for ``l3fwd-power`` is a standalone mode, in this mode +The telemetry mode support for ``l3fwd-power`` is a standalone mode. In this mode, ``l3fwd-power`` does simple l3fwding along with calculating empty polls, full polls, and busy percentage for each forwarding core. The aggregation of these values of all cores is reported as application level telemetry to metric @@ -261,7 +261,7 @@ The new stats ``empty_poll`` , ``full_poll`` and ``busy_percent`` can be viewed PMD power management Mode ------------------------- -The PMD power management mode support for ``l3fwd-power`` is a standalone mode. +The PMD power management mode support for ``l3fwd-power`` is a standalone mode. In this mode, ``l3fwd-power`` does simple l3fwding along with enabling the power saving scheme on specific port/queue/lcore. Main purpose for this mode is to demonstrate diff --git a/doc/guides/sample_app_ug/link_status_intr.rst b/doc/guides/sample_app_ug/link_status_intr.rst index a4c0712bd9..22c736a6eb 100644 --- a/doc/guides/sample_app_ug/link_status_intr.rst +++ b/doc/guides/sample_app_ug/link_status_intr.rst @@ -4,7 +4,7 @@ Link Status Interrupt Sample Application ======================================== -The Link Status Interrupt sample application is a simple example of packet processing using +The Link Status Interrupt sample application is an example of packet processing using the Data Plane Development Kit (DPDK) that demonstrates how network link status changes for a network port can be captured and used by a DPDK application. @@ -14,6 +14,7 @@ Overview The Link Status Interrupt sample application registers a user space callback for the link status interrupt of each port and performs L2 forwarding for each packet that is received on an RX_PORT. + The following operations are performed: * RX_PORT and TX_PORT are paired with available ports one-by-one according to the core mask @@ -28,7 +29,7 @@ and the behavior of L2 forwarding each time the link status changes. 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 ``link_status_interrupt`` sub-directory. @@ -67,8 +68,8 @@ The following sections provide some explanation of the code. Command Line Arguments ~~~~~~~~~~~~~~~~~~~~~~ -The Link Status Interrupt sample application takes specific parameters, -in addition to Environment Abstraction Layer (EAL) arguments (see Section `Running the Application`_). +The Link Status Interrupt sample application takes specific parameters +and Environment Abstraction Layer (EAL) arguments (see Section `Running the Application`_). Command line parsing is done in the same way as it is done in the L2 Forwarding Sample Application. See :ref:`l2_fwd_app_cmd_arguments` for more information. diff --git a/doc/guides/sample_app_ug/server_node_efd.rst b/doc/guides/sample_app_ug/server_node_efd.rst index 7253b38da7..a580f0e7b4 100644 --- a/doc/guides/sample_app_ug/server_node_efd.rst +++ b/doc/guides/sample_app_ug/server_node_efd.rst @@ -5,7 +5,7 @@ Server-Node EFD Sample Application ================================== This sample application demonstrates the use of EFD library as a flow-level -load balancer, for more information about the EFD Library please refer to the +load balancer. For more information about the EFD Library, please refer to the DPDK programmer's guide. This sample application is a variant of the @@ -56,12 +56,12 @@ then the pair of <key,target> is inserted into the flow distribution table. The main loop of the server process receives a burst of packets, then for each packet, a flow key (IP destination address) is extracted. The flow -distributor table is looked up and the target node id is returned. Packets are +distributor table is looked up and the target node id is returned. Packets are then enqueued to the specified target node id. -It should be noted that flow distributor table is not a membership test table. -I.e. if the key has already been inserted the target node id will be correct, -but for new keys the flow distributor table will return a value (which can be +It should be noted that flow distributor table is not a membership test table, +i.e. if the key has already been inserted the target node id will be correct. +But for new keys, the flow distributor table will return a value (which can be valid). Backend Worker Nodes @@ -81,7 +81,7 @@ that this is a new flow, which is dropped. 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 ``server_node_efd`` sub-directory. -- 2.34.1
