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> --- 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 +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. -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 +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 +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. -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 -#### 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 $ poetry install -$ poetry shell +$ poetry run ./main.py ``` -### 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 -``` - -### 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. -### 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
