Generated Output: Word Document (.docx)

Relevant source files

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

• regif.py
• readme.md
• setup.py
• regif/regif_template.xls
• regif/init.py

The regif tool automatically generates a human-readable register specification document in .docx format, titled [modulename]_Register_Manual.docx. This document serves as a reference manual, detailing the memory map, register offsets, field descriptions, and reset values. The generation process leverages the same parsed Excel data used for creating the Verilog RTL, ensuring consistency between the hardware implementation and the documentation.

This feature relies on the python-docx library, which is a required dependency for the tool. The generation is triggered as the final step in the main execution flow, after the Verilog files have been created.

Sources: regif.py:11, 1420-1422, 1475-1477, readme.md:19, 32, setup.py:24

Document Generation Flow

The .docx generation is initiated by the gen_regif_doc function. This function orchestrates the creation of the document, from initializing the Document object to structuring the content and saving the final file.

The diagram below illustrates the high-level process flow for generating the register manual.

This flowchart shows the sequence from script invocation to the final .docx file being saved.

Sources: regif.py:1463-1477

Core Components

The document generation is handled by a set of dedicated functions located at the end of regif.py.

Sources: regif.py:1420-1459

Dependency Check

Before any processing, the script ensures that the necessary libraries are installed. The checklib function verifies the presence of xlrd and python-docx. If python-docx is missing, an error message is printed, and the script exits. The dependency is formally declared in setup.py.

# regif.py:27-32
    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)

# setup.py:24-25
      install_requires=[
          "xlrd>=1.1.0",
          "python_docx>=1.11.3",
          ]

Sources: regif.py:27-32, setup.py:24-25

Main Function: gen_regif_doc

This is the primary function that controls the document creation process. It takes the module name and the extracted register data (regs) as input.

1. Initializes a new Document object.
2. Adds the main title "Register Interface".
3. Calls creat_regs_detail to populate the document with register information.
4. Saves the document with the name [modulename]_Register_Manual.docx.

# regif.py:1453-1459
def gen_regif_doc(name, regs):
    document = Document()
    document.add_heading(u'Register Interface', 1)
    # craet_addrs_map(regs)
    creat_regs_detail(document, regs)
    document.save(u"{}_Register_Manual.docx".format(name))

Sources: regif.py:1453-1459

Detail Creation: creat_regs_detail

This function iterates through each register definition provided in the regs list. For each register, it:

1. Sets the default font to '宋体' (SimSun) for East Asian character support.
2. Adds a Level 2 heading with the register name and its address (e.g., REG_NAME (0x0004)).
3. Adds paragraphs for the offset address and the register's description.
4. Calls creat_reg_table to generate a new table for the register's fields.
5. Calls fill_reg_fields to populate the newly created table.

Sources: regif.py:1444-1451

Table Structure: creat_reg_table

This function is responsible for creating the table that holds the details of a register's fields. It defines the structure, style, and column headers.

• Style: Uses the "Table Grid" style.
• Font Size: Sets the font size to 10.5pt.
• Columns: Defines 5 columns with specific relative widths.

The table columns are defined as follows:

Header	Description
位数 (Bits)	The bit-range of the field (e.g., [7:0]).
名称 (Name)	The name of the field.
方向 (Direction)	The access type (e.g., RW, RO, WO).
复位值 (Reset Value)	The default value of the field after reset.
描述 (Description)	A description of the field's functionality.

Sources: regif.py:1424-1441

Table Population: fill_reg_fields

This function populates the rows of a given table with the data for each field within a register. It iterates through the fields list, adding a new row for each field and filling the cells with the corresponding data: bit section, name, type, reset value, and description. For fields named "RESERVED", the direction and reset value are marked as "N/A".

# regif.py:1444-1451
def fill_reg_fields(table, fields):
    for field in fields:
        row_cells = table.add_row().cells
        reserved = True if field[1] == "RESERVED" else False
        row_cells[0].text = force2str(field[0])[1:-1]
        row_cells[1].text = force2str(field[1])
        row_cells[2].text = "N/A" if reserved else force2str(field[2])
        row_cells[3].text = "N/A" if reserved else force2str(field[3])
        row_cells[4].text = force2str(field[6])

The data for these fields is originally parsed from the input Excel file, which follows the structure laid out in the template.

Sources: regif.py:1444-1451, regif/regif_template.xls

Execution Context

The .docx generation is the final step of the regif script when a source Excel file is provided.

The following sequence diagram shows the interaction between the main script execution, the Regif class instance, and the document generation functions.

This diagram clarifies that document generation happens sequentially after Verilog generation, using the same configuration data.

Sources: regif.py:1463-1477