[major] Layer-associated probe semantics and ABI

include/firrtl.xml

@@ -27,6 +27,7 @@
       <item>intrinsic</item>
       <item>propassign</item>
       <item>public</item>
+      <item>enablelayer</item>
     </list>
     <list name="types">
       <item>UInt</item>

revision-history.yaml

@@ -16,6 +16,7 @@ revisionHistory:
       - Change the minimum width of the result of "Shift Right" on UInt to 0-bit.
       - Allow assert and assume statements to have a format string
       - Add Property primitive operations, starting with integer addition
+      - Define/clarify layer-colored probe semantics.
     abi:
       - Add ABI for public modules and filelist output.
       - Changed ABI for group and ref generated files.

spec.md

@@ -233,6 +233,7 @@ The types of intrinsic module parameters may only be literal integers or string
 ## Layers
 
 Layers are collections of functionality which will not be present in all executions of a circuit.
+When a layer is enabled, the FIRRTL circuit behaves *as-if* all the optional functionality of that layer was executed.
 Layers are intended to be used to keep verification, debugging, or other collateral, not relevant to the operation of the circuit, in a separate area.
 Each layer can then be optionally included in the resulting design.
 
@@ -260,6 +261,26 @@ circuit Foo :
 Functionality enabled by a layer is put in one or more layer blocks inside modules.
 For more information on layer blocks see [@sec:layer-blocks].
 
+Probe types may be colored with a layer.
+Layer coloring indicates which layers must be enabled for a probe to be used.
+For more information on layer-colored probes see [@sec:probe-types] and [@sec:layer-coloring].
+
+### Modules with Enabled Layers
+
+Modules may be declared with enabled layers.
+A module with enabled layers colors the body of the module with the color of all enabled layers.
+This affects the legality of operations which use probes.
+See [@sec:layer-coloring] for more information on layer coloring.
+
+To declare a module with layers enabled, use the `enablelayer`{.firrtl} keyword.
+The circuit below shows a module with one layer enabled:
+
+``` firrtl
+circuit Foo :
+  layer A, bind :
+  module Foo enablelayer A :
+```
+
 # Circuit Components
 
 Circuit components are the named parts of a module corresponding to hardware.
@@ -687,8 +708,9 @@ Probe<UInt<8>>
 RWProbe<UInt<8>>
 ```
 
-`Probe`{.firrtl} and `RWProbe`{.firrtl} types may be associated with a layer (see [@sec:layers]).
-When associated with a layer, the reference type may only be driven from layer blocks associated with the same layer.
+`Probe`{.firrtl} and `RWProbe`{.firrtl} types may be *colored* with a layer (see [@sec:layers]).
+When *layer-colored*, there are restrictions placed on the use of the probe.
+See [@sec:layer-coloring] for a description of these restrictions.
 
 For example:
 
@@ -2027,19 +2049,16 @@ Since they are intended for verification, ports with a probe type do not necessa
 ## Types
 
 There are two probe types, `Probe<T>`{.firrtl} is a read-only variant and `RWProbe<T>`{.firrtl} is a read-write variant.
-(See [@sec:probe-types]).
+Probes may be layer-colored.
+See [@sec:probe-types] for more information.
 
-Examples:
+## Layer Coloring
 
-``` firrtl
-Probe<UInt<8>>
-RWProbe<UInt<8>>
-```
-
-A `RWProbe<T>`{.firrtl} will be implicitly cast to a `Probe<T>`{.firrtl} whenever an expression of type `RWProbe<T>`{.firrtl} is assigned to a port with type `Probe<T>`{.firrtl}.
+Probe types may be colored with a layer (see [@sec:layers]).
+A layer-colored probe type places restrictions on the operations which use it.
 
-While `RWProbe<T>`{.firrtl} is strictly more powerful, `Probe<T>`{.firrtl} allows for more aggressive optimization.
-You should consider using `Probe`{.firrtl} whenever you know you don't need to ability to force (see [@sec:forcing]).
+An operation may only "read" from a probe whose layer color is enabled when the operation is enabled.
+An operation that "writes" to a probe must be in a region whose layer color is enabled when the probe's layer color is enabled.
 
 ## The `probe`{.firrtl} and `rwprobe`{.firrtl} Expressions
 
@@ -2254,20 +2273,6 @@ module DUT :
   connect y, p
 ```
 
-## Probes and Layers
-
-`Probe`{.firrtl} and `RWProbe`{.firrtl} types may be associated with a layer (see [@sec:layers]).
-When associated with a layer, the probe type may only be driven from that layer.
-
-For example:
-
-``` firrtl
-Probe<UInt<8>, A.B>     ; A.B is a layer
-RWProbe<UInt<8>, A.B>
-```
-
-For details on how probes are lowered, see the FIRRTL ABI Specification.
-
 ## External Modules
 
 Ports with probe types may be specified on the interface of an external module (see [@sec:externally-defined-modules]).