Troubleshooting¶

Start with the first error. Later messages are often consequences.

Compile and type errors¶

“No declaration for …”¶

Check:

Spelling and scope.
Required library/use clause.
Package compiled before its consumer.
Signal declared in the architecture declarative region.
File type set to VHDL-2008 if using VHDL-2008 constructs.

“Cannot resolve overloaded …”¶

The compiler sees multiple possible types/operators.

Fix by making intent explicit:

count_s <= unsigned(raw_s) + to_unsigned(1, count_s'length);

Remove old arithmetic packages and use only numeric_std.

Width mismatch¶

Check both type and length:

wide_s <= resize(narrow_s, wide_s'length);

For an adder carry, extend operands before addition.

Signed/unsigned mismatch¶

Do not cast randomly until it compiles. Decide the number interpretation, then convert at the boundary.

Elaboration errors¶

Unit not found in library¶

Compile source before the testbench.
Confirm the library name. Standalone xvhdl defaults to work; Vivado project flows commonly use xil_defaultlib.
Confirm entity name and selected architecture.
Check compile order.

Port or generic does not match¶

Named maps expose the mismatch clearly. Compare spelling, direction, type, and width.

Wrong simulation top¶

The design entity is not the testbench. Set the no-port testbench entity as the Simulation Top.

Simulation problems¶

Signal remains `U`¶

Likely causes:

No driver.
Driver process has not executed.
Missing initialization/reset.
Wrong port map.
Test ended before reset/settling.

Signal becomes `X`¶

Likely causes:

Multiple conflicting drivers.
Unknown input propagated through logic.
Uninitialized state.
Bus contention.

Find the first upstream U/X, not only the final corrupted output.

Output appears one cycle late¶

Determine whether:

The specification expects registered output.
The testbench samples before the post-edge delta cycle.
A pipeline stage is intentional.
A signal assignment inside a process used the previous signal value.

Simulation never ends¶

Add std.env.finish on success.
Add a watchdog process.
Check wait conditions and clock generation.
Use xsim snapshot -R only with a self-ending test or defined run duration.

Assertion printed but test command passed¶

Confirm assertion severity and simulator stop settings.
Check $LASTEXITCODE.
Intentionally inject a failing expected value once to validate the runner.
Consider parsing logs or a test framework for stricter CI behavior.

Vector file cannot open¶

Simulator working directory differs from source directory.
Pass an absolute normalized path through a generic.
Confirm file deployment and spelling.
Print/report the chosen path at test start.

Synthesis problems¶

Inferred latch¶

A combinational output is not assigned on every path. Give defaults at process start and cover every branch.

Multiple drivers¶

Assign the internal signal from one process/assignment. Replace distributed driving with an explicit mux or arbitration block.

Logic removed¶

Synthesis found no observable effect or proved it constant. Trace the result to an output/register, inspect generics/resets, and verify top entity selection.

Expected block RAM or DSP not inferred¶

Coding style, reset behavior, widths, or read/write timing may not match an inference template. Compare with current Vivado synthesis coding techniques and inspect the synthesis log.

Implementation and timing¶

Unconstrained clock/path¶

Add create_clock to the correct port.
Define generated clocks.
Add valid I/O delays for synchronous interfaces.
Inspect report_clocks and constraint query results.

Negative setup slack¶

Verify constraints first. Then inspect the path for long logic, high fanout, routing, missing pipeline stages, or an invalid clock relationship.

Hold failure¶

Confirm clocks and exceptions. Do not add RTL delay chains. Let implementation tools handle physical delay once the analysis model is correct.

CDC warnings¶

Classify each crossing. Use a synchronizer, handshake, Gray transfer, or asynchronous FIFO as appropriate. Do not suppress the report globally.

Bitstream blocked by unconstrained I/O¶

Every used top port needs a package pin and I/O standard. Start from the Basys 3 master XDC and align names exactly.

Hardware does not behave like simulation¶

Check in order:

Correct bitstream and top entity.
Correct board power/JTAG connection.
XDC pins and active polarity.
Clock constraint and actual clock source.
Reset release.
Synchronization/debounce of external inputs.
Implementation timing.
Width/sign assumptions.
Hardware observation with LEDs/UART/ILA.

Common physical-only causes:

Button bounce.
Metastability/unsafe CDC.
Wrong pin or active-low polarity.
Timing failure.
Electrical incompatibility.
Programming an older bitstream.

Vivado cannot find the board¶

If using the part directly, board files are not required. If Hardware Manager cannot see the FPGA:

Use a data-capable USB cable.
Check board power and jumper settings.
Confirm cable drivers.
Close other JTAG applications.
Refresh the hardware server/target.

Diagnostic information to save¶

When asking for help, provide:

Exact first error and nearby log lines.
Vivado version.
FPGA part.
Minimal source/testbench.
Command used.
XDC relevant to the failing port/clock.
Timing path or CDC report section.
What was expected and what occurred.