Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/135886/?format=api
{ "id": 135886, "url": "http://patches.dpdk.org/api/patches/135886/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20240116114449.486708-1-luca.vizzarro@arm.com/", "project": { "id": 1, "url": "http://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20240116114449.486708-1-luca.vizzarro@arm.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20240116114449.486708-1-luca.vizzarro@arm.com", "date": "2024-01-16T11:44:48", "name": "[v2,1/2] dts: improve documentation", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": true, "hash": "0c7992893866888b8a6ba66d8ef7a774810d207f", "submitter": { "id": 3197, "url": "http://patches.dpdk.org/api/people/3197/?format=api", "name": "Luca Vizzarro", "email": "luca.vizzarro@arm.com" }, "delegate": { "id": 1, "url": "http://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "http://patches.dpdk.org/project/dpdk/patch/20240116114449.486708-1-luca.vizzarro@arm.com/mbox/", "series": [ { "id": 30811, "url": "http://patches.dpdk.org/api/series/30811/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=30811", "date": "2024-01-16T11:44:48", "name": "[v2,1/2] dts: improve documentation", "version": 2, "mbox": "http://patches.dpdk.org/series/30811/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/135886/comments/", "check": "success", "checks": "http://patches.dpdk.org/api/patches/135886/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from mails.dpdk.org (mails.dpdk.org [217.70.189.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id E5A85438DC;\n\tTue, 16 Jan 2024 12:46:08 +0100 (CET)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 739CC402ED;\n\tTue, 16 Jan 2024 12:46:08 +0100 (CET)", "from foss.arm.com (foss.arm.com [217.140.110.172])\n by mails.dpdk.org (Postfix) with ESMTP id 863114029F\n for <dev@dpdk.org>; Tue, 16 Jan 2024 12:46:06 +0100 (CET)", "from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14])\n by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 85EE02F4;\n Tue, 16 Jan 2024 03:46:51 -0800 (PST)", "from localhost.localdomain (unknown [172.31.20.19])\n by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPA id 42B643F6C4;\n Tue, 16 Jan 2024 03:46:02 -0800 (PST)" ], "From": "Luca Vizzarro <luca.vizzarro@arm.com>", "To": "dev@dpdk.org", "Cc": "Luca Vizzarro <luca.vizzarro@arm.com>,\n Thomas Monjalon <thomas@monjalon.net>,\n =?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>,\n Paul Szczepanek <paul.szczepanek@arm.com>", "Subject": "[PATCH v2 1/2] dts: improve documentation", "Date": "Tue, 16 Jan 2024 11:44:48 +0000", "Message-Id": "<20240116114449.486708-1-luca.vizzarro@arm.com>", "X-Mailer": "git-send-email 2.34.1", "In-Reply-To": "<20240103125438.182098-1-Luca.Vizzarro@arm.com>", "References": "<20240103125438.182098-1-Luca.Vizzarro@arm.com>", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org" }, "content": "Improve instructions for installing dependencies, configuring and\nlaunching the project. Add mypy in the list of developer tools.\n\nFinally, fix a bug where Poetry expects to install DTS as a package\nas well while resolving the dependencies. Because DTS is not setup\nas a package, this results in an error raised.\n\nReviewed-by: Paul Szczepanek <paul.szczepanek@arm.com>\nSigned-off-by: Luca Vizzarro <luca.vizzarro@arm.com>\n---\nv2:\n- updated email address in .mailmap\n- amended commit message\n- split configuration schema docs into a separate commit\n- specified that DPDK will be built on the target node\n- fixed a pre-existing typo\n- added mypy under DTS developer tools\n- fix headings spacing\n- specified skip_smoke_tests is optional in conf.yaml\n- capitalized DTS in help command\n- updated DPDK version to 23.11\n\n .mailmap | 1 +\n doc/guides/tools/dts.rst | 79 ++++++++++++++++++++-------------------\n dts/conf.yaml | 31 ++++++++++-----\n dts/framework/settings.py | 2 +-\n 4 files changed, 64 insertions(+), 49 deletions(-)", "diff": "diff --git a/.mailmap b/.mailmap\nindex ab0742a382..acc6b9bc18 100644\n--- a/.mailmap\n+++ b/.mailmap\n@@ -815,6 +815,7 @@ Louise Kilheeney <louise.kilheeney@intel.com>\n Louis Luo <llouis@vmware.com>\n Louis Peens <louis.peens@corigine.com> <louis.peens@netronome.com>\n Luca Boccassi <luca.boccassi@microsoft.com> <bluca@debian.org> <luca.boccassi@gmail.com> <lboccass@brocade.com> <luca.boccassi@intl.att.com>\n+Luca Vizzarro <luca.vizzarro@arm.com>\n Luc Pelletier <lucp.at.work@gmail.com>\n Lukasz Bartosik <lbartosik@marvell.com>\n Lukasz Czapnik <lukasz.czapnik@intel.com>\ndiff --git a/doc/guides/tools/dts.rst b/doc/guides/tools/dts.rst\nindex b6a3e1e791..f49337b997 100644\n--- a/doc/guides/tools/dts.rst\n+++ b/doc/guides/tools/dts.rst\n@@ -91,7 +91,7 @@ Setting up DTS environment\n \n .. code-block:: console\n \n- poetry install\n+ poetry install --no-root\n poetry shell\n \n #. **SSH Connection**\n@@ -189,7 +189,10 @@ Running DTS\n -----------\n \n DTS needs to know which nodes to connect to and what hardware to use on those nodes.\n-Once that's configured, DTS needs a DPDK tarball and it's ready to run.\n+Once that's configured, either a DPDK source code tarball or a Git revision ID of\n+choice needs to be supplied. DTS will use this to compile DPDK on the SUT node and\n+then run the tests with the newly built binaries.\n+\n \n Configuring DTS\n ~~~~~~~~~~~~~~~\n@@ -208,53 +211,49 @@ which don't require password authentication.\n The other fields are mostly self-explanatory\n and documented in more detail in ``dts/framework/config/conf_yaml_schema.json``.\n \n+\n DTS Execution\n ~~~~~~~~~~~~~\n \n-DTS is run with ``main.py`` located in the ``dts`` directory after entering Poetry shell::\n+DTS is run with ``main.py`` located in the ``dts`` directory after entering Poetry shell:\n \n- usage: main.py [-h] [--config-file CONFIG_FILE] [--output-dir OUTPUT_DIR] [-t TIMEOUT]\n- [-v VERBOSE] [-s SKIP_SETUP] [--tarball TARBALL]\n- [--compile-timeout COMPILE_TIMEOUT] [--test-cases TEST_CASES]\n- [--re-run RE_RUN]\n+.. code-block:: console\n \n- Run DPDK test suites. All options may be specified with the environment variables provided in\n- brackets. Command line arguments have higher priority.\n+ (dts-py3.10) $ ./main.py --help\n+ usage: main.py [-h] [--config-file CONFIG_FILE] [--output-dir OUTPUT_DIR] [-t TIMEOUT] [-v] [-s] [--tarball TARBALL] [--compile-timeout COMPILE_TIMEOUT] [--test-cases TEST_CASES] [--re-run RE_RUN]\n+\n+ Run DPDK test suites. All options may be specified with the environment variables provided in brackets. Command line arguments have higher priority.\n \n options:\n- -h, --help show this help message and exit\n- --config-file CONFIG_FILE\n- [DTS_CFG_FILE] configuration file that describes the test cases, SUTs\n- and targets. (default: conf.yaml)\n- --output-dir OUTPUT_DIR, --output OUTPUT_DIR\n- [DTS_OUTPUT_DIR] Output directory where dts logs and results are\n- saved. (default: output)\n- -t TIMEOUT, --timeout TIMEOUT\n- [DTS_TIMEOUT] The default timeout for all DTS operations except for\n- compiling DPDK. (default: 15)\n- -v VERBOSE, --verbose VERBOSE\n- [DTS_VERBOSE] Set to 'Y' to enable verbose output, logging all\n- messages to the console. (default: N)\n- -s SKIP_SETUP, --skip-setup SKIP_SETUP\n- [DTS_SKIP_SETUP] Set to 'Y' to skip all setup steps on SUT and TG\n- nodes. (default: N)\n- --tarball TARBALL, --snapshot TARBALL\n- [DTS_DPDK_TARBALL] Path to DPDK source code tarball which will be\n- used in testing. (default: dpdk.tar.xz)\n- --compile-timeout COMPILE_TIMEOUT\n- [DTS_COMPILE_TIMEOUT] The timeout for compiling DPDK. (default: 1200)\n- --test-cases TEST_CASES\n- [DTS_TESTCASES] Comma-separated list of test cases to execute.\n- Unknown test cases will be silently ignored. (default: )\n- --re-run RE_RUN, --re_run RE_RUN\n- [DTS_RERUN] Re-run each test case the specified amount of times if a\n- test failure occurs (default: 0)\n+ -h, --help show this help message and exit\n+ --config-file CONFIG_FILE\n+ [DTS_CFG_FILE] configuration file that describes the test cases, SUTs and targets. (default: ./conf.yaml)\n+ --output-dir OUTPUT_DIR, --output OUTPUT_DIR\n+ [DTS_OUTPUT_DIR] Output directory where DTS logs and results are saved. (default: output)\n+ -t TIMEOUT, --timeout TIMEOUT\n+ [DTS_TIMEOUT] The default timeout for all DTS operations except for compiling DPDK. (default: 15)\n+ -v, --verbose [DTS_VERBOSE] Specify to enable verbose output, logging all messages to the console. (default: False)\n+ -s, --skip-setup [DTS_SKIP_SETUP] Specify to skip all setup steps on SUT and TG nodes. (default: None)\n+ --tarball TARBALL, --snapshot TARBALL, --git-ref TARBALL\n+ [DTS_DPDK_TARBALL] Path to DPDK source code tarball or a git commit ID, tag ID or tree ID to test. To test local changes, first commit them, then use the commit ID with this option. (default: dpdk.tar.xz)\n+ --compile-timeout COMPILE_TIMEOUT\n+ [DTS_COMPILE_TIMEOUT] The timeout for compiling DPDK. (default: 1200)\n+ --test-cases TEST_CASES\n+ [DTS_TESTCASES] Comma-separated list of test cases to execute. Unknown test cases will be silently ignored. (default: )\n+ --re-run RE_RUN, --re_run RE_RUN\n+ [DTS_RERUN] Re-run each test case the specified number of times if a test failure occurs (default: 0)\n \n \n The brackets contain the names of environment variables that set the same thing.\n-The minimum DTS needs is a config file and a DPDK tarball.\n+The minimum DTS needs is a config file and a DPDK tarball or git ref ID.\n You may pass those to DTS using the command line arguments or use the default paths.\n \n+Example command for running DTS with the template configuration and DPDK tag v23.11:\n+\n+.. code-block:: console\n+\n+ (dts-py3.10) $ ./main.py --git-ref v23.11\n+\n \n DTS Results\n ~~~~~~~~~~~\n@@ -355,7 +354,7 @@ There are four types of methods that comprise a test suite:\n | Methods ``set_up_test_case`` and ``tear_down_test_case`` will be executed\n before and after each test case, respectively.\n | These methods don't need to be implemented if there's no need for them in a test suite.\n- In that case, nothing will happen when they're is executed.\n+ In that case, nothing will happen when they are executed.\n \n #. **Configuration, traffic and other logic**\n \n@@ -410,6 +409,10 @@ There are three tools used in DTS to help with code checking, style and formatti\n :start-after: [tool.pylama]\n :end-at: linters\n \n+* `mypy <https://github.com/python/mypy>`_\n+\n+ Enables static typing for Python, exploiting the type hints in the source code.\n+\n These three tools are all used in ``devtools/dts-check-format.sh``,\n the DTS code check and format script.\n Refer to the script for usage: ``devtools/dts-check-format.sh -h``.\ndiff --git a/dts/conf.yaml b/dts/conf.yaml\nindex 37967daea0..8068345dd5 100644\n--- a/dts/conf.yaml\n+++ b/dts/conf.yaml\n@@ -1,65 +1,76 @@\n # SPDX-License-Identifier: BSD-3-Clause\n # Copyright 2022-2023 The DPDK contributors\n+# Copyright 2023 Arm Limited\n \n executions:\n+ # define one execution environment\n - build_targets:\n - arch: x86_64\n os: linux\n cpu: native\n+ # the combination of the following two makes CC=\"ccache gcc\"\n compiler: gcc\n compiler_wrapper: ccache\n- perf: false\n- func: true\n- skip_smoke_tests: false # optional flag that allows you to skip smoke tests\n- test_suites:\n+ perf: false # disable performance testing\n+ func: true # enable functional testing\n+ skip_smoke_tests: false # optional\n+ test_suites: # the following test suites will be run in their entirety\n - hello_world\n - os_udp\n+ # The machine running the DPDK test executable\n system_under_test_node:\n node_name: \"SUT 1\"\n vdevs: # optional; if removed, vdevs won't be used in the execution\n - \"crypto_openssl\"\n+ # Traffic generator node to use for this execution environment\n traffic_generator_node: \"TG 1\"\n nodes:\n+ # Define a system under test node, having two network ports physically\n+ # connected to the corresponding ports in TG 1 (the peer node)\n - name: \"SUT 1\"\n hostname: sut1.change.me.localhost\n user: dtsuser\n arch: x86_64\n os: linux\n- lcores: \"\"\n- use_first_core: false\n- memory_channels: 4\n+ lcores: \"\" # use all the available logical cores\n+ use_first_core: false # tells DPDK to use any physical core\n+ memory_channels: 4 # tells DPDK to use 4 memory channels\n hugepages: # optional; if removed, will use system hugepage configuration\n amount: 256\n force_first_numa: false\n ports:\n+ # sets up the physical link between \"SUT 1\"@000:00:08.0 and \"TG 1\"@0000:00:08.0\n - pci: \"0000:00:08.0\"\n os_driver_for_dpdk: vfio-pci # OS driver that DPDK will use\n- os_driver: i40e\n+ os_driver: i40e # OS driver to bind when the tests are not running\n peer_node: \"TG 1\"\n peer_pci: \"0000:00:08.0\"\n+ # sets up the physical link between \"SUT 1\"@000:00:08.1 and \"TG 1\"@0000:00:08.1\n - pci: \"0000:00:08.1\"\n os_driver_for_dpdk: vfio-pci\n os_driver: i40e\n peer_node: \"TG 1\"\n peer_pci: \"0000:00:08.1\"\n+ # Define a Scapy traffic generator node, having two network ports\n+ # physically connected to the corresponding ports in SUT 1 (the peer node).\n - name: \"TG 1\"\n hostname: tg1.change.me.localhost\n user: dtsuser\n arch: x86_64\n os: linux\n- lcores: \"\"\n ports:\n+ # sets up the physical link between \"TG 1\"@000:00:08.0 and \"SUT 1\"@0000:00:08.0\n - pci: \"0000:00:08.0\"\n os_driver_for_dpdk: rdma\n os_driver: rdma\n peer_node: \"SUT 1\"\n peer_pci: \"0000:00:08.0\"\n+ # sets up the physical link between \"SUT 1\"@000:00:08.0 and \"TG 1\"@0000:00:08.0\n - pci: \"0000:00:08.1\"\n os_driver_for_dpdk: rdma\n os_driver: rdma\n peer_node: \"SUT 1\"\n peer_pci: \"0000:00:08.1\"\n- use_first_core: false\n hugepages: # optional; if removed, will use system hugepage configuration\n amount: 256\n force_first_numa: false\ndiff --git a/dts/framework/settings.py b/dts/framework/settings.py\nindex 41f98e8519..609c8d0e62 100644\n--- a/dts/framework/settings.py\n+++ b/dts/framework/settings.py\n@@ -199,7 +199,7 @@ def _get_parser() -> argparse.ArgumentParser:\n \"--output\",\n action=_env_arg(\"DTS_OUTPUT_DIR\"),\n default=SETTINGS.output_dir,\n- help=\"[DTS_OUTPUT_DIR] Output directory where dts logs and results are saved.\",\n+ help=\"[DTS_OUTPUT_DIR] Output directory where DTS logs and results are saved.\",\n )\n \n parser.add_argument(\n", "prefixes": [ "v2", "1/2" ] }