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

[Paul Szczepanek <paul.szczepanek@arm.com>]

Reviewed-by: Paul Szczepanek <paul.szczepanek@arm.com>

On 28/05/2025 21:40, Patrick Robb wrote:
> 
> 
> On Tue, May 27, 2025 at 11:37 AM Dean Marx <dmarx@iol.unh.edu
> <mailto: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 <mailto: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/ <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 <probb@iol.unh.edu <mailto:probb@iol.unh.edu>>