Improve PTF documentation (#821)

* Improve PTF documentation

* Some additional changes (reorganizing document and address comment)

ptf/Makefile

@@ -2,7 +2,7 @@
 # Copyright 2020-present Open Networking Foundation
 
 # generates python protobuf files and builds ptf docker image
-build: 
+build:
 	cd .. && make py-pb
 	docker build -t bess-upf-ptf .
 

ptf/README.md

@@ -2,22 +2,6 @@
 <!-- Copyright 2021 Open Networking Foundation -->
 # PTF tests for BESS-UPF
 
-
-## Structure
-* `tests/`: contains all PTF test case definitions
-    * `unary/`: single-packet test cases
-    * `linerate/`: high-speed test cases
-* `lib/`: general purpose libraries and classes to be imported in PTF
-test definitions
-* `config/`: contains YAML config file definition for TRex along with
-other personalized config files
-
-## Tools
-* [PTF](https://github.com/p4lang/PTF) (Packet Testing Framework): a
-data plane testing framework written in Python
-* [TRex](https://github.com/cisco-system-traffic-generator/trex-core): a
-high-speed traffic generator built on top of DPDK, containing a Python API
-
 ## Overview
 
 The aim of implementing a test framework for UPF is to create a
@@ -34,6 +18,36 @@ this framework, we opt for **BESS gRPC calls** instead of calls to the PFCP
 agent because they allow direct communication between the framework and
 the BESS instance for both installing rules and reading metrics.
 
+## Workflow
+Tests require two separate machines to run, since both TRex and UPF
+use DPDK. Currently, the test workflow is as such:
+
+![Test](docs/test-run.svg)
+
+In **step 1**, rules are installed onto the UPF instance by the test
+framework via BESS gRPC messages.
+
+In **step 2**, TRex or Scapy (depending on the type of test case)
+generates traffic to the UPF across NICs and physical links.
+
+In **step 3**, traffic routes through the UPF and back to the machine
+hosting TRex, where results are asserted.
+
+## Required Tools/Components
+* [PTF](https://github.com/p4lang/PTF) (Packet Testing Framework): a
+data plane testing framework written in Python
+* [TRex](https://github.com/cisco-system-traffic-generator/trex-core): a
+high-speed traffic generator built on top of DPDK, containing a Python API
+
+## Directory Structure
+* `tests/`: contains all PTF test case definitions
+    * `unary/`: single-packet test cases
+    * `linerate/`: high-speed test cases
+* `lib/`: general purpose libraries and classes to be imported in PTF
+test definitions
+* `config/`: contains YAML config file definition for TRex along with
+other personalized config files
+
 ## Tests
 This directory maintains all of the test case definitions (written in
 Python), as well as scripts for running them in a test environment. We
@@ -56,21 +70,6 @@ API](https://github.com/cisco-system-traffic-generator/trex-core/blob/master/doc
     latency, etc. of the UPF is as expected when handling high-speed
     downlink traffic from 10,000 unique UEs.
 
-## Workflow
-Tests require two separate machines to run, since both TRex and UPF
-use DPDK. Currently, the test workflow is as such:
-
-![Test](docs/test-run.svg)
-
-In **step 1**, rules are installed onto the UPF instance by the test
-framework via BESS gRPC messages.
-
-In **step 2**, TRex or Scapy (depending on the type of test case)
-generates traffic to the UPF across NICs and physical links.
-
-In **step 3**, traffic routes through the UPF and back to the machine
-hosting TRex, where results are asserted.
-
 ## Steps to run tests
 The run script assumes that the TRex daemon server and the UPF
 instance are already running on their respective machines. Please see
@@ -83,21 +82,28 @@ To install TRex onto your server, please refer to the
 
 ### Steps
 1. Update the following files accordingly to route traffic to the UPF and vice versa.
-* `upf/ptf/.env` file updated with `UPF_ADDR` and `TREX_ADDR` parameters
-* `upf/ptf/config/trex-cfg-for-ptf.yaml` file updated with proper values for
+* `ptf/.env` file updated with `UPF_ADDR` and `TREX_ADDR` parameters
+* `ptf/config/trex-cfg-for-ptf.yaml` file updated with proper values for
   `interfaces`, `port_info`, and `platform` parameters
-* `upf/ptf/tests/linerate/common.py` file updated with proper MAC address values
-  for `TREX_SRC_MAC`, `UPF_CORE_MAC`, and `UPF_ACCESS_MAC`
+* `ptf/tests/linerate/common.py` file updated with proper MAC address values for
+  `TREX_SRC_MAC`, `UPF_CORE_MAC`, and `UPF_ACCESS_MAC`
 
-2. Generate BESS Python protobuf files for gRPC library and PTF Dockerfile image
+2. Move into the `ptf` directory
+```bash
+cd ptf
+```
+
+3. Generate BESS Python protobuf files for gRPC library and PTF Dockerfile image
    build dependencies:
 ```bash
 make build
 ```
-3. Run PTF tests using the `run_tests` script:
+
+4. Run PTF tests using the `run_tests` script:
 ```bash
 ./run_tests -t [test-dir] [optional: filename/filename.test_case]
 ```
+
 ### Examples
 To run all test cases in the `unary/` directory:
 ```bash