Using e macros can greatly improve your productivity by raising the level of abstraction at which these testbenches are created and used. With e macros, you can reduce the amount of code and simplify usage of code that needs to be used in several places in the testbench.

e macros are powerful code generators whose key benefit istheir ability to extend the e language.

What is called "macro" in some other languages might be merely text replacement, such as replacing all occurrences of some text "A" with the text "B".

Macros in e can do this too, but they are capable of far more sophisticated things. These usages might be more complicated to debug, so Specman allows us to debug the generated code, instead of the macro definition code itself.

In this document, we are going to explore ways to debug macros in various stages of the simulation.

Let's consider the following test case:

Here we have a macro (define as) which simply creates a client object, and adds a client to a list of clients. (Note: The parentheses and quotation marks that enclose <x'string> prevent the preprocessor from considering all the parameters that come after the <x'string> declaration in the program code as part of the string.)

The addition of client to the list is done via another macro: 

And the macro call is made here:

Parsing time errors

Specman parser gives clear error messages for syntax or parser issues at parsing time. For example, as seen below, we assign <x'name> (instead of <x'num>) to ‘it.num', but we do not have any such argument in the match expression.

This results in the following error:

The error here is pretty straightforward to fix. So let us correct the macro code (change line #14 to "it.num  == <x'num>") and re-run it.

Macro expansion errors (at load time)

There could be cases where the macro parses correctly but encounters issues after it was expanded at load time. In such cases, the code is still not loaded.

We can use the "trace reparse" command to debug such issues. Let us again look at our example. The macro is modified a bit, as shown below:

Note: The code "it.name==<3>" at line #9 and 13 parses well, but will fail to load with an error that doesn't give much information (the message merely says that Specman expects a string for "i"). So let us use "trace reparse" (before load phase). This re-parses the code, and gives us the following helpful message from which we can understand the root cause of the error.

Run-time errors

Run-time errors will occur on the expansion code that was created by the macro. In some cases, you might not get errors per se, but might see unintended or incorrect functionality. This is just like any other bug in your testbench, but the actual code is hidden under the macro definition.

Let's look how this reflects in our example. Once we are done loading and start to run the test, we get the following output:

For some reason, we generate NULL clients all the time. Is that expected behavior? Ummm...it doesn't seem so. So let's check what went wrong?

Like any other e code, we will use the source debugger to find the root cause:

1.       Put a breakpoint on the macro call and then step into the macro call itself, so that it breaks when macro is called.

As seen above, a breakpoint is applied at line #37.

2.       Run the simulation again after adding breakpoint. It automatically opens the source browser at breakpoint. If you step into the macro, the debugger will take you to the macro definition code:

3.       Click on the macro debug mode button  to select expansion mode. This will expand the macro code, to the real code Specman is running. Now you can keep on clicking ‘step into' button  to see the flow of execution.

We can set a ‘watch' on x and x1 to see how they take the values. After setting a ‘watch', run it for few more steps and the Watch window should show following values.

This shows that the client ‘x' (NOT x1) was generated. Since x1 is empty, it keeps adding empty items to the list. This clarifies what was causing a NULL list of clients.

Problem solved!

To summarize, macros in e are a very powerful tool. You need to know how to use them, and especially how to debug them. Having the correct tools makes this task much easier and intuitive, and prevents the frustration of debugging code you cannot even see.

Happy Debugging!

Mahesh Soni

Avi Farjoun