Tutorial: debugging a failed simulation

Objective#

Find and fix one bug in a loadable counter, using only the failure message, the waveform and the specification.

Before you start#

You have done the counter tutorial, or are comfortable with nelix test and nelix waveform.

1. Create the project#

nelix new g2-debug --template g2-debug
cd ~/project/g2-debug
cat START_HERE.md

2. Run the test#

nelix test

Expected: it fails.

test_top.test_top failed
AssertionError: load with en=1: count expected 200, got 6
** TESTS=1 PASS=0 FAIL=1 SKIP=0 **

3. Read the message#

It is one sentence, and it contains everything you need to start:

So the design counted when it should have loaded.

4. Find the moment in the waveform#

nelix waveform

Find the clock edge where count first goes wrong. Note the values of en and load at that moment.

5. Compare with the specification#

Open rtl/top.sv. The comment at the top of the module says what the design should do. Read it against the line of code that handles load and en. One line does not do what the comment says.

6. Fix the RTL#

Edit rtl/top.sv. Change the design, not the test.

7. Run the test again#

nelix test

Expected: PASS=1 FAIL=0.

How to tell it worked#

The test passes, and you can say in one sentence what the bug was and why your change fixes it. If you cannot, read the waveform again.

The method#

This is the method for every failed simulation.

1. Read the message. What was expected, what was seen?
2. Find the first wrong moment in the waveform.
3. Look at the inputs at that moment.
4. Compare with the specification.
5. Change the design, or decide that the test is wrong and say why.

Next#

Repairing RTL with AI assistance does the same job with Nelix Agent, so you can compare its diagnosis with yours.