Skip to content

Commit

Permalink
DOCS: updated commands section, few grammar and spelling mistakes, us…
Browse files Browse the repository at this point in the history
…ing fixed width fornt for CLI options, use '--' prefix for options, clean up of sentance capitalization and punctuation.
  • Loading branch information
jeras committed Jul 22, 2022
1 parent ef0c00f commit fae996b
Showing 1 changed file with 54 additions and 56 deletions.
110 changes: 54 additions & 56 deletions docs/source/commands.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,29 +8,29 @@ 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
----------
This command is used to clone and update the tests from the official `riscv-arch-test <https://github.com/riscv/riscv-arch-test>`_ repository.

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
Expand All @@ -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
Expand All @@ -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`.

Expand All @@ -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.


Expand All @@ -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
--------
Expand All @@ -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
Expand All @@ -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.
==================== =============================================================

0 comments on commit fae996b

Please sign in to comment.