Simulation failures
The test ran and a check did not hold, or the run never finished.
On this page
An assertion failedThe output is unknownOff by one clockThe run timed outIt passes, and you are not sure it shouldAsk for helpAn assertion failed#
AssertionError: load with en=1: count expected 200, got 6The design ran and disagreed with the test. Either can be wrong.
- Read the message: what was expected, what was seen.
- Open the waveform and find the first moment the output is wrong.
- Look at the inputs at that moment, and compare with the specification.
- If the design is wrong, fix the design. If the test expects something the specification never asked for, fix the test, and say why.
The worked example is Debugging a failed simulation.
The output is unknown#
| Symptom | Cause | Fix |
|---|---|---|
A value shows as x in the waveform | A flip-flop was never reset, or an input was never driven | Reset every flip-flop. Drive every input in the test before the first check |
ValueError when the test reads a value | The signal contains unknown bits and cannot be turned into a number | The same. Find where the unknown starts |
An output is z | Nothing drives it | A missing assignment or an unconnected port |
Off by one clock#
The test sees the right value one clock early or late.
| Cause | Fix |
|---|---|
| The test reads on the same edge the design updates | Drive and read on the falling edge |
| The design's latency differs from the specification | Decide which is right. Latency belongs in docs/DESIGN.md |
The run timed out#
A simulation may run for 5 minutes. A test that reaches the limit is almost always waiting for something that never happens.
| Look for | Because |
|---|---|
| A clock that was never started | Without cocotb.start_soon(Clock(...).start()) no edge ever comes |
A while loop waiting for a signal | If the design never raises it, the loop never ends. Add a limit to the loop |
| Reset never released | The design sits in reset |
It passes, and you are not sure it should#
A pass shows that the test and the design agree. Break the design on purpose and run the test again. If it still passes, the test does not check that behaviour.
Ask for help#
Debug with Nelix Agent on the failed card gives a diagnosis from the run's own evidence, and can propose a repair. It uses AI credits.
Something unclear or missing? Send feedbackSign in and use Feedback to tell us.