From d38aee1156965178af0b44662f45af70dedb6e93 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge <schuyler.eldridge@sifive.com>
Date: Wed, 10 Apr 2024 16:51:06 -0400
Subject: [PATCH] [minor] Add ABI to public module, extmodule

Add a way to specify the port lowering ABI of a public module or an
external module.  This uses syntax like the following:

    public module<v1> Foo:

    extmodule<v2> Bar:

This includes language that indicates that the "v1" ABI is used if no ABI
is specified.  This makes this change fully backwards compatible with
older FIRRTL versions (and thereby a "minor" change).

Fixes #171.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>
---
 abi.md                | 16 ++++++++++++++++
 revision-history.yaml |  3 +++
 spec.md               | 35 +++++++++++++++++++++++++++++++++--
 3 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/abi.md b/abi.md
index e9041f95..7a630116 100644
--- a/abi.md
+++ b/abi.md
@@ -72,6 +72,18 @@ This is done to avoid name collisions with the private modules produced by other
 
 There are two supported port lowering ABIs.
 These ABIs are applicable to public modules or external modules only.
+These ABIs can be specified on each public module or external module using the following syntax:
+
+``` {.firrtl .notest}
+FIRRTL version 4.0.0
+circuit Foo :
+  ;; snippetbegin
+  public module<v1> Foo:
+  extmodule<v2> Bar:
+  ;; snippetend
+```
+
+*Port Lowering ABIv1 is the default lowering for public modules if no port lowering is specified.*
 
 #### Port Lowering ABIv1
 
@@ -117,6 +129,8 @@ This ABI does not specify whether the original aggregate referent is scalarized
 
 All other port types shall lower according ot the type lowering in section ["On Types"](@sec:On-Types).
 
+Port lowering ABIv1 uses the identifier `v1` when explicitly specified on a public module or external module.
+
 #### Port Lowering ABIv2
 
 Ports are lowered per the v1 ABI above, except for aggregate types.
@@ -129,6 +143,8 @@ Passive bundles shall be lowered to Verilog packed structs.
 
 Reference types in ports shall be logically split out from aggregates and named as though "Aggregate Type Lowering" was used.
 
+Port lowering ABIv2 uses the identifier `v2` when explicitly specified on a public module or external module.
+
 ## On Layers
 
 The lowering convention of a declared layer specifies how a layer and all its associated layer blocks will be lowered.
diff --git a/revision-history.yaml b/revision-history.yaml
index 91ad912d..02d3f653 100644
--- a/revision-history.yaml
+++ b/revision-history.yaml
@@ -30,12 +30,15 @@ revisionHistory:
       - Restore id and info in printf grammar, add to verif commands.
       - Add intrinsic expressions and statements.
       - Remove intrinsic modules.
+      - Add ABI to public module and external module.
     abi:
       - Add ABI for public modules and filelist output.
       - Changed ABI for group and ref generated files.
         These now use the public module and not the circuit.
       - Use EBNF to describe probe port macros and filename.
       - Correct mistakes in code examples.
+      - Clarify that ABI v1 is the default ABI if unspecified on a public module
+        or external module.
   # Information about the old versions.  This should be static.
   oldVersions:
     - version: 3.2.0
diff --git a/spec.md b/spec.md
index 43ae58c5..e4a2705e 100644
--- a/spec.md
+++ b/spec.md
@@ -143,6 +143,19 @@ A public module has a number of restrictions:
 3.  A `RWProbe`{.firrtl} may not be used to access a public module's ports.
 4.  A public module may be instantiated by other modules within a circuit, but the behavior of the module must not be affected by these instantiations.
 
+A public module may specify which ABI a compiler must use for a specific public module.
+This can be specified with the syntax below:
+
+``` {.firrtl .notest}
+FIRRTL version 4.0.0
+circuit Foo:
+  ;; snippetbegin
+  public module<v1> Foo:
+  ;; snippetend
+```
+
+If the ABI is unspecified, the ABI for that public module uses the default ABI version as defined in the FIRRTL ABI Specification.
+
 For more information on the lowering of public modules, see the FIRRTL ABI Specification.
 
 ### Private Modules
@@ -225,6 +238,21 @@ Foo #(
 endmodule
 ```
 
+Externally defined modules may specify an explicit lowering ABI using the same syntax as public modules:
+
+``` {.firrtl .notest}
+FIRRTL version 4.0.0
+circuit Foo:
+  public module Foo:
+  ;; snippetbegin
+  extmodule<v2> Bar:
+  ;; snippetend
+```
+
+If the ABI is unspecified, the ABI for that public module uses the default ABI version as defined in the FIRRTL ABI Specification.
+
+For more information on the lowering of public modules, see the FIRRTL ABI Specification.
+
 ## Layers
 
 Layers are collections of functionality which will not be present in all executions of a circuit.
@@ -4169,15 +4197,18 @@ decl =
   | decl_layer
   | decl_type_alias ;
 
+abi =
+  "<" , id , ">" ;
+
 decl_module =
-  [ "public" ], "module" , id , { enablelayer } , ":" , [ info ] ,
+  [ "public" ], "module" , [ abi ] , id , { enablelayer } , ":" , [ info ] ,
     newline , indent ,
     { port , newline } ,
     { statement , newline } ,
   dedent ;
 
 decl_extmodule =
-  "extmodule" , id , ":" , [ info ] , newline , indent ,
+  "extmodule" , [ abi ] , id , ":" , [ info ] , newline , indent ,
     { port , newline } ,
     [ "defname" , "=" , id , newline ] ,
     { "parameter" , id , "=" , type_param , newline } ,