Re: [PATCH v1 1/3] dts: rewrite README

[Patrick Robb <probb@iol.unh.edu>]

[-- Attachment #1: Type: text/plain, Size: 11507 bytes --]

On Tue, May 27, 2025 at 11:37 AM Dean Marx <dmarx@iol.unh.edu> wrote:

> Remove unnecessary information from README.md, and add new sections to
> clarify
> the purpose/use of DTS along with clear setup instructions.
>
> Signed-off-by: Dean Marx <dmarx@iol.unh.edu>
> ---
>  dts/README.md | 104 +++++++++++++++++++-------------------------------
>  1 file changed, 39 insertions(+), 65 deletions(-)
>
> diff --git a/dts/README.md b/dts/README.md
> index 2b3a7f89c5..879cf65abc 100644
> --- a/dts/README.md
> +++ b/dts/README.md
> @@ -1,81 +1,55 @@
> -# DTS Environment
> +# Description
>
> -The execution and development environments for DTS are the same,
> -a [Docker](https://docs.docker.com/) container defined by our
> [Dockerfile](./Dockerfile).
> -Using a container for the development environment helps with a few things.
> +DTS is a testing framework and set of testsuites for end to end testing
> of DPDK and DPDK
> +enabled hardware. Unlike the DPDK unit test application, DTS is intended
> to be used to


Maybe change to "unlike DPDK's dpdk-test application, which is used for
running unit tests, DTS is intended to be used to evaluate real DPDK
workloads run over supported hardware."


>
> +evaluate real DPDK workloads run over supported hardware. For instance,
> DTS will control
> +a traffic generator node which will send packets to a system under test
> node which is
> +running a DPDK application, and evaluate those results.
>
>
Change to "evaluate the resulting DPDK application behavior."


> -1. It helps enforce the boundary between the DTS environment and the
> TG/SUT,
> -   something which caused issues in the past.
> -2. It makes creating containers to run DTS inside automated tooling much
> easier, since
> -   they can be based off of a known-working environment that will be
> updated as DTS is.
> -3. It abstracts DTS from the server it is running on. This means that the
> bare-metal OS
> -   can be whatever corporate policy or your personal preferences dictate,
> -   and DTS does not have to try to support all distros that are supported
> by DPDK CI.
> -4. It makes automated testing for DTS easier,
> -   since new dependencies can be sent in with the patches.
> -5. It fixes the issue of undocumented dependencies,
> -   where some test suites require Python libraries that are not installed.
> -6. Allows everyone to use the same Python version easily,
> -   even if they are using a distribution or Windows with out-of-date
> packages.
> -7. Allows you to run the tester on Windows while developing via Docker
> for Windows.
> +# Supported Test Node Topologies
>
> -## Tips for setting up a development environment
> +DTS is a python application which will control a traffic generator node
> (TG) and system
> +under test node (SUT). The nodes represent a DPDK device (usually a NIC)
> located on a
> +host. The devices/NICs can be located on two separate servers, or on the
> same server. If you use
> +the same server for both NICs, install them on separate NUMA domains if
> possible (this is ideal
> +for performance testing.)
>
> -### Getting a docker shell
> +1. 2 link: Represents a topology in which the TG node and SUT node both
> have two network interfaces
>

2 links topology


> +which form the TG <-> SUT connection. An example of this would be a dual
> interface NIC which is the
> +TG node connected to a dual interface NIC which is the SUT node.
> Interface 0 on TG <-> interface 0
> +on SUT, interface 1 on TG <-> interface 1 on SUT.
> +2. 1 link: Works, but may result in skips for testsuites which are
> explicitly decorated with a
>

1 links topology


> +2 link requirement. Represents a topology in which the TG node and SUT
> node are both located on one
> +network interface. An example of this would be a dual interface NIC with
> a connection between
> +its own ports.
>

I wonder whether it makes sense to provide an ascii drawing of the various
topologies?

I google an online ascii art tool and got these 2 showing the 2 links
topology for 2 servers and 1 server:

+------------------------------+
+------------------------------+
|                              |                 |
         |
|                              | --------------- |
         |
|                              |                 |
         |
|  Tester (Traffic Generator)  |                 |     System Under
Test        |
|                              |                 |
         |
|                              | --------------- |
         |
|                              |                 |
         |
+------------------------------+
+------------------------------+





                       -----------------------------------
                      |                                   |
                      |     -------------------------     |
                      |    |                        |     |
                      |    |                        |     |
                      |    |                        |     |
                      |    |                        |     |
                      |    |                        |     |
                      |    |                        |     |
                      |    |                        |     |
                      |    |                        |     |
                +--------------------------------------------------+
                |                                                  |
                |                                                  |
                |                                                  |
                |                                                  |
                |          Combined Tester & SUT system            |
                |                                                  |
                |                                                  |
                               -
                |                                                  |
                |                                                  |
                +--------------------------------------------------+



If you wanted to do this you might have to use triple tilde to put it in a
code block so it renders with a monospaced font for readers.



> -These commands will give you a bash shell inside the container
> -with all the Python dependencies installed.
> -This will place you inside a Python virtual environment.
> -DTS is mounted via a volume, which is essentially a symlink from the host
> to the container.
> -This enables you to edit and run inside the container
> -and then delete the container when you are done, keeping your work.
> -It is also strongly recommended that you mount your SSH keys into the
> container
> -to allow you to connect to hosts without specifying a password.
> +# Simple linux setup
>

capitalize linux and setup


>
> -#### Start docker container with SSH keys
> +1. On your TG and SUT nodes, add a dedicated user. In this example I will
> name the user "dts."
> +2. Grant passwordless sudo to the dts user, like so:
> +    2a: enter 'visudo' in your terminal
> +    2b: In the visudo text editor, add:
> +        dts   ALL=(ALL:ALL) NOPASSWD:ALL
> +3. DTS uses ssh key auth to control the nodes. Copy your ssh keys to the
> TG and SUT:
> +    ssh-copy-id dts@{your host}.
>
> -```shell
> -docker build --target dev -t dpdk-dts .
> -docker run -v $(pwd)/..:/dpdk -v /home/dtsuser/.ssh:/root/.ssh:ro -it
> dpdk-dts bash
> -$ poetry install
> -$ poetry shell
> -```
> +For additional detail, please refer to [dts.rst](doc/guides/tools/dts.rst)
> +
> +# DTS Configuration
>
> -#### Start docker container without SSH keys
> +DTS requires two yaml files to be filled out with information about your
> environment,
> +test_run.yaml and nodes.yaml, which follow the format illustrated in the
> example files.
>
>  ```shell
>  docker build --target dev -t dpdk-dts .
> -docker run -v $(pwd)/..:/dpdk -it dpdk-dts bash
> +docker run -v $(pwd)/..:/dpdk -v /home/dtsuser/.ssh:/root/.ssh:ro -it
> dpdk-dts bash
>

Instead of dtsuser maybe we can more explicitly say {insert your dts ssh
user}/ or similar.


>  $ poetry install
> -$ poetry shell
> +$ poetry run ./main.py
>  ```
>

This information looks good, but I think it needs to be tied together more
cohesively. I would make a step 4 like:

4. Create and fill out a test_run.yaml and nodes.yaml file within your dts
directory, based on the structure from the example config files.

And a step 5 like:

5. Run the bash terminal commands below in order to run the DTS container
and start the DTS execution.

```shell
docker build --target dev -t dpdk-dts .
docker run -v $(pwd)/..:/dpdk -v /home/{insert your dts ssh
user}/.ssh:/root/.ssh:ro -it dpdk-dts bash
$ poetry install
$ poetry run ./main.py
```


I also think we may have to call out some of the project dependencies (this
is outside of the python dependencies that poetry handles for the DTS
execution). So that would include Docker on the execution host, Scapy on
the TG host.


> -### Vim/Emacs
> -
> -Any editor in the Ubuntu repos should be easy to use,
> -with Vim and Emacs already installed.
> -You can add your normal config files as a volume,
> -enabling you to use your preferred settings.
> -
> -```shell
> -docker run -v ${HOME}/.vimrc:/root/.vimrc -v $(pwd)/..:/dpdk -it dpdk-dts
> bash
> -```
>

I agree we can remove this.


> -
> -### Visual Studio Code
> -
> -VSCode has first-class support for developing with containers.
> -You may need to run the non-Docker setup commands in the integrated
> terminal.
> -DTS contains a .devcontainer config,
> -so if you open the folder in VSCode it should prompt you to use the dev
> container
> -assuming you have the plugin installed.
> -Please refer to
> -[VS Development Containers Docs](
> https://code.visualstudio.com/docs/remote/containers)
> -to set it all up.
> -Additionally, there is a line in `.devcontainer/devcontainer.json` that,
> when included,
> -will mount the SSH keys of the user currently running VSCode into the
> container for you.
> -The `source` on this line can be altered to mount any SSH keys
> -on the local machine into the container at the correct location.
> +These commands will give you a bash shell inside a docker container
> +with all DTS Python dependencies installed.
>
>
Well... I know I was saying the devcontainers aren't so useful, but upon
reflection, it's kind of nice to not have to manage the 2nd terminal for
driving the container, and of course it means python intellisense will work
without having to poetry install on your base system. I would leave this
part in, but stick a sentence in at the start saying  "usage of vscode
devcontainers is NOT required for developing on DTS and running DTS, but
provide some small quality of life improvements for the developer. If you
want to develop from a devcontainer, see the instructions here" or
somethign like that.


> -### Other
> +## Other
>
> -Searching for '$IDE dev containers' will probably lead you in the right
> direction.
> +Searching for '$IDE dev containers' will probably lead you in the right
> direction.
> \ No newline at end of file
> --
> 2.49.0
>
>
Reviewed-by: Patrick Robb <probb@iol.unh.edu>

[-- Attachment #2: Type: text/html, Size: 16138 bytes --]