[PATCH v2] dts: update yaml configs

[Andrew Bailey]

Previously, optional arguments and the descriptions of them had no clear
format. This patch adds an optional fields section to all yaml
configuration files to improve readability. Additionally, the vdev
argument in the test run config had minimal usage in DTS. This patch
comments the argument out by default.

Bugzilla ID: 1896
Signed-off-by: Andrew Bailey <abailey at iol.unh.edu>
---
 dts/configurations/nodes.example.yaml        |  7 ++-
 dts/configurations/test_run.example.yaml     | 48 +++++++++++++-------
 dts/configurations/tests_config.example.yaml |  7 +++
 3 files changed, 44 insertions(+), 18 deletions(-)

diff --git a/dts/configurations/nodes.example.yaml b/dts/configurations/nodes.example.yaml
index 3f23df11ec..4da5585318 100644
--- a/dts/configurations/nodes.example.yaml
+++ b/dts/configurations/nodes.example.yaml
@@ -2,6 +2,9 @@
 # Copyright 2022-2023 The DPDK contributors
 # Copyright 2023 Arm Limited
 
+# Optional Fields:
+#   `hugepages_2mb`: if removed, will use system hugepage configuration
+
 # Define a system under test node, having two network ports physically
 # connected to the corresponding ports in TG 1 (the peer node)
 - name: "SUT 1"
@@ -17,7 +20,7 @@
       pci: "0000:00:08.1"
       os_driver_for_dpdk: vfio-pci
       os_driver: i40e
-  hugepages_2mb: # optional; if removed, will use system hugepage configuration
+  hugepages_2mb: # see 'Optional Fields'
       number_of: 256
       force_first_numa: false
 # Define a Scapy traffic generator node, having two network ports
@@ -35,6 +38,6 @@
       pci: "0000:00:08.1"
       os_driver_for_dpdk: rdma
       os_driver: rdma
-  hugepages_2mb: # optional; if removed, will use system hugepage configuration
+  hugepages_2mb: # see 'Optional Fields'
       number_of: 256
       force_first_numa: false
diff --git a/dts/configurations/test_run.example.yaml b/dts/configurations/test_run.example.yaml
index c8035fccf0..707a3104ed 100644
--- a/dts/configurations/test_run.example.yaml
+++ b/dts/configurations/test_run.example.yaml
@@ -2,27 +2,44 @@
 # Copyright 2022-2023 The DPDK contributors
 # Copyright 2023 Arm Limited
 
+# Optional Fields:
+#   `dpdk_tree` & `tarball`:
+#       Either `dpdk_tree` or `tarball` can be defined, but not both. dpdk_tree is
+#       for an uncompressed DPDK directory while tarball is a compressed DPDK.
+#   `remote`:
+#       Optional, Defaults to false. If it's true, the `dpdk_tree` or `tarball`
+#       is located on the SUT node, instead of the execution host.
+#   `precompiled_build_dir` & `build_options`:
+#       If `precompiled_build_dir` is defined, DPDK has been pre-built
+#       and the build directory is in a subdirectory of DPDK tree root directory.
+#       Otherwise, will be using the `build_options` to build the DPDK from source. Either
+#       `precompiled_build_dir` or `build_options` can be defined, but not both.
+#   `compiler_wrapper`:
+#       Optional, adds a compiler wrapper if present.
+#   `func_traffic_generator` & `perf_traffic_generator`:
+#       Define `func_traffic_generator` when `func` set to true.
+#       Define `perf_traffic_generator` when `perf` set to true.
+#   `skip_smoke_tests`:
+#       Defaults to true. If it's false, smoke tests will run.
+#   `test_suites`:
+#       By removing the `test_suites` field, this test run will run every test suite available.
+#   `vdevs`:
+#       Uncomment to add a specific virtual device to run on the SUT node.
+
 # Define the test run environment
 dpdk:
   lcores: "" # use all available logical cores (Skips first core)
   memory_channels: 4 # tells DPDK to use 4 memory channels
   build:
     dpdk_location:
-      # dpdk_tree: Commented out because `tarball` is defined.
+      # dpdk_tree: see `Optional Fields`
       tarball: dpdk-tarball.tar.xz
-      # Either `dpdk_tree` or `tarball` can be defined, but not both.
-      remote: false # Optional, defaults to false. If it's true, the `dpdk_tree` or `tarball`
-                    # is located on the SUT node, instead of the execution host.
-
-    # precompiled_build_dir: Commented out because `build_options` is defined.
+      remote: false # see `Optional Fields`
+    # precompiled_build_dir: see `Optional Fields`
     build_options:
       # the combination of the following two makes CC="ccache gcc"
       compiler: gcc
-      compiler_wrapper: ccache # Optional.
-    # If `precompiled_build_dir` is defined, DPDK has been pre-built and the build directory is
-    # in a subdirectory of DPDK tree root directory. Otherwise, will be using the `build_options`
-    # to build the DPDK from source. Either `precompiled_build_dir` or `build_options` can be
-    # defined, but not both.
+      compiler_wrapper: ccache # see `Optional Fields`
 func_traffic_generator:
   type: SCAPY
 # perf_traffic_generator:
@@ -32,12 +49,11 @@ func_traffic_generator:
 perf: false # disable performance testing
 func: true # enable functional testing
 use_virtual_functions: false # use virtual functions (VFs) instead of physical functions
-skip_smoke_tests: true # optional
-# by removing the `test_suites` field, this test run will run every test suite available
-test_suites: # the following test suites will be run in their entirety
+skip_smoke_tests: true # see `Optional Fields`
+test_suites: # see `Optional Fields`; the following test suites will be run in their entirety
   - hello_world
-vdevs: # optional; if removed, vdevs won't be used in the execution
-  - "crypto_openssl"
+# vdevs: # see `Optional Fields`
+#   - "crypto_openssl"
 # The machine running the DPDK test executable
 system_under_test_node: "SUT 1"
 # Traffic generator node to use for this execution environment
diff --git a/dts/configurations/tests_config.example.yaml b/dts/configurations/tests_config.example.yaml
index 64fa630aa0..39e96660a5 100644
--- a/dts/configurations/tests_config.example.yaml
+++ b/dts/configurations/tests_config.example.yaml
@@ -1,5 +1,8 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
+# Optional Fields:
+#   All fields are optional, uncomment a test suite to run it with a specific configuration.
+
 # Define the custom test suite configurations
 hello_world:
   msg: A custom hello world to you!
@@ -15,3 +18,7 @@ hello_world:
 #       num_descriptors: 1024
 #       expected_mpps: 1.0
 #   delta_tolerance: 0.05
+# pmd_rss:
+#   NUM_QUEUES: 4
+#   ACTUAL_KEY_SIZE: 52
+#   ACTUAL_RETA_SIZE: 512
-- 
2.50.1