docs: Minor formatting updates to R&D test procedures

1 files changed, 65 insertions, 60 deletions

diff --git a/host/docs/rd_testing.dox b/host/docs/rd_testing.dox
index 1d05bc94e..a9105d2bb 100644
--- a/host/docs/rd_testing.dox
+++ b/host/docs/rd_testing.dox
@@ -149,15 +149,16 @@ pass/fail conditions (return code 0 means 'pass').
 
 Test benches provide a faster way to verify the design through simulations.
 
-| Test Code        | Device    | Peripherals       | Manual Test Procedure        | Automatic Test Procedure  |
-|------------------|-----------|-------------------|------------------------------|---------------------------|
-| FPGATB-v1   | None      | None         | \ref rdtesting_fpga_testbenches_manual  | \ref rdtesting_fpga_testbenches_auto |
+| Test Code        | Device    | Peripherals       | Manual Test Procedure                   | Automatic Test Procedure             |
+|------------------|-----------|-------------------|-----------------------------------------|--------------------------------------|
+| FPGATB-v1        | None      | None              | \ref rdtesting_fpga_testbenches_manual  | \ref rdtesting_fpga_testbenches_auto |
 
-\subsection rdtesting_fpga_testbenches_requirement: Requirements
+\subsection rdtesting_fpga_testbenches_requirement Requirements
 
-These tests are simulations and do not need any device. Vivado 15.4 should be installed.
+These tests are simulations and do not need any device. Vivado 15.4 should be
+installed.
 
-\subsection rdtesting_fpga_testbenches_manual: Manual Test Procedure
+\subsection rdtesting_fpga_testbenches_manual Manual Test Procedure
 
 1. Go to the fpga directory depending on which test needs to be run.
 
@@ -179,34 +180,38 @@ These tests are simulations and do not need any device. Vivado 15.4 should be in
 
 4. All of these tests must report no failure with a 'PASS' validation. Example testbench output:
 
-    ========================================================
-    TESTBENCH STARTED: noc_block_skeleton
-    ========================================================
-    [TEST CASE   1] (t=000000000) BEGIN: Wait for Reset...
-    [TEST CASE   1] (t=000001002) DONE... Passed
-    [TEST CASE   2] (t=000001002) BEGIN: Check NoC ID...
-    Read Skeleton NOC ID: 1234000000000000
-    [TEST CASE   2] (t=000001238) DONE... Passed
-    [TEST CASE   3] (t=000001238) BEGIN: Connect RFNoC blocks...
-    Connecting noc_block_tb (SID: 1:0) to noc_block_skeleton (SID: 0:0)
-    Connecting noc_block_skeleton (SID: 0:0) to noc_block_tb (SID: 1:0)
-    [TEST CASE   3] (t=000005457) DONE... Passed
-    [TEST CASE   4] (t=000005457) BEGIN: Write / readback user registers...
-    [TEST CASE   4] (t=000006888) DONE... Passed
-    [TEST CASE   5] (t=000006888) BEGIN: Test sequence...
-    [TEST CASE   5] (t=000007403) DONE... Passed
-    ========================================================
-    TESTBENCH FINISHED: noc_block_skeleton
-     - Time elapsed:   7500 ns             
-     - Tests Expected: 5
-     - Tests Run:      5
-     - Tests Passed:   5
-    Result: PASSED   
-    ========================================================
-
-Failing tests can be debugged by checking the waveform in a Vivado GUI by running 'make GUI=1 xsim'. More details on debugging https://kb.ettus.com/Debugging_FPGA_images
-
-\subsection rdtesting_fpga_testbenches_auto: Automatic Test Procedure
+\code
+========================================================
+TESTBENCH STARTED: noc_block_skeleton
+========================================================
+[TEST CASE   1] (t=000000000) BEGIN: Wait for Reset...
+[TEST CASE   1] (t=000001002) DONE... Passed
+[TEST CASE   2] (t=000001002) BEGIN: Check NoC ID...
+Read Skeleton NOC ID: 1234000000000000
+[TEST CASE   2] (t=000001238) DONE... Passed
+[TEST CASE   3] (t=000001238) BEGIN: Connect RFNoC blocks...
+Connecting noc_block_tb (SID: 1:0) to noc_block_skeleton (SID: 0:0)
+Connecting noc_block_skeleton (SID: 0:0) to noc_block_tb (SID: 1:0)
+[TEST CASE   3] (t=000005457) DONE... Passed
+[TEST CASE   4] (t=000005457) BEGIN: Write / readback user registers...
+[TEST CASE   4] (t=000006888) DONE... Passed
+[TEST CASE   5] (t=000006888) BEGIN: Test sequence...
+[TEST CASE   5] (t=000007403) DONE... Passed
+========================================================
+TESTBENCH FINISHED: noc_block_skeleton
+ - Time elapsed:   7500 ns             
+ - Tests Expected: 5
+ - Tests Run:      5
+ - Tests Passed:   5
+Result: PASSED   
+========================================================
+\endcode
+
+Failing tests can be debugged by checking the waveform in a Vivado GUI by
+running 'make GUI=1 xsim'. More details on
+debugging: https://kb.ettus.com/Debugging_FPGA_images
+
+\subsection rdtesting_fpga_testbenches_auto Automatic Test Procedure
 
  Go to <fpga-dir>/usrp3/ and run 'build.py xsim all'. All tests should report 'PASS'.
 
@@ -419,32 +424,6 @@ Note: Any sample rate warnings can be ignored.
 
 tbd
 
-\section rdtesting_defining Defining R&D Tests
-
-Tests can be added any time to define procedures for pass/fail validation. Any
-test must include the following:
-
-- An unambiguous test code. This code consists of three characters that
-  identify the test, a short description of the devices required, and a version
-  suffix. Example: `GPS-X310-OCXO-v1` is a GPS-related test, requires an X310
-  and an OCXO to run, and is version 1 of this test.
-- A manual testing procedure. This must unambiguously define a set of tasks,
-  and clearly identify whether or not a test has failed or passed. Tests do not
-  require any other defined outcome other than 'pass' and 'fail'.
-- Optional, but highly recommended: An automatic test procedure. This must
-  consist of a command, or a script, or a set of commands that can be
-  automatically executed, and that will report a failure condition by means of
-  returning a non-zero return value.
-
-Basic understanding of the operation of USRPs by the test operator should be
-assumed when authoring test procedures. The descriptions should be as short as
-possible to fully describe, unambiguously, how to reach a pass/fail conclusion.
-
-Test procedures may be updated at any time. If this happens, a new test code
-must be generated, with the version number increased. Old test codes are
-considered deprecated (if there exists a version 2 of a test, version 1 should
-not be run any more).
-
 \section rdtesting_phasealignment Phase alignment tests
 
 | Test Code           | Device    | Peripherals        | Manual Test Procedure                | Automatic Test Procedure    |
@@ -515,5 +494,31 @@ Also supply `--lo-export True,False,False,False` and `--lo-source internal,compa
 Phase alignment testing with N210 and MIMO cable works like in the case with X3x0 devices but no Octoclock is needed for device synchronization. Instead two N210 devices are connected with a MIMO cable and only one N210 is connected with an ethernet cable to the host computer.
 Supply `--time-source internal,mimo` and `--clock-source internal,mimo` on the commandline to instruct the N2x0s to share time and clock over the MIMO cable.
 
+\section rdtesting_defining Defining R&D Tests
+
+Tests can be added any time to define procedures for pass/fail validation. Any
+test must include the following:
+
+- An unambiguous test code. This code consists of three characters that
+  identify the test, a short description of the devices required, and a version
+  suffix. Example: `GPS-X310-OCXO-v1` is a GPS-related test, requires an X310
+  and an OCXO to run, and is version 1 of this test.
+- A manual testing procedure. This must unambiguously define a set of tasks,
+  and clearly identify whether or not a test has failed or passed. Tests do not
+  require any other defined outcome other than 'pass' and 'fail'.
+- Optional, but highly recommended: An automatic test procedure. This must
+  consist of a command, or a script, or a set of commands that can be
+  automatically executed, and that will report a failure condition by means of
+  returning a non-zero return value.
+
+Basic understanding of the operation of USRPs by the test operator should be
+assumed when authoring test procedures. The descriptions should be as short as
+possible to fully describe, unambiguously, how to reach a pass/fail conclusion.
+
+Test procedures may be updated at any time. If this happens, a new test code
+must be generated, with the version number increased. Old test codes are
+considered deprecated (if there exists a version 2 of a test, version 1 should
+not be run any more).
+
 */
 // vim:ft=doxygen: