########
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:

1. Parse CLI arguments.
2. Validate that the input file exists.
3. Detect the file type from the extension.
4. Parse the VHDL entity into an internal HDL dictionary.
5. Apply user-specified clock and reset assignments.
6. Run automatic signal classification for missing clock and reset information.
7. 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.