Command-Line Interface (CLI) Reference

Relevant source files

The following files were used as context for generating this wiki page:

• regif.py
• readme.md
• setup.py
• .github/workflows/python-publish.yml
• LICENSE

The regif tool provides a command-line interface for automatically generating register interface RTL (Verilog) and documentation from a structured Excel file. The CLI is the primary user entry point for interacting with the generator, allowing for both the creation of template register definition files and the generation of output artifacts from a completed definition.

The tool is implemented in Python and utilizes the argparse module to handle command-line arguments. It is distributed as a package and can be installed via pip, making it accessible as a system command.

Sources: regif.py:1450-1453, readme.md:1-25, setup.py:10

Installation and Usage

The regif tool can be installed using pip. Once installed, it can be invoked directly from the command line.

Installation

pip install regif

Sources: readme.md:27-28, setup.py:10, 23-26

Usage
The CLI has two primary modes of operation: initializing a new template file and generating code from an existing file.

# 1. Initialize a new template
regif --init mymodule

# 2. Generate Verilog and DOCX from the completed template
regif mymodule_regif.xls

Sources: readme.md:32-36, regif.py:1469-1488

Commands and Arguments

The CLI behavior is controlled by the arguments provided at runtime. The arguments are defined using Python's argparse library.

Argument	Type	Description
excel	Positional	The path to the input _regif.xls file to be parsed for code generation.
--init	Optional	Creates a template Excel file named <name>_regif.xls in the current directory.

Sources: regif.py:1450-1455

The following diagram illustrates the argument parsing logic.

This diagram shows how the regif command branches based on the provided arguments.
Sources: regif.py:1469-1488

Execution Flow

The main execution logic is contained within the if __name__ == "__main__": block of regif.py. It first parses the arguments and then proceeds down one of two main paths.

Sources: regif.py:1467-1488

Path 1: Template Initialization

If the --init <name> argument is used, the copyTemplate function is called. This function locates the regif_template.xls file packaged with the tool and copies it to the current working directory with the specified name (<name>_regif.xls). The program then exits.

# regif.py:1458-1466
def copyTemplate(name):
    regif = os.path.abspath(__file__)
    binpath = os.path.dirname(regif)
    template = os.path.join(binpath, "../regif/regif_template.xls")
    dest = "%s_regif.xls" % name
    if os.path.exists(dest):
        print("\n%s already exists !!!\n" % dest)
        exit(0)
    os.system("cp %s %s" % (template, dest))
    print("\nRegIf excel template %s created\n" % dest)

Sources: regif.py:1458-1466, 1471-1472

Path 2: Code and Document Generation

If a positional argument (the Excel file path) is provided, the script initiates the generation process.

The following sequence diagram shows the high-level flow for code generation.

This diagram outlines the sequence of operations from command execution to the generation of output files.
Sources: regif.py:1473-1487

The key steps are:

1. File Validation: The script checks if the provided Excel file path exists.
2. Excel Parsing: It uses the xlrd library to open and read the first sheet of the workbook.
3. Regif Instantiation: An instance of the Regif class is created. During initialization, it performs critical validation:
   • Static Check: Verifies the format of register and field definitions against predefined regex patterns.
   • Dynamic Check: Verifies logical consistency, such as bitfield continuity and protection logic correctness.
     If any checks fail, the program prints detailed error messages and exits.
4. Verilog Generation: The regif.genverilog() method is called to generate the _regif.v and, if applicable, _regif_wrap.v files.
5. Documentation Generation: The gen_regif_doc() function is called to create the _Register_Manual.docx file.

Sources: regif.py:1181-1221, 1473-1487

Dependencies

The CLI tool and its underlying functions rely on external Python libraries. These are specified in setup.py and checked at runtime.

Library	Version	Purpose
xlrd	>=1.1.0	To read data from the input .xls Excel file.
python_docx	>=1.11.3	To generate the .docx register manual.

A check is performed at the start of regif.py to ensure these libraries are installed.

# regif.py:21-33
def checklib():
    info = ""
    try:
        import xlrd
    except ImportError as e:
        info += str(e) + ", 'pip install xlrd' first!! \n"
    try:
        from docx import Document
    except ImportError as e:
        info += str(e) + ", 'pip install python_docx' first!! \n"
    if(info):
        info = "Error: \n" + info 
        print(info)
        exit(0)

Sources: regif.py:21-33, setup.py:23-26

Summary

The regif command-line interface serves as a simple yet powerful entry point for the entire register generation workflow. It abstracts the complexity of parsing, validation, and code generation into two straightforward commands. By handling both template creation and artifact generation, the CLI provides a complete, user-friendly solution for automating the creation of register interfaces from a single source of truth in an Excel spreadsheet.

Sources: readme.md:1-25, regif.py:1450-1488