[minor] Add optional circuit to target syntax (#294)

Change the target syntax to include an optional circuit.  Note: this
change is strange becauase the spec was _always_ incomplete in how it
discussed targets.  It never discussed the circuit, though it showed them
in examples.

Change this so that the circuit name is optional.  This creates a somewhat
funky syntax where targets, which never care about the circuit due to the
co-location of annotation JSON in the circuit, will all be prefixed with
`~|`.  This, while it would be nice to remove, provides a sigil that
avoids conflicts with a legacy, undocumented target format used by Chisel
originally called "named".  This would use the following:

``` ebnf
    circuit , [ '.' , module , ['.' , component ] ]
```

I originally wanted to dorp the `~|` and have all targets start with the
module.  However, this would create an ambiguity with a named circuit.
E.g., a bare `Foo` could be "circuit Foo" or "module Foo".  I am working
to burn this down in Chisel and, after recent changes, Chisel will no
longer emit this.  However, I'd like to let that cook for a while.  Hence,
this is the new syntax.

Conveniently, CIRCT will already parse this due to a pleasntly
permissive (bugby) target parser.

Signed-off-by: Schuyler Eldridge <[email protected]>

Author: seldridge

revision-history.yaml

@@ -5,6 +5,7 @@ revisionHistory:
   # additions to the specification should append entries here.
   thisVersion:
     spec:
+      - Add optional circuit to target syntax.
     abi:
   # Information about the old versions.  This should be static.
   oldVersions:

spec.md

@@ -3439,7 +3439,7 @@ A circuit is described, stored, and optimized in a folded representation.
 For example, there may be multiple instances of a module which will eventually become multiple physical copies of that module on the die.
 
 Targets are a mechanism to identify specific hardware in specific instances of modules in a FIRRTL circuit.
-A target consists of a root module, an optional instance hierarchy, and an optional reference.
+A target consists of an optional circuit, a mandatory root module, an optional instance hierarchy, and an optional reference.
 A target can only identify hardware with a name, e.g., a module, instance, register, wire, or node.
 References may further refer to specific fields or subindices in aggregates.
 A target with no instance hierarchy is local.
@@ -3448,7 +3448,7 @@ A target with an instance hierarchy is non-local.
 Targets use a shorthand syntax of the form:
 
 ``` ebnf
-target = module , [ { “/” (instance) “:” (module) } , [ “>” , ref ] ]
+target = "~" , [ circuit ] , "|" , module , [ { “/” (instance) “:” (module) } , [ “>” , ref ] ]
 ```
 
 A reference is a name inside a module and one or more qualifying tokens that encode subfields (of a bundle) or subindices (of a vector):
@@ -3490,11 +3490,11 @@ Some examples include:
 
 | Target | Description |
 |-------------------------|-----------------------------------------------|
-| `Foo` | refers to module `Foo`{.firrtl} (or the only instance of module `Foo`{.firrtl}) |
-| `Bar` | refers to module `Bar`{.firrtl} (or both instances of module `Bar`{.firrtl}) |
-| `Foo/a:Bar` | refers just to one instance of module `Bar`{.firrtl} |
-| `Foo/b:Bar/c:Baz` | refers to one instance of module `Baz`{.firrtl} |
-| `Bar/d:Baz` | refers to two instances of module `Baz`{.firrtl} |
+| `~|Foo` | refers to module `Foo`{.firrtl} (or the only instance of module `Foo`{.firrtl}) |
+| `~|Bar` | refers to module `Bar`{.firrtl} (or both instances of module `Bar`{.firrtl}) |
+| `~|Foo/a:Bar` | refers just to one instance of module `Bar`{.firrtl} |
+| `~|Foo/b:Bar/c:Baz` | refers to one instance of module `Baz`{.firrtl} |
+| `~|Bar/d:Baz` | refers to two instances of module `Baz`{.firrtl} |
 
 If a target does not contain an instance path, it is a *local* target.
 A local target points to all instances of a module.
@@ -3511,11 +3511,11 @@ The following shows a valid annotation file containing two annotations:
 [
   {
     "class":"hello",
-    "target":"~Foo|Bar"
+    "target":"~|Bar"
   },
   {
     "class":"world",
-    "target":"~Foo|Baz"
+    "target":"~|Baz"
   }
 ]
 ```
@@ -3529,11 +3529,11 @@ FIRRTL version 4.0.0
 circuit Foo: %[[
   {
     "class":"hello",
-    "target":"~Foo|Bar"
+    "target":"~|Bar"
   },
   {
     "class":"world",
-    "target":"~Foo|Baz"
+    "target":"~|Baz"
   }
 ]]
   module Baz :