From 2da71dabf1a4d4dde615625b93c8d83636e5d485 Mon Sep 17 00:00:00 2001 From: Dennis Date: Wed, 20 Oct 2021 22:25:07 -0700 Subject: [PATCH] Update README.md to latest feature set --- README.md | 95 ++++++++++++++++++++++++++++++++++------------ srdl2sv/cli/cli.py | 68 ++++++++++++++++----------------- 2 files changed, 104 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index ecbb22e..194027e 100644 --- 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 diff --git a/srdl2sv/cli/cli.py b/srdl2sv/cli/cli.py index 3a5e0c6..1567caf 100644 --- 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,