############
Introduction
############

hdltbgen parses a VHDL entity declaration and generates testbench artifacts from
the extracted interface.

The tool is designed for a simple, file-based workflow:

1. Read a VHDL file containing an entity declaration.
2. Extract generics, ports, and basic signal metadata.
3. Classify clock and reset signals automatically or from CLI options.
4. Generate one or more output artifacts for testbench creation.

Supported input
===============

hdltbgen currently supports:

* VHDL source files with the extension ``.vhd``
* One top-level entity per processed file
* Entity generics and ports declared in a form the regular-expression based parser can interpret

Supported generators
====================

* VHDL testbench
* CSV stimulus and response table
* Excel workbook with optional VBA-assisted CSV export

What the tool produces
======================

Depending on the selected generator type, hdltbgen can create these files in the
output directory:

* ``entity_tb.vhd`` for the generated testbench
* ``entity_tb_sim.vhd`` for an optional simulation wrapper around the generated testbench
* ``entity_tb.csv`` for editable stimulus and expected response vectors
* ``entity_tb.xlsm`` for spreadsheet-driven editing of vectors and export to CSV

Core capabilities
=================

The implementation includes the following behaviors that are important when using
the tool in practice:

* Automatic detection of clock signals from port names containing ``clk`` if no clock is provided explicitly
* Automatic detection of active-low resets from names such as ``rstn``, ``resetn``, ``nreset``, or ``nrst``
* Automatic detection of active-high resets from names containing ``rst`` or ``reset`` if no active-low reset was detected
* Automatic insertion of a virtual input clock named ``clk_auto_gen`` when no clock can be found in the entity
* Optional interactive prompting for generic values via the command line
* Parallel generation of multiple artifact types from the same parsed interface

When to use hdltbgen
====================

hdltbgen is a good fit when you want to create a repeatable starting point for
testbench work from an entity interface instead of writing all boilerplate by hand.

Typical use cases are:

* creating a first executable VHDL testbench skeleton
* preparing CSV-based stimulus tables for simulation
* handing signal-oriented test vectors to engineers who prefer spreadsheet editing
* generating a VUnit-compatible testbench scaffold

For the exact command-line syntax, see :doc:`/overview/usage` and the generated
argument reference in :doc:`/code/cli`.