[dpdk-dev] [PATCH] doc: document all EAL parameters in one place

[dpdk-dev] [PATCH] doc: document all EAL parameters in one place

[Anatoly Burakov]

Currently, the most complete (but still incomplete) user guide for
EAL command-line parameters resides in user guide for testpmd.
This is wrong on multiple levels, and should not be the case.

To fix it, we have to create a document that lists all supported
EAL command-line arguments. However, because different platforms
support different subsets of available EAL parameters, instead of
creating a single file, we will create a common file in
doc/guides/common containing documentation for EAL parameters
that are supported on all of our supported platforms (Linux and
FreeBSD at the time of this writing).

We will then include this document in the Getting Started guides
for all supported platforms, so that any changes made to
documentation for commonly supported EAL parameters will be
reflected in Getting Started guides for all platforms.

This patch also removes EAL parameters documentation from the
testpmd user guide, and instead adds references to the newly
created documents in both testpmd user guides and in sample
applications guide.

Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
---

Notes:
    Here, "supported" is defined not as "doesn't produce error
    on a particular platform, but rather is defined as "actually
    works according to current codebase". All command-line
    options have been traced through code to determine whether
    they actually do anything.
    
    As a result, even though some command-line options (such as
    "--vmware-tsc-map") are handled in eal_common_options (and
    thus are supposed to be supported on all platforms), they
    are nevertheless marked as Linux-specific. I believe this
    is a good standard to follow.
    
    It would also be good to include links to relevant PG
    sections for each parameters, but that can be done in
    the future. This is a good enough start, i think.
    
    Also, currently, this breaks our pdf doc build because
    i've added a "common" directory, and our PDF generator
    expects an index.rst to be in there, even though this
    directory is not supposed to be an actual document. I
    would kindly request community's advice on how to best
    resolve this situation.
    
    Things that i can think of myself:
    - Put the common EAL flags somewhere in the existing
      directories (we don't have anything appropriate for
      that, but the last resolt would be something like
      Linux GSG directory)
    - Hack our build system to not create a "common" PDF
      file and skip this directory altogether
    - Put this file outside of doc/guides (doc/common?)

 doc/guides/common/eal_args.include.rst        | 146 ++++++++++++++++++
 .../freebsd_gsg/freebsd_eal_parameters.rst    |  20 +++
 doc/guides/freebsd_gsg/index.rst              |   1 +
 doc/guides/linux_gsg/index.rst                |   1 +
 doc/guides/linux_gsg/linux_eal_parameters.rst | 118 ++++++++++++++
 doc/guides/sample_app_ug/intro.rst            |  10 ++
 doc/guides/testpmd_app_ug/run_app.rst         | 132 +---------------
 7 files changed, 299 insertions(+), 129 deletions(-)
 create mode 100644 doc/guides/common/eal_args.include.rst
 create mode 100644 doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
 create mode 100644 doc/guides/linux_gsg/linux_eal_parameters.rst

diff --git a/doc/guides/common/eal_args.include.rst b/doc/guides/common/eal_args.include.rst
new file mode 100644
index 000000000..cf421a56e
--- /dev/null
+++ b/doc/guides/common/eal_args.include.rst
@@ -0,0 +1,146 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Intel Corporation.
+
+Lcore-related options
+~~~~~~~~~~~~~~~~~~~~~
+
+*   ``-c <core mask>``
+
+    Set the hexadecimal bitmask of the cores to run on.
+
+*   ``-l <core list>``
+
+    List of cores to run on
+
+    The argument format is ``<c1>[-c2][,c3[-c4],...]``
+    where ``c1``, ``c2``, etc are core indexes between 0 and 128.
+
+*   ``--lcores <core map>``
+
+    Map lcore set to physical cpu set
+
+    The argument format is::
+
+       <lcores[@cpus]>[<,lcores[@cpus]>...]
+
+    Lcore and CPU lists are grouped by ``(`` and ``)`` Within the group.
+    The ``-`` character is used as a range separator and ``,`` is used as a
+    single number separator.
+    The grouping ``()`` can be omitted for single element group.
+    The ``@`` can be omitted if cpus and lcores have the same value.
+
+.. Note::
+    At a given instance only one core option ``--lcores``, ``-l`` or ``-c`` can
+    be used.
+
+*   ``--master-lcore <core ID>``
+
+    Core ID that is used as master.
+
+*   ``-s <service core mask>``
+
+    Hexadecimal bitmask of cores to be used as service cores.
+
+Device-related options
+~~~~~~~~~~~~~~~~~~~~~~
+
+*   ``-b, --pci-blacklist <[domain:]bus:devid.func>``
+
+    Blacklist a PCI device to prevent EAL from using it. Multiple -b options are
+    allowed.
+
+.. Note::
+    PCI blacklist cannot be used with ``-w`` option.
+
+*   ``-w, --pci-whitelist <[domain:]bus:devid.func>``
+
+    Add a PCI device in white list.
+
+.. Note::
+    PCI whitelist cannot be used with ``-b`` option.
+
+*   ``--vdev <device arguments>``
+
+    Add a virtual device using the format::
+
+       <driver><id>[,key=val, ...]
+
+    For example::
+
+       --vdev 'net_pcap0,rx_pcap=input.pcap,tx_pcap=output.pcap'
+
+*   ``-d <path to shared object or directory>``
+
+    Load external drivers. An argument can be a single shared object file, or a
+    directory containing multiple driver shared objects. Multiple -d options are
+    allowed.
+
+*   ``--no-pci``
+
+    Disable PCI bus.
+
+Multiprocessing-related options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*   ``--proc-type <primary|secondary|auto>``
+
+    Set the type of the current process.
+
+Memory-related options
+~~~~~~~~~~~~~~~~~~~~~~
+
+*   ``-n <number of channels>``
+
+    Set the number of memory channels to use.
+
+*   ``-r <number of ranks>``
+
+    Set the number of memory ranks (auto-detected by default).
+
+*   ``-m <megabytes>``
+
+    Amount of memory to preallocate at startup.
+
+*   ``--in-memory``
+
+    Do not create any shared data structures and run entirely in memory. Implies
+    ``--no-shconf`` and (if applicable) ``--huge-unlink``.
+
+*   ``--iova-mode <pa|va>``
+
+    Force IOVA mode to a specific value.
+
+Debugging options
+~~~~~~~~~~~~~~~~~
+
+*   ``--no-shconf``
+
+    No shared files created (implies no secondary process support).
+
+*   ``--no-huge``
+
+    Use anonymous memory instead of hugepages (implies no secondary process
+    support).
+
+*   ``--log-level <type:val>``
+
+    Specify log level for a specific component. For example::
+
+        --log-level eal:8
+
+    Can be specified multiple times.
+
+Other options
+~~~~~~~~~~~~~
+
+*   ``-h``, ``--help``
+
+    Display help message listing all EAL parameters.
+
+*   ``-v``
+
+    Display the version information on startup.
+
+*   ``mbuf-pool-ops-name``:
+
+    Pool ops name for mbuf to use.
diff --git a/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst b/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
new file mode 100644
index 000000000..9db6381a0
--- /dev/null
+++ b/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
@@ -0,0 +1,20 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Intel Corporation.
+
+EAL parameters
+==============
+
+This document contains a list of all EAL parameters. These parameters can be
+used by any DPDK application running on Linux.
+
+Common EAL parameters
+---------------------
+
+The following EAL parameters are common to all platforms supported by DPDK.
+
+.. include:: ../common/eal_args.include.rst
+
+FreeBSD-specific EAL parameters
+-------------------------------
+
+There are currently no FreeBSD-specific EAL command-line parameters available.
diff --git a/doc/guides/freebsd_gsg/index.rst b/doc/guides/freebsd_gsg/index.rst
index fdb4df32e..9af5988dc 100644
--- a/doc/guides/freebsd_gsg/index.rst
+++ b/doc/guides/freebsd_gsg/index.rst
@@ -14,3 +14,4 @@ Getting Started Guide for FreeBSD
     install_from_ports
     build_dpdk
     build_sample_apps
+    freebsd_eal_parameters
diff --git a/doc/guides/linux_gsg/index.rst b/doc/guides/linux_gsg/index.rst
index 077f93023..0f9f6242c 100644
--- a/doc/guides/linux_gsg/index.rst
+++ b/doc/guides/linux_gsg/index.rst
@@ -16,6 +16,7 @@ Getting Started Guide for Linux
     cross_build_dpdk_for_arm64
     linux_drivers
     build_sample_apps
+    linux_eal_parameters
     enable_func
     quick_start
     nic_perf_intel_platform
diff --git a/doc/guides/linux_gsg/linux_eal_parameters.rst b/doc/guides/linux_gsg/linux_eal_parameters.rst
new file mode 100644
index 000000000..b0698636d
--- /dev/null
+++ b/doc/guides/linux_gsg/linux_eal_parameters.rst
@@ -0,0 +1,118 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Intel Corporation.
+
+EAL parameters
+==============
+
+This document contains a list of all EAL parameters. These parameters can be
+used by any DPDK application running on Linux.
+
+Common EAL parameters
+---------------------
+
+The following EAL parameters are common to all platforms supported by DPDK.
+
+.. include:: ../common/eal_args.include.rst
+
+Linux-specific EAL parameters
+-----------------------------
+
+In addition to common EAL parameters, there are also Linux-specific EAL
+parameters.
+
+Device-related options
+~~~~~~~~~~~~~~~~~~~~~~
+
+*   ``--create-uio-dev``
+
+    Create ``/dev/uioX`` files for devices bound to igb_uio kernel driver
+    (usually done by the igb_uio driver itself).
+
+*   ``--vmware-tsc-map``
+
+    Use VMware TSC map instead of native RDTSC.
+
+*   ``--no-hpet``
+
+    Do not use the HPET timer.
+
+*   ``--vfio-intr <legacy|msi|msix>``
+
+    Use specified interrupt mode for devices bound to VFIO kernel driver.
+
+Multiprocessing-related options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*   ``--file-prefix <prefix name>``
+
+    Use a different shared data file prefix for a DPDK process. This option
+    allows running multiple independent DPDK primary/secondary processes under
+    different prefixes.
+
+*   ``--base-virtaddr <address>``
+
+    Attempt to use a different starting address for all memory maps of the
+    primary DPDK process. This can be helpful if secondary processes cannot
+    start due to conflicts in address map.
+
+Memory-related options
+~~~~~~~~~~~~~~~~~~~~~~
+
+*   ``--legacy-mem``
+
+    Use legacy DPDK memory allocation mode.
+
+*   ``--socket-mem <amounts of memory per socket>``
+
+    Preallocate specified amounts of memory per socket. The parameter is a
+    comma-separated list of values. For example::
+
+        --socket-mem 1024,2048
+
+    This will allocate 1 gigabyte of memory on socket 0, and 2048 megabytes of
+    memory on socket 1.
+
+*   ``--socket-limit <amounts of memory per socket>``
+
+    Place a per-socket upper limit on memory use (non-legacy memory mode only).
+    0 will disable the limit for a particular socket.
+
+*   ``--single-file-segments``
+
+    Create fewer files in hugetlbfs (non-legacy mode only).
+
+*   ``--huge-dir <path to hugetlbfs directory>``
+
+    Use specified hugetlbfs directory instead of autodetected ones.
+
+*   ``--huge-unlink``
+
+    Unlink hugepage files after creating them (implies no secondary process
+    support).
+
+Other options
+~~~~~~~~~~~~~
+
+*   ``--syslog <syslog facility>``
+
+    Set syslog facility. Valid syslog facilities are::
+
+        auth
+        cron
+        daemon
+        ftp
+        kern
+        lpr
+        mail
+        news
+        syslog
+        user
+        uucp
+        local0
+        local1
+        local2
+        local3
+        local4
+        local5
+        local6
+        local7
diff --git a/doc/guides/sample_app_ug/intro.rst b/doc/guides/sample_app_ug/intro.rst
index 575995de0..159bcf73b 100644
--- a/doc/guides/sample_app_ug/intro.rst
+++ b/doc/guides/sample_app_ug/intro.rst
@@ -10,6 +10,16 @@ DPDK features.  Users interested in getting started with DPDK can take the
 applications, try out the features, and then extend them to fit their needs.
 
 
+Running Sample Applications
+---------------------------
+
+Some sample applications may have their own command-line parameters described in
+their respective guides, however all of them also share the same EAL parameters.
+Please refer to  :doc:`../linux_gsg/linux_eal_parameters` or
+:doc:`../freebsd_gsg/freebsd_eal_parameters` for a list of available EAL
+command-line options.
+
+
 The DPDK Sample Applications
 ----------------------------
 
diff --git a/doc/guides/testpmd_app_ug/run_app.rst b/doc/guides/testpmd_app_ug/run_app.rst
index c79fd0d0b..f717bd3f4 100644
--- a/doc/guides/testpmd_app_ug/run_app.rst
+++ b/doc/guides/testpmd_app_ug/run_app.rst
@@ -7,135 +7,9 @@ Running the Application
 EAL Command-line Options
 ------------------------
 
-The following are the EAL command-line options that can be used in conjunction with the testpmd,
-or any other DPDK application.
-See the DPDK Getting Started Guides for more information on these options.
-
-*   ``-c COREMASK``
-
-    Set the hexadecimal bitmask of the cores to run on.
-
-*   ``-l CORELIST``
-
-    List of cores to run on
-
-    The argument format is ``<c1>[-c2][,c3[-c4],...]``
-    where ``c1``, ``c2``, etc are core indexes between 0 and 128.
-
-*   ``--lcores COREMAP``
-
-    Map lcore set to physical cpu set
-
-    The argument format is::
-
-       <lcores[@cpus]>[<,lcores[@cpus]>...]
-
-    Lcore and CPU lists are grouped by ``(`` and ``)`` Within the group.
-    The ``-`` character is used as a range separator and ``,`` is used as a single number separator.
-    The grouping ``()`` can be omitted for single element group.
-    The ``@`` can be omitted if cpus and lcores have the same value.
-
-.. Note::
-    At a given instance only one core option ``--lcores``, ``-l`` or ``-c`` can be used.
-
-
-*   ``--master-lcore ID``
-
-    Core ID that is used as master.
-
-*   ``-n NUM``
-
-    Set the number of memory channels to use.
-
-*   ``-b, --pci-blacklist domain:bus:devid.func``
-
-    Blacklist a PCI device to prevent EAL from using it. Multiple -b options are allowed.
-
-*   ``-d LIB.so``
-
-    Load an external driver. Multiple -d options are allowed.
-
-*   ``-w, --pci-whitelist domain:bus:devid:func``
-
-    Add a PCI device in white list.
-
-*   ``-m MB``
-
-    Memory to allocate. See also ``--socket-mem``.
-
-*   ``-r NUM``
-
-    Set the number of memory ranks (auto-detected by default).
-
-*   ``-v``
-
-    Display the version information on startup.
-
-*   ``--syslog``
-
-    Set the syslog facility.
-
-*   ``--socket-mem``
-
-    Set the memory to allocate on specific sockets (use comma separated values).
-
-*   ``--huge-dir``
-
-    Specify the directory where the hugetlbfs is mounted.
-
-*   ``mbuf-pool-ops-name``:
-
-    Pool ops name for mbuf to use.
-
-*   ``--proc-type``
-
-    Set the type of the current process.
-
-*   ``--file-prefix``
-
-    Prefix for hugepage filenames.
-
-*   ``-vmware-tsc-map``
-
-    Use VMware TSC map instead of native RDTSC.
-
-*   ``--vdev``
-
-    Add a virtual device using the format::
-
-       <driver><id>[,key=val, ...]
-
-    For example::
-
-       --vdev 'net_pcap0,rx_pcap=input.pcap,tx_pcap=output.pcap'
-
-*   ``--base-virtaddr``
-
-    Specify base virtual address.
-
-*   ``--create-uio-dev``
-
-    Create ``/dev/uioX`` (usually done by hotplug).
-
-*   ``--no-shconf``
-
-    No shared config (mmap-ed files).
-
-*   ``--no-pci``
-
-    Disable pci.
-
-*   ``--no-hpet``
-
-    Disable hpet.
-
-*   ``--no-huge``
-
-    Use malloc instead of hugetlbfs.
-
-*   ``--iova-mode <pa|va>``
-
-    Force IOVA mode to a specific value.
+Please refer to  :doc:`../linux_gsg/linux_eal_parameters` or
+:doc:`../freebsd_gsg/freebsd_eal_parameters` for a list of available EAL
+command-line options.
 
 
 Testpmd Command-line Options
-- 
2.17.1

Re: [dpdk-dev] [PATCH] doc: document all EAL parameters in one place

[Ferruh Yigit]

On 11/16/2018 4:52 PM, Anatoly Burakov wrote:
> Currently, the most complete (but still incomplete) user guide for
> EAL command-line parameters resides in user guide for testpmd.
> This is wrong on multiple levels, and should not be the case.
> 
> To fix it, we have to create a document that lists all supported
> EAL command-line arguments. However, because different platforms
> support different subsets of available EAL parameters, instead of
> creating a single file, we will create a common file in
> doc/guides/common containing documentation for EAL parameters
> that are supported on all of our supported platforms (Linux and
> FreeBSD at the time of this writing).
> 
> We will then include this document in the Getting Started guides
> for all supported platforms, so that any changes made to
> documentation for commonly supported EAL parameters will be
> reflected in Getting Started guides for all platforms.
> 
> This patch also removes EAL parameters documentation from the
> testpmd user guide, and instead adds references to the newly
> created documents in both testpmd user guides and in sample
> applications guide.
> 
> Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>

+1

Acked-by: Ferruh Yigit <ferruh.yigit@intel.com>

Re: [dpdk-dev] [PATCH] doc: document all EAL parameters in one place

[Rami Rosen]

On 11/16/2018 4:52 PM, Anatoly Burakov wrote:
> Currently, the most complete (but still incomplete) user guide for
> EAL command-line parameters resides in user guide for testpmd.
> This is wrong on multiple levels, and should not be the case.
>
> To fix it, we have to create a document that lists all supported
> EAL command-line arguments. However, because different platforms
> support different subsets of available EAL parameters, instead of
> creating a single file, we will create a common file in
> doc/guides/common containing documentation for EAL parameters
> that are supported on all of our supported platforms (Linux and
> FreeBSD at the time of this writing).
>
> We will then include this document in the Getting Started guides
> for all supported platforms, so that any changes made to
> documentation for commonly supported EAL parameters will be
> reflected in Getting Started guides for all platforms.
>
> This patch also removes EAL parameters documentation from the
> testpmd user guide, and instead adds references to the newly
> created documents in both testpmd user guides and in sample
> applications guide.
>
> Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>

This is a right and needed thing to do, thanks!

Reviewed-by: Rami Rosen <roszenrami at gmail.com>

Re: [dpdk-dev] [PATCH] doc: document all EAL parameters in one place

[Burakov, Anatoly]

On 16-Nov-18 4:52 PM, Anatoly Burakov wrote:
> Currently, the most complete (but still incomplete) user guide for
> EAL command-line parameters resides in user guide for testpmd.
> This is wrong on multiple levels, and should not be the case.
> 
> To fix it, we have to create a document that lists all supported
> EAL command-line arguments. However, because different platforms
> support different subsets of available EAL parameters, instead of
> creating a single file, we will create a common file in
> doc/guides/common containing documentation for EAL parameters
> that are supported on all of our supported platforms (Linux and
> FreeBSD at the time of this writing).
> 
> We will then include this document in the Getting Started guides
> for all supported platforms, so that any changes made to
> documentation for commonly supported EAL parameters will be
> reflected in Getting Started guides for all platforms.
> 
> This patch also removes EAL parameters documentation from the
> testpmd user guide, and instead adds references to the newly
> created documents in both testpmd user guides and in sample
> applications guide.
> 
> Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
> ---
> 
> Notes:
>      Here, "supported" is defined not as "doesn't produce error
>      on a particular platform, but rather is defined as "actually
>      works according to current codebase". All command-line
>      options have been traced through code to determine whether
>      they actually do anything.
>      
>      As a result, even though some command-line options (such as
>      "--vmware-tsc-map") are handled in eal_common_options (and
>      thus are supposed to be supported on all platforms), they
>      are nevertheless marked as Linux-specific. I believe this
>      is a good standard to follow.
>      
>      It would also be good to include links to relevant PG
>      sections for each parameters, but that can be done in
>      the future. This is a good enough start, i think.
>      
>      Also, currently, this breaks our pdf doc build because
>      i've added a "common" directory, and our PDF generator
>      expects an index.rst to be in there, even though this
>      directory is not supposed to be an actual document. I
>      would kindly request community's advice on how to best
>      resolve this situation.
>      
>      Things that i can think of myself:
>      - Put the common EAL flags somewhere in the existing
>        directories (we don't have anything appropriate for
>        that, but the last resolt would be something like
>        Linux GSG directory)
>      - Hack our build system to not create a "common" PDF
>        file and skip this directory altogether
>      - Put this file outside of doc/guides (doc/common?)
> 

The above problem with pdf doc build still exists and needs to be solved 
before this patch is integrated. Unfortunately, my LaTeX-fu is lacking, 
so i'd really like some help here :)

-- 
Thanks,
Anatoly

Re: [dpdk-dev] [PATCH] doc: document all EAL parameters in one place

[Mcnamara, John]

> -----Original Message-----
> From: Rami Rosen [mailto:roszenrami@gmail.com]
> Sent: Saturday, November 17, 2018 5:15 AM
> To: Yigit, Ferruh <ferruh.yigit@intel.com>
> Cc: Burakov, Anatoly <anatoly.burakov@intel.com>; dev@dpdk.org; Mcnamara,
> John <john.mcnamara@intel.com>; Kovacevic, Marko
> <marko.kovacevic@intel.com>; Richardson, Bruce
> <bruce.richardson@intel.com>; Lu, Wenzhuo <wenzhuo.lu@intel.com>; Wu,
> Jingjing <jingjing.wu@intel.com>; Iremonger, Bernard
> <bernard.iremonger@intel.com>; thomas@monjalon.net; Wiles, Keith
> <keith.wiles@intel.com>
> Subject: Re: [dpdk-dev] [PATCH] doc: document all EAL parameters in one
> place
> 
> This is a right and needed thing to do, thanks!
> 

Agreed. +1

John

[dpdk-dev] [PATCH v2] doc: document all EAL parameters in one place

[Anatoly Burakov]

Currently, the most complete (but still incomplete) user guide for
EAL command-line parameters resides in user guide for testpmd.
This is wrong on multiple levels, and should not be the case.

To fix it, we have to create a document that lists all supported
EAL command-line arguments. However, because different platforms
support different subsets of available EAL parameters, instead of
creating a single file, we will create a common file in
doc/guides/common containing documentation for EAL parameters
that are supported on all of our supported platforms (Linux and
FreeBSD at the time of this writing).

We will then include this document in the Getting Started guides
for all supported platforms, so that any changes made to
documentation for commonly supported EAL parameters will be
reflected in Getting Started guides for all platforms.

This patch also removes EAL parameters documentation from the
testpmd user guide, and instead adds references to the newly
created documents in both testpmd user guides and in sample
applications guide.

Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
Acked-by: Ferruh Yigit <ferruh.yigit@intel.com>
Reviewed-by: Rami Rosen <roszenrami@gmail.com>
---

Notes:
    v2:
    - Moved the new file into Linux GSG directory instead of
      common directory. Seems like the least bad solution of
      them all.
    
    Here, "supported" is defined not as "doesn't produce error
    on a particular platform", but rather is defined as "actually
    works according to current codebase". All command-line
    options have been traced through code to determine whether
    they actually do anything.
    
    As a result, even though some command-line options (such as
    "--vmware-tsc-map") are handled in eal_common_options (and
    thus are supposed to be supported on all platforms), they
    are nevertheless marked as Linux-specific. I believe this
    is a good standard to follow.
    
    It would also be good to include links to relevant PG
    sections for each parameters, but that can be done in
    the future. This is a good enough start, i think.

 .../freebsd_gsg/freebsd_eal_parameters.rst    |  20 +++
 doc/guides/freebsd_gsg/index.rst              |   1 +
 doc/guides/linux_gsg/eal_args.include.rst     | 146 ++++++++++++++++++
 doc/guides/linux_gsg/index.rst                |   1 +
 doc/guides/linux_gsg/linux_eal_parameters.rst | 118 ++++++++++++++
 doc/guides/sample_app_ug/intro.rst            |  10 ++
 doc/guides/testpmd_app_ug/run_app.rst         | 132 +---------------
 7 files changed, 299 insertions(+), 129 deletions(-)
 create mode 100644 doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
 create mode 100644 doc/guides/linux_gsg/eal_args.include.rst
 create mode 100644 doc/guides/linux_gsg/linux_eal_parameters.rst

diff --git a/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst b/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
new file mode 100644
index 000000000..b8dd3c7e8
--- /dev/null
+++ b/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
@@ -0,0 +1,20 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Intel Corporation.
+
+EAL parameters
+==============
+
+This document contains a list of all EAL parameters. These parameters can be
+used by any DPDK application running on Linux.
+
+Common EAL parameters
+---------------------
+
+The following EAL parameters are common to all platforms supported by DPDK.
+
+.. include:: ../linux_gsg/eal_args.include.rst
+
+FreeBSD-specific EAL parameters
+-------------------------------
+
+There are currently no FreeBSD-specific EAL command-line parameters available.
diff --git a/doc/guides/freebsd_gsg/index.rst b/doc/guides/freebsd_gsg/index.rst
index fdb4df32e..9af5988dc 100644
--- a/doc/guides/freebsd_gsg/index.rst
+++ b/doc/guides/freebsd_gsg/index.rst
@@ -14,3 +14,4 @@ Getting Started Guide for FreeBSD
     install_from_ports
     build_dpdk
     build_sample_apps
+    freebsd_eal_parameters
diff --git a/doc/guides/linux_gsg/eal_args.include.rst b/doc/guides/linux_gsg/eal_args.include.rst
new file mode 100644
index 000000000..cf421a56e
--- /dev/null
+++ b/doc/guides/linux_gsg/eal_args.include.rst
@@ -0,0 +1,146 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Intel Corporation.
+
+Lcore-related options
+~~~~~~~~~~~~~~~~~~~~~
+
+*   ``-c <core mask>``
+
+    Set the hexadecimal bitmask of the cores to run on.
+
+*   ``-l <core list>``
+
+    List of cores to run on
+
+    The argument format is ``<c1>[-c2][,c3[-c4],...]``
+    where ``c1``, ``c2``, etc are core indexes between 0 and 128.
+
+*   ``--lcores <core map>``
+
+    Map lcore set to physical cpu set
+
+    The argument format is::
+
+       <lcores[@cpus]>[<,lcores[@cpus]>...]
+
+    Lcore and CPU lists are grouped by ``(`` and ``)`` Within the group.
+    The ``-`` character is used as a range separator and ``,`` is used as a
+    single number separator.
+    The grouping ``()`` can be omitted for single element group.
+    The ``@`` can be omitted if cpus and lcores have the same value.
+
+.. Note::
+    At a given instance only one core option ``--lcores``, ``-l`` or ``-c`` can
+    be used.
+
+*   ``--master-lcore <core ID>``
+
+    Core ID that is used as master.
+
+*   ``-s <service core mask>``
+
+    Hexadecimal bitmask of cores to be used as service cores.
+
+Device-related options
+~~~~~~~~~~~~~~~~~~~~~~
+
+*   ``-b, --pci-blacklist <[domain:]bus:devid.func>``
+
+    Blacklist a PCI device to prevent EAL from using it. Multiple -b options are
+    allowed.
+
+.. Note::
+    PCI blacklist cannot be used with ``-w`` option.
+
+*   ``-w, --pci-whitelist <[domain:]bus:devid.func>``
+
+    Add a PCI device in white list.
+
+.. Note::
+    PCI whitelist cannot be used with ``-b`` option.
+
+*   ``--vdev <device arguments>``
+
+    Add a virtual device using the format::
+
+       <driver><id>[,key=val, ...]
+
+    For example::
+
+       --vdev 'net_pcap0,rx_pcap=input.pcap,tx_pcap=output.pcap'
+
+*   ``-d <path to shared object or directory>``
+
+    Load external drivers. An argument can be a single shared object file, or a
+    directory containing multiple driver shared objects. Multiple -d options are
+    allowed.
+
+*   ``--no-pci``
+
+    Disable PCI bus.
+
+Multiprocessing-related options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*   ``--proc-type <primary|secondary|auto>``
+
+    Set the type of the current process.
+
+Memory-related options
+~~~~~~~~~~~~~~~~~~~~~~
+
+*   ``-n <number of channels>``
+
+    Set the number of memory channels to use.
+
+*   ``-r <number of ranks>``
+
+    Set the number of memory ranks (auto-detected by default).
+
+*   ``-m <megabytes>``
+
+    Amount of memory to preallocate at startup.
+
+*   ``--in-memory``
+
+    Do not create any shared data structures and run entirely in memory. Implies
+    ``--no-shconf`` and (if applicable) ``--huge-unlink``.
+
+*   ``--iova-mode <pa|va>``
+
+    Force IOVA mode to a specific value.
+
+Debugging options
+~~~~~~~~~~~~~~~~~
+
+*   ``--no-shconf``
+
+    No shared files created (implies no secondary process support).
+
+*   ``--no-huge``
+
+    Use anonymous memory instead of hugepages (implies no secondary process
+    support).
+
+*   ``--log-level <type:val>``
+
+    Specify log level for a specific component. For example::
+
+        --log-level eal:8
+
+    Can be specified multiple times.
+
+Other options
+~~~~~~~~~~~~~
+
+*   ``-h``, ``--help``
+
+    Display help message listing all EAL parameters.
+
+*   ``-v``
+
+    Display the version information on startup.
+
+*   ``mbuf-pool-ops-name``:
+
+    Pool ops name for mbuf to use.
diff --git a/doc/guides/linux_gsg/index.rst b/doc/guides/linux_gsg/index.rst
index 077f93023..0f9f6242c 100644
--- a/doc/guides/linux_gsg/index.rst
+++ b/doc/guides/linux_gsg/index.rst
@@ -16,6 +16,7 @@ Getting Started Guide for Linux
     cross_build_dpdk_for_arm64
     linux_drivers
     build_sample_apps
+    linux_eal_parameters
     enable_func
     quick_start
     nic_perf_intel_platform
diff --git a/doc/guides/linux_gsg/linux_eal_parameters.rst b/doc/guides/linux_gsg/linux_eal_parameters.rst
new file mode 100644
index 000000000..28aebfbda
--- /dev/null
+++ b/doc/guides/linux_gsg/linux_eal_parameters.rst
@@ -0,0 +1,118 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Intel Corporation.
+
+EAL parameters
+==============
+
+This document contains a list of all EAL parameters. These parameters can be
+used by any DPDK application running on Linux.
+
+Common EAL parameters
+---------------------
+
+The following EAL parameters are common to all platforms supported by DPDK.
+
+.. include:: eal_args.include.rst
+
+Linux-specific EAL parameters
+-----------------------------
+
+In addition to common EAL parameters, there are also Linux-specific EAL
+parameters.
+
+Device-related options
+~~~~~~~~~~~~~~~~~~~~~~
+
+*   ``--create-uio-dev``
+
+    Create ``/dev/uioX`` files for devices bound to igb_uio kernel driver
+    (usually done by the igb_uio driver itself).
+
+*   ``--vmware-tsc-map``
+
+    Use VMware TSC map instead of native RDTSC.
+
+*   ``--no-hpet``
+
+    Do not use the HPET timer.
+
+*   ``--vfio-intr <legacy|msi|msix>``
+
+    Use specified interrupt mode for devices bound to VFIO kernel driver.
+
+Multiprocessing-related options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*   ``--file-prefix <prefix name>``
+
+    Use a different shared data file prefix for a DPDK process. This option
+    allows running multiple independent DPDK primary/secondary processes under
+    different prefixes.
+
+*   ``--base-virtaddr <address>``
+
+    Attempt to use a different starting address for all memory maps of the
+    primary DPDK process. This can be helpful if secondary processes cannot
+    start due to conflicts in address map.
+
+Memory-related options
+~~~~~~~~~~~~~~~~~~~~~~
+
+*   ``--legacy-mem``
+
+    Use legacy DPDK memory allocation mode.
+
+*   ``--socket-mem <amounts of memory per socket>``
+
+    Preallocate specified amounts of memory per socket. The parameter is a
+    comma-separated list of values. For example::
+
+        --socket-mem 1024,2048
+
+    This will allocate 1 gigabyte of memory on socket 0, and 2048 megabytes of
+    memory on socket 1.
+
+*   ``--socket-limit <amounts of memory per socket>``
+
+    Place a per-socket upper limit on memory use (non-legacy memory mode only).
+    0 will disable the limit for a particular socket.
+
+*   ``--single-file-segments``
+
+    Create fewer files in hugetlbfs (non-legacy mode only).
+
+*   ``--huge-dir <path to hugetlbfs directory>``
+
+    Use specified hugetlbfs directory instead of autodetected ones.
+
+*   ``--huge-unlink``
+
+    Unlink hugepage files after creating them (implies no secondary process
+    support).
+
+Other options
+~~~~~~~~~~~~~
+
+*   ``--syslog <syslog facility>``
+
+    Set syslog facility. Valid syslog facilities are::
+
+        auth
+        cron
+        daemon
+        ftp
+        kern
+        lpr
+        mail
+        news
+        syslog
+        user
+        uucp
+        local0
+        local1
+        local2
+        local3
+        local4
+        local5
+        local6
+        local7
diff --git a/doc/guides/sample_app_ug/intro.rst b/doc/guides/sample_app_ug/intro.rst
index 575995de0..159bcf73b 100644
--- a/doc/guides/sample_app_ug/intro.rst
+++ b/doc/guides/sample_app_ug/intro.rst
@@ -10,6 +10,16 @@ DPDK features.  Users interested in getting started with DPDK can take the
 applications, try out the features, and then extend them to fit their needs.
 
 
+Running Sample Applications
+---------------------------
+
+Some sample applications may have their own command-line parameters described in
+their respective guides, however all of them also share the same EAL parameters.
+Please refer to  :doc:`../linux_gsg/linux_eal_parameters` or
+:doc:`../freebsd_gsg/freebsd_eal_parameters` for a list of available EAL
+command-line options.
+
+
 The DPDK Sample Applications
 ----------------------------
 
diff --git a/doc/guides/testpmd_app_ug/run_app.rst b/doc/guides/testpmd_app_ug/run_app.rst
index c79fd0d0b..f717bd3f4 100644
--- a/doc/guides/testpmd_app_ug/run_app.rst
+++ b/doc/guides/testpmd_app_ug/run_app.rst
@@ -7,135 +7,9 @@ Running the Application
 EAL Command-line Options
 ------------------------
 
-The following are the EAL command-line options that can be used in conjunction with the testpmd,
-or any other DPDK application.
-See the DPDK Getting Started Guides for more information on these options.
-
-*   ``-c COREMASK``
-
-    Set the hexadecimal bitmask of the cores to run on.
-
-*   ``-l CORELIST``
-
-    List of cores to run on
-
-    The argument format is ``<c1>[-c2][,c3[-c4],...]``
-    where ``c1``, ``c2``, etc are core indexes between 0 and 128.
-
-*   ``--lcores COREMAP``
-
-    Map lcore set to physical cpu set
-
-    The argument format is::
-
-       <lcores[@cpus]>[<,lcores[@cpus]>...]
-
-    Lcore and CPU lists are grouped by ``(`` and ``)`` Within the group.
-    The ``-`` character is used as a range separator and ``,`` is used as a single number separator.
-    The grouping ``()`` can be omitted for single element group.
-    The ``@`` can be omitted if cpus and lcores have the same value.
-
-.. Note::
-    At a given instance only one core option ``--lcores``, ``-l`` or ``-c`` can be used.
-
-
-*   ``--master-lcore ID``
-
-    Core ID that is used as master.
-
-*   ``-n NUM``
-
-    Set the number of memory channels to use.
-
-*   ``-b, --pci-blacklist domain:bus:devid.func``
-
-    Blacklist a PCI device to prevent EAL from using it. Multiple -b options are allowed.
-
-*   ``-d LIB.so``
-
-    Load an external driver. Multiple -d options are allowed.
-
-*   ``-w, --pci-whitelist domain:bus:devid:func``
-
-    Add a PCI device in white list.
-
-*   ``-m MB``
-
-    Memory to allocate. See also ``--socket-mem``.
-
-*   ``-r NUM``
-
-    Set the number of memory ranks (auto-detected by default).
-
-*   ``-v``
-
-    Display the version information on startup.
-
-*   ``--syslog``
-
-    Set the syslog facility.
-
-*   ``--socket-mem``
-
-    Set the memory to allocate on specific sockets (use comma separated values).
-
-*   ``--huge-dir``
-
-    Specify the directory where the hugetlbfs is mounted.
-
-*   ``mbuf-pool-ops-name``:
-
-    Pool ops name for mbuf to use.
-
-*   ``--proc-type``
-
-    Set the type of the current process.
-
-*   ``--file-prefix``
-
-    Prefix for hugepage filenames.
-
-*   ``-vmware-tsc-map``
-
-    Use VMware TSC map instead of native RDTSC.
-
-*   ``--vdev``
-
-    Add a virtual device using the format::
-
-       <driver><id>[,key=val, ...]
-
-    For example::
-
-       --vdev 'net_pcap0,rx_pcap=input.pcap,tx_pcap=output.pcap'
-
-*   ``--base-virtaddr``
-
-    Specify base virtual address.
-
-*   ``--create-uio-dev``
-
-    Create ``/dev/uioX`` (usually done by hotplug).
-
-*   ``--no-shconf``
-
-    No shared config (mmap-ed files).
-
-*   ``--no-pci``
-
-    Disable pci.
-
-*   ``--no-hpet``
-
-    Disable hpet.
-
-*   ``--no-huge``
-
-    Use malloc instead of hugetlbfs.
-
-*   ``--iova-mode <pa|va>``
-
-    Force IOVA mode to a specific value.
+Please refer to  :doc:`../linux_gsg/linux_eal_parameters` or
+:doc:`../freebsd_gsg/freebsd_eal_parameters` for a list of available EAL
+command-line options.
 
 
 Testpmd Command-line Options
-- 
2.17.1

Re: [dpdk-dev] [PATCH v2] doc: document all EAL parameters in one place

[Burakov, Anatoly]

On 19-Nov-18 1:10 PM, Anatoly Burakov wrote:
> Currently, the most complete (but still incomplete) user guide for
> EAL command-line parameters resides in user guide for testpmd.
> This is wrong on multiple levels, and should not be the case.
> 
> To fix it, we have to create a document that lists all supported
> EAL command-line arguments. However, because different platforms
> support different subsets of available EAL parameters, instead of
> creating a single file, we will create a common file in
> doc/guides/common containing documentation for EAL parameters

Oops, forgot to fix commit message. Should be "doc/guides/linux_gsg", 
not "doc/guides/common".

> that are supported on all of our supported platforms (Linux and
> FreeBSD at the time of this writing).
> 
> We will then include this document in the Getting Started guides
> for all supported platforms, so that any changes made to
> documentation for commonly supported EAL parameters will be
> reflected in Getting Started guides for all platforms.
> 
> This patch also removes EAL parameters documentation from the
> testpmd user guide, and instead adds references to the newly
> created documents in both testpmd user guides and in sample
> applications guide.
> 
> Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
> Acked-by: Ferruh Yigit <ferruh.yigit@intel.com>
> Reviewed-by: Rami Rosen <roszenrami@gmail.com>
> ---

-- 
Thanks,
Anatoly

Re: [dpdk-dev] [PATCH v2] doc: document all EAL parameters in one place

[Thomas Monjalon]

19/11/2018 14:10, Anatoly Burakov:
> --- /dev/null
> +++ b/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
> @@ -0,0 +1,20 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2018 Intel Corporation.
> +
> +EAL parameters
> +==============
> +
> +This document contains a list of all EAL parameters. These parameters can be
> +used by any DPDK application running on Linux.

Is it a typo? running on FreeBSD?

Re: [dpdk-dev] [PATCH v2] doc: document all EAL parameters in one place

[Burakov, Anatoly]

On 22-Nov-18 5:27 PM, Thomas Monjalon wrote:
> 19/11/2018 14:10, Anatoly Burakov:
>> --- /dev/null
>> +++ b/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
>> @@ -0,0 +1,20 @@
>> +..  SPDX-License-Identifier: BSD-3-Clause
>> +    Copyright(c) 2018 Intel Corporation.
>> +
>> +EAL parameters
>> +==============
>> +
>> +This document contains a list of all EAL parameters. These parameters can be
>> +used by any DPDK application running on Linux.
> 
> Is it a typo? running on FreeBSD?
> 
> 

Yes, a typo. Good catch, thanks! Should i respin?

-- 
Thanks,
Anatoly

Re: [dpdk-dev] [PATCH v2] doc: document all EAL parameters in one place

[Thomas Monjalon]

23/11/2018 10:20, Burakov, Anatoly:
> On 22-Nov-18 5:27 PM, Thomas Monjalon wrote:
> > 19/11/2018 14:10, Anatoly Burakov:
> >> --- /dev/null
> >> +++ b/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
> >> @@ -0,0 +1,20 @@
> >> +..  SPDX-License-Identifier: BSD-3-Clause
> >> +    Copyright(c) 2018 Intel Corporation.
> >> +
> >> +EAL parameters
> >> +==============
> >> +
> >> +This document contains a list of all EAL parameters. These parameters can be
> >> +used by any DPDK application running on Linux.
> > 
> > Is it a typo? running on FreeBSD?
> 
> Yes, a typo. Good catch, thanks! Should i respin?

I can fix it.

Re: [dpdk-dev] [PATCH v2] doc: document all EAL parameters in one place

[Thomas Monjalon]

19/11/2018 14:10, Anatoly Burakov:
> Currently, the most complete (but still incomplete) user guide for
> EAL command-line parameters resides in user guide for testpmd.
> This is wrong on multiple levels, and should not be the case.
> 
> To fix it, we have to create a document that lists all supported
> EAL command-line arguments. However, because different platforms
> support different subsets of available EAL parameters, instead of
> creating a single file, we will create a common file in
> doc/guides/common containing documentation for EAL parameters
> that are supported on all of our supported platforms (Linux and
> FreeBSD at the time of this writing).
> 
> We will then include this document in the Getting Started guides
> for all supported platforms, so that any changes made to
> documentation for commonly supported EAL parameters will be
> reflected in Getting Started guides for all platforms.
> 
> This patch also removes EAL parameters documentation from the
> testpmd user guide, and instead adds references to the newly
> created documents in both testpmd user guides and in sample
> applications guide.
> 
> Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
> Acked-by: Ferruh Yigit <ferruh.yigit@intel.com>
> Reviewed-by: Rami Rosen <roszenrami@gmail.com>

Applied with typo fixed, thanks