[PATCH v4 2/2] User Manual: Added ini format in rtems-tester

[Tanu Hari Dixit]

Added specification for ini format for configuration
files in documentation of rtems-tester
---
 user/tools/tester.rst | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 134 insertions(+)

diff --git a/user/tools/tester.rst b/user/tools/tester.rst
index ae8c3b6..966a373 100644
--- a/user/tools/tester.rst
+++ b/user/tools/tester.rst
@@ -66,6 +66,140 @@ There is the ``erc32`` tester which uses the GDB back-end and the
 how to use :program:`rtems-test` command with the erc32 BSP because it is easy 
 to build an use.
 
+Adding support for a BSP to the tester
+--------------------------------------
+
+To add support for a BSP, one should add a configuration file in 
+``rtems-tools.git/tester/rtems/testing/bsps``. The configuration files 
+should be specified in an INI file. The configuration files provide a 
+means to the backend of `rtems-tester` to automate the running of tests.
+There is the ``<bsp>`` tester which uses the GDB back-end and the ``<bsp>-run`` 
+tester which uses the command line version of the respective simulator.
+The general format for specifying an INI configuration file is as follows:
+
+``<bsp>.ini``:
+
+.. code-block:: shell
+
+    [<bsp_name>]
+    bsp = '<bsp_name>'
+    gdb = '%{_rtscripts}/gdb.cfg'
+    arch = '<arch_name>'
+
+    [gdb_script]
+    gdb_script ='<bsp>_gdb_script'
+    <bsp>_gdb_script =   '<Instructions for gdb
+	    ...
+	    ...>'
+
+``<bsp>-run.ini``:
+
+.. code-block:: shell
+
+    [<bsp_name>]
+    bsp = '<bsp_name>'
+
+    [run]
+    run = '%{_rtscripts}/run.cfg'
+    arch = '<arch_name>'
+    bsp_run_cmd = '%{rtems_tools}/%{bsp_arch}-rtems%{rtems_version}-run'
+    bsp_run_opts = '<options>'
+
+Here is an example:
+
+``arm7tdmi.ini``:
+
+.. code-block:: shell
+
+    [arm7tdmi]
+    bsp = 'arm7tdmi'
+    gdb = '%{_rtscripts}/gdb.cfg'
+    arch = 'arm'
+
+    [gdb_script]
+    gdb_script ='arm7tdmi_gdb_script'
+    arm7tdmi_gdb_script =   'target sim
+        load
+        run'
+
+``arm7tdmi-run.ini``:
+
+.. code-block:: shell
+
+    [arm7tdmi]
+    bsp = 'arm7tdmi'
+
+    [run]
+    run = '%{_rtscripts}/run.cfg'
+    arch = 'arm'
+    bsp_run_cmd = '%{rtems_tools}/%{bsp_arch}-rtems%{rtems_version}-run'
+    bsp_run_opts = '-a -nouartrx'
+
+If the tester should run the tests on qemu for a bsp, the given pattern can 
+be followed:
+
+.. code-block:: shell
+
+    [<bsp_name>]
+    bsp = '<bsp_name>'
+
+    [qemu-script]
+    run = '%{_rtscripts}/qemu.cfg'
+    arch = '<arch_name>'
+    opts = '%{qemu_opts_base} %{qemu_opts_no_net} -m 32M'
+
+For instance,
+
+``generic_or1k.ini``:
+
+.. code-block:: shell
+
+    [generic_or1k]
+    bsp = 'generic_or1k'
+
+    [qemu-script]
+    run = '%{_rtscripts}/qemu.cfg'
+    arch = 'or32'
+    opts = '%{qemu_opts_base} %{qemu_opts_no_net} -m 32M'
+
+User can also provide a "settings.ini" file in case a configuration file needs 
+a path to, for instance, a first stage bootloader (fsbl) that is placed 
+somewhere in the host machine. The settings.ini file can be passed with 
+``rtems-test --with-settings = /path/to/settings/file`` option. The 
+<bsp_name>.ini can contain defaults and the settings file can contain the 
+user-specified configuration.
+
+
+``xilinx_zynq_zc706.ini``:
+
+.. code-block:: shell
+
+    [xilinx_zynq_zc706]
+    bsp = 'xilinx_zynq_zc706'
+    jobs = '1'
+
+    [gdb-script]
+    gdb = '%{_rtscripts}/gdb.cfg'
+    arch = 'arm'
+    bsp_tty_dev =  ${settings:bsp_tty_dev}
+    gdb_script = 'xilinx_zynq_zc706_gdb_script'
+    xilinx_zynq_zc706_gdb_script = 'target remote kaka:3333
+    mon load_image ${settings:path_to_fsbl} 0 elf
+        mon resume 0
+        mon sleep 4000
+        mon halt
+        load
+        b bsp_reset
+        continue'
+
+``settings.ini``:
+
+.. code-block:: shell
+
+    [settings]
+    bsp_tty_dev = '/dev/cu.SLAB_USBtoUART'
+    path_to_fsbl = '/path/to/fsbl'
+    
 Building RTEMS Tests
 --------------------
 
-- 
2.1.4