Re: [dpdk-dev] [PATCH v2 1/5] doc: add performance-thread sample application guide

["Mcnamara, John" <john.mcnamara@intel.com>]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of ibetts
> Sent: Thursday, October 29, 2015 3:09 PM
> To: dev@dpdk.org
> Cc: Betts, Ian
> Subject: [dpdk-dev] [PATCH v2 1/5] doc: add performance-thread sample
> application guide
> 
> From: Ian Betts <ian.betts@intel.com>
> 
> This commit adds documentation for the performance-thread
> sample application.

Hi Ian,

Thanks for this. It is really excellent documentation.

See below for a few minor format/rendering issues.

> 
> diff --git a/doc/guides/sample_app_ug/performance_thread.rst
> b/doc/guides/sample_app_ug/performance_thread.rst
> new file mode 100644
> index 0000000..c735931
> --- /dev/null
> +++ b/doc/guides/sample_app_ug/performance_thread.rst
> @@ -0,0 +1,1243 @@
> +..  BSD LICENSE
> +    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.

The year should be 2015.


> +       export RTE_SDK=/path/to/rte_sdk cd ${RTE_SDK}/examples/performance-thread/l3fwd-thread
> +

These two commands should be on separate lines. The same applies to the later shim example.


> +The application has a number of command line options:
> +
> +.. code-block:: console
> +
> +    ./build/l3fwd-thread [EAL options] -- -p PORTMASK [-P] --
> rx(port,queue,lcore,thread)[,(port,queue,lcore,thread)] --
> tx(lcore,thread)[,(lcore,thread)] [--enable-jumbo [--max-pkt-len PKTLEN]]
> [--no-numa][--hash-entry-num][--ipv6] [--no-lthreads] [--stat-lcore lcore]


Thanks for following the guidelines. This is the only code line that is over 80 chars. I'd suggest formatting it like this:


The application has a number of command line options::

    ./build/l3fwd-thread [EAL options] --
        -p PORTMASK [-P]
        --rx(port,queue,lcore,thread)[,(port,queue,lcore,thread)]
        --tx(lcore,thread)[,(lcore,thread)]
        [--enable-jumbo] [--max-pkt-len PKTLEN]]  [--no-numa]
        [--hash-entry-num] [--ipv6] [--no-lthreads] [--stat-lcore lcore]



Note also, in most cases you can avoid " .. code-block:: console" and just use "::"
for single line code blocks.





> +
> +where,
> +
> +*   -p PORTMASK: Hexadecimal bitmask of ports to configure
> +
> +*   -P: optional, sets all ports to promiscuous mode so that packets are
> +     accepted regardless of the packet's Ethernet MAC destination
> address.
> +     Without this option, only packets with the Ethernet MAC destination
> +     address set to the Ethernet address of the port are accepted.

This would looks better with fixed width fonts for the parameters:

Where:

*   ``-p PORTMASK``: Hexadecimal bitmask of ports to configure

*   ``-P``: optional, sets all ports to promiscuous mode so that packets are
    accepted regardless of the packet's Ethernet MAC destination address.
    Without this option, only packets with the Ethernet MAC destination
    address set to the Ethernet address of the port are accepted.

The indentation is wrong in a few of these items as well.



> +The l3fwd-threads application allows you to start packet processing in
> two threading
> +models: L-Threads (default) and EAL Threads (when the "--no-lthreads"
> parameter
> +is used). For consistency all parameters are used in the same way for
> both models.
> +
> +* rx  parameters
> +
> +.. _table_l3fwd_rx_parameters:
> +
> ++--------+------------------------------------------------------+
> +| port   | rx port                                              |
> ++--------+------------------------------------------------------+
> +| queue  | rx queue that will be read on the specified rx port  |
> ++--------+------------------------------------------------------+
> +| lcore  | core to use for the thread                           |
> ++--------+------------------------------------------------------+
> +| thread | thread id (continuously from 0 to N)                 |
> ++--------+------------------------------------------------------+


The tables should be indented 3 spaces to align with the bullet list.


> +Running with L-threads
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +When the L-thread model is used (default option), lcore and thread
> parameters in
> +--rx/--tx are used to affine threads to the selected scheduler using the
> rules:
> +
> +e.g.
> +
> +
> +    .. code-block:: console
> +
> +l3fwd-thread -c ff -n 2 -- -P -p 3 \
> +        --rx="(0,0,0,0)(1,0,1,1)" \
> +        --tx="(2,0)(3,1)"
> +
> +Places every l-thread on different lcore
> +
> +    .. code-block:: console
> +
> +l3fwd-thread -c ff -n 2 -- -P -p 3 \
> +        --rx="(0,0,0,0)(1,0,0,1)" \
> +        --tx="(1,0)(2,1)"
> +

The examples should be indented

> +Places rx lthreads on lcore 0 and tx l-threads on lcore 1 and 2
> +
> +and so on.
> +
> +Running with EAL threads
> +~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +When the --no-lthreads parameter is used, L-threading model is turned off

Parameters should be quoted with backquotes ``--no-lthreads``.


> and EAL
> +threads are used for all processing. EAL Threads are enumerated in the
> same way as L-threads,
> +but the --lcores EAL parameter is used to affine thread to the selected
> cpu-set (scheduler).
> +
> +Thus it is possible to place every Rx and TX thread on different lcores
> +
> +e.g.
> +
> +    .. code-block:: console
> +
> +l3fwd-thread -c ff -n 2 -- -P -p 3 \
> +        --rx="(0,0,0,0)(1,0,1,1)" \
> +        --tx="(2,0)(3,1)" \
> +	--no-lthreads
> +
> +Places every EAL thread on different lcore.
> +
> +To affine two ore more EAL threads to one cpu-set, eal --lcores parameter
> is used

Affinitize is probably better here and s/ore/or/. There are a few other minor spellings to fix as well.


> +
> +For selected scenarios the command line configuration of the application
> for L-threads
> +and its corresponding EAL threads command line can be realized as
> follows:
> +
> +a) Start every thread on different scheduler (1:1)
> +
> +    .. code-block:: console
> +
> +l3fwd-thread -c ff -n 2 -- -P -p 3 \
> +	--rx="(0,0,0,0)(1,0,1,1)" \
> +	--tx="(2,0)(3,1)"
> +
> +    .. code-block:: console
> +
> +l3fwd-thread -c ff -n 2 -- -P -p 3 \
> +		--rx="(0,0,0,0)(1,0,1,1)" \
> +		--tx="(2,0)(3,1)" \
> +		--no-lthreads
> +


The examples should be indented. Also there are two examples here but no explanation of the difference, unlike the following examples.

I'll review the rest of the docs and the text and send on some more comments.

John.
--