Discussion on Register Design Tools

Excerpt from pages 96-100 of the book, Hardware/Firmware Interface Design: Best Practices for Improving Embedded Systems Development.

5.5.2. Register Design Tools

A problem with documentation is its susceptibility to being inaccurate and out-of-date with the actual block. Registers and bits are modified in hardware but the documents are not updated. Documents are updated but firmware is not changed. Or typos are introduced along the way. Failure to catch these problems typically results in hours wasted on debugging that could and should have been avoided.

Design teams have attempted to solve this problem by using scripts to extract register information from hardware Verilog and VHDL files and converting them into firmware C header files. Others have extracted data from FrameMaker, XML, and CSV files and generated C and Verilog/VHDL files from those. These home-grown tools are limited in the information that they extract, they do not produce documentation, and they create a tool maintenance burden on the design team.

A few companies (see reviews and comparisons) have produced tools to address that issue. This is a new niche market and there is no consensus on the name of that market or its tools. But I will use the name, “register design tools.”

The key feature of these register design tools is the ability to keep pertinent hardware, firmware, testing, and documentation files in sync. They can also generate system modeling files.

Register and bit specifications, including addresses and descriptions, are written in a strict format using an editor or a GUI front end. The register design tools then process the input files to generate a variety of hardware, firmware, verification, modeling, and documentation files. The generated hardware files are synthesized with other hardware design files and the generated firmware files are compiled with other firmware files. The documentation files are made available to technical publications and appropriate development engineers. The diagram in Figure 5.2 illustrates how the one set of register design files are processed through the register design tool to generate appropriate hardware, firmware, and document files.

Figure 5.2: Register design tools generate hardware, firmware, and document files.

When a change is needed, the input files are modified as appropriate and the tool regenerates all the hardware, firmware, and documentation files for re-synthesis, re-compile, and re-distribution. This avoids the arduous and error-prone task of manually updating all those files.

These tools are not meant to be used to develop all of the hardware or firmware design files. They at least produce include files that specify bit and register mappings. Each brand is different as to how much their tools can do.

I’ll give an example of how these tools can be used. Listing 5.1 is a simple listing of an example input file, monkey.rdt (using a made-up suffix, .rdt) to the register design tool.

Listing 5.1: Listing of the monkey input file for the register design tool.

// monkey.rdt
define register monkey_reg
    {
    address: 0x14
    description: This is the monkey register that does something.
    define bit some_bit
        {
        mask: 0x02
        type: readonly
        description: This bit is true when the state machine is busy.
        }
    define bit some_other_bit
        ...
    ...
    }
define register monkey_other_reg
    ...

The register design tool processes monkey.rdt and generates monkey.vh, monkey.h, and monkey.rtf. Listing 5.2 shows two hardware files, the .vh as generated by the tool and the .v file as generated by hand.

Listing 5.2: The hardware files for the monkey register.

// monkey.vh
// Generated by the Register Design Tool
reg [31:0] monkey_reg;
monkey_reg[1] = some_bit;

// monkey.v
`include "monkey.vh"
if(condition_a & condition_b) begin
    some_bit <= 1'b0;
end

Listing 5.3 shows two firmware files, the .h as generated by the tool and the .c as generated by hand.

Listing 5.3: The firmware files for the monkey register.

// monkey.h
// Generated by the Register Design Tool
#define MONKEY_REG_ADDR 0x14
#define SOME_BIT_MASK 0x02

/* monkey.c */
#include "monkey.h"
statusBit = readReg (MONKEY_REG_ADDR) & SOME_BIT_MASK;

And Figure 5.3 shows how the documentation file might appear in a word processor.

The Monkey Block

This section describes the registers in the Monkey Block.
monkey_reg 0x14: This is the monkey register that does something.
This register contains the following bits:

• some_bit 0x02 Read-only: This bit is true when the state machine is busy.
• some_other_bit ...

Figure 5.3: The documentation file for the monkey block.

If, for some reason, we need to move some_bit from 0x02 to 0x08, then monkey.rdt is modified accordingly, the file is re-processed by the register design tool to regenerate the .vh, .h, and .rtf. Then the hardware files are re-synthesized, the firmware files are re-compiled, and the document files re-distributed.

Most of these tools have ways of customizing the output files generated. This permits the user to control the contents and format of the generated files. This enables the use of these tools to generate files for use in co-simulators and virtual prototypes.

Although register design tools can capture and generate block documentation (among the other files), they cannot be used to generate all of the documentation necessary for a block. The block documentation generated fits only in the reference section. It contains only register and bit details, not overviews or tutorials. Even within the reference section, there are some bits and registers that will require more details and explanations than the register design tools can handle. The generated documentation will need to be hand-edited and put in with the rest of the block documentation. If the register design files are modified and the document file regenerated, care must be taken to make sure the same hand-edits are done. Though they do have limitations, register design tools are worth looking into.

These tools have the added benefit in that they encourage interdisciplinary interactions between hardware and firmware engineers by improving communication between them, and allowing firmware engineers a chance to review the designs sooner in document format. This collaboration leads to better product development.