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/code_examples/intro/.gitignore

@@ -0,0 +1 @@
+synth.v

docs/source/code_examples/intro/Makefile

@@ -2,12 +2,12 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-DOTS = counter_00.dot counter_proc.dot counter_01.dot counter_02.dot counter_03.dot
+DOTS = counter_00.dot counter_01.dot counter_02.dot counter_03.dot
 
 dots: $(DOTS)
 
-$(DOTS): counter.v counter_outputs.ys mycells.lib
+$(DOTS): counter.v counter.ys mycells.lib
-	$(YOSYS) counter_outputs.ys
+	$(YOSYS) counter.ys
 
 .PHONY: clean
 clean:

docs/source/code_examples/intro/counter.ys

@@ -2,12 +2,20 @@
 read_verilog counter.v
 hierarchy -check -top counter
 
+show -notitle -format dot -prefix counter_00
+
 # the high-level stuff
-proc; opt; memory; opt; fsm; opt
+proc; opt
+memory; opt
+fsm; opt
+
+show -notitle -format dot -prefix counter_01
 
 # mapping to internal cell library
 techmap; opt
 
+splitnets -ports;; show -notitle -format dot -prefix counter_02
+
 # mapping flip-flops to mycells.lib
 dfflibmap -liberty mycells.lib
 
@@ -17,5 +25,7 @@ abc -liberty mycells.lib
 # cleanup
 clean
 
+show -notitle -lib mycells.v -format dot -prefix counter_03
+
 # write synthesized design
 write_verilog synth.v

docs/source/code_examples/intro/counter_outputs.ys

@@ -1,28 +0,0 @@
-# read
-read_verilog counter.v
-hierarchy -check -top counter
-show -notitle -format dot -prefix counter_00
-
-# elaborate
-proc
-show -notitle -format dot -prefix counter_proc
-
-opt
-show -notitle -format dot -prefix counter_01
-
-# mapping to internal cell library
-techmap; opt
-
-splitnets -ports;;
-show -notitle -format dot -prefix counter_02
-
-# mapping flip-flops to mycells.lib
-dfflibmap -liberty mycells.lib
-
-# mapping logic to mycells.lib
-abc -liberty mycells.lib
-
-# cleanup
-clean
-
-show -notitle -lib mycells.v -format dot -prefix counter_03

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

docs/source/using_yosys/synthesis/index.rst

@@ -12,4 +12,5 @@ Synthesis in detail
    memory
    opt
    abc
+   cell_libs