diff mbox series

[v2,6/7] doc: update argument options for external DPDK build

Message ID 20241021134935.1210500-7-luca.vizzarro@arm.com (mailing list archive)
State Superseded, archived
Delegated to: Paul Szczepanek
Headers
Series DTS external DPDK build |

Checks

Context Check Description
ci/checkpatch warning coding style issues

Commit Message

Luca Vizzarro Oct. 21, 2024, 1:49 p.m. UTC 
From: Tomáš Ďurovec <tomas.durovec@pantheon.tech>

By adding support for external build, we extend the
argument documentation for supported options.

Signed-off-by: Tomáš Ďurovec <tomas.durovec@pantheon.tech>
Signed-off-by: Luca Vizzarro <luca.vizzarro@arm.com>
---
 doc/guides/tools/dts.rst | 75 ++++++++++++++++++++++++----------------
 1 file changed, 45 insertions(+), 30 deletions(-)

Comments

Dean Marx Oct. 25, 2024, 6:30 p.m. UTC | #1 
On Mon, Oct 21, 2024 at 9:50 AM Luca Vizzarro <luca.vizzarro@arm.com> wrote:

> From: Tomáš Ďurovec <tomas.durovec@pantheon.tech>
>
> By adding support for external build, we extend the
> argument documentation for supported options.
>
> Signed-off-by: Tomáš Ďurovec <tomas.durovec@pantheon.tech>
> Signed-off-by: Luca Vizzarro <luca.vizzarro@arm.com>
>

Other than the comments I brought up on the previous patch:

Reviewed-by: Dean Marx <dmarx@iol.unh.edu>
Patrick Robb Oct. 29, 2024, 1:23 a.m. UTC | #2 
On Mon, Oct 21, 2024 at 9:50 AM Luca Vizzarro <luca.vizzarro@arm.com> wrote:

>
> +
> +   DPDK Build Options:
> +   Arguments in this group (and subgroup) will be applied to a
> DPDKLocation when the DPDK tree, tarball or revision will be provided,
> other arguments
> +   like remote source and build dir are optional. A DPDKLocation from
> settings are used instead of from config if construct successful.
>

Maybe call this "DPDK Source Options?" To me, "DPDK Build Options" invokes
meson options supported in DPDK. Up to you though.

Reviewed-by: Patrick Robb <probb@iol.unh.edu>
Luca Vizzarro Oct. 29, 2024, 12:35 p.m. UTC | #3 
On 29/10/2024 01:23, Patrick Robb wrote:
> On Mon, Oct 21, 2024 at 9:50 AM Luca Vizzarro <luca.vizzarro@arm.com 
> <mailto:luca.vizzarro@arm.com>> wrote:
> 
> 
>     +
>     +   DPDK Build Options:
>     +   Arguments in this group (and subgroup) will be applied to a
>     DPDKLocation when the DPDK tree, tarball or revision will be
>     provided, other arguments
>     +   like remote source and build dir are optional. A DPDKLocation
>     from settings are used instead of from config if construct successful.
> 
> 
> Maybe call this "DPDK Source Options?" To me, "DPDK Build Options" 
> invokes meson options supported in DPDK. Up to you though.
> Reviewed-by: Patrick Robb <probb@iol.unh.edu <mailto:probb@iol.unh.edu>>

Perfectly understandable concern to be honest. But it's also somewhat 
complicated, given this refers to the build whether it's uncompiled or 
precompiled and the location of the sources. It may require some thought.
Patrick Robb Oct. 29, 2024, 8:04 p.m. UTC | #4 
On Tue, Oct 29, 2024 at 8:35 AM Luca Vizzarro <Luca.Vizzarro@arm.com> wrote:

> On 29/10/2024 01:23, Patrick Robb wrote:
> > On Mon, Oct 21, 2024 at 9:50 AM Luca Vizzarro <luca.vizzarro@arm.com
> > <mailto:luca.vizzarro@arm.com>> wrote:
> >
> >
> >     +
> >     +   DPDK Build Options:
> >     +   Arguments in this group (and subgroup) will be applied to a
> >     DPDKLocation when the DPDK tree, tarball or revision will be
> >     provided, other arguments
> >     +   like remote source and build dir are optional. A DPDKLocation
> >     from settings are used instead of from config if construct
> successful.
> >
> >
> > Maybe call this "DPDK Source Options?" To me, "DPDK Build Options"
> > invokes meson options supported in DPDK. Up to you though.
> > Reviewed-by: Patrick Robb <probb@iol.unh.edu <mailto:probb@iol.unh.edu>>
>
> Perfectly understandable concern to be honest. But it's also somewhat
> complicated, given this refers to the build whether it's uncompiled or
> precompiled and the location of the sources. It may require some thought.
>

"DPDK Build Source" instead of "DPDK Build Options"?

I don't know why but for some reason "Build Options" strongly translates to
meson options in my mind.

But if it's a headache I think we can drop it - everything is documented in
any case so it shouldn't be a big deal.
diff mbox series

Patch

diff --git a/doc/guides/tools/dts.rst b/doc/guides/tools/dts.rst
index 65cce9e5ed..7b90c4856e 100644
--- a/doc/guides/tools/dts.rst
+++ b/doc/guides/tools/dts.rst
@@ -195,10 +195,10 @@  Running DTS
 -----------
 
 DTS needs to know which nodes to connect to and what hardware to use on those nodes.
-Once that's configured, either a DPDK source code tarball or a Git revision ID
-of choice needs to be supplied.
-DTS will use this to compile DPDK on the SUT node
-and then run the tests with the newly built binaries.
+Once that's configured, either a DPDK source code tarball or tree folder need to be supplied whether
+these are on your DTS host machine or the SUT node.
+DTS can accept a pre-compiled build placed in a subdirectory, or it will compile DPDK on the SUT
+node, and then run the tests with the newly built binaries.
 
 
 Configuring DTS
@@ -221,44 +221,59 @@  DTS is run with ``main.py`` located in the ``dts`` directory after entering Poet
 .. code-block:: console
 
    (dts-py3.10) $ ./main.py --help
-   usage: main.py [-h] [--config-file FILE_PATH] [--output-dir DIR_PATH] [-t SECONDS] [-v] [-s] (--tarball FILE_PATH | --revision ID)
-                  [--compile-timeout SECONDS] [--test-suite TEST_SUITE [TEST_CASES ...]] [--re-run N_TIMES]
+   usage: main.py [-h] [--config-file FILE_PATH] [--output-dir DIR_PATH] [-t SECONDS] [-v] [--dpdk-tree DIR_PATH | --tarball FILE_PATH] [--remote-source]
+                  [--precompiled-build-dir DIR_NAME] [--compile-timeout SECONDS] [--test-suite TEST_SUITE [TEST_CASES ...]] [--re-run N_TIMES]
+                  [--random-seed NUMBER]
 
-   Run DPDK test suites. All options may be specified with the environment variables provided in brackets. Command line arguments have higher
-   priority.
+   Run DPDK test suites. All options may be specified with the environment variables provided in brackets. Command line arguments have higher priority.
 
    options:
-     -h, --help            show this help message and exit
-     --config-file FILE_PATH
-                           [DTS_CFG_FILE] The configuration file that describes the test cases, SUTs and targets. (default: conf.yaml)
-     --output-dir DIR_PATH, --output DIR_PATH
+   -h, --help            show this help message and exit
+   --config-file FILE_PATH
+                           [DTS_CFG_FILE] The configuration file that describes the test cases, SUTs and DPDK build configs. (default:
+                           /home/lucviz01/dpdk/dts/conf.yaml)
+   --output-dir DIR_PATH, --output DIR_PATH
                            [DTS_OUTPUT_DIR] Output directory where DTS logs and results are saved. (default: output)
-     -t SECONDS, --timeout SECONDS
+   -t SECONDS, --timeout SECONDS
                            [DTS_TIMEOUT] The default timeout for all DTS operations except for compiling DPDK. (default: 15)
-     -v, --verbose         [DTS_VERBOSE] Specify to enable verbose output, logging all messages to the console. (default: False)
-     -s, --skip-setup      [DTS_SKIP_SETUP] Specify to skip all setup steps on SUT and TG nodes. (default: False)
-     --tarball FILE_PATH, --snapshot FILE_PATH
-                           [DTS_DPDK_TARBALL] Path to DPDK source code tarball to test. (default: None)
-     --revision ID, --rev ID, --git-ref ID
+   -v, --verbose           [DTS_VERBOSE] Specify to enable verbose output, logging all messages to the console. (default: False)
+   --revision ID, --rev ID, --git-ref ID
                            [DTS_DPDK_REVISION_ID] Git revision ID to test. Could be commit, tag, tree ID etc. To test local changes, first
                            commit them, then use their commit ID. (default: None)
-     --compile-timeout SECONDS
+   --compile-timeout SECONDS
                            [DTS_COMPILE_TIMEOUT] The timeout for compiling DPDK. (default: 1200)
-     --test-suite TEST_SUITE [TEST_CASES ...]
-                           [DTS_TEST_SUITES] A list containing a test suite with test cases. The first parameter is the test suite name, and
-                           the rest are test case names, which are optional. May be specified multiple times. To specify multiple test suites
-                           in the environment variable, join the lists with a comma. Examples: --test-suite suite case case --test-suite
-                           suite case ... | DTS_TEST_SUITES='suite case case, suite case, ...' | --test-suite suite --test-suite suite case
-                           ... | DTS_TEST_SUITES='suite, suite case, ...' (default: [])
-     --re-run N_TIMES, --re_run N_TIMES
+   --test-suite TEST_SUITE [TEST_CASES ...]
+                           [DTS_TEST_SUITES] A list containing a test suite with test cases. The first parameter is the test suite name, and the rest are
+                           test case names, which are optional. May be specified multiple times. To specify multiple test suites in the environment
+                           variable, join the lists with a comma. Examples: --test-suite suite case case --test-suite suite case ... |
+                           DTS_TEST_SUITES='suite case case, suite case, ...' | --test-suite suite --test-suite suite case ... | DTS_TEST_SUITES='suite,
+                           suite case, ...' (default: [])
+   --re-run N_TIMES, --re_run N_TIMES
                            [DTS_RERUN] Re-run each test case the specified number of times if a test failure occurs. (default: 0)
-     --random-seed NUMBER  [DTS_RANDOM_SEED] The seed to use with the pseudo-random generator. If not specified, the configuration value is
-                           used instead. If that's also not specified, a random seed is generated. (default: None)
+   --random-seed NUMBER  [DTS_RANDOM_SEED] The seed to use with the pseudo-random generator. If not specified, the configuration value is used instead.
+                           If that's also not specified, a random seed is generated. (default: None)
+
+   DPDK Build Options:
+   Arguments in this group (and subgroup) will be applied to a DPDKLocation when the DPDK tree, tarball or revision will be provided, other arguments
+   like remote source and build dir are optional. A DPDKLocation from settings are used instead of from config if construct successful.
+
+   --dpdk-tree DIR_PATH  [DTS_DPDK_TREE] The path to the DPDK source tree directory to test. Cannot be used in conjunction with --tarball. (default:
+                           None)
+   --tarball FILE_PATH, --snapshot FILE_PATH
+                           [DTS_DPDK_TARBALL] The path to the DPDK source tarball to test. DPDK must be contained in a folder with the same name as the
+                           tarball file. Cannot be used in conjunction with --dpdk-tree. (default: None)
+   --remote-source       [DTS_REMOTE_SOURCE] Set this option if either the DPDK source tree or tarball to be used are located on the SUT node. Can only
+                           be used with --dpdk-tree or --tarball. (default: False)
+   --precompiled-build-dir DIR_NAME
+                           [DTS_PRECOMPILED_BUILD_DIR] Define the subdirectory under the DPDK tree root directory where the pre-compiled binaries are
+                           located. If set, DTS will build DPDK under the `build` directory instead. Can only be used with --dpdk-tree or --tarball.
+                           (default: None)
 
 
 The brackets contain the names of environment variables that set the same thing.
-The minimum DTS needs is a config file and a DPDK tarball or git ref ID.
-You may pass those to DTS using the command line arguments or use the default paths.
+The minimum DTS needs is a config file and a pre-built DPDK or DPDK
+sources location which can be specified in said config file or on the
+command line or environment variables.
 
 Example command for running DTS with the template configuration and DPDK tag v23.11: