These tests are intended to be the examples in the Chisel3 Wiki Cookbook.

Additionally, fix Clock.asUInt (previously, it threw an esoteric exception), and add a simple test of both.

In the Chisel frontend, the implicit clock is named clock, but in the
generated FIRRTL, it is named clk.  There is no reason for this
discrepancy, and yet fixing it is painful, as it will break test harnesses.
Better to take the pain now than later.

Resolves #258.

Add IrrevocableIO subclass of DecoupledIO that promises not to change .bits on a cycle after .valid is high and .ready is low

Fix bug in Printable FullName of submodule port

Printable was using HasId.instanceName to get full names of Chisel nodes.
instanceName uses the parent module of the HasId to get the Component to use in
calling fullName on the underlying Ref. Unfortunately this means that any
reference to a port of a instance will leave off the instance name. Fixing this
required the following:

- Add Component argument to Printable.unpack so that we can call Arg.fullName
  directly in the Printable
- Pass the currently emitting module as the Component to Printable.unpack in
  the Emitter
- Remove ability to create FullName Printables from Modules since the Module
  name is not known until after the printf is already emitted

This commit also updates the PrintableSpec test to check that FullName and
Decimal printing work on ports of instances

Printable is a new type that changes how printing of Chisel types is represented
It uses an ordered collection rather than a format string and specifiers
Features:
 - Custom String Interpolator for Scala-like printf
 - String-like manipulation of "hardware strings" for custom pretty-printing
 - Default pretty-printing for Chisel data types

The O(n) type legality check was redundantly executed n times.  D'oh.

Check that Vecs have homogeneous types

Vec[Element] can have heterogeneous widths.

Vec[Aggregate] cannot (but possibly could relax this by stripping widths
from constituent Elements and relying on width inference).

Public APIs for chisel object names

signalName -> instanceName
SignalId -> InstanceId
Based on Stephen's comments on PR

Removed extraneous logic
Renamed doStuff to buildAnnotatedCircuit
Removed println's

Add AnnotationSpec file which provides an example of a way to implement generation of annotations in a chisel circuit that could be used by custom firrtl passes
This spec also shows and tests in a limited way the new API of .signalName, .pathName, parentModName which allows access to the various path information of a chisel component (something that subclasses SignalId, most prominently SubClasses of Data and Module

* signalName: returns the chirrtl name of the signal

* pathName: returns the full path name of the signal from the top module

* parentPathName: returns the full path of the signal's parent module instance from the top module

* parentModName: returns the signal's parent **module(not instance)** name.

* Make "def width" a private API; expose isWidthKnown instead

Resolves #256.

Since width was used to determine whether getWidth would succeed, I added

    def isWidthKnown: Boolean

but another option would be to expose something like

    def widthOption: Option[Int]

...thoughts?

* Document getWidth/isWidthKnown

* Add widthOption for more idiomatic Scala manipulation of widths

The API allowed this before, but not safely, as users could create
name conflicts.  This exposes the pre-deduplication/sanitization
naming API, and closes the other one.

It's not entirely clear what the FIRRTL implementation supports, so
I'm using the ANSI C requirements for the time being.

This has been deprecated for a long time now (and really shouldn't
have existed to begin with).

Deprecating toBits removes the capability to cast an arbitrary
type to UInt.  While it's still possible to do so using asBits.asUInt,
this creates boilerplate.  (asBits is almost never useful itself.)

For Chisel nodes defined in Module class-level values of type Option or
Iterable, we can still use reflection to assign names based on the name
of the value. This works for arbitrary nesting of Option and Iterable so
long as the innermost type is HasId. Note that this excludes Maps which
always have an innermost type of Tuple2[_,_].

Clean up Scala code, and use +& to generate a lot less FIRRTL

For reasonable circuit delay, need to divide & conquer.

Closes #229

h/t @sdtwigg @davidbiancolin

renamechisel3 - "chisel" -> "chisel3"