diff --git a/docs/source/code_examples/intro/.gitignore b/docs/source/code_examples/intro/.gitignore new file mode 100644 index 000000000..9f8173c6d --- /dev/null +++ b/docs/source/code_examples/intro/.gitignore @@ -0,0 +1 @@ +synth.v diff --git a/docs/source/code_examples/intro/Makefile b/docs/source/code_examples/intro/Makefile index 90b91d7a5..e6509681f 100644 --- a/docs/source/code_examples/intro/Makefile +++ b/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 - $(YOSYS) counter_outputs.ys +$(DOTS): counter.v counter.ys mycells.lib + $(YOSYS) counter.ys .PHONY: clean clean: diff --git a/docs/source/code_examples/intro/counter.ys b/docs/source/code_examples/intro/counter.ys index 5582f1b78..e327a6f6b 100644 --- a/docs/source/code_examples/intro/counter.ys +++ b/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 diff --git a/docs/source/code_examples/intro/counter_outputs.ys b/docs/source/code_examples/intro/counter_outputs.ys deleted file mode 100644 index d52934b3f..000000000 --- a/docs/source/code_examples/intro/counter_outputs.ys +++ /dev/null @@ -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 diff --git a/docs/source/using_yosys/synthesis/cell_libs.rst b/docs/source/using_yosys/synthesis/cell_libs.rst new file mode 100644 index 000000000..5f54b894f --- /dev/null +++ b/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 diff --git a/docs/source/using_yosys/synthesis/index.rst b/docs/source/using_yosys/synthesis/index.rst index d062c1c3d..19d302fcc 100644 --- a/docs/source/using_yosys/synthesis/index.rst +++ b/docs/source/using_yosys/synthesis/index.rst @@ -12,4 +12,5 @@ Synthesis in detail memory opt abc + cell_libs