Csr schema update (#17)

* Misa skeleton done.

* Done mtvec,mideleg,medeleg,id csrs,mstatus.

* fixed alignment and trailing whitespaces

* Machine csrs almost done.

* changing exists to implemented

* removing reset-values from sub-fields

* Added defaults and minimized required fields in yaml.

* adding isa specific checks

* adding max length check for reset-values

* adding misa to default setter

* misa checks done.

* missed adding updated schema for misa-checks

* Trimming function done.

* Fixed bug in trimming function.

* few checks for readonly machine csrs.

* example to show trimming doesn't work

* Fixed trimming function.

* RO reset value check added.

* fixed misa reset-val check when misa is not defined by user.

* defined types for mtvec fields

* specific check for mtvec

* removing trailing spaces

* adding reset value checks for mtvec

* Create csr_template_draft1.yaml

* adding support for delegation registers

* rv32i

* Changes done

* Changes done

* changes done

* Seperate warl class added

* Update modes done

* support for bitmask done

* support for bitmask done

* changes done

* Changes done

* Changes done

* Changes done

* changes done

* Changes done

* Changes finalized

* Minor bug fixes for erratic check functions.

* Function for reset value checking done.

* Example update.

* updated docs

* adding platform yaml docs

* updated schemavalidator for ISA checks

Close #10
Close #11
Close #12
Close #13

* renaming mcause

* adding changelog and removed obsolete files

* Added counter registers.

* Removed redundant functions and obsolete code.

* Example update.

* Formatting for wpri fields.

* Yapf formatting for files.

* Dependency fix.

Co-authored-by: dracarys99 <[email protected]>
Co-authored-by: lavanyajagan <[email protected]>
Co-authored-by: Sujeet <[email protected]>

Author: 4 people

.gitignore

@@ -1,9 +1,11 @@
 docs/build
+docs/source/schema_isa.rst
+docs/source/schema_platform.rst
 
 run.log
 
 __pycache__/*
 
 *.pyc
 
-riscv_config_work/*
+riscv_config_work/*

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.0.0 - 2020-03-25
+### Added
+- adding support for warl fields and support
+- documentation for the warl fields added
+- reset-value checks added
+### Changed
+- using a new common template for defining all csrs
+- updated docs with new template
+- using special function within conf.py to extract comments from yaml file as docs.
+### Fixed
+- closed issues #10, #11, #12, #13
+
 ## 1.0.2 - 2019-08-09
 ### Changed
 - Log is generated only if specified(for API calls to checker.check_specs).

docs/source/conf.py

@@ -14,6 +14,21 @@
 #
 import os
 import sys
+import re
+
+def gen_schema_doc(infile, outfile):
+    text = open(infile,'r').read()
+    rst_file = open(outfile,'w')
+    x = re.findall("^###(?:(?:\r\n|[\r\n]).+$)*",text,re.M|re.U)
+    for y in x:
+        y = y.replace('#','')
+        y = y.lstrip(' ')
+        rst_file.write(y+'\n')
+    
+    rst_file.close()
+
+gen_schema_doc('../../riscv_config/schemas/schema_isa.yaml', 'schema_isa.rst')
+gen_schema_doc('../../riscv_config/schemas/schema_platform.yaml', 'schema_platform.rst')
 
 sys.path.insert(0, os.path.abspath('../..'))
 sys.setrecursionlimit(1500)

docs/source/overview.rst

@@ -13,8 +13,8 @@ The user is required to provide 2 YAML files as input:
 1. **ISA Spec**: This YAML file is meant to capture the ISA related features implemented by the user. Details of this input file can be found here : :ref:`isa_yaml_spec`. 
 2. **Platform Spec**: This YAML file is meant to capture the platform specific features implemented by the user. Details of this input file can be found here : :ref:`platform_yaml_spec`.
 
-Working:
---------
+Working
+=======
 
 The ISA and Platform spec are first checked by the validator for any inconsistencies. Checks like 'F' to exist for 'D' are performed by the validator. The validator exits with an error if any illegal configuration for the spec is provided. Once the validator checks pass, two separate standard yaml files are generated, one for each input type. These standard yaml files contain all fields elaborated and additional info for each node. While the user need not specify all the fields in the input yaml files, the validator will assign defaults to those fields and generate a standard exhaustive yaml for both ISA and Platform spec.
 

docs/source/quickstart.rst

@@ -2,103 +2,134 @@
 Quickstart
 ##########
 
-Installation and Setup
-^^^^^^^^^^^^^^^^^^^^^^^
-1. Install riscv_config
+This doc is meant to serve as a quick-guide to setup RISCOF and perform a sample compliance check
+between ``spike`` (DUT in this case) and ``riscvOVPsim`` (Golden model in this case).
 
-    Before proceding further please ensure *pip* and *python (>3.7.0)* is installed and configured.
+Install Python Dependencies
+===========================
 
-    In case you have issues installing python-3.7, we recommend using `pyenv`. 
-    
-    Installing instructions for pyenv:
+RISCOF requires `pip` and `python` (>=3.7) to be available on your system. If you have issues, instead of
+installing either of these directly on your system, we suggest using a virtual environment
+like `pyenv` to make things easy.
+
+Installing Pyenv [optional]
+---------------------------
+
+If you are working on Ubuntu/Debian systems make sure you have the following libraries installed:
+
+.. code-block:: bash
 
-    .. code-block:: bash
+  $ sudo apt-get install -y make build-essential libssl-dev zlib1g-dev libbz2-dev \
+      libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
+      xz-utils tk-dev libffi-dev liblzma-dev python-openssl git
 
-        #!/bin/sh
-        curl -L https://raw.githubusercontent.com/yyuu/pyenv-installer/master/bin/pyenv-installer | bash
-        echo "export PATH=\"/home/$USER/.pyenv/bin:$PATH\"" >> ~/.bashrc
-        pyenv install 3.7.0
-        pyenv global 3.7.0
-        pip install --upgrade pip
-        
-    You can simply use pip and python for 3.7 by default.
+Download and install pyenv:
 
-    *Support exists for python versions > 3.7.0 only. Please ensure correct version before proceding further.*
+.. code-block:: bash
 
-    * Install using pip(For users):
+  $ curl -L https://raw.githubusercontent.com/yyuu/pyenv-installer/master/bin/pyenv-installer | bash
 
-    .. code-block:: bash
+Add the following lines to your .bashrc:
 
-        pip3 install riscv_config
+.. code-block:: bash
 
+  $ export PATH="/home/<username>/.pyenv/bin:$PATH"
+  $ eval "$(pyenv init -)"
+  $ eval "$(pyenv virtualenv-init -)"
 
-    * Clone from git(For developers):
+Open a new terminal and create a virtual environment using the following
 
-    .. code-block:: bash
+.. code-block:: bash
 
-        git clone https://github.com/riscv/riscv-config.git
-        cd riscv_config
-        pip3 install -r requirements.txt
+  $ pyenv install 3.7.0
+  $ pyenv virtualenv 3.7.0 riscof_env
 
-Usage
-^^^^^
 
-* For users
+Now you can activate this virtual environment using the following command:
 
 .. code-block:: bash
 
-    riscv-config [-h] --isa_spec YAML --platform_spec YAML [--verbose]
+  $ pyenv activate riscof_env
+  $ python ==version
 
-    RISC-V Configuration Validator 
-    
-    optional arguments:
-      --isa_spec YAML, -ispec YAML
-                            The YAML which contains the ISA specs.
-      --platform_spec YAML, -pspec YAML
-                            The YAML which contains the Platfrorm specs.
-      --verbose             debug | info | warning | error
-      -h, --help            show this help message and exit
+Install via PIP [users]
+=======================
+
+**NOTE**: If you are using `pyenv` as mentioned above, make sure to enable that environment before
+performing the following steps.
 
+.. code-block:: bash
 
+  $ pip install riscv_config
 
-* For developers
+To update an already installed version of RISCOF to the latest version:
 
 .. code-block:: bash
 
-    cd riscv_config/
+  $ pip install -U riscv_config
 
-    python3 -m riscv_config.main -h
-    usage: [-h] --isa_spec YAML --platform_spec YAML [--verbose]
+To checkout a specific version of riscof:
 
-    RISC-V Configuration Validator 
+.. code-block:: bash
+
+  $ pip install riscv_config==1.x.x
+
+Once you have RISCV_CONFIG installed, executing ``riscv_config ==help`` should print the following on the terminal:
+
+.. code-block:: bash
+
+    riscv-config [-h] ==isa_spec YAML ==platform_spec YAML [==verbose]
 
+    RISC-V Configuration Validator 
+    
     optional arguments:
-      --isa_spec YAML, -ispec YAML
+      ==isa_spec YAML, -ispec YAML
                             The YAML which contains the ISA specs.
-      --platform_spec YAML, -pspec YAML
+      ==platform_spec YAML, -pspec YAML
                             The YAML which contains the Platfrorm specs.
-      --verbose             debug | info | warning | error
-      -h, --help            show this help message and exit
+      ==verbose             debug | info | warning | error
+      -h, ==help            show this help message and exit
 
 
 
-Example
-^^^^^^^
+RISCV_CONFIG for Developers
+===========================
 
-    * For users
+Clone the repository from git and install required dependencies. Note, you will still need
+python-3.7.0 and pip. If you are using `pyenv` as mentioned above, make sure to enable that environment before
+performing the following steps.
 
-    .. code-block:: bash
+.. code-block:: bash
 
-        git clone https://github.com/riscv/riscv-config.git
+  $ git clone https://github.com/riscv/riscv-config.git
+  $ cd riscv_config
+  $ pip3 install -r requirements.txt
 
-        cd riscv_config/
+Executing ``python -m riscv_config.main ==help`` should display the same help message as above.
 
-        riscv-config -ispec ./examples/template_isa.yaml -pspec ./examples/template_platform.yaml
+Usage Example
+=============
 
-    * For developers
-    
-    .. code-block:: bash
+.. code-block:: bash
+
+    $ riscv_config -ispec examples/rv32i_isa.yaml -pspec examples/rv32i_platform.yaml
+
+Executing the above command should display the following on the terminal:
+
+.. code-block:: bash
 
-        cd riscv_config/
+  [INFO]    : Input-ISA file
+  [INFO]    : Loading input file: /scratch/git-repo/github/riscv-config/examples/rv32i_isa.yaml
+  [INFO]    : Load Schema /scratch/git-repo/github/riscv-config/riscv_config/schemas/schema_isa.yaml
+  [INFO]    : Initiating Validation
+  [INFO]    : No Syntax errors in Input ISA Yaml. :)
+  [INFO]    : Initiating post processing and reset value checks.
+  [INFO]    : Dumping out Normalized Checked YAML: /scratch/git-repo/github/riscv-config/riscv_config_work/rv32i_isa_checked.yaml
+  [INFO]    : Input-Platform file
+  [INFO]    : Loading input file: /scratch/git-repo/github/riscv-config/examples/rv32i_platform.yaml
+  [INFO]    : Load Schema /scratch/git-repo/github/riscv-config/riscv_config/schemas/schema_platform.yaml
+  [INFO]    : Initiating Validation
+  [INFO]    : No Syntax errors in Input Platform Yaml. :)
+  [INFO]    : Dumping out Normalized Checked YAML: /scratch/git-repo/github/riscv-config/riscv_config_work/rv32i_platform_checked.yaml
+  
 
-        python3 -m riscv_config.main -ispec ./examples/template_isa.yaml -pspec ./examples/template_platform.yaml