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:

1. Correct bitstream and top entity.
2. Correct board power/JTAG connection.
3. XDC pins and active polarity.
4. Clock constraint and actual clock source.
5. Reset release.
6. Synchronization/debounce of external inputs.
7. Implementation timing.
8. Width/sign assumptions.
9. 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.