Move presentation intro example

Rework images makefile a bit to get it to import and build from resources folder(s).
Currently requires running twice from a clean build due to the way it finds `.dot` files to convert.

docs/source/getting_started/examples.rst

@@ -13,38 +13,133 @@ synth.v using the cell library described by the Liberty file :
 .. code:: yoscrypt
    :number-lines:
 
-   # read input file to internal representation
+   #. read input file to internal representation
    read_verilog design.v
 
-   # convert high-level behavioral parts ("processes") to d-type flip-flops and muxes
+   #. convert high-level behavioral parts ("processes") to d-type flip-flops and muxes
    proc
 
-   # perform some simple optimizations
+   #. perform some simple optimizations
    opt
 
-   # convert high-level memory constructs to d-type flip-flops and multiplexers
+   #. convert high-level memory constructs to d-type flip-flops and multiplexers
    memory
 
-   # perform some simple optimizations
+   #. perform some simple optimizations
    opt
 
-   # convert design to (logical) gate-level netlists
+   #. convert design to (logical) gate-level netlists
    techmap
 
-   # perform some simple optimizations
+   #. perform some simple optimizations
    opt
 
-   # map internal register types to the ones from the cell library
+   #. map internal register types to the ones from the cell library
    dfflibmap -liberty cells.lib
 
-   # use ABC to map remaining logic to cells from the cell library
+   #. use ABC to map remaining logic to cells from the cell library
    abc -liberty cells.lib
 
-   # cleanup
+   #. cleanup
    opt
 
-   # write results to output file
+   #. write results to output file
    write_verilog synth.v
 
 A detailed description of the commands available in Yosys can be found in
 :ref:`cmd_ref`.
+
+Simple synthesis script
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This section covers an example project available in
+``docs/resources/PRESENTATION_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``).
+
+.. literalinclude:: ../../resources/PRESENTATION_Intro/counter.ys
+   :language: yoscrypt
+   :caption: ``docs/resources/PRESENTATION_Intro/counter.ys``
+
+.. role:: yoscrypt(code)
+   :language: yoscrypt
+
+#. :yoscrypt:`read_verilog counter.v` - Read Verilog source file and convert to
+   internal representation.
+#. :yoscrypt:`hierarchy -check -top counter` - Elaborate the design hierarchy.
+   Should always be the first command after reading the design. Can re-run AST front-end.
+#. :yoscrypt:`proc` - Convert ``processes`` (the internal representation of
+   behavioral Verilog code) into multiplexers and registers.
+#. :yoscrypt:`opt` - Perform some basic optimizations and cleanups.
+#. :yoscrypt:`fsm` - Analyze and optimize finite state machines.
+#. :yoscrypt:`opt` - Perform some basic optimizations and cleanups.
+#. :yoscrypt:`memory` - Analyze memories and create circuits to implement them.
+#. :yoscrypt:`opt` - Perform some basic optimizations and cleanups.
+#. :yoscrypt:`techmap` - Map coarse-grain RTL cells (adders, etc.) to fine-grain
+   logic gates (AND, OR, NOT, etc.).
+#. :yoscrypt:`opt` - Perform some basic optimizations and cleanups.
+#. :yoscrypt:`dfflibmap -liberty mycells.lib` - Map registers to available
+   hardware flip-flops.
+#. :yoscrypt:`abc -liberty mycells.lib` - Map logic to available hardware gates.
+#. :yoscrypt:`clean` - Clean up the design (just the last step of ``opt``).
+#. :yoscrypt:`write_verilog synth.v` - Write final synthesis result to output
+   file.
+
+Running the script
+^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ../../resources/PRESENTATION_Intro/counter.v
+   :language: Verilog
+   :caption: ``docs/resources/PRESENTATION_Intro/counter.v``
+
+.. literalinclude:: ../../resources/PRESENTATION_Intro/mycells.lib
+   :language: Liberty
+   :caption: ``docs/resources/PRESENTATION_Intro/mycells.lib``
+
+Step 1
+""""""
+
+.. literalinclude:: ../../resources/PRESENTATION_Intro/counter.ys
+   :language: yoscrypt
+   :lines: 1-3
+
+Result:
+
+.. figure:: ../../images/res/PRESENTATION_Intro/counter_00.*
+    :class: width-helper
+
+Step 2
+""""""
+
+.. literalinclude:: ../../resources/PRESENTATION_Intro/counter.ys
+   :language: yoscrypt
+   :lines: 5-6
+
+Result:
+
+.. figure:: ../../images/res/PRESENTATION_Intro/counter_01.*
+    :class: width-helper
+
+Step 3
+""""""
+
+.. literalinclude:: ../../resources/PRESENTATION_Intro/counter.ys
+   :language: yoscrypt
+   :lines: 8-9
+
+Result:
+
+.. figure:: ../../images/res/PRESENTATION_Intro/counter_02.*
+    :class: width-helper
+
+Step 4
+""""""
+
+.. literalinclude:: ../../resources/PRESENTATION_Intro/counter.ys
+   :language: yoscrypt
+   :lines: 11-18
+
+Result:
+
+.. figure:: ../../images/res/PRESENTATION_Intro/counter_03.*
+    :class: width-helper

docs/source/introduction.rst

@@ -28,13 +28,37 @@ What is Yosys
 	This document was originally published as bachelor thesis at the Vienna
 	University of Technology :cite:p:`BACC`.
 
-Yosys is a tool for synthesising (behavioural) Verilog HDL code to target
-architecture netlists. Yosys aims at a wide range of application domains and
-thus must be flexible and easy to adapt to new tasks.
+Yosys is a Verilog HDL synthesis tool. This means that it takes a behavioural
+design description as input and generates an RTL, logical gate or physical gate
+level description of the design as output. Yosys' main strengths are behavioural
+and RTL synthesis. A wide range of commands (synthesis passes) exist within
+Yosys that can be used to perform a wide range of synthesis tasks within the
+domain of behavioural, rtl and logic synthesis. Yosys is designed to be
+extensible and therefore is a good basis for implementing custom synthesis tools
+for specialised tasks.
+
+.. figure:: ../images/levels_of_abstraction.*
+    :class: width-helper
+    :name: fig:Levels_of_abstraction
+
+    Where Yosys exists in the layers of abstraction
 
 What you can do with Yosys
 --------------------------
 
+- Read and process (most of) modern Verilog-2005 code
+- Perform all kinds of operations on netlist (RTL, Logic, Gate)
+- Perform logic optimizations and gate mapping with ABC
+
+Things you can't do
+~~~~~~~~~~~~~~~~~~~
+
+- Process high-level languages such as C/C++/SystemC
+- Create physical layouts (place&route)
+  + Check out `nextpnr`_ for that
+
+.. _nextpnr: https://github.com/YosysHQ/nextpnr
+
 The extended Yosys universe
 ---------------------------
 

docs/source/yosys_internals/flow/index.rst

@@ -1,6 +1,16 @@
 Internal flow
 =============
 
+
+A (usually short) synthesis script controls Yosys.
+
+This scripts contain three types of commands:
+
+- **Frontends**, that read input files (usually Verilog);
+- **Passes**, that perform transformations on the design in memory;
+- **Backends**, that write the design in memory to a file (various formats are
+  available: Verilog, BLIF, EDIF, SPICE, BTOR, . . .).
+
 .. toctree:: 
 	:maxdepth: 2