yosys/manual/PRESENTATION_ExAdv.tex

\section{Yosys by example -- Advanced Synthesis}

\begin{frame}
\sectionpage
\end{frame}

\begin{frame}{Overview}
This section contains 4 subsections:
\begin{itemize}
\item Using selections
\item Advanced uses of techmap
\item Coarse-grain synthesis
\item Automatic design changes
\end{itemize}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Using selections}

\begin{frame}
\subsectionpage
\subsectionpagesuffix
\end{frame}

\subsubsection{Simple selections}

\begin{frame}[fragile]{\subsubsecname}
Most Yosys commands make use of the ``selection framework'' of Yosys. It can be used
to apply commands only to part of the design. For example:

\medskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
delete                # will delete the whole design, but

delete foobar         # will only delete the module foobar.
\end{lstlisting}

\bigskip
The {\tt select} command can be used to create a selection for subsequent
commands. For example:

\medskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
select foobar         # select the module foobar
delete                # delete selected objects
select -clear         # reset selection (select whole design)
\end{lstlisting}
\end{frame}

\subsubsection{Selection by object name}

\begin{frame}[fragile]{\subsubsecname}
The easiest way to select objects is by object name. This is usually only done
in synthesis scripts that are hand-tailored for a specific design.

\bigskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
select foobar         # select module foobar
select foo*           # select all modules whose names start with foo
select foo*/bar*      # select all objects matching bar* from modules matching foo*
select */clk          # select objects named clk from all modules
\end{lstlisting}
\end{frame}

\subsubsection{Module and design context}

\begin{frame}[fragile]{\subsubsecname}
Commands can be executed in {\it module\/} or {\it design\/} context. Until now all
commands have been executed in design context. The {\tt cd} command can be used
to switch to module context.

\bigskip
In module context all commands only effect the active module. Objects in the module
are selected without the {\tt <module\_name>/} prefix. For example:

\bigskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
cd foo                # switch to module foo
delete bar            # delete object foo/bar

cd mycpu              # switch to module mycpu
dump reg_*            # print details on all objects whose names start with reg_

cd ..                 # switch back to design
\end{lstlisting}

\bigskip
Note: Most synthesis script never switch to module context. But it is a very powerful
tool for interactive design investigation.
\end{frame}

\subsubsection{Selecting by object property or type}

\begin{frame}[fragile]{\subsubsecname}
Special pattern can be used to select by object property or type. For example:

\bigskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
select w:reg_*        # select all wires whose names start with reg_
select a:foobar       # select all objects with the attribute foobar set
select a:foobar=42    # select all objects with the attribute foobar set to 42
select A:blabla       # select all module with the attribute blabla set
select foo/t:$add     # select all $add cells from the module foo
\end{lstlisting}

\bigskip
A complete list of this pattern expressions can be found in the command
reference to the {\tt select} command.
\end{frame}

\subsubsection{Combining selection}

\begin{frame}[fragile]{\subsubsecname}
When more than one selection expression is used in one statement they are
pushed on a stack. At the final elements on the stack are combined into a union:

\medskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
select t:$dff r:WIDTH>1     # all cells of type $dff and/or with a parameter WIDTH > 1
\end{lstlisting}

\bigskip
Special \%-commands can be used to combine the elements on the stack:

\medskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
select t:$dff r:WIDTH>1 %i  # all cells of type $dff *AND* with a parameter WIDTH > 1
\end{lstlisting}

\medskip
\begin{block}{Examples for {\tt \%}-codes (see {\tt help select} for full list)}
{\tt \%u} \dotfill union of top two elements on stack -- pop 2, push 1 \\
{\tt \%d} \dotfill difference of top two elements on stack -- pop 2, push 1 \\
{\tt \%i} \dotfill intersection of top two elements on stack -- pop 2, push 1 \\
{\tt \%n} \dotfill inverse of top element on stack -- pop 1, push 1 \\
\end{block}
\end{frame}

\subsubsection{Expanding selections}

\begin{frame}[fragile]{\subsubsecname}
Selections of cells and wires can be expanded along connections using {\tt \%}-codes
for selecting input cones ({\tt \%ci}), output cones ({\tt \%co}), or both ({\tt \%x}).

\medskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
# select all wires that are inputs to $add cells
select t:$add %ci w:* %i
\end{lstlisting}

\bigskip
Additional constraints such as port names can be specified.

\medskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
# select all wires that connect a "Q" output with a "D" input
select c:* %co:+[Q] w:* %i c:* %ci:+[D] w:* %i %i

# select the multiplexer tree that drives the signal 'state'
select state %ci*:+$mux,$pmux[A,B,Y]
\end{lstlisting}

\bigskip
See {\tt help select} for full documentation of this expressions.
\end{frame}

\subsubsection{Incremental selection}

\begin{frame}[fragile]{\subsubsecname}
Sometime a selection can most easily described by a series of add/delete operations.
For the commands {\tt select -add} and {\tt select -del} add or remove objects
from the current selection instead of overwriting it.

\medskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
select -none            # start with an empty selection
select -add reg_*       # select a bunch of objects
select -del reg_42      # but not this one
select -add state %ci   # and add mor stuff
\end{lstlisting}

\bigskip
Within a select expression the token {\tt \%} can be used to push the previous selection
on the stack.

\medskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
select t:$add t:$sub    # select all $add and $sub cells
select % %ci % %d       # select only the input wires to those cells
\end{lstlisting}
\end{frame}

\subsubsection{Creating selection variables}

\begin{frame}[fragile]{\subsubsecname}
Selections can be stored under a name with the {\tt select -set <name>}
command. The stored selections can be used in later select expressions
using the syntax {\tt @<name>}.

\medskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
select -set cone_a state_a %ci*:-$dff  # set @cone_a to the input cone of state_a
select -set cone_b state_b %ci*:-$dff  # set @cone_b to the input cone of state_b
select @cone_a @cone_b %i              # select the objects that are in both cones
\end{lstlisting}

\bigskip
Remember that select expressions can also be used directly as arguments to most
commands. Some commands also except a single select argument to some options.
In those cases selection variables must be used to capture more complex selections.

\medskip
\begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys]
dump @cone_a @cone_b

select -set cone_ab @cone_a @cone_b %i
show -color red @cone_ab -color magenta @cone_a -color blue @cone_b
\end{lstlisting}
\end{frame}

\begin{frame}[fragile]{\subsubsecname{} -- Example}
\begin{columns}
\column[t]{4cm}
\lstinputlisting[basicstyle=\ttfamily\fontsize{6pt}{7pt}\selectfont, language=verilog]{PRESENTATION_ExAdv/select_01.v}
\column[t]{7cm}
\lstinputlisting[basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys, frame=single]{PRESENTATION_ExAdv/select_01.ys}
\end{columns}
\hfil\includegraphics[width=\linewidth,trim=0 0cm 0 0cm]{PRESENTATION_ExAdv/select_01.pdf}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Advanced uses of techmap}

\begin{frame}
\subsectionpage
\subsectionpagesuffix
\end{frame}

\subsubsection{TBD}

\begin{frame}{\subsubsecname}
TBD
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Coarse-grain synthesis}

\begin{frame}
\subsectionpage
\subsectionpagesuffix
\end{frame}

\subsubsection{TBD}

\begin{frame}{\subsubsecname}
TBD
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Automatic design changes}

\begin{frame}
\subsectionpage
\subsectionpagesuffix
\end{frame}

\subsubsection{TBD}

\begin{frame}{\subsubsecname}
TBD
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Summary}

\begin{frame}{\subsecname}
\begin{itemize}
\item TBD
\item TBD
\item TBD
\item TBD
\end{itemize}

\bigskip
\bigskip
\begin{center}
Questions?
\end{center}

\bigskip
\bigskip
\begin{center}
\url{http://www.clifford.at/yosys/}
\end{center}
\end{frame}