Thanks to all the people who attended the webinar Extend the Language! An Introduction to Specman Macros that we had on March the 17th. If you did not attend, or attended and want to see it again – you can view Extend the Language Using Specman e Macros! Webinar Recording (Video). The video contains English captions.
Many questions were asked during the session, and under limitation of time – not all of them were answered or were answered only briefly. We collected here some of the questions, for your convenience.
Defining/referring to variables inside macros
The question:
When defining <action> macro, suppose I have 'var a' in my code and same 'var a' in the macro body, if the code in the macro changes 'a' - will it change 'a' in code as well?
The answer:
The macro adds a new inner scope, same as when adding blocks (e.g. ‘if’ blocks). If there are variables of same name defined in the method – then the macro changes only the var defined in the macro itself, and not the one in the outer scope.
Macro parameter type – ‘any’
The question:
Is there a better syntactic element than <any> when we need to get a string as a parameter for the macro (top.core.block_name)?
The answer:
Depending on the case, perhaps <exp> is the right choice. When you decide what syntactic type to use, ask yourself in what context this parameter is used in the macro body. If you are going to use the parameter as an expression – use <exp>.
Here are few examples of where expressions are used.
- Arithmetic operators work on expressions
- <exp1> + <exp2>, …
- Print/out accept expressions
- print <exp>
- Constraints accept expressions
- keep <exp1> == <exp2>
If the body of the macro performs any of these on the parameter – the parameter can be <exp>.
When to use <any>?
Main guideline of using <any> is to use it if all other syntactic types don’t fit.
Spaces & Optional
The question:
How can I treat multiple whitespaces as one, without using [ ] ?
The answer:
Multiple white spaces are treated as one. No need for “[]”
So the following macro
define <add'action> "add <item'exp> to <list'exp>" as {
<list'exp>.add(<item'exp>);
};
Allows all these:
add 1 to my_items;
add 2 to my_items;
add 3 to my_items;
add 4 to my_items;
Creating the result of ‘define as computed’
The question:
What is the best way to create the result code?
The answer:
The main ways to construct the result of define as computed are either using append() for creating one string, or to create a list of string and use str_join() to join the list of strings to one string. Personally, I prefer creating list of strings. But this is matter of coding style, and any other way that works for you is fine.
For example -
define <morning'action> "GOOD MORNING" as computed {
result = append("print sys.time;");
result = append(result, "print me;");
};
define <evening'action> "GOOD EVENING" as computed {
var result_code : list of string;
result_code.add(append("print sys.time;"));
result_code.add(append("print me;"));
result = str_join(result_code, "");
};
Macros performance
The question:
Assume we replace a method with a macro, and the method should have been called in a loop 1000000 times. When using macro which implements same method, will the runtime of the test will be more efficient?
The answer:
When talking about exp and action macros, every macro call “embeds” the replacement code in place. In some cases, as is described in the question – embedding the code is more efficient. In other cases, when the macro body is very long – using a macro means we add millions of lines of code, and this might affect the performance of parsing. When considering the trade-offs, one cannot say that macro has better or worse performance than method. Sometimes you pay in parsing time, but the run-time will be better than the alternative of using a method.
We can say the typically, with macros we have seen – the effect of using macro vs. using method is neglectable. So when choosing whether to use macros or methods – we recommend to have other considerations, rather than performance. See some guidelines in https://community.cadence.com/cadence_blogs_8/b/fv/posts/tips-on-using-e-macros-to-raise-abstraction-amp-facilitate-reuse
Debugging macros
The question #1:
The first question about macro debug, is about the challenge of defining the macro pattern. Sometimes you are not sure what syntactic elements to use, sometimes you are not sure whether the pattern will recognize all the expressions it has to, and only them.
The answer:
There are multiple tools that can help understanding whether the pattern will recognize the pieces of code you plan to support, and only them. The main tool is the show macro command. With show macro you can see how lines in the code are parsed, and also you can provide a string and check if it is matched by the macro and what the replacement code is.
For example, assume this macro:
define <add_2'action> "add <item'num> to <list'exp>" as {
<list'exp>.add(<item'exp>);
};
To see what lines are recognized by this macro, we call show macro, passing the string we want to try -
- var values := {1;2;3}
- show macro"add 7 to values" -macro=<add_2'action>
If the string does not match the macro pattern, show macro will print that the match FAILED
The match failed, because the macro expects a num, and “val” is not a number (rather – it is a variable).
Using show macro, you can also try out the macro pattern, before writing any e code. For example, this command will show if the planned pattern recognizes the code “add 7 to values”
show macro"add 7 to values" -mexp="add <item'num> to <list'exp>"
The question #2:
The second question about macro debug, is debugging the macro body (the replacement code).
The answer:
When the macro is of <action>, then debugging the macro code is like debugging methods – you can set a break point, and debug step by step in the source browser.
Documentation
The question:
Where are macros documented? There was a side question, about documentation of reflection.
The answer:
Macros are documented in the Specman e Language Reference. Search for ‘macros’ or for ‘define as’.
The show macro command is documented in Specman Command Reference. Search for ‘show macro’
The reflection is documented in the Specman e Language Reference. This section is being enhanced, more usage examples are added. The reflection is documented using eDoc, and can be viewed on any browser directly from the installation.
Code examples are available, beside the CadenceHelp, also on github - https://github.com/efratcdn/reflection_examples.
Tips of writing and debugging macros, are provided also in some blogs, for example -
- https://community.cadence.com/cadence_blogs_8/b/fv/posts/tips-on-using-e-macros-to-raise-abstraction-amp-facilitate-r
- https://community.cadence.com/cadence_blogs_8/b/fv/posts/macro-debugging
- https://community.cadence.com/cadence_blogs_8/b/fv/posts/tips-on-writing-macros-in-e
- https://community.cadence.com/cadence_blogs_8/b/fv/posts/getting-source-information-on-macros
And, as said in the webinar, don’t hesitate submitting questions on stackoverflow (where answers come not only from Cadence), or send to Specman support, or even directly to me – efrat@cadence.com. I will make sure the right person will get the question.