Add cell_libs.rst

Updates code examples, removing `counter_outputs.ys` in favour of a single script.  Also adds a .gitignore for the output file `synth.v`.
`example_synth.rst` still pending updated example.

docs/source/using_yosys/synthesis/cell_libs.rst

@@ -0,0 +1,129 @@
+Mapping to cell libraries
+-------------------------
+
+.. role:: yoscrypt(code)
+   :language: yoscrypt
+
+While much of this documentation focuses on the use of Yosys with FPGAs, it is
+also possible to map to cell libraries which can be used in designing ASICs.
+This section will cover a brief `example project`_, available in the Yosys
+source code as ``docs/source/code_examples/intro/*``.  The project contains a
+simple ASIC synthesis script (``counter.ys``), a digital design written in
+Verilog (``counter.v``), and a simple CMOS cell library (``mycells.lib``).  Many
+of the early steps here are already covered in more detail in the
+:doc:`/getting_started/example_synth` document.
+
+.. note::
+
+   The ``counter.ys`` script includes the commands used to generate the images
+   in this document.  Code snippets in this document skip these commands;
+   including line numbers to allow the reader to follow along with the source.
+   
+   To learn more about these commands, check out :ref:`interactive_show`.
+
+.. _example project: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/intro
+
+A simple counter
+~~~~~~~~~~~~~~~~
+
+First, let's quickly look at the design:
+
+.. literalinclude:: /code_examples/intro/counter.v
+   :language: Verilog
+   :linenos:
+   :name: counter-v
+   :caption: ``counter.v``
+
+This is a simple counter with reset and enable.  If the reset signal, ``rst``,
+is high then the counter will reset to 0.  Otherwise, if the enable signal,
+``en``, is high then the ``count`` register will increment by 1 each rising edge
+of the clock, ``clk``.  
+
+Loading the design
+~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: /code_examples/intro/counter.ys
+   :language: yoscrypt
+   :lines: 1-3
+   :lineno-match:
+   :caption: ``counter.ys`` - read design
+
+Our circuit now looks like this:
+
+.. figure:: /_images/code_examples/intro/counter_00.*
+   :class: width-helper
+   :name: counter-hierarchy
+
+   ``counter`` after :cmd:ref:`hierarchy`
+
+Coarse-grain representation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: /code_examples/intro/counter.ys
+   :language: yoscrypt
+   :lines: 7-10
+   :lineno-match:
+   :caption: ``counter.ys`` - the high-level stuff
+
+.. figure:: /_images/code_examples/intro/counter_01.*
+   :class: width-helper
+
+   Coarse-grain representation of the ``counter`` module
+
+Logic gate mapping
+~~~~~~~~~~~~~~~~~~
+
+.. TODO:: comment on similarities and/or differences with example_synth
+
+.. literalinclude:: /code_examples/intro/counter.ys
+   :language: yoscrypt
+   :lines: 14-15
+   :lineno-match:
+   :caption: ``counter.ys`` - mapping to internal cell library
+
+.. figure:: /_images/code_examples/intro/counter_02.*
+   :class: width-helper
+
+   ``counter`` after :cmd:ref:`techmap`
+
+Mapping to hardware
+~~~~~~~~~~~~~~~~~~~
+
+.. todo:: are we recalling or is this new information
+
+For this example, we are using a Liberty file to describe a cell library which
+our internal cell library will be mapped to:
+
+.. literalinclude:: /code_examples/intro/mycells.lib
+   :language: Liberty
+   :linenos:
+   :name: mycells-lib
+   :caption: ``mycells.lib``
+
+Recall that the Yosys built-in logic gate types are ``$_NOT_``, ``$_AND_``,
+``$_OR_``, ``$_XOR_``, and ``$_MUX_`` with an assortment of dff memory types.
+:ref:`mycells-lib` defines our target cells as ``BUF``, ``NOT``, ``NAND``,
+``NOR``, and ``DFF``.  Mapping between these is performed with the commands
+:cmd:ref:`dfflibmap` and :cmd:ref:`abc` as follows:
+
+.. literalinclude:: /code_examples/intro/counter.ys
+   :language: yoscrypt
+   :lines: 20-27
+   :lineno-match:
+   :caption: ``counter.ys`` - mapping to hardware
+
+The final version of our ``counter`` module looks like this:
+
+.. figure:: /_images/code_examples/intro/counter_03.*
+   :class: width-helper
+
+   ``counter`` after hardware cell mapping
+
+Before finally being output as a verilog file with :cmd:ref:`write_verilog`,
+which can then be loaded into another tool:
+
+.. literalinclude:: /code_examples/intro/counter.ys
+   :language: yoscrypt
+   :lines: 30-31
+   :lineno-match:
+   :caption: ``counter.ys`` - write synthesized design