Update README.md to latest feature set

2024-12-22 06:58:41 +00:00 · 2021-10-20 22:25:07 -07:00 · 2021-10-20 22:25:07 -07:00 · 2da71dabf1
commit 2da71dabf1
parent 1b011ff593
2 changed files with 104 additions and 59 deletions
--- a/README.md
+++ b/README.md
@ -1,8 +1,21 @@
 ![srdl2sv logo](images/srdl2sv_logo.gif)
+# Table of Contents
+1. [Introduction](#introduction)
+    1. [Non-production ready](#non-production-ready)
+2. [Getting started](#getting-started)
+    1. [Installation](#installation)
+    2. [Compiling your first RDL](#compiling-your-first-rdl)
+    3. [Using the generated RTL](#using-the-generated-rtl)
+3. [Supported bus protocols](#supported-bus-protocols)
+4. [Help function](#help-functions)
+5. [Contributing](#contributing)
+6. [License](#license)
+7. [Limitations](#limitations)
+
 # Introduction 
 srdl2sv is a [SystemRDL 2.0](https://www.accellera.org/images/downloads/standards/systemrdl/SystemRDL_2.0_Jan2018.pdf) to (synthesizable) [SystemVerilog](https://ieeexplore.ieee.org/document/8299595/versions) compiler. The tool is based on based on [SystemRDL/systemrdl-compiler](https://github.com/SystemRDL/systemrdl-compiler). 
-## ⚠️ Non-production ready
-Warning! This software is still under development and not yet ready for use in production. 
+## Non-production ready
+⚠️ Warning ⚠️ This software is still under development and not yet ready for use in production. 
 # Getting started
 ## Installation
 ## Compiling your first RDL
@ -30,14 +43,33 @@ If the RDL file includes other RDL files, the directories that contain these fil
 srdl2sv example_addrmap.rdl
    --search_paths SEARCH_PATHS [SEARCH_PATHS ...]
 ```
+By default, the compiler will generate SystemVerilog enumerations if SystemRDL enums are used. These enums are dumped in a seperate package to be included outside of the register module. To turn off this feature, use the flag `--disable_enums`:
+```
+srdl2sv example_addrmap.rdl
+    --disable_enums
+```
+By default, the registers in the RTL are byte-addressable. If this is not required it is recommened to turn off byte-addressing by using the flag `--no_byte_enable` to achieve more efficient results in synthesis:
+```
+srdl2sv example_addrmap.rdl
+    --no_byte_enable
+```
 ## Using the generated RTL

-## Help function
+# Supported bus protocols
+The following bus protocols are supported:
+- AMBA 3 AHB-Lite Protocol (default)
+
+The following bus protocols are planned at this point:
+- AMBA 3 APB Protocol
+
+# Help function
 A comprehensive help function of the tool can be invoked by running `srdl2sv --help`.
 ```
-usage: main.py [-h] [-b {amba3ahblite}] [-o OUT_DIR] [-d SEARCH_PATHS [SEARCH_PATHS ...]] [-r] [-x]
-               [-e] [--stream_log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL,NONE}]
-               [--file_log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL,NONE}] [--real_tabs]
+usage: main.py [-h] [-b {amba3ahblite}] [-c DESCRIPTIONS]
+               [-d SEARCH_PATHS [SEARCH_PATHS ...]] [-e]
+               [--file_log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL,NONE}]
+               [--stream_log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL,NONE}]
+               [--no_byte_enable] [-o OUT_DIR] [-r] [--real_tabs]
               [--tab_width TAB_WIDTH]
               IN_RDL [IN_RDL ...]

@ -49,29 +81,42 @@ positional arguments:
 optional arguments:
  -h, --help            show this help message and exit
  -b {amba3ahblite}, --bus {amba3ahblite}
-                        Set the bus protocol that shall be used by software to ', communicate with the
-                        registers. (default: amba3ahblite)
-  -o OUT_DIR, --out_dir OUT_DIR
-                        Define output directory to dump files. If directory is non-existent, it will
-                        be created. (default: ./srdl2sv_out)
+                        Set the bus protocol that shall be used by software to
+                        ', communicate with the registers. (default:
+                        amba3ahblite)
+  -c DESCRIPTIONS, --descriptions DESCRIPTIONS
+                        Include descriptions of addrmaps (+16), regfiles (+8),
+                        memories (+4) registers (+2), and fields (+1) in RTL.
+                        This is a bitfield.
  -d SEARCH_PATHS [SEARCH_PATHS ...], --search_paths SEARCH_PATHS [SEARCH_PATHS ...]
-                        Point to one (or more) directories that will be searched for RDL files.
-  -r, --recursive_search
-                        If set, the dependency directories will be searched recursively.
-  -x, --disable_sanity  Disable sanity checks or components. This might speed up the compiler but is
-                        generally not recommended!
-  -e, --disable_enums   Disable enumeration generation. This will prevent the compiler from generating
-                        packages and it will prevent it from using enums in the port list.
-  --stream_log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL,NONE}
-                        Set verbosity level of output to shell. When set to 'NONE', nothing will be
-                        printed to the shell. (default: WARNING)
+                        Point to one (or more) directories that will be
+                        searched for RDL files.
+  -e, --disable_enums   Disable enumeration generation. This will prevent the
+                        compiler from generating packages and it will prevent
+                        it from using enums in the port list.
  --file_log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL,NONE}
-                        Set verbosity level of output to log-file. When set to 'NONE', nothing will be
-                        printed to the shell. (default: INFO)
+                        Set verbosity level of output to log-file. When set to
+                        'NONE', nothing will be printed to the shell.
+                        (default: INFO)
+  --stream_log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL,NONE}
+                        Set verbosity level of output to shell. When set to
+                        'NONE', nothing will be printed to the shell.
+                        (default: WARNING)
+  --no_byte_enable      If this flag gets set, byte-enables get disabled. At
+                        that point, it is only possible to address whole
+                        registers, not single bytes within these registers
+                        anymore.
+  -o OUT_DIR, --out_dir OUT_DIR
+                        Define output directory to dump files. If directory is
+                        non-existent, it will be created. (default:
+                        ./srdl2sv_out)
+  -r, --recursive_search
+                        If set, the dependency directories will be searched
+                        recursively.
  --real_tabs           Use tabs, rather than spaces, for tabs
  --tab_width TAB_WIDTH
-                        Define how many tabs or spaces will be contained in one level of indentation.
-                        (default: 4)
+                        Define how many tabs or spaces will be contained in
+                        one level of indentation. (default: 4)
 ```
 # Contributing
 # License
--- a/srdl2sv/cli/cli.py
+++ b/srdl2sv/cli/cli.py
@ -28,13 +28,12 @@ class CliArguments():
                  communicate with the registers. (default: %(default)s)")

        self.parser.add_argument(
-            "-o",
-            "--out_dir",
-            type=str,
-            default="./srdl2sv_out",
-            help="Define output directory to dump files.\
-                  If directory is non-existent, it will be created.\
-                  (default: %(default)s)")
+            "-c",
+            "--descriptions",
+            type=int,
+            default=0,
+            help="Include descriptions of addrmaps (+16), regfiles (+8), memories (+4) \
+                  registers (+2), and fields (+1) in RTL. This is a bitfield.")

        self.parser.add_argument(
            "-d",
@ -44,13 +43,6 @@ class CliArguments():
            help="Point to one (or more) directories that will\
                  be searched for RDL files.")

-        self.parser.add_argument(
-            "-r",
-            "--recursive_search",
-            action="store_true",
-            help="If set, the dependency directories will be\
-                  searched recursively.")
-
        self.parser.add_argument(
            "-e",
            "--disable_enums",
@ -59,6 +51,13 @@ class CliArguments():
                  compiler from generating packages and it will prevent\
                  it from using enums in the port list.")

+        self.parser.add_argument(
+            "--file_log_level",
+            choices=['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL', 'NONE'],
+            default='INFO',
+            help="Set verbosity level of output to log-file. When set to 'NONE',\
+                  nothing will be printed to the shell. (default: %(default)s)")
+
        self.parser.add_argument(
            "--stream_log_level",
            choices=['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL', 'NONE'],
@ -67,11 +66,27 @@ class CliArguments():
                  nothing will be printed to the shell. (default: %(default)s)")

        self.parser.add_argument(
-            "--file_log_level",
-            choices=['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL', 'NONE'],
-            default='INFO',
-            help="Set verbosity level of output to log-file. When set to 'NONE',\
-                  nothing will be printed to the shell. (default: %(default)s)")
+            "--no_byte_enable",
+            action="store_true",
+            help="If this flag gets set, byte-enables get disabled. At that point, it \
+                  is only possible to address whole registers, not single bytes within \
+                  these registers anymore.")
+
+        self.parser.add_argument(
+            "-o",
+            "--out_dir",
+            type=str,
+            default="./srdl2sv_out",
+            help="Define output directory to dump files.\
+                  If directory is non-existent, it will be created.\
+                  (default: %(default)s)")
+
+        self.parser.add_argument(
+            "-r",
+            "--recursive_search",
+            action="store_true",
+            help="If set, the dependency directories will be\
+                  searched recursively.")

        self.parser.add_argument(
            "--real_tabs",
@ -85,21 +100,6 @@ class CliArguments():
            help="Define how many tabs or spaces will be contained\
                  in one level of indentation. (default: %(default)s)")

-        self.parser.add_argument(
-            "-c",
-            "--descriptions",
-            type=int,
-            default=0,
-            help="Include descriptions of addrmaps (+16), regfiles (+8), memories (+4) \
-                  registers (+2), and fields (+1) in RTL. This is a bitfield.")
-
-        self.parser.add_argument(
-            "--no_byte_enable",
-            action="store_true",
-            help="If this flag gets set, byte-enables get disabled. At that point, it \
-                  is only possible to address whole registers, not single bytes within \
-                  these registers anymore.")
-
        self.parser.add_argument(
            "IN_RDL",
            type=str,