[v2,2/2] dts: add configuration schema docs
Checks
Commit Message
Document the configuration schema in the docs, describing all of the
relevant definitions and properties.
Reviewed-by: Paul Szczepanek <paul.szczepanek@arm.com>
Signed-off-by: Luca Vizzarro <luca.vizzarro@arm.com>
---
v2:
- changed arrays, objects terminology
doc/guides/tools/dts.rst | 208 +++++++++++++++++++++++++++++++++++++--
1 file changed, 198 insertions(+), 10 deletions(-)
Comments
Reviewed-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
On Tue, Jan 16, 2024 at 12:46 PM Luca Vizzarro <luca.vizzarro@arm.com> wrote:
>
> Document the configuration schema in the docs, describing all of the
> relevant definitions and properties.
>
> Reviewed-by: Paul Szczepanek <paul.szczepanek@arm.com>
> Signed-off-by: Luca Vizzarro <luca.vizzarro@arm.com>
@@ -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 <configuration_schema_example>`,
+which is a template that illustrates what can be configured in DTS.
The user must have :ref:`administrator privileges <sut_admin_user>`
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 <https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range>`_ listing
+ the execution environments. Each entry is described as per the following
+ `mapping <https://docs.python.org/3/library/stdtypes.html#mapping-types-dict>`_:
+
+ +----------------------------+-------------------------------------------------------------------+
+ | ``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 <https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range>`_ listing
+ the nodes. Each entry is described as per the following
+ `mapping <https://docs.python.org/3/library/stdtypes.html#mapping-types-dict>`_:
+
+ +-----------------------+---------------------------------------------------------------------------------------+
+ | ``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: