verilog-auto-inst

verilog-auto-inst is a compiled Lisp function in `verilog-mode.el'.

(verilog-auto-inst)

Expand AUTOINST statements, as part of M-x verilog-auto.
Replace the pin connections to an instantiation or interface
declaration with ones automatically derived from the module or
interface header of the instantiated item.

If `verilog-auto-star-expand' is set, also expand SystemVerilog .* ports,
and delete them before saving unless `verilog-auto-star-save' is set.
See `verilog-auto-star' for more information.

The pins are printed in declaration order or alphabetically,
based on the `verilog-auto-inst-sort' variable.

Limitations:
Module names must be resolvable to filenames by adding a
`verilog-library-extensions', and being found in the same directory, or
by changing the variable `verilog-library-flags' or
`verilog-library-directories'. Macros `modname are translated through the
vh-{name} Emacs variable, if that is not found, it just ignores the `.

In templates you must have one signal per line, ending in a ), or ));,
and have proper () nesting, including a final ); to end the template.

Typedefs must match `verilog-typedef-regexp', which is disabled by default.

SystemVerilog multidimensional input/output has only experimental support.

SystemVerilog .name syntax is used if `verilog-auto-inst-dot-name' is set.

Parameters referenced by the instantiation will remain symbolic, unless
`verilog-auto-inst-param-value' is set.

Gate primitives (and/or) may have AUTOINST for the purpose of
AUTOWIRE declarations, etc. Gates are the only case when
position based connections are passed.

The array part of arrayed instances are ignored; this may
result in undesirable default AUTOINST connections; use a
template instead.

For example, first take the submodule InstModule.v:

module InstModule (o,i);
output [31:0] o;
input i;
wire [31:0] o = {32{i}};
endmodule

This is then used in an upper level module:

module ExampInst (o,i);
output o;
input i;
InstModule instName
(/*AUTOINST*/);
endmodule

Typing M-x verilog-auto will make this into:

module ExampInst (o,i);
output o;
input i;
InstModule instName
(/*AUTOINST*/
// Outputs
.ov (ov[31:0]),
// Inputs
.i (i));
endmodule

Where the list of inputs and outputs came from the inst module.

Exceptions:

Unless you are instantiating a module multiple times, or the module is
something trivial like an adder, DO NOT CHANGE SIGNAL NAMES ACROSS HIERARCHY.
It just makes for unmaintainable code. To sanitize signal names, try
vrename from URL `http://www.veripool.org'.

When you need to violate this suggestion there are two ways to list
exceptions, placing them before the AUTOINST, or using templates.

Any ports defined before the /*AUTOINST*/ are not included in the list of
automatics. This is similar to making a template as described below, but
is restricted to simple connections just like you normally make. Also note
that any signals before the AUTOINST will only be picked up by AUTOWIRE if
you have the appropriate // Input or // Output comment, and exactly the
same line formatting as AUTOINST itself uses.

InstModule instName
(// Inputs
.i (my_i_dont_mess_with_it),
/*AUTOINST*/
// Outputs
.ov (ov[31:0]));


Templates:

For multiple instantiations based upon a single template, create a
commented out template:

/* InstModule AUTO_TEMPLATE (
.sig3 (sigz[]),
);
*/

Templates go ABOVE the instantiation(s). When an instantiation is
expanded `verilog-mode' simply searches up for the closest template.
Thus you can have multiple templates for the same module, just alternate
between the template for an instantiation and the instantiation itself.
(For backward compatibility if no template is found above, it
will also look below, but do not use this behavior in new designs.)

The module name must be the same as the name of the module in the
instantiation name, and the code "AUTO_TEMPLATE" must be in these exact
words and capitalized. Only signals that must be different for each
instantiation need to be listed.

Inside a template, a [] in a connection name (with nothing else
inside the brackets) will be replaced by the same bus subscript
as it is being connected to, or the [] will be removed if it is
a single bit signal.

Inside a template, a [][] in a connection name will behave
similarly to a [] for scalar or single-dimensional connection;
for a multidimensional connection it will print a comment
similar to that printed when a template is not used. Generally
it is a good idea to do this for all connections in a template,
as then they will work for any width signal, and with AUTOWIRE.
See PTL_BUS becoming PTL_BUSNEW below.

Inside a template, a [] in a connection name (with nothing else inside
the brackets) will be replaced by the same bus subscript as it is being
connected to, or the [] will be removed if it is a single bit signal.
Generally it is a good idea to do this for all connections in a template,
as then they will work for any width signal, and with AUTOWIRE. See
PTL_BUS becoming PTL_BUSNEW below.

If you have a complicated template, set `verilog-auto-inst-template-numbers'
to see which regexps are matching. Don't leave that mode set after
debugging is completed though, it will result in lots of extra differences
and merge conflicts.

Setting `verilog-auto-template-warn-unused' will report errors
if any template lines are unused.

For example:

/* InstModule AUTO_TEMPLATE (
.ptl_bus (ptl_busnew[]),
);
*/
InstModule ms2m (/*AUTOINST*/);

Typing M-x verilog-auto will make this into:

InstModule ms2m (/*AUTOINST*/
// Outputs
.NotInTemplate (NotInTemplate),
.ptl_bus (ptl_busnew[3:0]), // Templated
....


Multiple Module Templates:

The same template lines can be applied to multiple modules with
the syntax as follows:

/* InstModuleA AUTO_TEMPLATE
InstModuleB AUTO_TEMPLATE
InstModuleC AUTO_TEMPLATE
InstModuleD AUTO_TEMPLATE (
.ptl_bus (ptl_busnew[]),
);
*/

Note there is only one AUTO_TEMPLATE opening parenthesis.

@ Templates:

It is common to instantiate a cell multiple times, so templates make it
trivial to substitute part of the cell name into the connection name.

/* InstName AUTO_TEMPLATE <optional "REGEXP"> (
.sig1 (sigx[@]),
.sig2 (sigy[@"(% (+ 1 @) 4)"]),
);
*/

If no regular expression is provided immediately after the AUTO_TEMPLATE
keyword, then the @ character in any connection names will be replaced
with the instantiation number; the first digits found in the cell's
instantiation name.

If a regular expression is provided, the @ character will be replaced
with the first () grouping that matches against the cell name. Using a
regexp of "\([0-9]+\)" provides identical values for @ as when no
regexp is provided. If you use multiple layers of parenthesis,
"test\([^0-9]+\)_\([0-9]+\)" would replace @ with non-number
characters after test and before _, whereas
"\(test\([a-z]+\)_\([0-9]+\)\)" would replace @ with the entire
match.

For example:

/* InstModule AUTO_TEMPLATE (
.ptl_mapvalidx (ptl_mapvalid[@]),
.ptl_mapvalidp1x (ptl_mapvalid[@"(% (+ 1 @) 4)"]),
);
*/
InstModule ms2m (/*AUTOINST*/);

Typing M-x verilog-auto will make this into:

InstModule ms2m (/*AUTOINST*/
// Outputs
.ptl_mapvalidx (ptl_mapvalid[2]),
.ptl_mapvalidp1x (ptl_mapvalid[3]));

Note the @ character was replaced with the 2 from "ms2m".

Alternatively, using a regular expression for @:

/* InstModule AUTO_TEMPLATE "_\([a-z]+\)" (
.ptl_mapvalidx (@_ptl_mapvalid),
.ptl_mapvalidp1x (ptl_mapvalid_@),
);
*/
InstModule ms2_FOO (/*AUTOINST*/);
InstModule ms2_BAR (/*AUTOINST*/);

Typing M-x verilog-auto will make this into:

InstModule ms2_FOO (/*AUTOINST*/
// Outputs
.ptl_mapvalidx (FOO_ptl_mapvalid),
.ptl_mapvalidp1x (ptl_mapvalid_FOO));
InstModule ms2_BAR (/*AUTOINST*/
// Outputs
.ptl_mapvalidx (BAR_ptl_mapvalid),
.ptl_mapvalidp1x (ptl_mapvalid_BAR));


Regexp Templates:

A template entry of the form

.pci_req\([0-9]+\)_l (pci_req_jtag_[\1]),

will apply an Emacs style regular expression search for any port beginning
in pci_req followed by numbers and ending in _l and connecting that to
the pci_req_jtag_[] net, with the bus subscript coming from what matches
inside the first set of \( \). Thus pci_req2_l becomes pci_req_jtag_[2].

Since \([0-9]+\) is so common and ugly to read, a @ in the port name
does the same thing. (Note a @ in the connection/replacement text is
completely different -- still use \1 there!) Thus this is the same as
the above template:

.pci_req@_l (pci_req_jtag_[\1]),

Here's another example to remove the _l, useful when naming conventions
specify _ alone to mean active low. Note the use of [] to keep the bus
subscript:

.\(.*\)_l (\1_[]),

Lisp Templates:

First any regular expression template is expanded.

If the syntax @"( ... )" is found in a connection, the expression in
quotes will be evaluated as a Lisp expression, with @ replaced by the
instantiation number. The MAPVALIDP1X example above would put @+1 modulo
4 into the brackets. Quote all double-quotes inside the expression with
a leading backslash (\"...\"); or if the Lisp template is also a
regexp template backslash the backslash quote (\\"...\\").

There are special variables defined that are useful in these
Lisp functions:

vl-name Name portion of the input/output port.
vl-bits Bus bits portion of the input/output port ('[2:0]').
vl-mbits Multidimensional array bits for port ('[2:0][3:0]').
vl-width Width of the input/output port ('3' for [2:0]).
May be a (...) expression if bits isn't a constant.
vl-dir Direction of the pin input/output/inout/interface.
vl-modport The modport, if an interface with a modport.
vl-cell-type Module name/type of the cell ('InstModule').
vl-cell-name Instance name of the cell ('instName').

Normal Lisp variables may be used in expressions. See
`verilog-read-defines' which can set vh-{definename} variables for use
here. Also, any comments of the form:

/*AUTO_LISP(setq foo 1)*/

will evaluate any Lisp expression inside the parenthesis between the
beginning of the buffer and the point of the AUTOINST. This allows
functions to be defined or variables to be changed between instantiations.
(See also `verilog-auto-insert-lisp' if you want the output from your
lisp function to be inserted.)

Note that when using lisp expressions errors may occur when @ is not a
number; you may need to use the standard Emacs Lisp functions
`number-to-string' and `string-to-number'.

After the evaluation is completed, @ substitution and [] substitution
occur.

For more information see the M-x verilog-faq and forums at URL
`http://www.veripool.org'.