d/numam-dpdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc: fix references in sample apps guide

Browse Source 
MANY references in the sample applications user guide are wrong because
they are hard-coded and section numbers have changed over the time.
This patch changes thoses references to dynamic ones, in this way if
section numbers change the reference get updated automatically.

Signed-off-by: Mauricio Vasquez B <mauricio.vasquezbernal@studenti.polito.it>
This commit is contained in:
Mauricio Vasquez B 2016-02-25 18:02:27 +01:00 committed by Thomas Monjalon
parent 377cd98e0a
commit 513b07238a
19 changed files with 71 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
doc/guides/sample_app_ug/dist_app.rst
View File

@ -160,16 +160,16 @@ Application Initialization
--------------------------
Command line parsing is done in the same way as it is done in the L2 Forwarding Sample
Application. See Section 9.4.1, "Command Line Arguments".
Application. See :ref:`l2_fwd_app_cmd_arguments`.
Mbuf pool initialization is done in the same way as it is done in the L2 Forwarding
Sample Application. See Section 9.4.2, "Mbuf Pool Initialization".
Sample Application. See :ref:`l2_fwd_app_mbuf_init`.
Driver Initialization is done in same way as it is done in the L2 Forwarding Sample
Application. See Section 9.4.3, "Driver Initialization".
Application. See :ref:`l2_fwd_app_dvr_init`.
RX queue initialization is done in the same way as it is done in the L2 Forwarding
Sample Application. See Section 9.4.4, "RX Queue Initialization".
Sample Application. See :ref:`l2_fwd_app_rx_init`.
TX queue initialization is done in the same way as it is done in the L2 Forwarding
Sample Application. See Section 9.4.5, "TX Queue Initialization".
Sample Application. See :ref:`l2_fwd_app_tx_init`.

5
doc/guides/sample_app_ug/exception_path.rst
View File

@ -134,8 +134,7 @@ The following sections provide some explanation of the code.
Initialization
~~~~~~~~~~~~~~
Setup of the mbuf pool, driver and queues is similar to the setup done in the L2 Forwarding sample application
(see Chapter 9 "L2 forwarding Sample Application (in Real and Virtualized Environments" for details).
Setup of the mbuf pool, driver and queues is similar to the setup done in the :ref:`l2_fwd_app_real_and_virtual`.
In addition, the TAP interfaces must also be created.
A TAP interface is created for each lcore that is being used.
The code for creating the TAP interface is as follows:
@ -221,7 +220,7 @@ This function first checks the lcore_id against the user provided input_cores_ma
if this core is reading from or writing to a TAP interface.
For the case that reads from a NIC port, the packet reception is the same as in the L2 Forwarding sample application
(see Section 9.4.6, "Receive, Process and Transmit Packets").
(see :ref:`l2_fwd_app_rx_tx_packets`).
The packet transmission is done by calling write() with the file descriptor of the appropriate TAP interface
and then explicitly freeing the mbuf back to the pool.

2
doc/guides/sample_app_ug/intel_quickassist.rst
View File

@ -203,7 +203,7 @@ where,
* --config'(port,queue,lcore)[,(port,queue,lcore)]': determines which queues from which ports are mapped to which cores.
Refer to Chapter 10 , "L3 Forwarding Sample Application" for more detailed descriptions of the --config command line option.
Refer to the :doc:`l3_forward` for more detailed descriptions of the --config command line option.
As an example, to run the application with two ports and two cores,
which are using different Intel® QuickAssist Technology execution engines,

3
doc/guides/sample_app_ug/ip_frag.rst
View File

@ -39,8 +39,7 @@ Overview
--------
The application demonstrates the use of zero-copy buffers for packet fragmentation.
The initialization and run-time paths are very similar to those of the L2 forwarding application
(see Chapter 9 "L2 Forwarding Simple Application (in Real and Virtualized Environments)" for more information).
The initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
This guide highlights the differences between the two applications.
There are three key differences from the L2 Forwarding sample application:

6
doc/guides/sample_app_ug/ip_reassembly.rst
View File

@ -39,8 +39,7 @@ Overview
The application demonstrates the use of the DPDK libraries to implement packet forwarding
with reassembly for IPv4 and IPv6 fragmented packets.
The initialization and run- time paths are very similar to those of the L2 forwarding application
(see Chapter 9 "L2 Forwarding Sample Application" for more information).
The initialization and run- time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
The main difference from the L2 Forwarding sample application is that
it reassembles fragmented IPv4 and IPv6 packets before forwarding.
The maximum allowed size of reassembled packet is 9.5 KB.
@ -182,8 +181,7 @@ 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 L2 forwarding application
(see Chapter 9 "L2 Forwarding Sample Application" for more information).
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

6
doc/guides/sample_app_ug/ipv4_multicast.rst
View File

@ -39,8 +39,7 @@ Overview
--------
The application demonstrates the use of zero-copy buffers for packet forwarding.
The initialization and run-time paths are very similar to those of the L2 forwarding application
(see Chapter 9 "L2 Forwarding Sample Application (in Real and Virtualized Environments)" for details more information).
The initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
This guide highlights the differences between the two applications.
There are two key differences from the L2 Forwarding sample application:
@ -134,8 +133,7 @@ Explanation
The following sections provide some explanation of the code.
As mentioned in the overview section,
the initialization and run-time paths are very similar to those of the L2 Forwarding sample application
(see Chapter 9 "L2 Forwarding Sample Application in Real and Virtualized Environments" for more information).
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.
Memory Pool Initialization

6
doc/guides/sample_app_ug/keep_alive.rst
View File

@ -59,7 +59,7 @@ Note: Only the worker cores are monitored. A local (on the host) mechanism
or agent to supervise the Keep Alive Monitor Agent Core DPDK core is required
to detect its failure.
Note: This application is based on the L2 forwarding application. As
Note: This application is based on the :doc:`l2_forward_real_virtual`. As
such, the initialization and run-time paths are very similar to those
of the L2 forwarding application.
@ -127,9 +127,7 @@ Explanation
The following sections provide some explanation of the 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 L2 forwarding application (see Chapter 9
"L2 Forwarding Sample Application (in Real and Virtualized
Environments)" for more information).
similar to those of the :doc:`l2_forward_real_virtual`.
The Keep-Alive/'Liveliness' conceptual scheme:

7
doc/guides/sample_app_ug/kernel_nic_interface.rst
View File

@ -237,8 +237,7 @@ The following sections provide some explanation of code.
Initialization
~~~~~~~~~~~~~~
Setup of mbuf pool, driver and queues is similar to the setup done in the L2 Forwarding sample application
(see Chapter 9 "L2 Forwarding Sample Application (in Real and Virtualized Environments" for details).
Setup of mbuf pool, driver and queues is similar to the setup done in the :doc:`l2_forward_real_virtual`..
In addition, one or more kernel NIC interfaces are allocated for each
of the configured ports according to the command line parameters.
@ -425,7 +424,7 @@ to see if this lcore is reading from or writing to kernel NIC interfaces.
For the case that reads from a NIC port and writes to the kernel NIC interfaces,
the packet reception is the same as in L2 Forwarding sample application
(see Section 9.4.6 "Receive, Process and Transmit Packets").
(see :ref:`l2_fwd_app_rx_tx_packets`).
The packet transmission is done by sending mbufs into the kernel NIC interfaces by rte_kni_tx_burst().
The KNI library automatically frees the mbufs after the kernel successfully copied the mbufs.
@ -472,7 +471,7 @@ The KNI library automatically frees the mbufs after the kernel successfully copi
For the other case that reads from kernel NIC interfaces and writes to a physical NIC port, packets are retrieved by reading
mbufs from kernel NIC interfaces by `rte_kni_rx_burst()`.
The packet transmission is the same as in the L2 Forwarding sample application
(see Section 9.4.6 "Receive, Process and Transmit Packet's").
(see :ref:`l2_fwd_app_rx_tx_packets`).
.. code-block:: c

19
doc/guides/sample_app_ug/l2_forward_real_virtual.rst
View File

@ -28,6 +28,8 @@
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.. _l2_fwd_app_real_and_virtual:
L2 Forwarding Sample Application (in Real and Virtualized Environments)
=======================================================================
@ -73,6 +75,7 @@ The L2 Forwarding application can also be used as a starting point for developin
Performance Benchmark Setup (Virtualized Environment)
.. _l2_fwd_vf_setup:
Virtual Function Setup Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -147,11 +150,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.
@ -179,6 +184,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
~~~~~~~~~~~~~~~~~~~~~~~~
@ -216,6 +223,8 @@ Two callback pointers are also given to the rte_mempool_create() function:
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
~~~~~~~~~~~~~~~~~~~~~
@ -303,6 +312,8 @@ The global configuration is stored in a static structure:
},
};
.. _l2_fwd_app_rx_init:
RX Queue Initialization
~~~~~~~~~~~~~~~~~~~~~~~
@ -335,7 +346,7 @@ 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).
(see :ref:`l2_fwd_app_rx_tx_packets`).
The global configuration for the RX queues is stored in a static structure:
@ -349,6 +360,8 @@ The global configuration for the RX queues is stored in a static structure:
},
};
.. _l2_fwd_app_tx_init:
TX Queue Initialization
~~~~~~~~~~~~~~~~~~~~~~~
@ -377,6 +390,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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

8
doc/guides/sample_app_ug/l3_forward.rst
View File

@ -38,8 +38,7 @@ Overview
--------
The application demonstrates the use of the hash and LPM libraries in the DPDK to implement packet forwarding.
The initialization and run-time paths are very similar to those of the L2 forwarding application
(see Chapter 9 "L2 Forwarding Sample Application (in Real and Virtualized Environments)" for more information).
The initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
The main difference from the L2 Forwarding sample application is that the forwarding decision
is made based on information read from the input packet.
@ -157,12 +156,13 @@ In this command:
Refer to the *DPDK Getting Started Guide* for general information on running applications and
the Environment Abstraction Layer (EAL) options.
.. _l3_fwd_explanation:
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 L2 forwarding application
(see Chapter 9 "L2 Forwarding Sample Application (in Real and Virtualized Environments)" for more information).
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 L3 Forwarding sample application.
Hash Initialization

6
doc/guides/sample_app_ug/l3_forward_access_ctrl.rst
View File

@ -51,8 +51,7 @@ When packets are received from a port,
the application extracts the necessary information from the TCP/IP header of the received packet and
performs a lookup in the rule database to figure out whether the packets should be dropped (in the ACL range)
or forwarded to desired ports.
The initialization and run-time paths are similar to those of the L3 forwarding application
(see Chapter 10, "L3 Forwarding Sample Application" for more information).
The initialization and run-time paths are similar to those of the :doc:`l3_forward`.
However, there are significant differences in the two applications.
For example, the original L3 forwarding application uses either LPM or
an exact match algorithm to perform forwarding port lookup,
@ -360,8 +359,7 @@ Explanation
-----------
The following sections provide some explanation of the sample application code.
The aspects of port, device and CPU configuration are similar to those of the L3 forwarding application
(see Chapter 10, "L3 Forwarding Sample Application" for more information).
The aspects of port, device and CPU configuration are similar to those of the :doc:`l3_forward`.
The following sections describe aspects that are specific to L3 forwarding with access control.
Parse Rules from File

5
doc/guides/sample_app_ug/l3_forward_power_man.rst
View File

@ -43,8 +43,7 @@ Overview
--------
The application demonstrates the use of the Power libraries in the DPDK to implement packet forwarding.
The initialization and run-time paths are very similar to those of the L3 forwarding sample application
(see Chapter 10 "L3 Forwarding Sample Application" for more information).
The initialization and run-time paths are very similar to those of the :doc:`l3_forward`.
The main difference from the L3 Forwarding sample application is that this application introduces power-aware optimization algorithms
by leveraging the Power library to control P-state and C-state of processor based on packet load.
@ -152,7 +151,7 @@ where,
* --no-numa: optional, disables numa awareness
See Chapter 10 "L3 Forwarding Sample Application" for details.
See :doc:`l3_forward` for details.
The L3fwd-power example reuses the L3fwd command line options.
Explanation

7
doc/guides/sample_app_ug/l3_forward_virtual.rst
View File

@ -39,8 +39,7 @@ Overview
--------
The application demonstrates the use of the hash and LPM libraries in the DPDK to implement packet forwarding.
The initialization and run-time paths are very similar to those of the L3 forwarding application
(see Chapter 10 "L3 Forwarding Sample Application" for more information).
The initialization and run-time paths are very similar to those of the :doc:`l3_forward`.
The forwarding decision is taken based on information read from the input packet.
The lookup method is either hash-based or LPM-based and is selected at compile time.
@ -60,7 +59,7 @@ The set of LPM rules used by the application is statically configured and loaded
.. note::
Please refer to Section 9.1.1 "Virtual Function Setup Instructions" for virtualized test case setup.
Please refer to :ref:`l2_fwd_vf_setup` for virtualized test case setup.
Compiling the Application
-------------------------
@ -155,4 +154,4 @@ Explanation
-----------
The operation of this application is similar to that of the basic L3 Forwarding Sample Application.
See Section 10.4 "Explanation" for more information.
See :ref:`l3_fwd_explanation` for more information.

8
doc/guides/sample_app_ug/link_status_intr.rst
View File

@ -118,16 +118,16 @@ Command Line Arguments
~~~~~~~~~~~~~~~~~~~~~~
The Link Status Interrupt sample application takes specific parameters,
in addition to Environment Abstraction Layer (EAL) arguments (see Section 13.3).
in addition to 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 Section 9.4.1, "Command Line Arguments" for more information.
See :ref:`l2_fwd_app_cmd_arguments` for more information.
Mbuf Pool Initialization
~~~~~~~~~~~~~~~~~~~~~~~~
Mbuf pool initialization is done in the same way as it is done in the L2 Forwarding Sample Application.
See Section 9.4.2, "Mbuf Pool Initialization" for more information.
See :ref:`l2_fwd_app_mbuf_init` for more information.
Driver Initialization
~~~~~~~~~~~~~~~~~~~~~
@ -287,7 +287,7 @@ 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 n_rx_port and rx_port_list[] fields are used in the main packet processing loop
(see Section 13.4.7, "Receive, Process and Transmit Packets" later in this chapter).
(see `Receive, Process and Transmit Packets`_).
The global configuration for the RX queues is stored in a static structure:

4
doc/guides/sample_app_ug/multi_process.rst
View File

@ -378,7 +378,7 @@ using the local cache mechanism of mempool structures.
This application performs the same functionality as the L2 Forwarding sample application,
therefore this chapter does not cover that part but describes functionality that is introduced in this multi-process example only.
Please refer to Chapter 9, "L2 Forwarding Sample Application (in Real and Virtualized Environments)" for more information.
Please refer to :doc:`l2_forward_real_virtual` for more information.
Unlike previous examples where all processes are started from the command line with input arguments, in this example,
only one process is spawned from the command line and that process creates other processes.
@ -464,7 +464,7 @@ Therefore, to provide the capability to resume the new slave instance if the pre
#. Set up a notification mechanism for slave process exit cases. After the specific slave leaves,
the master should be notified and then help to create a new instance.
This mechanism is provided in Section 15.1.5.1, "Master-slave Process Models".
This mechanism is provided in Section `Master-slave Process Models`_.
#. Use a synchronization mechanism among dependent processes.
The master should have the capability to stop or kill slave processes that have a dependency on the one that has exited.

8
doc/guides/sample_app_ug/tep_termination.rst
View File

@ -121,7 +121,7 @@ The example in this section have been validated with the following distributions
Prerequisites
-------------
Refer to the guide in section 27.4 in the vhost sample.
Refer to :ref:`vhost_app_prerequisites`.
Compiling the Sample Code
-------------------------
@ -225,7 +225,7 @@ Parameters
**The same parameters with the vhost sample.**
Refer to the guide in section 27.6.1 in the vhost sample for the meanings of 'Basename',
Refer to :ref:`vhost_app_parameters` for the meanings of 'Basename',
'Stats', 'RX Retry', 'RX Retry Number' and 'RX Retry Delay Time'.
**Number of Devices.**
@ -303,12 +303,12 @@ The default value is 1.
Running the Virtual Machine (QEMU)
----------------------------------
Refer to the guide in section 27.7 in the vhost sample.
Refer to :ref:`vhost_app_running`.
Running DPDK in the Virtual Machine
-----------------------------------
Refer to the guide in section 27.8 in the vHost sample.
Refer to :ref:`vhost_app_running_dpdk`.
Passing Traffic to the Virtual Machine Device
---------------------------------------------

13
doc/guides/sample_app_ug/vhost.rst
View File

@ -144,6 +144,8 @@ The example in this section have been validated with the following distributions
* Fedora* 20
.. _vhost_app_prerequisites:
Prerequisites
-------------
@ -260,7 +262,7 @@ Setting up the Guest Execution Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is recommended for testing purposes that the DPDK testpmd sample application is used in the guest to forward packets,
the reasons for this are discussed in Section 22.7, "Running the Virtual Machine (QEMU)".
the reasons for this are discussed in `Running the Virtual Machine (QEMU)`_.
The testpmd application forwards packets between pairs of Ethernet devices,
it requires an even number of Ethernet devices (virtio or otherwise) to execute.
@ -405,6 +407,8 @@ Running the Sample Code
The number used with the --socket-mem parameter may need to be more than 1024.
The number required depends on the number of mbufs allocated by vhost-switch.
.. _vhost_app_parameters:
Parameters
~~~~~~~~~~
@ -530,6 +534,8 @@ It is enabled by default.
./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
-- --vlan-strip [0, 1]
.. _vhost_app_running:
Running the Virtual Machine (QEMU)
----------------------------------
@ -583,7 +589,7 @@ an open file descriptor must be passed to QEMU running as a child process.
.. note::
This process is automated in the QEMU wrapper script discussed in Section 24.7.3.
This process is automated in the `QEMU Wrapper Script`_.
Mapping the Virtual Machine's Memory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -600,7 +606,7 @@ In this case, the path passed to the guest should be that of the 1 GB page huget
.. note::
This process is automated in the QEMU wrapper script discussed in Section 24.7.3.
This process is automated in the `QEMU Wrapper Script`_.
The following two sections only applies to vhost cuse.
For vhost-user, please make corresponding changes to qemu-wrapper script and guest XML file.
@ -760,6 +766,7 @@ Common Issues
Linux module but which is necessary for the user space VHOST current implementation (CUSE-based) to communicate with
the guest.
.. _vhost_app_running_dpdk:
Running DPDK in the Virtual Machine
-----------------------------------

4
doc/guides/sample_app_ug/vm_power_management.rst
View File

@ -72,7 +72,7 @@ The solution is comprised of two high-level components:
the APCI cpufreq sysfs interface used on the host.
The l3fwd-power application will use this implementation when deployed on a VM
(see Chapter 11 "L3 Forwarding with Power Management Application").
(see :doc:`l3_forward_power_man`).
.. _figure_vm_power_mgr_highlevel:
@ -314,7 +314,7 @@ Manual control and inspection can also be carried in relation CPU frequency scal
Compiling and Running the Guest Applications
--------------------------------------------
For compiling and running l3fwd-power, see Chapter 11 "L3 Forwarding with Power Management Application".
For compiling and running l3fwd-power, see :doc:`l3_forward_power_man`.
A guest CLI is also provided for validating the setup.

6
doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst
View File

@ -77,7 +77,7 @@ To have the application display the statistics, send a SIGHUP signal to the runn
where, <pid> is the process id of the application process.
The VMDQ and DCB Forwarding sample application is in many ways simpler than the L2 Forwarding application
(see Chapter 9 , "L2 Forwarding Sample Application (in Real and Virtualized Environments)")
(see :doc:`l2_forward_real_virtual`)
as it performs unidirectional L2 forwarding of packets from one port to a second port.
No command-line options are taken by this application apart from the standard EAL command-line options.
@ -132,7 +132,7 @@ Initialization
The EAL, driver and PCI configuration is performed largely as in the L2 Forwarding sample application,
as is the creation of the mbuf pool.
See Chapter 9, "L2 Forwarding Sample Application (in Real and Virtualized Environments)".
See :doc:`l2_forward_real_virtual`.
Where this example application differs is in the configuration of the NIC port for RX.
The VMDQ and DCB hardware feature is configured at port initialization time by setting the appropriate values in the
@ -228,7 +228,7 @@ so the pools parameter in the rte_eth_vmdq_dcb_conf structure is specified as a
Once the network port has been initialized using the correct VMDQ and DCB values,
the initialization of the port's RX and TX hardware rings is performed similarly to that
in the L2 Forwarding sample application.
See Chapter 9, "L2 Forwarding Sample Application (in Real and Virtualized Environments)" for more information.
See :doc:`l2_forward_real_virtual` for more information.
Statistics Display
~~~~~~~~~~~~~~~~~~