Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

- Adds firrtl.options package and tests
- Does not use firrtl.options in any way

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

This adds a new package, "firrtl.options", that provides a framework for
working with options inside and outside FIRRTL.

Small changes:
  - Make TerminateOnExit return the correct exit code
  - Deprecate mutable TerminateOnExit
  - Add immutable DoNotTermianteOnExit

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

- Add Target.prettyPrint method
- Improve UninferredWidth exception message

This changes the CheckTypes.UniferredWidth exception to include the pretty
printed Target that was uninferred and suggests to the user that they may
have forgotten to assign to it. This changes the CheckTypes pass to
communicate the necessary Target information during AST traversal such
that when an uninferred width is found, the Target is known and available.

This also adds one test checking the message of the UniferredWidth
exception.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

This adds a pretty printer for firrtl.annotation.Target and associated
tests. This uses a tree-like output where the following target
~Circuit|Module/foo:Foo>ref.field[0] will serialize to:

  circuit Circuit:
  └── module Module:
      └── foo of Foo:
          └── ref.field[0]

This enables better error messages and a human readable syntax better than
the existing serialize method (and avoiding the need for users to
understand the Target serialization syntax), but that is not intended to
be deserialized nor space efficient.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

With the newest version of SBT, the commandline `sbt publish-local` should be changed to `sbt publishLocal`.

Adds performance improvements by removing list appends.

It is O(n) and every use is in an O(n) iteration resulting in O(n^2).
Same information can be extracted from create_exps which happens to also
be called at every use of get_flip.

When constructing the black box helper file list (firrtl_black_box_resource_files.f), filter out Verilog header files (*.vh) - Fixes #917

Formerly #865 

Major Code Changes/Features Added:

Added Target trait as replacement for Named
Added TargetToken as token in building Target
Added GenericTarget as a catch-all Target
Added CircuitTarget, ModuleTarget, ReferenceTarget, and InstanceTarget
Added ResolvePaths annotation
Added EliminateTargetPaths (and helper class DuplicationHelper)
Updated Dedup to work with instance annotations
Updated RenameMap to work with instance annotations
DCE & ConstantProp extend ResolveAnnotationPaths

- Travis unshallow if shallow clone breaks ancestry

This makes "skip chisel tests" work properly

This reverts commit 7e2f787e.

Added Target, which now supports Instance Annotations. See #865 for details.

Better error message on missing BlackBox resource

This wraps interactions with a BlackBox resource file such that a
FileNotFoundException are wrapped in a BlackBoxNotFoundException and
rethrown. This provides a better, verbose error message to the user and avoids a
FileNotFoundException showing up as an internal FIRRTL error.

This adds tests that the expected exception is thrown for both
BlackBoxResourceAnno and BlackBoxResourceAnno.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

Verilog renaming uses "_", works on whole AST

This moves VerilogRename out of Passes.scala and genericizes it as the new
Transform KemoveKeywordCollisions. This new Transform will remove keywords
for arbitrary sets of reserved keyword.

This adds VerilogRename back as a class instead of an object.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

Summary of changes to firrtl.passes.VerilogRename:
  - Use "_" to mangle names that conflict with Verilog
    keywords (previously "$")
  - Rewrite to operate on the whole AST to propogate mangled ports and
    module names
  - Make VerilogRename a Transform (was previously a Pass)
  - Renames are now propagated
  - Adds documentation for new VerilogRename

This makes the VerilogRename Transform (previously a Pass) use an
underscore ('_') instead of a dollar sign ('$') to mangle names that
conflict with Verilog keywords. This prevents problems with potentially
buggy tools that are not expecting '$' in Verilog names.

This reimplements VerilogRename to be safe for name collisions that may
occur anywhere in the AST, e.g., in ports, module names, circuit names, or
in any statements/expressions. Previously, names were only mangled in
statements and in place. This resulted in problems where renames of ports
in a child's namespace would not be guaranteed to be mangled the same way
in a parent's namespace. The algorithm is reimplemented to walk all
modules in reverse topological order (from leafs to main) and relying on a
RenameMap to track name changes.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

Use "_" for Inline Name Mangling, Respect Namespaces

Summary of changes:
  - Use "_" as an inlining delimiter instead of "$"
  - Makes inlining avoid namespace conflicts

This changes the delimiter used for inlining to "_" instead of "$". This
avoids problems with buggy parsers that may not handle "$" correctly. As
ClockListTransform relies on the explicit use of "$", the delimiter is a
FIRRTL-private val that the ClockListTransform overrides (to the original
"$").

Namespace conflicts could occur previously, but are very rare as users
will almost never use "$" in a name (even though it's allowed by both the
FIRRTL and Verilog specifications). Moving to "_" increases the
probability of namespace conflicts occurring. This adds explicit checking
that inlined names will not introduce namespace conflicts and that
generated names are prefix unique (as defined in the spec).

Note: inlined modules may not have unique prefixes. A test is included
that this is the case and an ignored test shows what prefix uniqueness
would look like.

MISC:
  - [skip chisel tests]: Changing the delimiter causes the Chisel
    InlineSpec to fail as this explicitly checks for "$".

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

This makes findValidPrefix and enumerateNames both private to
FIRRTL (previously, these were private). This enables their use for name
generation by other FIRRTL passes/transforms.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

This adds a method, cloneUnderlying, to Namespace that returns a copy of
the underlying mutable.HashSet. This is useful for constructing a
Namespace that you would like to manipulate manually without using
Namespace's methods to generate temporaries.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Merge makefile changes from dev/specification-fixes

- New top level makefile target: `specification`
  - Builds the specification document.

* Number all code examples.

This is more a change of convenience than anything. Referring to syntax
examples is much easier when they are numbered!

This commit is in the context of freechipsproject/firrtl#890 - Updating
examples and syntax specification is made easier if they are numbered.

- Change `verbatim` environments to `lstlisting`
- Add very basic keyword highlighting.
- Rebuild specification PDF.

 On branch dev/number-code-examples
 Changes to be committed:
	modified:   spec/spec.pdf
	modified:   spec/spec.tex

This adds a utility, expandPrefixes, that expands a string into all
possible prefixes based on a delimiter. Any repeated occurrence of the
delimiter is viewed as a contributing to a prefix. E.g., "foo_bar" expands
to Seq("foo_", "foo_bar"). This is useful for inlining and keyword
mangling on LowForm. You would like to be able to generate a new name that
is prefix unique with respect to a namespace.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

Enforce port uniqueness in Chirrtl/High Checks

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

When different levels of the circuit were annotated, the TopWiring signals of the lower levels would "run-over" the TopWiring signals of the higher levels