Reviewed-by: Paul Szczepanek <paul.szczepa...@arm.com>
On 28/05/2025 21:40, Patrick Robb wrote:
>
>
> On Tue, May 27, 2025 at 11:37 AM Dean Marx <dm...@iol.unh.edu
> <mailto:dm...@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 <dm...@iol.unh.edu <mailto:dm...@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/ <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 <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 <pr...@iol.unh.edu <mailto:pr...@iol.unh.edu>>
