From fae996bff585a8107dbbfb46bf11ebbfc303b9c4 Mon Sep 17 00:00:00 2001 From: Iztok Jeras Date: Sun, 26 Jun 2022 19:50:02 +0200 Subject: [PATCH] DOCS: updated commands section, few grammar and spelling mistakes, using fixed width fornt for CLI options, use '--' prefix for options, clean up of sentance capitalization and punctuation. --- docs/source/commands.rst | 110 +++++++++++++++++++-------------------- 1 file changed, 54 insertions(+), 56 deletions(-) diff --git a/docs/source/commands.rst b/docs/source/commands.rst index 644f6e5..561efc2 100644 --- a/docs/source/commands.rst +++ b/docs/source/commands.rst @@ -8,13 +8,13 @@ RISCOF Commands This section provides an overview and working of the various sub commands available in RISCOF. The current list of subcommands includes: -- arch-tests -- coverage -- gendb -- setup -- validateyaml -- testlist -- run +- ``arch-tests`` +- ``coverage`` +- ``gendb`` +- ``setup`` +- ``validateyaml`` +- ``testlist`` +- ``run`` arch-tests ---------- @@ -22,15 +22,15 @@ This command is used to clone and update the tests from the official `riscv-arch This command requires one of the following flags to be specified from the CLI. -- show-version: Display the current version of the official suite present at the specified directory path. -- clone: Clone the suite from github. -- update: Update the suite to reflect latest changes from github. +- ``--show-version``: Display the current version of the official suite present at the specified directory path. +- ``--clone``: Clone the suite from github. +- ``--update``: Update the suite to reflect latest changes from github. Optional arguments from the CLI: -- get-version: The specific version of the tests to be fetched. Can be used with both the clone and +- ``--get-version``: The specific version of the tests to be fetched. Can be used with both the clone and update flags. The latest release is fetched if skipped. -- dir: The path to the directory where the suite is to be cloned to. Defaults to +- ``--dir``: The path to the directory where the suite is to be cloned to. Defaults to ``./riscv-arch-test`` if skipped. coverage @@ -41,17 +41,16 @@ report in html. This command will require the following inputs from the CLI: -- suite: The test suite path on which coverage needs to be run -- env: The path to the environment directory containing the suite-specific header files. -- cgf: list of covergroup-format files specifying the coverpoints that need to be covered by the - the suite +- ``--suite``: The test suite path on which coverage needs to be run. +- ``--env``: The path to the environment directory containing the suite-specific header files. +- ``--cgf``: The list of covergroup-format files specifying the coverpoints that need to be covered by the suite. Optional arguments from the CLI: -- config: path to the ``config.ini`` file. Defaults to ``./config.ini`` if skipped. -- work-dir: path to the working directory where all artifacts need to be dumped. Defaults to - ``./riscof_work`` -- no-browser: when used, RISCOF skips automatically opening the html report in the default web +- ``--config``: The path to the ``config.ini`` file. Defaults to ``./config.ini`` if skipped. +- ``--work-dir``: The path to the working directory where all artifacts need to be dumped. Defaults to + ``./riscof_work``. +- ``--no-browser``: When used, RISCOF skips automatically opening the html report in the default web browser. The coverage command simply passes the cgf files to the reference plugin's runTests function. The @@ -72,15 +71,15 @@ gendb This command is used to generate a database YAML file for all tests available in the test-suite. The commands requires the following inputs from the CLI: -- suite: The test suite path for which database needs to be generated. -- work-dir: path to the working directory where all artifacts need to be dumped. Defaults to - ``./riscof_work`` +- ``--suite``: The test suite path for which database needs to be generated. +- ``--work-dir``: The path to the working directory where all artifacts need to be dumped. Defaults to + ``./riscof_work``. This utility parses the ``suite`` directory and collects all the .S files. For each .S file, the utility will parse the test and collect informations from various macros such as RVTEST_ISA, RVTEST_CASE, etc. For each test the utility will create a new entry in a dictionary which captures the different parts of the tests, the enabling conditions of each part, the coverage contributions -of each part, any compile macros required for each part and muc more. +of each part, any compile macros required for each part and much more. The generated database YAML will follow the syntax described in section :ref:`database`. @@ -100,10 +99,10 @@ and should be modified by the users. The setup utility takes in the following optional inputs from the CLI: -- dutname: name of the dut for running the tests on. The utility will use this name to create a +- ``--dutname``: The name of the dut for running the tests on. The utility will use this name to create a template plugin directory with all the relevant files. These files will have to be modified by - the user. Defaults to "spike" when skipped. -- refname: name of the reference plugin to be used in RISCOF. The utility will use this name to + the user. Defaults to ``spike`` when skipped. +- ``--refname``: The name of the reference plugin to be used in RISCOF. The utility will use this name to create a reference plugin directory with all the relevant files. @@ -113,8 +112,8 @@ validateyaml ------------ This command simply performs a validation of the ISA spec and the platform pspec YAMLs of the DUT -as mentioned in the ``config.ini`` using riscv-config. The outputs are checked version of the YAMLs in -the directory pointed by ``work_dir`` +as mentioned in the ``config.ini`` using riscv-config. The outputs are checked for the version of the YAMLs in +the directory pointed to by ``work_dir``. testlist -------- @@ -123,13 +122,13 @@ This command is used to filter tests from the database.yaml based on the configu present in the ISA and platform YAMLs as mentioned in the ``config.ini``. This command will require the following inputs from the CLI: -- suite: The test suite from which the test need to filtered. +- ``--suite``: The test suite from which the tests need to be filtered. This command takes the following optional inputs from CLI -- config: path to the ``config.ini`` file. Defaults to ``./config.ini`` if skipped. -- work-dir: path to the working directory where all artifacts need to be dumped. Defaults to - ``./riscof_work`` +- ``--config``: The path to the ``config.ini`` file. Defaults to ``./config.ini`` if skipped. +- ``--work-dir``: The path to the working directory where all artifacts need to be dumped. Defaults to + ``./riscof_work``. The utility first creates a ``database.yaml`` for the input suite. For each test in the database YAML, this utility will check if the conditions of any parts of a test are enabled based on the ISA and @@ -150,36 +149,35 @@ generated signatures and present an html report of the findings. The following inputs are required on the CLI by this command: -- suite: The test suite path on which coverage needs to be run -- env: The path to the environment directory containing the suite-specific header files. +- ``--suite``: The test suite path on which coverage needs to be run +- ``--env``: The path to the environment directory containing the suite-specific header files. Optional arguments from the CLI: -- config: path to the ``config.ini`` file. Defaults to ``./config.ini`` if skipped. -- work-dir: path to the working directory where all artifacts need to be dumped. Defaults to - ``./riscof_work`` -- no-browser: when used, RISCOF skips automatically opening the html report in the default web - browser. -- dbfile: The path to the database file, from which testlist will be generated -- testfile: The path to the testlist file on which tests will be run -- no-ref-run: when used, RISCOF will not run tests on Reference and will quit before signatures comparison -- no-dut-run: when used, RISCOF will not run tests on DUT and will quit before signatures comparison -- no-clean: when used, RISCOF will not remove the ``work_dir``, if it exists. +- ``--config``: The path to the ``config.ini`` file. Defaults to ``./config.ini`` if skipped. +- ``--work-dir``: The path to the working directory where all artifacts need to be dumped. Defaults to + ``./riscof_work``. +- ``--no-browser``: When used, RISCOF skips automatically opening the html report in the default web browser. +- ``--dbfile``: The path to the database file, from which testlist will be generated. +- ``--testfile``: The path to the testlist file on which tests will be run. +- ``--no-ref-run``: When used, RISCOF will not run tests on Reference and will quit before signatures comparison. +- ``--no-dut-run``: When used, RISCOF will not run tests on DUT and will quit before signatures comparison. +- ``--no-clean``: When used, RISCOF will not remove the ``work_dir``, if it exists. The ``work_dir`` is cleaned by default. However, if one of ``no-clean``, ``testfile`` or ``dbfile`` are specified, it is preserved as is. -All artifacts of this command are generated in the ``work_dir`` directory. Typicall artifacts will +All artifacts of this command are generated in the ``work_dir`` directory. Typical artifacts will include: -==================== ============================================================= -Artifact Description -==================== ============================================================= -database.yaml This is the database of all the tests in the suite directory -Makefile.DUT* This is the Makefile generated by the DUT Plugin. -Makefile.Reference* This is the Makefile generated by the Reference Plugin. -report.html The final report generated at the end of the run after signature comparison -yaml files verified and checked YAML versions of the input ISA and platform YAMLs -test_list.yaml This list of filtered tests from the database.yaml -src directory this will include a directory for each test in the test_list.yaml. Each test-directory will include the test, compiled-binaries, signatures from both the DUT and the Reference Plugin. +======================== ============================================================= +Artifact Description +======================== ============================================================= +``database.yaml`` This is the database of all the tests in the suite directory. +``Makefile.DUT*`` This is the Makefile generated by the DUT Plugin. +``Makefile.Reference*`` This is the Makefile generated by the Reference Plugin. +``report.html`` The final report generated at the end of the run after signature comparison. +yaml files Verified and checked YAML versions of the input ISA and platform YAMLs. +``test_list.yaml`` This list of filtered tests from the ``database.yaml``. +src directory This will include a directory for each test in the ``test_list.yaml``. Each test-directory will include the test, compiled-binaries, signatures from both the DUT and the Reference Plugin. ==================== =============================================================