From 2674d6a949447e5874bf47d152bdca57d09a3864 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 21 Feb 2019 13:06:58 +1100 Subject: user: Remove nit-picky warnings. --- user/testing/configuration.rst | 21 ++++++++++++++++++++- user/testing/consoles.rst | 2 +- user/testing/gdb-jtag.rst | 2 +- user/testing/index.rst | 14 ++++++++------ user/testing/tests.rst | 15 +++++++++++++++ user/testing/tftp.rst | 29 ++++++++++++++++++++--------- 6 files changed, 65 insertions(+), 18 deletions(-) (limited to 'user/testing') diff --git a/user/testing/configuration.rst b/user/testing/configuration.rst index e740af6..9c65506 100644 --- a/user/testing/configuration.rst +++ b/user/testing/configuration.rst @@ -57,6 +57,7 @@ The RTEMS Tester and RTEMS Run are primed using defaults from the file User configuration file. .. index:: BSP configuration, User configuration + BSP and User Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -65,18 +66,21 @@ configuration file has to have an INI section that is the name of the BSP passed on the command line. The section has the following mandatory values: .. index:: bsp + ``bsp`` The name of the BSP. The BSP name is used to create a macro map to hold the BSP's configuration data. Typically this is the same as the BSP name used on the command line. .. index:: arch + ``arch`` The name of the BSP architecture. This is need for the GDB configuration scripts where the architecture specific GDB needs to run. It is mandatory so the *arch/bsp* standard RTEMS BSP string can be used. .. index:: tester + ``tester`` The tester or run configuration script. This is the name of the configuration script the RTEMS Tester or RTEMS Run executes as a back end. The ``tester`` @@ -87,18 +91,22 @@ Target commands support expansion of specific tags to provide a convenient way for users to customize a local test environment. The parameters expanded are: .. index:: @ARCH@ + ``@ARCH@`` The BSP architecture. .. index:: @BSP@ + ``@BSP@`` The BSP's name set by the ``bsp`` value. .. index:: @EXE@ + ``@EXE@`` The executable name as an absolute path .. index:: @FEXE@ + ``@FEXE@`` The filtered executable if a ``target_exe_filter`` is provided else the executable's file name. @@ -107,6 +115,7 @@ The following are optional and depend on the back end being used and the local target hardware set up: .. index:: jobs + ``jobs`` The jobs value sets the number of jobs that can be run at once. This setting only effects the RTEMS Tester. The tester can run up to the ``jobs`` value of @@ -116,12 +125,14 @@ target hardware set up: test timeouts may be recorded. .. index:: bsp_tty_dev + ``bsp_tty_dev`` The BSP's tty device. This can be a real device on the host machine the executable is being run from or it can be a telnet server and port defined - using the stand host format. See :ref:`tester-consoles` for details. + using the stand host format. See :ref:`TesterConsoles` for details. .. index:: target_pretest_command + ``target_pretest_command`` The pre-test command is a host shell command that is called before each test runs. It can be used to construct a suitable environment or image needed by a @@ -129,12 +140,14 @@ target hardware set up: and the bootloader specific format is the output. .. index:: target_posttest_command + ``target_posttest_command`` The post-test command is a host shell command that is called after each test has finished. It can be used to destroy any environment or image created by the pre-test command. .. index:: target_exe_filter + ``target_exe_filter`` The target executable filter transforms the executable name into a filtered executable name. This filter lets the tester or run command track the name of @@ -147,11 +160,13 @@ target hardware set up: is no need to escape the text in the second part, it is just plain test. .. index:: test_restarts + ``test_restarts`` The number of restarts before the test is considered ``invalid``. Currently not used. .. index:: target_reset_regex + ``target_reset_regex`` The target reset regular expression. This is a `Python regular expression `_ used @@ -161,6 +176,7 @@ target hardware set up: messages that indicate the boot process as failed. .. index:: target_start_regex + ``target_start_regex`` The target start regular expression. This is a Python regular expression to @@ -169,6 +185,7 @@ target hardware set up: restart and ends the test with a suitable result. .. index:: target_on_command + ``target_on_command`` The target on command is a host shell command that is called before the first test. This command powers on a target. Targets should be left powered off @@ -178,11 +195,13 @@ target hardware set up: command. .. index:: target_off_command + ``target_off_command`` The target off command is a host shell command that is called after the last test powering off the target. .. index:: target_reset_command + ``target_reset_command`` The target reset command is a host shell command that is called when the target needs to be reset. This command can power cycle the target or toggle a diff --git a/user/testing/consoles.rst b/user/testing/consoles.rst index ee5126a..28213c1 100644 --- a/user/testing/consoles.rst +++ b/user/testing/consoles.rst @@ -2,7 +2,7 @@ .. Copyright (C) 2018 Chris Johns -.. _tester-consoles: +.. _TesterConsoles: Consoles -------- diff --git a/user/testing/gdb-jtag.rst b/user/testing/gdb-jtag.rst index 0f91f52..83e950e 100644 --- a/user/testing/gdb-jtag.rst +++ b/user/testing/gdb-jtag.rst @@ -20,7 +20,7 @@ JTAG port of a target. RTEMS Tester using GDB and JTAG -The :ref:`fig-tester-gdb-jtag` figure shows the structure of RTEMS Testing +The Figure :ref:`fig-tester-gdb-jtag` shows the structure of RTEMS Testing using GDB and JTAG. The executables are built and the ``rtems-test`` command is run from the top of the build directory. The RTEMS Tester executes the BSP architecture's GDB and expects the user to provide a ``gdb-script`` to connect diff --git a/user/testing/index.rst b/user/testing/index.rst index 7eefff1..a938af4 100644 --- a/user/testing/index.rst +++ b/user/testing/index.rst @@ -39,9 +39,11 @@ extend the RTEMS kernel's build time and use more disk space but it worth building and running them. The RTEMS test executables have the ``.exe`` file extension. -.. include:: tests.rst -.. include:: configuration.rst -.. include:: consoles.rst -.. include:: simulation.rst -.. include:: gdb-jtag.rst -.. include:: tftp.rst +.. toctree:: + + tests + configuration + consoles + simulation + gdb-jtag + tftp diff --git a/user/testing/tests.rst b/user/testing/tests.rst index 37966c7..0b44d05 100644 --- a/user/testing/tests.rst +++ b/user/testing/tests.rst @@ -71,15 +71,18 @@ Test States The tests states are: .. index:: test state passed + ``passed`` The test start and end banners have been sent to the console. .. index:: test state failure + ``failure`` The test start banner has been sent to the console and no end banner has been seen when a target restart is detected. .. index:: test state expected-fail + ``excepted-fail`` The test is tagged as ``expected-fail`` in the RTEMS sources for this BSP and outputs the banner ``*** TEST STATE: EXPECTED_FAIL``. The test is known not @@ -88,6 +91,7 @@ The tests states are: otherwise it is recorded as *expected-fail*. .. index:: test state indeterminate + ``indeterminate`` The test is tagged as ``indeterminate`` in the RTEMS sources for this BSP and outputs the banner ``*** TEST STATE: INDETERMINATE``. The test may or may not @@ -95,12 +99,14 @@ The tests states are: the test run as far as it can and record the result as indeterminate. .. index:: test state user-input + ``user-input`` The test is tagged as ``user-input`` in the RTEMS sources and outputs the banner ``*** TEST STATE: USER_INPUT``. The RTEMS Tester will reset the target if the target's configuration provides a target reset command. .. index:: test state benchmark + ``benchmark`` The test is tagged as ``benchmark`` in the RTEMS sources and outputs the banner ``*** TEST STATE: BENCHMARK``. Benchmarks can take a while to run and @@ -108,6 +114,7 @@ The tests states are: the target if the target's configuration provides a target reset command. .. index:: test state timeout + ``timeout`` The test start banner has been sent to the console and no end banner is seen within the *timeout* period and the target has not restart. A default @@ -115,6 +122,7 @@ The tests states are: provide on the RTEMS Tester's command line using the ``--timeout`` option. .. index:: test state invalid + ``invalid`` The test did not output a start banner and the RTEMS Tester has detected the target has restarted. This means the executable did not load correctly, the @@ -171,38 +179,45 @@ Test Builds The test reports the build of RTEMS being tested. The build are: .. index:: build default + ``default`` The build is the default. No RTEMS configure options have been used. .. index:: build posix + ``posix`` The build includes the POSIX API. The RTEMS configure option ``--enable-posix`` has been used. The ``cpuopts.h`` define ``RTEMS_POSIX`` has defined and it true. .. index:: build smp + ``smp`` The build is an SMP kernel. The RTEMS configure option ``--enable-smp`` has been used. The ``cpuopts.h`` define ``RTEMS_SMP`` has defined and it true. .. index:: build mp + ``mp`` The build is an MP kernel. The RTEMS configure option ``--enable-multiprocessing`` has been used. The ``cpuopts.h`` define ``RTEMS_MULTIPROCESSING`` has defined and it true. .. index:: build paravirt + ``paravirt`` The build is a paravirtualization kernel. The ``cpuopts.h`` define ``RTEMS_PARAVIRT`` has defined and it true. .. index:: build debug + ``debug`` The build includes kernel debugging support. The RTEMS configure option ``--enable-debug`` has been used. The ``cpuopts.h`` define ``RTEMS_DEBUG`` has defined and it true. .. index:: build profiling + ``profiling`` The build include profiling support. The RTEMS configure option ``--enable-profiling`` has been used. The ``cpuopts.h`` define diff --git a/user/testing/tftp.rst b/user/testing/tftp.rst index 1d01673..54b744a 100644 --- a/user/testing/tftp.rst +++ b/user/testing/tftp.rst @@ -22,9 +22,10 @@ U-Boot script. RTEMS Tester using TFTP and U-Boot. -The :ref:`fig-tester-tftp-u-boot` figure shows the structure and control flow -of the RTEMS Tester using TFTP and U-boot. The executables are built and the -``rtems-test`` command is run from the top of the build directory. +The Figure :ref:`fig-tester-tftp-u-boot` figure shows the structure and +control flow of the RTEMS Tester using TFTP and U-boot. The executables are +built and the ``rtems-test`` command is run from the top of the build +directory. This test mode can only support a single test job running at once. You cannot add more test target hardware and run the tests in parallel. @@ -45,7 +46,7 @@ The RTEMS Tester TFTP and U-Boot method of testing requires: #. Console interface cable that matches your target's console UART interface. -#. Telnet terminal server. See :ref:`tester-consoles`. +#. Telnet terminal server. See :ref:`TesterConsoles`. The network power or IO switch is a device that can control power or an IO pin over a network connection using a script-able protocol such as Telnet or @@ -58,7 +59,9 @@ Obtain a working image of the U-Boot boot loader for your target. We suggest you follow the instructions for you target. Configure U-Boot to network boot using the TFTP protocol. This is U-Boot script -for a Zedboard:: +for a Zedboard: + +.. code-block:: shell loadaddr=0x02000000 uenvcmd=echo Booting RTEMS Zed from net; set autoload no; dhcp; set serverip 10.10.5.2; tftpboot zed/rtems.img; bootm; reset; @@ -86,7 +89,9 @@ The BSP's configuration file must contain the standard fields: - ``jobs`` - Must be set to ``1``. - ``tester`` - Set to ``%{_rtscripts}/tftp.cfg`` -For example the Zedboard's configuration is:: +For example the Zedboard's configuration is: + +.. code-block:: ini [xilinx_zynq_zedboard] bsp = xilinx_zynq_zedboard @@ -159,14 +164,18 @@ substituted. The parameters are: substituted Some of these field are normally provided by a user's configuration. To do this -use:: +use: + +.. code-block:: shell requires = bsp_tty_dev, target_on_command, target_off_command, target_reset_command The ``requires`` value requires the user provide these settings in their configuration file. -The Zedboard's configuration file is:: +The Zedboard's configuration file is: + +.. code-block:: ini [xilinx_zynq_zedboard] bsp = xilinx_zynq_zedboard @@ -186,7 +195,9 @@ happen if U-Boot cannot detect the PHY device. It also checks if too many DHCP requests happen and finally a check is made for any timeouts reported by U-Boot. -An example of a user configuration for the Zedboard is:: +An example of a user configuration for the Zedboard is: + +.. code-block:: ini [xilinx_zynq_zedboard] bsp_tty_dev = selserver:12345 -- cgit v1.2.3