Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/135887/?format=api
{ "id": 135887, "url": "http://patches.dpdk.org/api/patches/135887/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20240116114449.486708-2-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-2-luca.vizzarro@arm.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20240116114449.486708-2-luca.vizzarro@arm.com", "date": "2024-01-16T11:44:49", "name": "[v2,2/2] dts: add configuration schema docs", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": true, "hash": "4c40f8ac00812b1dfd185c03fb6b1f1d68ab24ed", "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-2-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/135887/comments/", "check": "success", "checks": "http://patches.dpdk.org/api/patches/135887/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 B5B7F438DC;\n\tTue, 16 Jan 2024 12:46:14 +0100 (CET)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id A4F8E4068A;\n\tTue, 16 Jan 2024 12:46:12 +0100 (CET)", "from foss.arm.com (foss.arm.com [217.140.110.172])\n by mails.dpdk.org (Postfix) with ESMTP id 317C74067C\n for <dev@dpdk.org>; Tue, 16 Jan 2024 12:46:11 +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 A34122F4;\n Tue, 16 Jan 2024 03:46:56 -0800 (PST)", "from localhost.localdomain (unknown [172.31.20.19])\n by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPA id 1EF123F6C4;\n Tue, 16 Jan 2024 03:46:06 -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 2/2] dts: add configuration schema docs", "Date": "Tue, 16 Jan 2024 11:44:49 +0000", "Message-Id": "<20240116114449.486708-2-luca.vizzarro@arm.com>", "X-Mailer": "git-send-email 2.34.1", "In-Reply-To": "<20240116114449.486708-1-luca.vizzarro@arm.com>", "References": "<20240103125438.182098-1-Luca.Vizzarro@arm.com>\n <20240116114449.486708-1-luca.vizzarro@arm.com>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=UTF-8", "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": "Document the configuration schema in the docs, describing all of the\nrelevant definitions and properties.\n\nReviewed-by: Paul Szczepanek <paul.szczepanek@arm.com>\nSigned-off-by: Luca Vizzarro <luca.vizzarro@arm.com>\n---\nv2:\n- changed arrays, objects terminology\n\n doc/guides/tools/dts.rst | 208 +++++++++++++++++++++++++++++++++++++--\n 1 file changed, 198 insertions(+), 10 deletions(-)", "diff": "diff --git a/doc/guides/tools/dts.rst b/doc/guides/tools/dts.rst\nindex f49337b997..8bf66e33b8 100644\n--- a/doc/guides/tools/dts.rst\n+++ b/doc/guides/tools/dts.rst\n@@ -197,19 +197,13 @@ then run the tests with the newly built binaries.\n Configuring DTS\n ~~~~~~~~~~~~~~~\n \n-DTS configuration is split into nodes and executions and build targets within executions.\n-By default, DTS will try to use the ``dts/conf.yaml`` config file,\n-which is a template that illustrates what can be configured in DTS:\n-\n- .. literalinclude:: ../../../dts/conf.yaml\n- :language: yaml\n- :start-at: executions:\n-\n+DTS configuration is split into nodes and executions and build targets within executions,\n+and follows a defined schema as described in `Configuration Schema`_.\n+By default, DTS will try to use the ``dts/conf.yaml`` :ref:`config file <configuration_schema_example>`,\n+which is a template that illustrates what can be configured in DTS.\n \n The user must have :ref:`administrator privileges <sut_admin_user>`\n 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@@ -416,3 +410,197 @@ There are three tools used in DTS to help with code checking, style and formatti\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``.\n+\n+\n+Configuration Schema\n+--------------------\n+\n+\n+Definitions\n+~~~~~~~~~~~\n+\n+_`Node name`\n+ *string* – A unique identifier for a node.\n+ **Examples**: ``SUT1``, ``TG1``.\n+\n+_`ARCH`\n+ *string* – The CPU architecture.\n+ **Supported values**: ``x86_64``, ``arm64``, ``ppc64le``.\n+\n+_`CPU`\n+ *string* – The CPU microarchitecture. Use ``native`` for x86.\n+ **Supported values**: ``native``, ``armv8a``, ``dpaa2``, ``thunderx``, ``xgene1``.\n+\n+_`OS`\n+ *string* – The operating system. **Supported values**: ``linux``.\n+\n+_`Compiler`\n+ *string* – The compiler used for building DPDK.\n+ **Supported values**: ``gcc``, ``clang``, ``icc``, ``mscv``.\n+\n+_`Build target`\n+ *mapping* – Build targets supported by DTS for building DPDK, described as:\n+\n+ ==================== =================================================================\n+ ``arch`` See `ARCH`_\n+ ``os`` See `OS`_\n+ ``cpu`` See `CPU`_\n+ ``compiler`` See `Compiler`_\n+ ``compiler_wrapper`` *string* – Value prepended to the CC variable for the DPDK build.\n+\n+ **Example**: ``ccache``\n+ ==================== =================================================================\n+\n+_`hugepages`\n+ *mapping* – hugepages described as:\n+\n+ ==================== ================================================================\n+ ``amount`` *integer* – The amount of hugepages to configure.\n+\n+ Hugepage size will be the system default.\n+ ``force_first_numa`` (*optional*, defaults to ``false``) – If ``true``, it forces the\n+\n+ configuration of hugepages on the first NUMA node.\n+ ==================== ================================================================\n+\n+_`Network port`\n+ *mapping* – the NIC port described as:\n+\n+ ====================== =================================================================================\n+ ``pci`` *string* – the local PCI address of the port. **Example**: ``0000:00:08.0``\n+ ``os_driver_for_dpdk`` | *string* – this port's device driver when using with DPDK\n+ | When setting up the SUT, DTS will bind the network device to this driver\n+ | for compatibility with DPDK.\n+\n+ **Examples**: ``vfio-pci``, ``mlx5_core``\n+ ``os_driver`` | *string* – this port's device driver when **not** using with DPDK\n+ | When tearing down the tests on the SUT, DTS will bind the network device\n+ | *back* to this driver. This driver is meant to be the one that the SUT would\n+ | normally use for this device, or whichever driver it is preferred to leave the\n+ | device bound to after testing.\n+ | This also represents the driver that is used in conjunction with the traffic\n+ | generator software.\n+\n+ **Examples**: ``i40e``, ``mlx5_core``\n+ ``peer_node`` *string* – the name of the peer node connected to this port.\n+ ``peer_pci`` *string* – the PCI address of the peer node port. **Example**: ``000a:01:00.1``\n+ ====================== =================================================================================\n+\n+_`Test suite`\n+ *string* – name of the test suite to run. **Examples**: ``hello_world``, ``os_udp``\n+\n+_`Test target`\n+ *mapping* – selects specific test cases to run from a test suite. Mapping is described as follows:\n+\n+ ========= ===============================================================================================\n+ ``suite`` See `Test suite`_\n+ ``cases`` (*optional*) *sequence* of *string* – list of the selected test cases in the test suite to run.\n+\n+ Unknown test cases will be silently ignored.\n+ ========= ===============================================================================================\n+\n+\n+Properties\n+~~~~~~~~~~\n+\n+The configuration requires listing all the execution environments and nodes\n+involved in the testing. These can be defined with the following mappings:\n+\n+``executions``\n+ `sequence <https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range>`_ listing\n+ the execution environments. Each entry is described as per the following\n+ `mapping <https://docs.python.org/3/library/stdtypes.html#mapping-types-dict>`_:\n+\n+ +----------------------------+-------------------------------------------------------------------+\n+ | ``build_targets`` | *sequence* of `Build target`_ |\n+ +----------------------------+-------------------------------------------------------------------+\n+ | ``perf`` | *boolean* – Enable performance testing. |\n+ +----------------------------+-------------------------------------------------------------------+\n+ | ``func`` | *boolean* – Enable functional testing. |\n+ +----------------------------+-------------------------------------------------------------------+\n+ | ``test_suites`` | *sequence* of **one of** `Test suite`_ **or** `Test target`_ |\n+ +----------------------------+-------------------------------------------------------------------+\n+ | ``skip_smoke_tests`` | (*optional*) *boolean* – Allows you to skip smoke testing |\n+ | | if ``true``. |\n+ +----------------------------+-------------------------------------------------------------------+\n+ | ``system_under_test_node`` | System under test node specified with: |\n+ | +---------------+---------------------------------------------------+\n+ | | ``node_name`` | See `Node name`_ |\n+ | +---------------+---------------------------------------------------+\n+ | | ``vdevs`` | (*optional*) *sequence* of *string* |\n+ | | | |\n+ | | | List of virtual devices passed with the ``--vdev``|\n+ | | | argument to DPDK. **Example**: ``crypto_openssl`` |\n+ +----------------------------+---------------+---------------------------------------------------+\n+ | ``traffic_generator_node`` | Node name for the traffic generator node. |\n+ +----------------------------+-------------------------------------------------------------------+\n+\n+``nodes``\n+ `sequence <https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range>`_ listing\n+ the nodes. Each entry is described as per the following\n+ `mapping <https://docs.python.org/3/library/stdtypes.html#mapping-types-dict>`_:\n+\n+ +-----------------------+---------------------------------------------------------------------------------------+\n+ | ``name`` | See `Node name`_ |\n+ +-----------------------+---------------------------------------------------------------------------------------+\n+ | ``hostname`` | *string* – The network hostname or IP address of this node. |\n+ +-----------------------+---------------------------------------------------------------------------------------+\n+ | ``user`` | *string* – The SSH user credential to use to login to this node. |\n+ +-----------------------+---------------------------------------------------------------------------------------+\n+ | ``password`` | (*optional*) *string* – The SSH password credential for this node. |\n+ | | |\n+ | | **NB**: Use only as last resort. SSH keys are **strongly** preferred. |\n+ +-----------------------+---------------------------------------------------------------------------------------+\n+ | ``arch`` | The architecture of this node. See `ARCH`_ for supported values. |\n+ +-----------------------+---------------------------------------------------------------------------------------+\n+ | ``os`` | The operating system of this node. See `OS`_ for supported values. |\n+ +-----------------------+---------------------------------------------------------------------------------------+\n+ | ``lcores`` | | (*optional*, defaults to 1) *string* – Comma-separated list of logical |\n+ | | | cores to use. An empty string means use all lcores. |\n+ | | |\n+ | | **Example**: ``1,2,3,4,5,18-22`` |\n+ +-----------------------+---------------------------------------------------------------------------------------+\n+ | ``use_first_core`` | (*optional*, defaults to ``false``) *boolean* |\n+ | | |\n+ | | Indicates whether DPDK should use only the first physical core or not. |\n+ +-----------------------+---------------------------------------------------------------------------------------+\n+ | ``memory_channels`` | (*optional*, defaults to 1) *integer* |\n+ | | |\n+ | | The number of the memory channels to use. |\n+ +-----------------------+---------------------------------------------------------------------------------------+\n+ | ``hugepages`` | (*optional*) See `hugepages`_. If unset, hugepages won't be configured |\n+ | | |\n+ | | in favour of the system configuration. |\n+ +-----------------------+---------------------------------------------------------------------------------------+\n+ | ``ports`` | | *sequence* of `Network port`_ – Describe ports that are **directly** paired with |\n+ | | | other nodes used in conjunction with this one. Both ends of the links must be |\n+ | | | described. If there any inconsistencies DTS won't run. |\n+ | | |\n+ | | **Example**: port 1 of node ``SUT1`` is connected to port 1 of node ``TG1`` etc. |\n+ +-----------------------+---------------------------------------------------------------------------------------+\n+ | ``traffic_generator`` | (*optional*) Traffic generator, if any, setup on this node described as: |\n+ | +----------+----------------------------------------------------------------------------+\n+ | | ``type`` | *string* – **Supported values**: *SCAPY* |\n+ +-----------------------+----------+----------------------------------------------------------------------------+\n+\n+\n+.. _configuration_schema_example:\n+\n+Example\n+~~~~~~~\n+\n+The following example (which can be found in ``dts/conf.yaml``) sets up two nodes:\n+\n+* ``SUT1`` which is already setup with the DPDK build requirements and any other\n+ required for execution;\n+* ``TG1`` which already has Scapy installed in the system.\n+\n+And they both have two network ports which are physically connected to each other.\n+\n+.. note::\n+ This example assumes that you have setup SSH keys in both the system under test\n+ and traffic generator nodes.\n+\n+.. literalinclude:: ../../../dts/conf.yaml\n+ :language: yaml\n+ :start-at: executions:\n", "prefixes": [ "v2", "2/2" ] }