From 8e4a4c5147a729ef98cdd6d9c0b21000eaf3ce42 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 fde94352..64c99cba 100644
--- a/revision-history.yaml
+++ b/revision-history.yaml
@@ -26,12 +26,15 @@ revisionHistory:
       - Main module must be public.
       - Make commas mandatory, not whitespace.
       - Update intrinsic module example to use a real intrinsic.
+      - 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 ecd0c5d4..4c36711c 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.
+
 ## Implementation Defined Modules (Intrinsics)
 
 Intrinsic modules are modules which represent implementation-defined, compiler-provided functionality.
@@ -4130,15 +4158,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 } ,