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

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

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

On Fri, Jul 11, 2025 at 1:25 PM Dean Marx <dmarx@iol.unh.edu> wrote:

> Remove unnecessary information from README.md,
>

I would call the dropped information "extraneous".


> and add new sections to clarify the purpose/use
> of DTS along with clear setup instructions.
>

Maybe say that the goal of the commit is refactoring the README to be a
document which contains only a high level description of the relevant
concepts in DTS and a simple getting started guide.


>
> +
> +1. 2 links topology: Represents a topology in which the TG node and SUT
> node both have two network interfaces
> +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 links topology: Works, but may result in skips for testsuites which
> are explicitly decorated with a

+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.
>

1 links -> 1 link

And the phrasing seems slightly off. Can you reword the 1 link topology to:

"Represents a topology in which the TG node and SUT node are connected over
a single networking link. An example of this would be two single interface
NICs directly connected to each other."

or similar to this phrasing.

And, maybe make this an unordered list? the "1. 2" and "2. 1" thing looks a
touch weird. Not a big deal but probably worth doing:
https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#lists

Also, I never did get a response from you about whether it would be good to
include some ascii art to depict these topologies :)

You don't have to be a fan, but it would be good to get your opinion. If
you think it's a good idea, can you add a bugzilla ticket so we can do this
during 25.11? If you're opposed I'm okay with it - ultimately the wording
should make the valid topologies clear enough to people. It's not something
we can add during RC4 in any case.


2 link topology:


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




1 link topology:


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

+------------------------------+
+------------------------------+



2 link topology on a single host:


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





> +
> +# Simple Linux Setup
> +
> +1. On your TG and SUT nodes, add a dedicated user. In this example I will
> name the user "dts."
>

"add a dedicated user for 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}.
> +
> +For additional detail, please refer to
> [dts.rst](../doc/guides/tools/dts.rst)
> +
> +# DTS Configuration
> +
> +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.
> +
> +1. Download Docker on the SUT, and Scapy on the TG.
>

It's semantics but let's say Install instead of download.


> -### Visual Studio Code
> +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 below:
>
>  VSCode has first-class support for developing with containers.
>  You may need to run the non-Docker setup commands in the integrated
> terminal.
> @@ -76,6 +75,6 @@ will mount the SSH keys of the user currently running
> VSCode into the container
>  The `source` on this line can be altered to mount any SSH keys
>  on the local machine into the container at the correct location.
>
> -### 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.
>

I would just drop this whole "Other" section with the comment about
searching for dev containers - it's not needed.

> \ No newline at end of file
> --
> 2.49.0
>
>

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