###########
Limitations
###########

This page documents important constraints that follow from the current
implementation.

Supported HDL scope
===================

hdltbgen currently supports only VHDL files with the extension ``.vhd``. The CLI does
not accept Verilog, SystemVerilog, or alternate VHDL filename extensions.

Parser limitations
==================

The parser is intentionally lightweight and uses regular expressions instead of a
full VHDL grammar. That keeps the tool simple, but it also means:

* the entity declaration must be written in a form the regex patterns can match
* malformed or highly unusual formatting may not parse correctly
* only the entity interface is analyzed, not behavioral code inside the architecture
* support for advanced VHDL constructs is limited to what the current expressions capture

Generic values
==============

If an entity contains generics and ``--ask`` is not used, generated generic constants
are populated with ``TODO`` placeholders. The generated VHDL is then a scaffold, not a
ready-to-compile artifact, until these values are replaced.

Clock and reset heuristics
==========================

Automatic classification is name-based. If your ports do not follow the expected
``clk``, ``rst``, or ``reset`` naming patterns, hdltbgen may choose the wrong signals or may
insert a virtual clock. Explicit CLI arguments are recommended in such cases.

Excel portability
=================

The Excel generator depends on:

* openpyxl for workbook creation
* xlwings for Excel automation and VBA insertion
* a local Excel configuration that permits access to the VBA project model

The first two are optional Python dependencies and are installed via the
``excel`` extra: ``pip install "hdltbgen[excel]"``.

This generator can therefore behave differently across environments even when the
Python dependencies are installed.

Failure behavior
================

The CLI currently raises direct Python exceptions for many error cases. There is no
custom error formatting layer, so failures are functional but not heavily
user-friendly.

Project maturity
================

The tool is best understood as a code-generation utility that creates a solid
starting point. Generated artifacts usually still require engineering review and
project-specific refinement before they are used as part of a production
verification flow.