RE: compiler directive with formal arguments

Hi,

Let me try to clarify things.

> -----Original Message-----
> From: Muranyi, Arpad
> Sent: Monday, November 06, 2006 10:06 PM
> To: Geoffrey.Coram; Bresticker, Shalom
> Cc: Marq Kole; verilog-ams
> Subject: RE: compiler directive with formal arguments
> 
> Hello everyone,
> 
> I need to add a few of my thoughts to this subject on text macros.
> 
> For one, the example below uses the double quotes around the macro
> text, which is incorrect considering what is shown in "will print".
> As I was studying section 11.3 in LRM v2.2 (p. 239), I was surprised
> to find out that macro text and string are two different things.
> Strings are surrounded by double quotes, but the macro text is NOT!
> I thought this was an inconsistency, but some Verilog-AMS gurus from
> a vendor convinced me that this is the way it is (and should be).
> 
> So the example below should have said:
> 
>   `define H(x) "Hello, x"
>   $display(`H(world));
> will print
>   "Hello, x"
> 
> including the double quotes!
[SB] 
What happens is that where the macro is used, the actual argument is
substituted as is as a textual substitution. Then the macro definition
with the actual arguments is text substituted for the macro call. This
is really a pre-compilation stage. 

However, there is an exception. A string literal is a single token from
the point of view of the pre-processor. The textual substitution of
macros occurs after the parser has turned the source text into a
sequence of tokens. Substitution does not occur within a string literal.
That is what Mantis 1119 comes to clarify, because it is not specified
in 1364-2005.

So you get the following:

$display(`H(world));

turns into

$display("Hello, x");

This prints simply

Hello, x

without quotes.

If the macro had been defined as 

Hello, x

without quotes, then `Hello(world) would give us

$display(Hello, world);

At this stage, the compiler has no idea what 'Hello' and 'world' are.

If 'Hello' and 'world' are variables or parameters, for example, this
will be legal. If not, it will be a syntax error. But the same macro
expansion occurs in both cases. 


> This raises another question in the LRM regarding arguments.  The LRM
> says the following in this section:
> 
> "The macro text can be any arbitrary text specified on the same line
as
> the text macro
> name, but shall not begin with __VAMS_ to avoid conflicts with
> predefined macros in
> Section 11.7."
> 
> The "any arbitrary text" means that the character "(" at the beginning
> of
> the macro text  can be part of the text.  On the other hand, if
> argument(s)
> are used, they will be enclosed by parentheses.  How is the compiler
> going
> to decide that an opening "(" character is an argument, or part of the
> macro
> text?  You may say that if there is no space between the
> text_macro_identifier
> and the first "(" character then it is an argument, but if there is a
> space
> then it is part of the macro text.  However, this is not spelled out
in
> the
> LRM.
[SB] As mentioned by Geoffrey, this is specified in 1364-2005.

>  In addition, what am I supposed to do if I want to start my macro
> text
> with a space or tab character?  Theoretically that should also be
> allowed,
> since "any arbitrary text" is allowed in the macro text, right?

[SB] You really can't start a macro with white space. It will be
stripped out by the compiler.

> 
> Another question I have on this subject is what the argument type can
> be.
> The LRM example on p. 241 uses a literal for the argument:
> 
> //define an adc with variable delay
> `define var_adc(dly) adc #(dly)
> // Given the above macro the following uses
> `var_adc(2) g121 (q21, n10, n11);
> `var_adc(5) g122 (q22, n10, n11);
> // shall result in:
> adc #(2) g121 (q21, n10, n11);
> adc #(5) g122 (q22, n10, n11);
> 
> Is it possible to use a variable or parameter instead, like this:
> 
> parameter integer MyNumber = 2;
> `define var_adc(dly) adc #(dly)
> `var_adc(MyNumber) g121 (q21, n10, n11);
> // and expect this result?
> adc #(2) g121 (q21, n10, n11);

[SB] Yes. As I said, pure textual substitution occurs. So

`var_adc(MyNumber) g121 (q21, n10, n11);

expands to 

adc #(MyNumber) g121 (q21, n10, n11);

Note that the substitution of 2 for MyNumber occurs later. 
So that if you use `var_adc(MyNumber) in different places, it can expand
to different values, if MyNumber has a different value in each place.

> 
> Take this further one step, can we use string parameters or variables
> and expect the compiler to expand it as if it was macro text?
[SB] Sure. As I said, the preprocessor just takes what is written as an
argument in the macro call, and substitutes it in for the formal
argument, without substituting a parameter's value for the parameter
name, etc.

  The
> example
> below is interesting from this perspective also:
> 
>   $display(`H(world));
> 
> Note that the argument world is not enclosed by double quotes.  Why?
> What
> is the type of this argument?  Is it a string?  If not, do we have a
> magic
> type perhaps called "text" which doesn't get enclosed by double
quotes?

[SB] That is maybe a good way of putting it. There is a Mantis item open
to clarify this. It is confusing because the LRM says that the actual
argument is an expression, but in reality that restriction does not
exist. The argument can be either with quotes or without, as you wish. 
It will be substituted as is into the text, with quotes or without,
respectively.

> 
> But what if the argument is a string variable or parameter?  Is that
> going
> to get expanded in the macro text and become part of the expanded
macro
> text?
> For example, can I write:
> 
> parameter string MacroArg = "world";
> `define H(x) Hello, x
> $display(`H(MacroArg));
> 
> and expect it to print:
>   Hello, world
> 
> Or is it going to print:
>   Hello, "world"
> 
> with the double quotes?  Or will (should) the compiler even take this?
[SB] This would turn into

$display(Hello, "world");

Hope this helps.

Shalom