RE: compiler directive with formal arguments

Shalom,

I read section 11.3.1 in LRM v2.2 again.  Even "knowing the
answer" I have a hard time with the following sentence on
pg. 240:

"However, a text macro with one or more arguments shall be
expanded by substituting each formal argument with the
expression used as the actual argument in the macro usage."

Being a little nitpicky, the word "string" may not be the
most appropriate word in the following sentence on pg. 239:

"The compiler substitutes the text of the macro for the
string `text_macro_name."

since `text_macro_name is not a string as in type string, it
is text in the source code.

But going back to the real reason I am writing this message,
it would be nice to have an example in which the sequence of
substitutions is clearly explained.  This example should also
include parameters (or variables) in the statement that uses
the macro, including a string parameter/variable example.
Just like you did it in your explanation for me in this email
thread.  The reason this is important is because there is
little explanation there for what the difference is between
a string and macro text (or code text).  This should also be
explained and clarified.

The problem is that the existing examples do not demonstrate
the entire process of the substitution, and given the rather
poor description above them, I am afraid that it is very
difficult to get a good understanding on what really is going
on.

Thanks,

Arpad
==============================================================



-----Original Message-----
From: Bresticker, Shalom 
Sent: Thursday, November 09, 2006 7:30 PM
To: Muranyi, Arpad; verilog-ams
Subject: RE: compiler directive with formal arguments

We'll try. I'd be glad to hear specific suggestions.

Shalom

> -----Original Message-----
> From: owner-verilog-ams@server.eda.org [mailto:owner-verilog-
> ams@server.eda.org] On Behalf Of Muranyi, Arpad
> Sent: Friday, November 10, 2006 1:19 AM
> To: verilog-ams
> Subject: RE: compiler directive with formal arguments
> 
> Shalom,
> 
> Thank you very much for your detailed explanation.
> I think I understand it now.  Would it be possible
> to make the LRM somewhat easier to understand (or
> am I the only one who took this long to get it)?
> 
> Thanks,
> 
> Arpad
> ==================================================
> 
> -----Original Message-----
> From: Bresticker, Shalom
> Sent: Tuesday, November 07, 2006 1:30 AM
> To: Muranyi, Arpad; 'Geoffrey.Coram'
> Cc: 'Marq Kole'; 'verilog-ams'
> Subject: 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