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

@@ -5,7 +5,8 @@
 /images/*.aux
 /images/*.pdf
 /images/*.svg
-/images/011/*.log
-/images/011/*.aux
-/images/011/*.pdf
-/images/011/*.svg
+/images/**/*.log
+/images/**/*.aux
+/images/**/*.pdf
+/images/**/*.svg
+/images/**/*.dot

docs/images/Makefile

@@ -1,9 +1,23 @@
-all: dots tex svg tidy
+all: resources dots tex svg tidy
+
+RES_LIST:= PRESENTATION_Intro/
+RES_DIRS:= $(addprefix ../resources/,$(RES_LIST))
+.PHONY: resources
+resources: $(RES_DIRS)
+FORCE:
+../resources/%: FORCE
+	@$(MAKE) -C $@
+	@mkdir -p res/$*
+	@cp --update -t res/$* $@*.dot
 
 TEX_SOURCE:= $(wildcard *.tex)
 DOT_LOC:= ../source/APPNOTE_011_Design_Investigation
 DOT_SOURCE:= $(wildcard $(DOT_LOC)/*.dot)
 
+RES_DOTS:= $(wildcard res/*/*.dot)
+RES_DIRS:= $(sort $(dir $(RES_DOTS)))
+RES_PDF:= $(RES_DOTS:%.dot=%.pdf)
+
 TEX_SOURCE+= 011/example_out.tex
 011/example_out.pdf: 011/example_00.pdf 011/example_01.pdf 011/example_02.pdf
 TEX_SOURCE+= 011/select_prod.tex
@@ -15,15 +29,18 @@ TEX_SOURCE+= 011/submod_dots.tex
 
 TEX_PDF:= $(patsubst %.tex,%.pdf,$(TEX_SOURCE))
 DOT_PDF:= $(addprefix 011/,$(notdir $(patsubst %.dot,%.pdf,$(DOT_SOURCE))))
-SVG_OUTPUT:= $(patsubst %.pdf,%.svg,$(TEX_PDF) $(DOT_PDF))
+SVG_OUTPUT:= $(patsubst %.pdf,%.svg,$(TEX_PDF) $(DOT_PDF) $(RES_PDF))
 
-dots: $(DOT_PDF)
+dots: $(DOT_PDF) $(RES_PDF)
 tex: $(TEX_PDF)
 svg: $(SVG_OUTPUT)
 
 011/%.pdf: $(DOT_LOC)/%.dot
 	faketime -f '2022-01-01 00:00:00 x0,001' dot -Tpdf -o $@ $<
 
+res/%.pdf: res/%.dot
+	faketime -f '2022-01-01 00:00:00 x0,001' dot -Tpdf -o $@ $<
+
 011/%.pdf: 011/%.tex
 	cd 011 && faketime -f '2022-01-01 00:00:00 x0,001' pdflatex $(<F) --interaction=nonstopmode
 

docs/images/levels_of_abstraction.tex

@@ -0,0 +1,42 @@
+\documentclass[12pt,tikz]{standalone}
+\pdfinfoomitdate 1
+\pdfsuppressptexinfo 1
+\pdftrailerid{}
+\usepackage[utf8]{inputenc}
+\usepackage{amsmath}
+\usepackage{pgfplots}
+\usepackage{tikz}
+\pagestyle{empty}
+\definecolor{MyBlue}{RGB}{85,130,180}
+
+\begin{document}
+\begin{tikzpicture}[scale=1.2, every node/.style={transform shape}]
+    \tikzstyle{lvl} = [draw, fill=MyBlue, rectangle, minimum height=2em, minimum width=15em]
+    \node[lvl] (sys) {System Level};
+    \node[lvl] (hl) [below of=sys] {High Level};
+    \node[lvl] (beh) [below of=hl] {Behavioral Level};
+    \node[lvl] (rtl) [below of=beh] {Register-Transfer Level (RTL)};
+    \node[lvl] (lg) [below of=rtl] {Logical Gate Level};
+    \node[lvl] (pg) [below of=lg] {Physical Gate Level};
+    \node[lvl] (sw) [below of=pg] {Switch Level};
+
+    \draw[dotted] (sys.east)  -- ++(1,0) coordinate (sysx);
+    \draw[dotted] (hl.east)  -- ++(1,0) coordinate (hlx);
+    \draw[dotted] (beh.east) -- ++(1,0) coordinate (behx);
+    \draw[dotted] (rtl.east) -- ++(1,0) coordinate (rtlx);
+    \draw[dotted] (lg.east)  -- ++(1,0) coordinate (lgx);
+    \draw[dotted] (pg.east)  -- ++(1,0) coordinate (pgx);
+    \draw[dotted] (sw.east)  -- ++(1,0) coordinate (swx);
+
+    \draw[gray,|->] (sysx) -- node[right] {System Design} (hlx);
+    \draw[|->|] (hlx) -- node[right] {High Level Synthesis (HLS)} (behx);
+    \draw[->|] (behx) -- node[right] {Behavioral Synthesis} (rtlx);
+    \draw[->|] (rtlx) -- node[right] {RTL Synthesis} (lgx);
+    \draw[->|] (lgx) -- node[right] {Logic Synthesis} (pgx);
+    \draw[gray,->|] (pgx) -- node[right] {Cell Library} (swx);
+
+    \draw[dotted] (behx) -- ++(4,0) coordinate (a);
+    \draw[dotted] (pgx) -- ++(4,0) coordinate (b);
+    \draw[|->|] (a) -- node[right] {Yosys} (b);
+\end{tikzpicture}
+\end{document}

docs/resources/PRESENTATION_Intro/.gitignore

@@ -0,0 +1,8 @@
+counter_00.dot
+counter_01.dot
+counter_02.dot
+counter_03.dot
+counter_00.pdf
+counter_01.pdf
+counter_02.pdf
+counter_03.pdf

docs/resources/PRESENTATION_Intro/Makefile

@@ -0,0 +1,10 @@
+
+all: counter_00.dot counter_01.dot counter_02.dot counter_03.dot
+
+counter_00.dot: counter.v counter.ys mycells.lib
+	../../../yosys counter_outputs.ys
+
+counter_01.dot: counter_00.dot
+counter_02.dot: counter_00.dot
+counter_03.dot: counter_00.dot
+

docs/resources/PRESENTATION_Intro/counter.v

@@ -0,0 +1,12 @@
+module counter (clk, rst, en, count);
+
+	input clk, rst, en;
+	output reg [1:0] count;
+
+	always @(posedge clk)
+		if (rst)
+			count <= 2'd0;
+		else if (en)
+			count <= count + 2'd1;
+
+endmodule

docs/resources/PRESENTATION_Intro/counter.ys

@@ -0,0 +1,21 @@
+# read design
+read_verilog counter.v
+hierarchy -check -top counter
+
+# the high-level stuff
+proc; opt; memory; opt; fsm; opt
+
+# mapping to internal cell library
+techmap; opt
+
+# mapping flip-flops to mycells.lib
+dfflibmap -liberty mycells.lib
+
+# mapping logic to mycells.lib
+abc -liberty mycells.lib
+
+# cleanup
+clean
+
+# write synthesized design
+write_verilog synth.v

docs/resources/PRESENTATION_Intro/counter_outputs.ys

@@ -0,0 +1,27 @@
+# read design
+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
+
+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/resources/PRESENTATION_Intro/mycells.lib

@@ -0,0 +1,38 @@
+library(demo) {
+  cell(BUF) {
+    area: 6;
+    pin(A) { direction: input; }
+    pin(Y) { direction: output;
+              function: "A"; }
+  }
+  cell(NOT) {
+    area: 3;
+    pin(A) { direction: input; }
+    pin(Y) { direction: output;
+              function: "A'"; }
+  }
+  cell(NAND) {
+    area: 4;
+    pin(A) { direction: input; }
+    pin(B) { direction: input; }
+    pin(Y) { direction: output;
+             function: "(A*B)'"; }
+  }
+  cell(NOR) {
+    area: 4;
+    pin(A) { direction: input; }
+    pin(B) { direction: input; }
+    pin(Y) { direction: output;
+             function: "(A+B)'"; }
+  }
+  cell(DFF) {
+    area: 18;
+    ff(IQ, IQN) { clocked_on: C;
+                  next_state: D; }
+    pin(C) { direction: input;
+                 clock: true; }
+    pin(D) { direction: input; }
+    pin(Q) { direction: output;
+              function: "IQ"; }
+  }
+}

docs/resources/PRESENTATION_Intro/mycells.v

@@ -0,0 +1,23 @@
+
+module NOT(A, Y);
+input A;
+output Y = ~A;
+endmodule
+
+module NAND(A, B, Y);
+input A, B;
+output Y = ~(A & B);
+endmodule
+
+module NOR(A, B, Y);
+input A, B;
+output Y = ~(A | B);
+endmodule
+
+module DFF(C, D, Q);
+input C, D;
+output reg Q;
+always @(posedge C)
+	Q <= D;
+endmodule
+

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