Various documentation updates

CodingReadme

@@ -159,6 +159,7 @@ Then with default config setting:
 	cd ~yosys
 	./yosys -p 'proc; show' tests/simple/fiedler-cooley.v
 	./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v
+	./yosys -p 'synth; show' tests/simple/fiedler-cooley.v
 
 	cd ~yosys
 	make manual

manual/CHAPTER_Appnotes.tex

@@ -2,11 +2,24 @@
 \chapter{Application Notes}
 \label{chapter:appnotes}
 
-\begin{fixme}
+% \begin{fixme}
-This appendix will cover some typical use-cases of Yosys in the form of application notes.
+% This appendix will cover some typical use-cases of Yosys in the form of application notes.
-\end{fixme}
+% \end{fixme}
+% 
+% \section{Synthesizing using a Cell Library in Liberty Format}
+% \section{Reverse Engeneering the MOS6502 from an NMOS Transistor Netlist}
+% \section{Reconfigurable Coarse-Grain Synthesis using Intersynth}
 
-\section{Synthesizing using a Cell Library in Liberty Format}
+This appendix contains copies of the Yosys application notes.
-\section{Reverse Engeneering the MOS6502 from an NMOS Transistor Netlist}
+
-\section{Reconfigurable Coarse-Grain Synthesis using Intersynth}
+\begin{itemize}
+\item Yosys AppNote 010: Converting Verilog to BLIF \dotfill Page \pageref{app:010} \hskip2cm\null
+\item Yosys AppNote 011: Interactive Design Investigation \dotfill Page \pageref{app:011} \hskip2cm\null
+\end{itemize}
+
+\eject\label{app:010}
+\includepdf[pages=-,pagecommand=\thispagestyle{plain}]{APPNOTE_010_Verilog_to_BLIF.pdf}
+
+\eject\label{app:011}
+\includepdf[pages=-,pagecommand=\thispagestyle{plain}]{APPNOTE_011_Design_Investigation.pdf}
 

manual/CHAPTER_Auxprogs.tex

@@ -17,3 +17,9 @@ The {\tt yosys-filterlib} tool is a small utility that can be used to strip
 or extract information from a Liberty file. See Sec.~\ref{sec:techmap_extern}
 for details.
 
+\section{yosys-abc}
+
+This is a unmodified copy of ABC \citeweblink{ABC}. Not all versions of Yosys
+work with all versions of ABC. So Yosys comes with its own yosys-abc to avoid
+compatibility issues between the two.
+

manual/PRESENTATION_ExAdv.tex

@@ -790,7 +790,7 @@ Unwrap in {\tt test2}:
 
 \hfil\begin{tikzpicture}
 \node at (0,0) {\includegraphics[width=11cm,trim=1.5cm 1.5cm 1.5cm 1.5cm]{PRESENTATION_ExAdv/macc_xilinx_test2d.pdf}};
-\node at (0,-4) {\includegraphics[width=11cm,trim=1.5cm 1.5cm 1.5cm 1.5cm]{PRESENTATION_ExAdv/macc_xilinx_test2e.pdf}};
+\node at (0,-4) {\includegraphics[width=8cm,trim=1.5cm 1.5cm 1.5cm 1.5cm]{PRESENTATION_ExAdv/macc_xilinx_test2e.pdf}};
 \node at (1,-1.7) {\begin{lstlisting}[linewidth=5.5cm, frame=single, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
 techmap -map macc_xilinx_unwrap_map.v ;;
 \end{lstlisting}};

manual/PRESENTATION_ExOth/axis_master.v

@@ -13,7 +13,7 @@ module axis_master(aclk, aresetn, tvalid, tready, tdata);
 	    if (tvalid && tready)
 	    	tvalid <= 0;
 	    if (!tvalid || !tready) begin
-	    //             ^- should be not inverted!
+	    //             ^- should not be inverted!
                 state = state ^ state << 13;
                 state = state ^ state >> 7;
                 state = state ^ state << 17;

manual/PRESENTATION_ExSyn.tex

@@ -268,7 +268,7 @@ memory -nomap; techmap -map my_memory_map.v; memory_map
 \end{frame}
 
 \begin{frame}[t, fragile]{\subsecname{} -- Example 1/2}
-\vbox to 0cm{\includegraphics[width=\linewidth,trim=0cm 0cm 0cm -10cm]{PRESENTATION_ExSyn/memory_01.pdf}\vss}
+\vbox to 0cm{\includegraphics[width=\linewidth,trim=0cm 0cm 0cm -6cm]{PRESENTATION_ExSyn/memory_01.pdf}\vss}
 \vskip-1cm
 \begin{columns}
 \column[t]{5cm}
@@ -455,7 +455,7 @@ read_verilog -D WITH_MULT cpu_alu.v
 hierarchy -check -top cpu_top
 
 # high-level synthesis
-proc; opt; memory -nomap;; fsm; opt
+proc; opt; fsm;; memory -nomap; opt
 
 # substitute block rams
 techmap -map map_rams.v
@@ -497,7 +497,7 @@ the next part (Section 3, ``Advanced Synthesis'') of this presentation.}
 \item Yosys provides commands for each phase of the synthesis.
 \item Each command solves a (more or less) simple problem.
 \item Complex commands are often only front-ends to simple commands.
-\item {\tt proc; opt; memory; opt; fsm; opt; techmap; opt; abc;;}
+\item {\tt proc; opt; fsm; opt; memory; opt; techmap; opt; abc;;}
 \end{itemize}
 
 \bigskip

manual/PRESENTATION_Intro.tex

@@ -277,7 +277,7 @@ Direct link to the files: \\ \footnotesize
 
 \medskip
 {\color{YosysGreen}\# the high-level stuff}\\
-\boxalert<3>{proc}; \boxalert<4>{opt}; \boxalert<5>{memory}; \boxalert<6>{opt}; \boxalert<7>{fsm}; \boxalert<8>{opt}
+\boxalert<3>{proc}; \boxalert<4>{opt}; \boxalert<5>{fsm}; \boxalert<6>{opt}; \boxalert<7>{memory}; \boxalert<8>{opt}
 
 \medskip
 {\color{YosysGreen}\# mapping to internal cell library}\\
@@ -308,9 +308,9 @@ Direct link to the files: \\ \footnotesize
 \only<2>{hierarchy -check -top counter}%
 \only<3>{proc}%
 \only<4>{opt}%
-\only<5>{memory}%
+\only<5>{fsm}%
 \only<6>{opt}%
-\only<7>{fsm}%
+\only<7>{memory}%
 \only<8>{opt}%
 \only<9>{techmap}%
 \only<10>{opt}%
@@ -333,13 +333,13 @@ Direct link to the files: \\ \footnotesize
 	Perform some basic optimizations and cleanups.
 }%
 \only<5>{
-	Analyze memories and create circuits to implement them.
+	Analyze and optimize finite state machines.
 }%
 \only<6>{
 	Perform some basic optimizations and cleanups.
 }%
 \only<7>{
-	Analyze and optimize finite state machines.
+	Analyze memories and create circuits to implement them.
 }%
 \only<8>{
 	Perform some basic optimizations and cleanups.
@@ -398,7 +398,7 @@ hierarchy -check -top counter
 
 \begin{frame}[t, fragile]{\subsecname{} -- Step 2/4}
 \begin{verbatim}
-proc; opt; memory; opt; fsm; opt
+proc; opt; fsm; opt; memory; opt
 \end{verbatim}
 
 \vfill
@@ -427,6 +427,48 @@ clean
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+\subsection{The synth command}
+
+\begin{frame}[fragile]{\subsecname{}}
+Yosys contains a default (recommended example) synthesis script in form of the
+{\tt synth} command. The following commands are executed by this synthesis command:
+
+\begin{columns}
+\column[t]{5cm}
+\begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
+begin:
+    hierarchy -check [-top <top>]
+
+coarse:
+    proc
+    opt
+    wreduce
+    alumacc
+    share
+    opt
+    fsm
+    opt -fast
+    memory -nomap
+    opt_clean
+\end{lstlisting}
+\column[t]{5cm}
+\begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
+fine:
+    opt -fast -full
+    memory_map
+    opt -full
+    techmap
+    opt -fast
+
+abc:
+    abc -fast
+    opt -fast
+\end{lstlisting}
+\end{columns}
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \subsection{Yosys Commands}
 
 \begin{frame}[fragile]{\subsecname{} 1/3 \hspace{0pt plus 1 filll} (excerpt)}
@@ -500,6 +542,7 @@ Commands for writing the results:
 \bigskip
 Script-Commands for standard synthesis tasks:
 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
+    synth                # generic synthesis script
     synth_xilinx         # synthesis for Xilinx FPGAs
 \end{lstlisting}
 
@@ -603,12 +646,8 @@ endmodule
 
 \begin{frame}{\subsecname}
 \begin{itemize}
-\item Multi-dimensional arrays (memories)
-\item Writing to arrays using bit- and part-selects (todo for 0.4.0)
-\item The wor/wand wire types (maybe for 0.4.0)
 \item Tri-state logic
-
+\item The wor/wand wire types (maybe for 0.5)
-\bigskip
 \item Latched logic (is synthesized as logic with feedback loops)
 \item Some non-synthesizable features that should be ignored in synthesis are not supported by the parser and cause a parser error (file a bug report if you encounter this problem)
 \end{itemize}
@@ -813,10 +852,12 @@ control logic because it is simpler than setting up a commercial flow.
 \item When building on other Linux distributions:
 \begin{itemize}
 \item Needs compiler with some C++11 support
+\item See README file for build instructions
 \item Post to the subreddit if you get stuck
 \end{itemize}
 \item Ported to OS X (Darwin) and OpenBSD
-\item No win32 support (yet)
+\item Native win32 build with VisualStudio
+\item Cross win32 build with MXE
 \end{itemize}
 \end{frame}
 

manual/PRESENTATION_Prog.tex

@@ -89,12 +89,13 @@ left with a much simpler version of RTLIL:
 \bigskip
 Many commands simply choose to only work on this simpler version:
 \begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont]
-if (module->processes.size() != 0 || module->memories.size() != 0)
+for (RTLIL::Module *module : design->selected_modules() {
-    log_error("This command does not operate on modules with processes "
+    if (module->has_memories_warn() || module->has_processes_warn())
-              "and/or memories! Run 'proc' and 'memory' first.\n");
+        continue;
+    ....
+}
 \end{lstlisting}
 
-\bigskip
 For simplicity we only discuss this version of RTLIL in this presentation.
 \end{frame}
 
@@ -145,7 +146,9 @@ See {\tt yosys/kernel/rtlil.h} for details.
 \subsubsection{RTLIL::IdString}
 
 \begin{frame}{\subsubsecname}{}
-{\tt RTLIL::IdString} is a simple wrapper for {\tt std::string}. It is used for names of RTLIL objects.
+{\tt RTLIL::IdString} in many ways behave like a {\tt std::string}. It is used
+for names of RTLIL objects. Internally a RTLIL::IdString object is only a
+single integer.
 
 \medskip
 The first character of a {\tt RTLIL::IdString} specifies if the name is {\it public\/} or {\it private\/}:
@@ -168,25 +171,25 @@ Use the {\tt NEW\_ID} macro to create a new unique private name.
 
 \begin{frame}[t, fragile]{\subsubsecname}
 The {\tt RTLIL::Design} and {\tt RTLIL::Module} structs are the top-level RTLIL
-data structures.
+data structures. Yosys always operates on one active design, but can hold many designs in memory.
-
-Yosys always operates on one active design, but can hold many designs in memory.
 
 \bigskip
 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 struct RTLIL::Design {
-    std::map<RTLIL::IdString, RTLIL::Module*> modules;
+    std::map<RTLIL::IdString, RTLIL::Module*> modules_;
     ...
 };
 
 struct RTLIL::Module {
     RTLIL::IdString name;
-    std::map<RTLIL::IdString, RTLIL::Wire*> wires;
+    std::map<RTLIL::IdString, RTLIL::Wire*> wires_;
-    std::map<RTLIL::IdString, RTLIL::Cell*> cells;
+    std::map<RTLIL::IdString, RTLIL::Cell*> cells_;
-    std::vector<RTLIL::SigSig> connections;
+    std::vector<RTLIL::SigSig> connections_;
     ...
 };
 \end{lstlisting}
+
+(Use the various accessor functions instead of directly working with the {\tt *\_} members.)
 \end{frame}
 
 \subsubsection{The RTLIL::Wire Structure}
@@ -251,21 +254,22 @@ constants are part of the RTLIL representation itself.
 
 \begin{frame}[t, fragile]{\subsubsecname}
 The {\tt RTLIL::SigSpec} struct represents a signal vector. Each bit can either be a bit from a wire
-or a constant value. Consecutive bits from a wire or consecutive constant bits are consolidated into
+or a constant value.
-a {\tt RTLIL::SigChunk}:
 
 \bigskip
 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
-struct RTLIL::SigChunk {
+struct RTLIL::SigBit
+{
     RTLIL::Wire *wire;
-    RTLIL::Const data; // only used if wire == NULL
+    union {
-    int width, offset;
+        RTLIL::State data; // used if wire == NULL
+        int offset;        // used if wire != NULL
+    };
     ...
 };
 
 struct RTLIL::SigSpec {
-    std::vector<RTLIL::SigChunk> chunks; // LSB at index 0
+    std::vector<RTLIL::SigBit> bits_; // LSB at index 0
-    int width;
     ...
 };
 \end{lstlisting}
@@ -289,7 +293,7 @@ instances:
 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 struct RTLIL::Cell {
     RTLIL::IdString name, type;
-    std::map<RTLIL::IdString, RTLIL::SigSpec> connections;
+    std::map<RTLIL::IdString, RTLIL::SigSpec> connections_;
     std::map<RTLIL::IdString, RTLIL::Const> parameters;
     ...
 };
@@ -345,7 +349,7 @@ typedef std::pair<RTLIL::SigSpec, RTLIL::SigSpec> RTLIL::SigSig;
 
 struct RTLIL::Module {
     ...
-    std::vector<RTLIL::SigSig> connections;
+    std::vector<RTLIL::SigSig> connections_;
     ...
 };
 \end{lstlisting}
@@ -354,8 +358,8 @@ struct RTLIL::Module {
 {\tt RTLIL::SigSig::first} is the driven signal and {\tt RTLIL::SigSig::second} is the driving signal.
 Example usage (setting wire {\tt foo} to value {\tt 42}):
 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
-module->connections.push_back(RTLIL::SigSig(module->wires.at("\\foo"),
+module->connect(module->wire("\\foo"),
-        RTLIL::SigSpec(42, module->wires.at("\\foo")->width)));
+                RTLIL::SigSpec(42, module->wire("\\foo")->width));
 \end{lstlisting}
 \end{frame}
 
@@ -378,17 +382,19 @@ endmodule
 RTLIL::Module *module = new RTLIL::Module;
 module->name = "\\absval";
 
-RTLIL::Wire *a = module->new_wire(4, "\\a");
+RTLIL::Wire *a = module->addWire("\\a", 4);
 a->port_input = true;
 a->port_id = 1;
 
-RTLIL::Wire *y = module->new_wire(4, "\\y");
+RTLIL::Wire *y = module->addWire("\\y", 4);
 y->port_output = true;
 y->port_id = 2;
 
-RTLIL::Wire *a_inv = module->new_wire(4, NEW_ID);
+RTLIL::Wire *a_inv = module->addWire(NEW_ID, 4);
 module->addNeg(NEW_ID, a, a_inv, true);
 module->addMux(NEW_ID, a, a_inv, RTLIL::SigSpec(a, 1, 3), y);
+
+module->fixup_ports();
 \end{lstlisting}
 \end{frame}
 
@@ -431,8 +437,8 @@ In this case {\tt a}, {\tt x}, and {\tt y} are all different names for the same
 
 \smallskip
 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
-RTLIL::SigSpec a(module->wires.at("\\a")), x(module->wires.at("\\x")),
+RTLIL::SigSpec a(module->wire("\\a")), x(module->wire("\\x")),
-                                           y(module->wires.at("\\y"));
+                                       y(module->wire("\\y"));
 log("%d %d %d\n", a == x, x == y, y == a); // will print "0 0 0"
 \end{lstlisting}
 
@@ -462,9 +468,9 @@ log("Mapped signal x: %s\n", log_signal(sigmap(x)));
 \end{lstlisting}
 
 \medskip
-Use {\tt RTLIL::id2cstr()} to create a C-string for an {\tt RTLIL::IdString}:
+Use {\tt log\_id()} to create a C-string for an {\tt RTLIL::IdString}:
 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
-log("Name of this module: %s\n", RTLIL::id2cstr(module->name));
+log("Name of this module: %s\n", log_id(module->name));
 \end{lstlisting}
 
 \medskip
@@ -513,9 +519,8 @@ a new yosys command:
 
 \bigskip
 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
-#include "kernel/rtlil.h"
+#include "kernel/yosys.h"
-#include "kernel/register.h"
+USING_YOSYS_NAMESPACE
-#include "kernel/log.h"
 
 struct MyPass : public Pass {
     MyPass() : Pass("my_cmd", "just a simple test") { }
@@ -526,9 +531,9 @@ struct MyPass : public Pass {
             log("  %s\n", arg.c_str());
 
         log("Modules in current design:\n");
-        for (auto &mod : design->modules)
+        for (auto mod : design->modules())
-            log("  %s (%zd wires, %zd cells)\n", RTLIL::id2cstr(mod.first),
+            log("  %s (%d wires, %d cells)\n", log_id(mod),
-                    mod.second->wires.size(), mod.second->cells.size());
+                    GetSize(mod->wires), GetSize(mod->cells));
     }
 } MyPass;
 \end{lstlisting}
@@ -566,7 +571,7 @@ yosys -m ./my_cmd.so -p 'my_cmd foo bar'
 \item \dots and even simpler if you don't need RTLIL::Memory or RTLIL::Process objects.
 
 \bigskip
-\item Writing synthesis software? Consider learning the Yosys API and make your stuff
+\item Writing synthesis software? Consider learning the Yosys API and make your work
 part of the Yosys framework.
 \end{itemize}
 

manual/PRESENTATION_Prog/my_cmd.cc

@@ -1,6 +1,9 @@
 #include "kernel/yosys.h"
 #include "kernel/sigtools.h"
 
+USING_YOSYS_NAMESPACE
+PRIVATE_NAMESPACE_BEGIN
+
 struct MyPass : public Pass {
     MyPass() : Pass("my_cmd", "just a simple test") { }
     virtual void execute(std::vector<std::string> args, RTLIL::Design *design)
@@ -25,6 +28,7 @@ struct Test1Pass : public Pass {
             log_error("A module with the name absval already exists!\n");
 
         RTLIL::Module *module = design->addModule("\\absval");
+        log("Name of this module: %s\n", log_id(module));
 
         RTLIL::Wire *a = module->addWire("\\a", 4);
         a->port_input = true;
@@ -38,7 +42,7 @@ struct Test1Pass : public Pass {
         module->addNeg(NEW_ID, a, a_inv, true);
         module->addMux(NEW_ID, a, a_inv, RTLIL::SigSpec(a, 3), y);
 
-        log("Name of this module: %s\n", log_id(module));
+	module->fixup_ports();
     }
 } Test1Pass;
 
@@ -69,3 +73,4 @@ struct Test2Pass : public Pass {
     }
 } Test2Pass;
 
+PRIVATE_NAMESPACE_END

manual/manual.tex

@@ -61,6 +61,7 @@ bookmarksopen=false%
 \usepackage{multibib}
 \usepackage{multirow}
 \usepackage{booktabs}
+\usepackage{pdfpages}
 
 \usepackage{listings}
 \usepackage{pifont}
@@ -202,7 +203,7 @@ YOSYS       & Yosys Open SYnthesis Suite \\
 \include{CHAPTER_Verilog}
 \include{CHAPTER_Optimize}
 \include{CHAPTER_Techmap}
-\include{CHAPTER_Eval}
+% \include{CHAPTER_Eval}
 
 \appendix
 
@@ -214,7 +215,7 @@ YOSYS       & Yosys Open SYnthesis Suite \\
 \input{command-reference-manual}
 
 \include{CHAPTER_Appnotes}
-\include{CHAPTER_StateOfTheArt}
+% \include{CHAPTER_StateOfTheArt}
 
 \bibliography{literature}
 \bibliographystyle{alphadin}

manual/presentation.sh

@@ -24,6 +24,8 @@ done
 
 PDFTEX_OPT="-shell-escape -halt-on-error"
 
+set -ex
+
 if ! $fast_mode; then
 	md5sum *.aux *.snm *.nav *.toc > autoloop.old
 	make -C PRESENTATION_Intro

manual/presentation.tex

@@ -133,7 +133,7 @@ I like writing open source software. For example:
 \item OpenSCAD (now maintained by Marius Kintel)
 \item SPL (a not very popular scripting language)
 \item EmbedVM (a very simple compiler+vm for 8 bit micros)
-\item Lib(X)SVF (a library to play SVF/XSVF files over JTAG, used at LHC)
+\item Lib(X)SVF (a library to play SVF/XSVF files over JTAG)
 \item ROCK Linux (discontinued since 2010)
 \end{itemize}
 \end{frame}