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

* bug fixes in TopWiring

add description nodes, transform; modify VerilogEmitter to emit comments

[F764.3] Add explicit SystemVerilogCompiler class

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

This adds a SystemVerilogCompiler class that extends, without modifying,
the existing VerilogCompiler. This is used by FIRRTL's Driver and will
cause a warning to be emitted indicating that the SystemVerilogCompiler
behaves the same as the VerilogCompiler.

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

[F764.1] Bump scopt from 3.6.0 -> 3.7.0

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

This provides support for increased introspection of options inside of
scopt, e.g., getting an options short option (shortOpt).

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

* Filter resource file names to avoid including the same file multiple times.
Addresses issue #882.

* Use a Set instead of a Map to filter Verilog files.

* Use canonical paths for file name comparison and unify name generation.
Provide a common method for copying resources to a directory to ensure the same resource ends up with the same name if it's copied by multiple clients.

* Reduce confusion - another absolute -> canonical switch.
Use the canonical path on the verilator command line for the filter additional Verilog sources.

Previously, mems marked no dedup would prevent mems with the same
instance name in other modules from deduping

[764: opts/annos] Easy conversion of String => LogLevel.value

This adds an apply method to the LogLevel object for conversion from a
String to a LogLevel.value.

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

Allow the #delay before random initialization to be overridden

The default of 0.002 can be less than the Verilog time precision, which
effectively causes it to be rounded down to 0.  So, allow the user to
`define RANDOMIZE_DELAY to some other value.

If the macro is not defined, the old behavior is preserved.

* Bump to Scala 2.12.6 and make it the default.

* Use Scala 2.11.12 for chisel tests.

* Try with Scala 2.12.4.

- Fixed edge case file name that starts with . and has no suffix

Fixes #780 

  - makes RemoveWires properly include registers in dependency graph
  - adds an apply method to WRef for DefNode
  - adds a test case requiring register reordering

Fixes a bug where registers could be instantiated after nodes that
referred to them

Also add WRef.apply utility for nodes

* Support for load memory annotations in chisel
This PR
 * Delays the BlackBoxSourceHelper transformation to the Emitter stage of the VerilogCompiler
   * remove from VerilogCompiler
   * move to VerilogEmitter
 * Changes the verilog emitter to allow programmatic access to the verilog module declaration
   * Creating a bindable module requires headers to match
 * Provides a unit test that shows how to generate a bindable module.

* Binding support
Treadle needed LoadMemoryAnnotation to be in firrtl instead of chisel in order to recognize the annotations and use them for memory loading

* Binding support
- Fixed bug that handled suffixes on memory initializing files

* Binding support
- Add a bit more doc to the API provided by the VerilogRenderer

* add FoldADD to const prop, add yosys miter tests

* add option for verilog compiler without optimizations

* rename FoldLogicalOp to FoldCommutativeOp

* add GetNamespace and RenameModules, GetNamespace stores namespace as a ModuleNamespaceAnnotation

* add constant propagation for Tail DoPrims

* add scaladocs for MinimumLowFirrtlOptimization and yosysExpectFalure/Success, add constant propagation for Head DoPrim

* add legalize pass to MinimumLowFirrtlOptimizations, use constPropBitExtract in legalize pass