Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[major] Move Extmodule Params to Instantiation #46

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

[major] Move Extmodule Params to Instantiation #46

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8f79a2b
[major] Move Extmodule Params to Instantiation
seldridge Sep 19, 2022
442b8b2
squash! [major] Move Extmodule Params to Instantiation
seldridge Sep 20, 2022
75126fc
squash! [major] Move Extmodule Params to Instantiation
seldridge Sep 20, 2022
48093c7
fixup! squash! [major] Move Extmodule Params to Instantiation
seldridge Sep 20, 2022
dbb406b
squash! squash! [major] Move Extmodule Params to Instantiation
seldridge Sep 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 36 additions & 15 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,12 +217,9 @@ instance statement for details on how to instantiate a module
## Externally Defined Modules

Externally defined modules are modules whose implementation is not provided in
the current circuit. Only the ports and name of the externally defined module
are specified in the circuit. An externally defined module may include, in
order, an optional _defname_ which sets the name of the external module in the
resulting Verilog and zero or more name--value _parameter_ statements. Each
name--value parameter statement will result in a value being passed to the named
parameter in the resulting Verilog.
the current circuit. Only the ports of the externally defined module are
specified in the circuit. No other statements may exist in the external module
body.

An example of an externally defined module is:

Expand All @@ -231,15 +228,36 @@ extmodule MyExternalModule :
input foo: UInt<2>
output bar: UInt<4>
output baz: SInt<8>
defname = VerilogName
parameter x = "hello"
parameter y = 42
```

The widths of all externally defined module ports must be specified. Width
inference, described in [@sec:width-inference], is not supported for module
ports.

Externally defined modules may have zero or more parameters. Parameters may be
of known-width `UInt`{.firrtl} or `SInt`{.firrtl} types or `String`{.firrtl}
type. The value of a parameter is set at each instantiation of an external
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we mention that they must be passed in declaration order (there is no name-specified parameter passing syntax)

module using a literal value.

An example of a parametric externally defined module and its instantiation is:

``` firrtl
extmodule MyExternalModule2<
parameter x: String,
parameter y: UInt<8>,
parameter z: SInt<4>
> :
; ...
mwachs5 marked this conversation as resolved.
Show resolved Hide resolved
module Top:
inst foo of MyExternalModule2<"hello", UInt<8>(42), SInt<4>(-1)>
inst bar of MyExternalModule2<"world", UInt(0), SInt(-2)>
```

As shown above, it is allowable to use a smaller, unknown width integer type
literal to set a parameter value so long as the width of the underlying
parameter value is large enough to store the literal type. A literal that is
too large for a given parameter type is illegal.

A common use of an externally defined module is to represent a Verilog module
that will be written separately and provided together with FIRRTL-generated
Verilog to downstream tools.
Expand Down Expand Up @@ -2899,8 +2917,8 @@ primop_1expr2int =
primop = primop_2expr | primop_1expr | primop_1expr1int | primop_1expr2int ;

(* Expression definitions *)
expr =
( "UInt" | "SInt" ) , [ width ] , "(" , ( int ) , ")"
int_lit = ( "UInt" | "SInt" ) , [ width ] , "(" , int , ")"
expr = int_lit
| reference
| "mux" , "(" , expr , "," , expr , "," , expr , ")"
| "validif" , "(" , expr , "," , expr , ")"
Expand All @@ -2924,11 +2942,13 @@ memory = "mem" , id , ":" , [ info ] , newline , indent ,
dedent ;

(* Statements *)
parameter = int_lit | string ;
parameter_seq = parameter | parameter , "," , parameter_seq ;
statement = "wire" , id , ":" , type , [ info ]
| "reg" , id , ":" , type , expr ,
[ "(with: {reset => (" , expr , "," , expr ")})" ] , [ info ]
| memory
| "inst" , id , "of" , id , [ info ]
| "inst" , id , "of" , id , [ "<" , parameter_seq , ">" ] , [ info ]
| "node" , id , "=" , expr , [ info ]
| reference , "<=" , expr , [ info ]
| reference , "<-" , expr , [ info ]
Expand All @@ -2948,10 +2968,11 @@ module = "module" , id , ":" , [ info ] , newline , indent ,
{ port , newline } ,
{ statement , newline } ,
dedent ;
extmodule = "extmodule" , id , ":" , [ info ] , newline , indent ,
parameter_decl = "parameter" , id , ":" , type ;
parameter_decl_seq = parameter_decl | parameter_decl , "," , parameter_decl_seq ;
extmodule = "extmodule" , id , [ "<" , parameter_decl_seq , ">" ] , ":" ,
[ info ] , newline , indent ,
{ port , newline } ,
[ "defname" , "=" , id , newline ] ,
{ "parameter" , "=" , ( string | int ) , newline } ,
dedent ;

(* Version definition *)
Expand Down