Workflow

This page describes the internal processing flow of hdltbgen from input file to generated artifacts.

Processing pipeline

The command-line entry point performs the following steps:

Parse CLI arguments.
Validate that the input file exists.
Detect the file type from the extension.
Parse the VHDL entity into an internal HDL dictionary.
Apply user-specified clock and reset assignments.
Run automatic signal classification for missing clock and reset information.
Invoke one generator instance per requested output type.

The implementation currently accepts only .vhd files. Other HDL formats are not supported.

Parsing model

The VHDL parser scans the file line by line and uses regular expressions to find:

the entity name
the generic section
the port section
the end of the entity

For every parsed generic, hdltbgen stores:

the generic name
the declared type string
a value used later for generated constants

For every parsed port, hdltbgen stores:

the port name
the direction: in, out, or inout
the declared type string
whether the signal is virtual and was inserted by the tool

Comments introduced by – are stripped before parsing. The parser focuses on the entity declaration and does not analyze the architecture body.

Signal classification

Clock and reset handling is a mix of explicit configuration and heuristics.

Explicit configuration via CLI takes precedence:

--clock marks one or more input ports as clocks
--reset-negative marks active-low resets
--reset-positive marks active-high resets

If no clock is given, hdltbgen searches for the first port whose name contains clk. If none is found, it inserts a virtual std_logic input named clk_auto_gen.

If no reset is given, hdltbgen searches first for active-low reset names and then for generic reset names. This affects the reset sequence emitted in the VHDL testbench.

Generic handling

Generics are copied into the internal model and later mapped into generated VHDL.

Without --ask:

every generic value is set to TODO
generated VHDL therefore requires manual completion before successful compilation when generics are used

With --ask:

the CLI prompts for a value for each generic
supported numeric categories include integer, natural, positive, and real
explicit ranges are used when they can be interpreted by the parser

Generator dispatch

Each value passed to --type creates one artifact generation run:

vhdl creates the main testbench file
csv creates a CSV vector file
excel creates an Excel workbook

Multiple --type arguments can be combined in a single invocation, so one parse run can feed several outputs.

Output naming

Generated filenames are derived from the input filename stem:

input my_design.vhd
VHDL output my_design_tb.vhd
VHDL simulation wrapper my_design_tb_sim.vhd
CSV output my_design_tb.csv
Excel macro workbook my_design_tb.xlsm

If no output directory is specified, the files are written next to the input VHDL file.