From patchwork Tue Jan 16 11:44:49 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Luca Vizzarro X-Patchwork-Id: 135887 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: 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]) by inbox.dpdk.org (Postfix) with ESMTP id B5B7F438DC; Tue, 16 Jan 2024 12:46:14 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A4F8E4068A; Tue, 16 Jan 2024 12:46:12 +0100 (CET) Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by mails.dpdk.org (Postfix) with ESMTP id 317C74067C for ; Tue, 16 Jan 2024 12:46:11 +0100 (CET) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id A34122F4; Tue, 16 Jan 2024 03:46:56 -0800 (PST) Received: from localhost.localdomain (unknown [172.31.20.19]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPA id 1EF123F6C4; Tue, 16 Jan 2024 03:46:06 -0800 (PST) From: Luca Vizzarro To: dev@dpdk.org Cc: Luca Vizzarro , Thomas Monjalon , =?utf-8?q?Juraj_Linke=C5=A1?= , Paul Szczepanek 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> <20240116114449.486708-1-luca.vizzarro@arm.com> MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Document the configuration schema in the docs, describing all of the relevant definitions and properties. Reviewed-by: Paul Szczepanek Signed-off-by: Luca Vizzarro Reviewed-by: Juraj Linkeš --- v2: - changed arrays, objects terminology doc/guides/tools/dts.rst | 208 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 198 insertions(+), 10 deletions(-) diff --git a/doc/guides/tools/dts.rst b/doc/guides/tools/dts.rst index f49337b997..8bf66e33b8 100644 --- a/doc/guides/tools/dts.rst +++ b/doc/guides/tools/dts.rst @@ -197,19 +197,13 @@ then run the tests with the newly built binaries. Configuring DTS ~~~~~~~~~~~~~~~ -DTS configuration is split into nodes and executions and build targets within executions. -By default, DTS will try to use the ``dts/conf.yaml`` config file, -which is a template that illustrates what can be configured in DTS: - - .. literalinclude:: ../../../dts/conf.yaml - :language: yaml - :start-at: executions: - +DTS configuration is split into nodes and executions and build targets within executions, +and follows a defined schema as described in `Configuration Schema`_. +By default, DTS will try to use the ``dts/conf.yaml`` :ref:`config file `, +which is a template that illustrates what can be configured in DTS. The user must have :ref:`administrator privileges ` which don't require password authentication. -The other fields are mostly self-explanatory -and documented in more detail in ``dts/framework/config/conf_yaml_schema.json``. DTS Execution @@ -416,3 +410,197 @@ There are three tools used in DTS to help with code checking, style and formatti These three tools are all used in ``devtools/dts-check-format.sh``, the DTS code check and format script. Refer to the script for usage: ``devtools/dts-check-format.sh -h``. + + +Configuration Schema +-------------------- + + +Definitions +~~~~~~~~~~~ + +_`Node name` + *string* – A unique identifier for a node. + **Examples**: ``SUT1``, ``TG1``. + +_`ARCH` + *string* – The CPU architecture. + **Supported values**: ``x86_64``, ``arm64``, ``ppc64le``. + +_`CPU` + *string* – The CPU microarchitecture. Use ``native`` for x86. + **Supported values**: ``native``, ``armv8a``, ``dpaa2``, ``thunderx``, ``xgene1``. + +_`OS` + *string* – The operating system. **Supported values**: ``linux``. + +_`Compiler` + *string* – The compiler used for building DPDK. + **Supported values**: ``gcc``, ``clang``, ``icc``, ``mscv``. + +_`Build target` + *mapping* – Build targets supported by DTS for building DPDK, described as: + + ==================== ================================================================= + ``arch`` See `ARCH`_ + ``os`` See `OS`_ + ``cpu`` See `CPU`_ + ``compiler`` See `Compiler`_ + ``compiler_wrapper`` *string* – Value prepended to the CC variable for the DPDK build. + + **Example**: ``ccache`` + ==================== ================================================================= + +_`hugepages` + *mapping* – hugepages described as: + + ==================== ================================================================ + ``amount`` *integer* – The amount of hugepages to configure. + + Hugepage size will be the system default. + ``force_first_numa`` (*optional*, defaults to ``false``) – If ``true``, it forces the + + configuration of hugepages on the first NUMA node. + ==================== ================================================================ + +_`Network port` + *mapping* – the NIC port described as: + + ====================== ================================================================================= + ``pci`` *string* – the local PCI address of the port. **Example**: ``0000:00:08.0`` + ``os_driver_for_dpdk`` | *string* – this port's device driver when using with DPDK + | When setting up the SUT, DTS will bind the network device to this driver + | for compatibility with DPDK. + + **Examples**: ``vfio-pci``, ``mlx5_core`` + ``os_driver`` | *string* – this port's device driver when **not** using with DPDK + | When tearing down the tests on the SUT, DTS will bind the network device + | *back* to this driver. This driver is meant to be the one that the SUT would + | normally use for this device, or whichever driver it is preferred to leave the + | device bound to after testing. + | This also represents the driver that is used in conjunction with the traffic + | generator software. + + **Examples**: ``i40e``, ``mlx5_core`` + ``peer_node`` *string* – the name of the peer node connected to this port. + ``peer_pci`` *string* – the PCI address of the peer node port. **Example**: ``000a:01:00.1`` + ====================== ================================================================================= + +_`Test suite` + *string* – name of the test suite to run. **Examples**: ``hello_world``, ``os_udp`` + +_`Test target` + *mapping* – selects specific test cases to run from a test suite. Mapping is described as follows: + + ========= =============================================================================================== + ``suite`` See `Test suite`_ + ``cases`` (*optional*) *sequence* of *string* – list of the selected test cases in the test suite to run. + + Unknown test cases will be silently ignored. + ========= =============================================================================================== + + +Properties +~~~~~~~~~~ + +The configuration requires listing all the execution environments and nodes +involved in the testing. These can be defined with the following mappings: + +``executions`` + `sequence `_ listing + the execution environments. Each entry is described as per the following + `mapping `_: + + +----------------------------+-------------------------------------------------------------------+ + | ``build_targets`` | *sequence* of `Build target`_ | + +----------------------------+-------------------------------------------------------------------+ + | ``perf`` | *boolean* – Enable performance testing. | + +----------------------------+-------------------------------------------------------------------+ + | ``func`` | *boolean* – Enable functional testing. | + +----------------------------+-------------------------------------------------------------------+ + | ``test_suites`` | *sequence* of **one of** `Test suite`_ **or** `Test target`_ | + +----------------------------+-------------------------------------------------------------------+ + | ``skip_smoke_tests`` | (*optional*) *boolean* – Allows you to skip smoke testing | + | | if ``true``. | + +----------------------------+-------------------------------------------------------------------+ + | ``system_under_test_node`` | System under test node specified with: | + | +---------------+---------------------------------------------------+ + | | ``node_name`` | See `Node name`_ | + | +---------------+---------------------------------------------------+ + | | ``vdevs`` | (*optional*) *sequence* of *string* | + | | | | + | | | List of virtual devices passed with the ``--vdev``| + | | | argument to DPDK. **Example**: ``crypto_openssl`` | + +----------------------------+---------------+---------------------------------------------------+ + | ``traffic_generator_node`` | Node name for the traffic generator node. | + +----------------------------+-------------------------------------------------------------------+ + +``nodes`` + `sequence `_ listing + the nodes. Each entry is described as per the following + `mapping `_: + + +-----------------------+---------------------------------------------------------------------------------------+ + | ``name`` | See `Node name`_ | + +-----------------------+---------------------------------------------------------------------------------------+ + | ``hostname`` | *string* – The network hostname or IP address of this node. | + +-----------------------+---------------------------------------------------------------------------------------+ + | ``user`` | *string* – The SSH user credential to use to login to this node. | + +-----------------------+---------------------------------------------------------------------------------------+ + | ``password`` | (*optional*) *string* – The SSH password credential for this node. | + | | | + | | **NB**: Use only as last resort. SSH keys are **strongly** preferred. | + +-----------------------+---------------------------------------------------------------------------------------+ + | ``arch`` | The architecture of this node. See `ARCH`_ for supported values. | + +-----------------------+---------------------------------------------------------------------------------------+ + | ``os`` | The operating system of this node. See `OS`_ for supported values. | + +-----------------------+---------------------------------------------------------------------------------------+ + | ``lcores`` | | (*optional*, defaults to 1) *string* – Comma-separated list of logical | + | | | cores to use. An empty string means use all lcores. | + | | | + | | **Example**: ``1,2,3,4,5,18-22`` | + +-----------------------+---------------------------------------------------------------------------------------+ + | ``use_first_core`` | (*optional*, defaults to ``false``) *boolean* | + | | | + | | Indicates whether DPDK should use only the first physical core or not. | + +-----------------------+---------------------------------------------------------------------------------------+ + | ``memory_channels`` | (*optional*, defaults to 1) *integer* | + | | | + | | The number of the memory channels to use. | + +-----------------------+---------------------------------------------------------------------------------------+ + | ``hugepages`` | (*optional*) See `hugepages`_. If unset, hugepages won't be configured | + | | | + | | in favour of the system configuration. | + +-----------------------+---------------------------------------------------------------------------------------+ + | ``ports`` | | *sequence* of `Network port`_ – Describe ports that are **directly** paired with | + | | | other nodes used in conjunction with this one. Both ends of the links must be | + | | | described. If there any inconsistencies DTS won't run. | + | | | + | | **Example**: port 1 of node ``SUT1`` is connected to port 1 of node ``TG1`` etc. | + +-----------------------+---------------------------------------------------------------------------------------+ + | ``traffic_generator`` | (*optional*) Traffic generator, if any, setup on this node described as: | + | +----------+----------------------------------------------------------------------------+ + | | ``type`` | *string* – **Supported values**: *SCAPY* | + +-----------------------+----------+----------------------------------------------------------------------------+ + + +.. _configuration_schema_example: + +Example +~~~~~~~ + +The following example (which can be found in ``dts/conf.yaml``) sets up two nodes: + +* ``SUT1`` which is already setup with the DPDK build requirements and any other + required for execution; +* ``TG1`` which already has Scapy installed in the system. + +And they both have two network ports which are physically connected to each other. + +.. note:: + This example assumes that you have setup SSH keys in both the system under test + and traffic generator nodes. + +.. literalinclude:: ../../../dts/conf.yaml + :language: yaml + :start-at: executions: