EMACS Verilog-mode 高级用法 AUTO_TEMPLATE

 摘录了 EMACS 关于 AUTO_TEMPLATE 部分的帮助文档，并且收集了相关的FAQ文档

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.

  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.
  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.

  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
	    ....

@ 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 (\").  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-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.
	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.

  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.

==============================================================
number-to-string is a built-in function.
(number-to-string NUMBER)

Convert NUMBER to a string by printing it in decimal.
Uses a minus sign if negative.
NUMBER may be an integer or a floating point number.

string-to-number is a built-in function.
(string-to-number STRING &optional BASE)

Convert STRING to a number by parsing it as a decimal number.
This parses both integers and floating point numbers.
It ignores leading spaces and tabs.

If BASE, interpret STRING as a number in that base.  If BASE isn't
present, base 10 is used.  BASE must be between 2 and 16 (inclusive).
If the base used is not 10, floating point is not recognized.
=========================================================================

How do I use AUTO_TEMPLATE to match multiple port names?¶
Regexps can be used as port names. Furthermore they can be captured to be used in the connection name. \1 for the first captured regexp in \(...\), and \2 for the second regexp, etc. Templates also allow a short-hand whereby the first "@" means matches-any-number and put in \1, that is, @ is short-hand for "\([0-9]+\)".

/* InstModule AUTO_TEMPLATE (
    .pin@_\(.*\) (wire\1of\2),
);
*/
   InstModule mod (
    .pin1_foo    (wire1offoo)   // Templated
   );
How do I use AUTO_TEMPLATE to tie off inputs to zero?¶
Use a LISP format template, and the lisp variable vl-width, which contains the width of the port.

/* InstModule AUTO_TEMPLATE (
    .\(.*\)_test ({@"vl-width"{1'b0}}),
);
*/
How do I use AUTO_TEMPLATE to lower case all signals?¶
Use a lisp expression, and the lisp function "downcase".

/* InstModule AUTO_TEMPLATE (
   .\(.*\) (@"(downcase vl-name)"[]),
*/
If you're trying the reverse, namely to upcase your signal names, did you consider lower case is more readable by 15% or so than all upper case?

How do I use AUTO_TEMPLATE to include the instantiation name for pin?¶
Yet another lisp expression:

/* InstModule AUTO_TEMPLATE (
     .a(@"vl-cell-name"_in[]),
     .b(@"vl-cell-name"_out[]),
     );*/

InstModule u_a0 (/*AUTOINST*/
     // Inouts
     .a    (u_a0_in[bitsa:0]),     // Templated
     .b    (u_a0_out[bitsb:0]));     // Templated
InstModule u_a1 (/*AUTOINST*/
     // Inouts
     .a    (u_a1_in[bitsa:0]),     // Templated
     .b    (u_a1_out[bitsb:0]));     // Templated
Oh, but what if I didn't want the u_?

/* InstModule AUTO_TEMPLATE (
     .a(@"(substring vl-cell-name 2)"_in[]),
     .b(@"(substring vl-cell-name 2)"_out[])
     );*/

InstModule u_a0 (/*AUTOINST*/
   // Inouts
   .a    (a0_in[bitsa:0]),     // Templated
   .b    (a0_out[bitsb:0]));     // Templated
Substring is very useful in templates. All of your cell names need to be the same length however. Often you can simply pad the names by adding zeros, for example use u_00 ... u_15, rather than u_0 ... u_15.

How do I have AUTO_TEMPLATE use the second number in a instance name?¶
The standard @ sign in a template by default returns the first number in a instance name, so if you want a earlier number, you have three main choices.

If you only need the second digit, you can define the @ sign to come from the second digits in the module:

/* InstModule AUTO_TEMPLATE "\([0-9]+\)$"; (
                             .a (in_@),
*/
Note this pattern works because it doesn't have to be at the beginning of the cell name; there's no "^" in the regexp to bind to the start of the string being matched.

Next easiest is to use @"(substring vl-cell-name ...) to extract the relevant digits. See the examples above.

The most flexible is to define your own function to do the relevant extraction, then call it. For example:

/* AUTO_LISP(defun getparam2 (strg)
    (string-match "[^0-9]*[0-9]+[^0-9]*\\([0-9]+\\)" strg)
    (match-string 1 strg)) */

/* InstModule AUTO_TEMPLATE (
    .in (@"(getparam2 vl-cell-name)"),
    );
    */
How do I use AUTO_TEMPLATE to connect bytes to instances?¶
This is for when you want the first instance to get a[7:0], the second a[15:8], and so on.

Use a lisp template and a little math.

/* InstModule AUTO_TEMPLATE (
     .a(@in[@"(+ (* 8 @) 7)":@"(* 8 @)"]),
     );*/

InstModule u_a0 (/*AUTOINST*/
     .a    (in[7:0]));     // Templated
InstModule u_a1 (/*AUTOINST*/
     .a    (in[15:8]));     // Templated
InstModule u_a2 (/*AUTOINST*/
     .a    (in[23:16]));     // Templated
InstModule u_a3 (/*AUTOINST*/
     .a    (in[31:24]));     // Templated
How do I propagate parameters in an instantiation?¶
AUTOINSTPARAM is very similar to AUTOINST, but it pulls parameters up using Verilog-2001 syntax:

module InstModule;
   parameter PARAM1 = 1;
   parameter PARAM2 = 2;
endmodule

module ModnameTest;
   InstModule #(/*AUTOINSTPARAM*/
         // Parameters                                                              
         .PARAM1  (PARAM1),
         .PARAM2  (PARAM2))
     instName 
       (/*AUTOINST*/
        ...);
See also the next FAQ.

How do I propagate parameters to pin connections?¶
If you set verilog-auto-inst-param-value, a AUTOINST cell that sets a Verilog-2001 style parameter will have that parameter's value substituted into the instantiation:

module InstModule;
   # (parameter WIDTH = 32)
   (output wire [WIDTH-1:0] out);
endmodule

module ModnameTest;
   InstModule #(.WIDTH(16))
     instName
       (/*AUTOINST*/
        // Outputs                                                                    
        .out   (out[15:0]));
endmodule

// Local Variables:                                                                 
// verilog-auto-inst-param-value:t                                                  
// End:                                                                             
Contrast this with the default

module ModnameTest;
   InstModule #(.WIDTH(16))
     instName
       (/*AUTOINST*/
        // Outputs                                                                    
        .out   (out[WIDTH-1:0]));
endmodule

// Local Variables:                                                                 
// verilog-auto-inst-param-value:nil
// End:                                                                             
How do I use AUTOINST with Interfaces?¶
AUTOINST will hook interfaces up similar to how normal inputs and outputs connect.

interface svi;
   logic       enable;
   modport master (input enable);
endinterface

module InstModule
  (input      clk,
   svi.master svi_modport,
   svi        svi_nomodport);
endmodule

module top;
   InstModule instName
     (/*AUTOINST*/
      // Interfaces                                    
      .svi_modport         (svi_modport.master),
      .svi_nomodport       (svi_nomodport),
      // Inputs                                        
      .clk                 (clk));
endmodule
You can also use AUTOINOUTMODULE and AUTOINOUTCOMP with interfaced ports.

module autoinst_interface
  (/*AUTOINOUTMODULE("autoinst_interface_sub")*/
   // Beginning of automatic in/out/inouts (from specific module)                   
   input      clk,
   svi.master svi_modport,
   svi        svi_nomodport
   // End of automatics                                                             
   );
endmodule

常用的lisp函数有：

 substring STRING  start  end

 downcase string-or-char

 upcase string-or-char

 capitalize string-or-char   // words 的首字母大写

 store-substring string idx  char     // 用 char 替换 从 idx 开始的 string.   string 长度不变。