diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/APPNOTE_010_Verilog_to_BLIF.tex | 8 | ||||
| -rw-r--r-- | manual/APPNOTE_011_Design_Investigation.tex | 6 | ||||
| -rw-r--r-- | manual/APPNOTE_012_Verilog_to_BTOR.tex | 6 | ||||
| -rw-r--r-- | manual/CHAPTER_Auxlibs.tex | 4 | ||||
| -rw-r--r-- | manual/CHAPTER_CellLib.tex | 393 | ||||
| -rw-r--r-- | manual/CHAPTER_Overview.tex | 26 | ||||
| -rw-r--r-- | manual/CHAPTER_Prog.tex | 11 | ||||
| -rw-r--r-- | manual/CHAPTER_StateOfTheArt/simlib_yosys.v | 2 | ||||
| -rw-r--r-- | manual/CHAPTER_TextRtlil.tex | 299 | ||||
| -rw-r--r-- | manual/CHAPTER_Verilog.tex | 5 | ||||
| -rw-r--r-- | manual/PRESENTATION_ExAdv.tex | 2 | ||||
| -rw-r--r-- | manual/PRESENTATION_ExOth.tex | 2 | ||||
| -rw-r--r-- | manual/PRESENTATION_ExSyn.tex | 2 | ||||
| -rw-r--r-- | manual/PRESENTATION_Intro.tex | 22 | ||||
| -rw-r--r-- | manual/PRESENTATION_Prog.tex | 7 | ||||
| -rw-r--r-- | manual/PRESENTATION_Prog/Makefile | 2 | ||||
| -rw-r--r-- | manual/command-reference-manual.tex | 2073 | ||||
| -rw-r--r-- | manual/literature.bib | 8 | ||||
| -rw-r--r-- | manual/manual.tex | 8 | ||||
| -rw-r--r-- | manual/presentation.tex | 6 | ||||
| -rw-r--r-- | manual/weblinks.bib | 12 |
21 files changed, 2401 insertions, 503 deletions
diff --git a/manual/APPNOTE_010_Verilog_to_BLIF.tex b/manual/APPNOTE_010_Verilog_to_BLIF.tex index 0ecdf6194..16254d593 100644 --- a/manual/APPNOTE_010_Verilog_to_BLIF.tex +++ b/manual/APPNOTE_010_Verilog_to_BLIF.tex @@ -52,7 +52,7 @@ \begin{document} \title{Yosys Application Note 010: \\ Converting Verilog to BLIF} -\author{Clifford Wolf \\ November 2013} +\author{Claire Xenia Wolf \\ November 2013} \maketitle \begin{abstract} @@ -437,12 +437,12 @@ design to fit a certain need without actually touching the RTL code. \begin{thebibliography}{9} \bibitem{yosys} -Clifford Wolf. The Yosys Open SYnthesis Suite. \\ -\url{http://www.clifford.at/yosys/} +Claire Xenia Wolf. The Yosys Open SYnthesis Suite. \\ +\url{https://yosyshq.net/yosys/} \bibitem{bigsim} yosys-bigsim, a collection of real-world Verilog designs for regression testing purposes. \\ -\url{https://github.com/cliffordwolf/yosys-bigsim} +\url{https://github.com/YosysHQ/yosys-bigsim} \bibitem{navre} Sebastien Bourdeauducq. Navr\'e AVR clone (8-bit RISC). \\ diff --git a/manual/APPNOTE_011_Design_Investigation.tex b/manual/APPNOTE_011_Design_Investigation.tex index 9780c7833..881212fe9 100644 --- a/manual/APPNOTE_011_Design_Investigation.tex +++ b/manual/APPNOTE_011_Design_Investigation.tex @@ -54,7 +54,7 @@ \begin{document} \title{Yosys Application Note 011: \\ Interactive Design Investigation} -\author{Clifford Wolf \\ Original Version December 2013} +\author{Claire Xenia Wolf \\ Original Version December 2013} \maketitle \begin{abstract} @@ -1041,8 +1041,8 @@ framework for new algorithms alike. \begin{thebibliography}{9} \bibitem{yosys} -Clifford Wolf. The Yosys Open SYnthesis Suite. -\url{http://www.clifford.at/yosys/} +Claire Xenia Wolf. The Yosys Open SYnthesis Suite. +\url{https://yosyshq.net/yosys/} \bibitem{graphviz} Graphviz - Graph Visualization Software. diff --git a/manual/APPNOTE_012_Verilog_to_BTOR.tex b/manual/APPNOTE_012_Verilog_to_BTOR.tex index 1bc277876..aabdc63c4 100644 --- a/manual/APPNOTE_012_Verilog_to_BTOR.tex +++ b/manual/APPNOTE_012_Verilog_to_BTOR.tex @@ -52,7 +52,7 @@ \begin{document} \title{Yosys Application Note 012: \\ Converting Verilog to BTOR} -\author{Ahmed Irfan and Clifford Wolf \\ April 2015} +\author{Ahmed Irfan and Claire Xenia Wolf \\ April 2015} \maketitle \begin{abstract} @@ -410,8 +410,8 @@ verification benchmarks with or without memories from Verilog designs. \begin{thebibliography}{9} \bibitem{yosys} -Clifford Wolf. The Yosys Open SYnthesis Suite. \\ -\url{http://www.clifford.at/yosys/} +Claire Xenia Wolf. The Yosys Open SYnthesis Suite. \\ +\url{https://yosyshq.net/yosys/} \bibitem{boolector} Robert Brummayer and Armin Biere, Boolector: An Efficient SMT Solver for Bit-Vectors and Arrays\\ diff --git a/manual/CHAPTER_Auxlibs.tex b/manual/CHAPTER_Auxlibs.tex index 440ea1375..b3041078f 100644 --- a/manual/CHAPTER_Auxlibs.tex +++ b/manual/CHAPTER_Auxlibs.tex @@ -22,7 +22,7 @@ ConstEval} class provided in {\tt kernel/consteval.h}. \label{sec:SubCircuit} The files in {\tt libs/subcircuit} provide a library for solving the subcircuit -isomorphism problem. It is written by Clifford Wolf and based on the Ullmann +isomorphism problem. It is written by C. Wolf and based on the Ullmann Subgraph Isomorphism Algorithm \cite{UllmannSubgraphIsomorphism}. It is used by the {\tt extract} pass (see {\tt help extract} or Sec.~\ref{cmd:extract}). @@ -30,6 +30,6 @@ the {\tt extract} pass (see {\tt help extract} or Sec.~\ref{cmd:extract}). The files in {\tt libs/ezsat} provide a library for simplifying generating CNF formulas for SAT solvers. It also contains bindings of MiniSAT. The ezSAT -library is written by Clifford Wolf. It is used by the {\tt sat} pass (see +library is written by C. Wolf. It is used by the {\tt sat} pass (see {\tt help sat} or Sec.~\ref{cmd:sat}). diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex index 25adcda86..3c9fb31cc 100644 --- a/manual/CHAPTER_CellLib.tex +++ b/manual/CHAPTER_CellLib.tex @@ -221,6 +221,26 @@ calculated signal and a constant zero with an {\tt \$and} gate). \subsection{Registers} +SR-type latches are represented by {\tt \$sr} cells. These cells have input ports +\B{SET} and \B{CLR} and an output port \B{Q}. They have the following parameters: + +\begin{itemize} +\item \B{WIDTH} \\ +The width of inputs \B{SET} and \B{CLR} and output \B{Q}. + +\item \B{SET\_POLARITY} \\ +The set input bits are active-high if this parameter has the value {\tt 1'b1} and active-low +if this parameter is {\tt 1'b0}. + +\item \B{CLR\_POLARITY} \\ +The reset input bits are active-high if this parameter has the value {\tt 1'b1} and active-low +if this parameter is {\tt 1'b0}. +\end{itemize} + +Both set and reset inputs have separate bits for every output bit. +When both the set and reset inputs of an {\tt \$sr} cell are active for a given bit +index, the reset input takes precedence. + D-type flip-flops are represented by {\tt \$dff} cells. These cells have a clock port \B{CLK}, an input port \B{D} and an output port \B{Q}. The following parameters are available for {\tt \$dff} cells: @@ -267,26 +287,24 @@ The state of \B{Q} will be set to this value when the reset is active. Note that the {\tt \$adff} and {\tt \$sdff} cells can only be used when the reset value is constant. -D-type flip-flops with asynchronous set and reset are represented by {\tt \$dffsr} cells. -As the {\tt \$dff} cells they have \B{CLK}, \B{D} and \B{Q} ports. In addition they also have -a single-bit \B{SET} input port for the set pin, a single-bit \B{CLR} input port for the reset pin, -and the following two parameters: +D-type flip-flops with asynchronous load are represented by {\tt \$aldff} cells. As the {\tt \$dff} +cells they have \B{CLK}, \B{D} and \B{Q} ports. In addition they also have a single-bit \B{ALOAD} +input port for the async load enable pin, a \B{AD} input port with the same width as data for +the async load data, and the following additional parameter: \begin{itemize} -\item \B{SET\_POLARITY} \\ -The set input is active-high if this parameter has the value {\tt 1'b1} and active-low -if this parameter is {\tt 1'b0}. - -\item \B{CLR\_POLARITY} \\ -The reset input is active-high if this parameter has the value {\tt 1'b1} and active-low +\item \B{ALOAD\_POLARITY} \\ +The asynchronous load is active-high if this parameter has the value {\tt 1'b1} and active-low if this parameter is {\tt 1'b0}. \end{itemize} -When both the set and reset inputs of a {\tt \$dffsr} cell are active, the reset input takes -precedence. +D-type flip-flops with asynchronous set and reset are represented by {\tt \$dffsr} cells. +As the {\tt \$dff} cells they have \B{CLK}, \B{D} and \B{Q} ports. In addition they also have +multi-bit \B{SET} and \B{CLR} input ports and the corresponding polarity parameters, like +{\tt \$sr} cells. -D-type flip-flops with enable are represented by {\tt \$dffe}, {\tt \$adffe}, {\tt \$dffsre}, -{\tt \$sdffe}, and {\tt \$sdffce} cells, which are enhanced variants of {\tt \$dff}, {\tt \$adff}, {\tt \$dffsr}, +D-type flip-flops with enable are represented by {\tt \$dffe}, {\tt \$adffe}, {\tt \$aldffe}, {\tt \$dffsre}, +{\tt \$sdffe}, and {\tt \$sdffce} cells, which are enhanced variants of {\tt \$dff}, {\tt \$adff}, {\tt \$aldff}, {\tt \$dffsr}, {\tt \$sdff} (with reset over enable) and {\tt \$sdff} (with enable over reset) cells, respectively. They have the same ports and parameters as their base cell. In addition they also have a single-bit \B{EN} input port for the enable pin and the following parameter: @@ -297,27 +315,53 @@ The enable input is active-high if this parameter has the value {\tt 1'b1} and a if this parameter is {\tt 1'b0}. \end{itemize} -\begin{fixme} -Add information about {\tt \$sr} cells (set-reset flip-flops), {\tt \$dlatch} cells (d-type latches), -{\tt \$adlatch} and {\tt \$dlatchsr} cells (d-type latches with set/reset). -\end{fixme} +D-type latches are represented by {\tt \$dlatch} cells. These cells have an enable port \B{EN}, +an input port \B{D}, and an output port \B{Q}. The following parameters are available for {\tt \$dlatch} cells: + +\begin{itemize} +\item \B{WIDTH} \\ +The width of input \B{D} and output \B{Q}. + +\item \B{EN\_POLARITY} \\ +The enable input is active-high if this parameter has the value {\tt 1'b1} and active-low +if this parameter is {\tt 1'b0}. +\end{itemize} + +The latch is transparent when the \B{EN} input is active. + +D-type latches with reset are represented by {\tt \$adlatch} cells. In addition to {\tt \$dlatch} +ports and parameters, they also have a single-bit \B{ARST} input port for the reset pin and the following additional parameters: + +\begin{itemize} +\item \B{ARST\_POLARITY} \\ +The asynchronous reset is active-high if this parameter has the value {\tt 1'b1} and active-low +if this parameter is {\tt 1'b0}. + +\item \B{ARST\_VALUE} \\ +The state of \B{Q} will be set to this value when the reset is active. +\end{itemize} + +D-type latches with set and reset are represented by {\tt \$dlatchsr} cells. +In addition to {\tt \$dlatch} ports and parameters, they also have multi-bit +\B{SET} and \B{CLR} input ports and the corresponding polarity parameters, like +{\tt \$sr} cells. \subsection{Memories} \label{sec:memcells} -Memories are either represented using RTLIL::Memory objects, {\tt \$memrd}, {\tt \$memwr}, and {\tt \$meminit} -cells, or by {\tt \$mem} cells alone. +Memories are either represented using RTLIL::Memory objects, {\tt \$memrd\_v2}, {\tt \$memwr\_v2}, and {\tt \$meminit\_v2} +cells, or by {\tt \$mem\_v2} cells alone. In the first alternative the RTLIL::Memory objects hold the general metadata for the memory (bit width, -size in number of words, etc.) and for each port a {\tt \$memrd} (read port) or {\tt \$memwr} (write port) +size in number of words, etc.) and for each port a {\tt \$memrd\_v2} (read port) or {\tt \$memwr\_v2} (write port) cell is created. Having individual cells for read and write ports has the advantage that they can be consolidated using resource sharing passes. In some cases this drastically reduces the number of required -ports on the memory cell. In this alternative, memory initialization data is represented by {\tt \$meminit} cells, +ports on the memory cell. In this alternative, memory initialization data is represented by {\tt \$meminit\_v2} cells, which allow delaying constant folding for initialization addresses and data until after the frontend finishes. -The {\tt \$memrd} cells have a clock input \B{CLK}, an enable input \B{EN}, an -address input \B{ADDR}, and a data output \B{DATA}. They also have the -following parameters: +The {\tt \$memrd\_v2} cells have a clock input \B{CLK}, an enable input \B{EN}, an +address input \B{ADDR}, a data output \B{DATA}, an asynchronous reset input \B{ARST}, +and a synchronous reset input \B{SRST}. They also have the following parameters: \begin{itemize} \item \B{MEMID} \\ @@ -327,7 +371,9 @@ The name of the RTLIL::Memory object that is associated with this read port. The number of address bits (width of the \B{ADDR} input port). \item \B{WIDTH} \\ -The number of data bits (width of the \B{DATA} output port). +The number of data bits (width of the \B{DATA} output port). Note that this may be a power-of-two +multiple of the underlying memory's width -- such ports are called wide ports and access an aligned +group of cells at once. In this case, the corresponding low bits of \B{ADDR} must be tied to 0. \item \B{CLK\_ENABLE} \\ When this parameter is non-zero, the clock is used. Otherwise this read port is asynchronous and @@ -337,12 +383,37 @@ the \B{CLK} input is not used. Clock is active on the positive edge if this parameter has the value {\tt 1'b1} and on the negative edge if this parameter is {\tt 1'b0}. -\item \B{TRANSPARENT} \\ -If this parameter is set to {\tt 1'b1}, a read and write to the same address in the same cycle will -return the new value. Otherwise the old value is returned. +\item \B{TRANSPARENCY\_MASK} \\ +This parameter is a bitmask of write ports that this read port is transparent with. The bits +of this parameter are indexed by the write port's \B{PORTID} parameter. Transparency can only be +enabled between synchronous ports sharing a clock domain. When transparency is enabled for a given +port pair, a read and write to the same address in the same cycle will return the new value. +Otherwise the old value is returned. + +\item \B{COLLISION\_X\_MASK} \\ +This parameter is a bitmask of write ports that have undefined collision behavior with this port. +The bits of this parameter are indexed by the write port's \B{PORTID} parameter. This behavior can only be +enabled between synchronous ports sharing a clock domain. When undefined collision is enabled for a given +port pair, a read and write to the same address in the same cycle will return the undefined (all-X) value. +This option is exclusive (for a given port pair) with the transparency option. + +\item \B{ARST\_VALUE} \\ +Whenever the \B{ARST} input is asserted, the data output will be reset to this value. +Only used for synchronous ports. + +\item \B{SRST\_VALUE} \\ +Whenever the \B{SRST} input is synchronously asserted, the data output will be reset to this value. +Only used for synchronous ports. + +\item \B{INIT\_VALUE} \\ +The initial value of the data output, for synchronous ports. + +\item \B{CE\_OVER\_SRST} \\ +If this parameter is non-zero, the \B{SRST} input is only recognized when \B{EN} is true. +Otherwise, \B{SRST} is recognized regardless of \B{EN}. \end{itemize} -The {\tt \$memwr} cells have a clock input \B{CLK}, an enable input \B{EN} (one +The {\tt \$memwr\_v2} cells have a clock input \B{CLK}, an enable input \B{EN} (one enable bit for each data bit), an address input \B{ADDR} and a data input \B{DATA}. They also have the following parameters: @@ -354,7 +425,9 @@ The name of the RTLIL::Memory object that is associated with this write port. The number of address bits (width of the \B{ADDR} input port). \item \B{WIDTH} \\ -The number of data bits (width of the \B{DATA} output port). +The number of data bits (width of the \B{DATA} output port). Like with {\tt \$memrd\_v2} cells, +the width is allowed to be any power-of-two multiple of memory width, with the corresponding +restriction on address. \item \B{CLK\_ENABLE} \\ When this parameter is non-zero, the clock is used. Otherwise this write port is asynchronous and @@ -364,12 +437,20 @@ the \B{CLK} input is not used. Clock is active on positive edge if this parameter has the value {\tt 1'b1} and on the negative edge if this parameter is {\tt 1'b0}. -\item \B{PRIORITY} \\ -The cell with the higher integer value in this parameter wins a write conflict. +\item \B{PORTID} \\ +An identifier for this write port, used to index write port bit mask parameters. + +\item \B{PRIORITY\_MASK} \\ +This parameter is a bitmask of write ports that this write port has priority over in case of writing +to the same address. The bits of this parameter are indexed by the other write port's \B{PORTID} parameter. +Write ports can only have priority over write ports with lower port ID. When two ports write to the same +address and neither has priority over the other, the result is undefined. Priority can only be set between +two synchronous ports sharing the same clock domain. \end{itemize} -The {\tt \$meminit} cells have an address input \B{ADDR} and a data input \B{DATA}, with the width -of the \B{DATA} port equal to \B{WIDTH} parameter times \B{WORDS} parameter. Both of the inputs +The {\tt \$meminit\_v2} cells have an address input \B{ADDR}, a data input \B{DATA}, with the width +of the \B{DATA} port equal to \B{WIDTH} parameter times \B{WORDS} parameter, and a bit enable mask input +\B{EN} with width equal to \B{WIDTH} parameter. All three of the inputs must resolve to a constant for synthesis to succeed. \begin{itemize} @@ -390,17 +471,17 @@ The cell with the higher integer value in this parameter wins an initialization \end{itemize} The HDL frontend models a memory using RTLIL::Memory objects and asynchronous -{\tt \$memrd} and {\tt \$memwr} cells. The {\tt memory} pass (i.e.~its various sub-passes) migrates -{\tt \$dff} cells into the {\tt \$memrd} and {\tt \$memwr} cells making them synchronous, then -converts them to a single {\tt \$mem} cell and (optionally) maps this cell type +{\tt \$memrd\_v2} and {\tt \$memwr\_v2} cells. The {\tt memory} pass (i.e.~its various sub-passes) migrates +{\tt \$dff} cells into the {\tt \$memrd\_v2} and {\tt \$memwr\_v2} cells making them synchronous, then +converts them to a single {\tt \$mem\_v2} cell and (optionally) maps this cell type to {\tt \$dff} cells for the individual words and multiplexer-based address decoders for the read and -write interfaces. When the last step is disabled or not possible, a {\tt \$mem} cell is left in the design. +write interfaces. When the last step is disabled or not possible, a {\tt \$mem\_v2} cell is left in the design. -The {\tt \$mem} cell provides the following parameters: +The {\tt \$mem\_v2} cell provides the following parameters: \begin{itemize} \item \B{MEMID} \\ -The name of the original RTLIL::Memory object that became this {\tt \$mem} cell. +The name of the original RTLIL::Memory object that became this {\tt \$mem\_v2} cell. \item \B{SIZE} \\ The number of words in the memory. @@ -417,26 +498,56 @@ The initial memory contents. \item \B{RD\_PORTS} \\ The number of read ports on this memory cell. +\item \B{RD\_WIDE\_CONTINUATION} \\ +This parameter is \B{RD\_PORTS} bits wide, containing a bitmask of ``wide continuation'' read ports. +Such ports are used to represent the extra data bits of wide ports in the combined cell, and must +have all control signals identical with the preceding port, except for address, which must have +the proper sub-cell address encoded in the low bits. + \item \B{RD\_CLK\_ENABLE} \\ This parameter is \B{RD\_PORTS} bits wide, containing a clock enable bit for each read port. \item \B{RD\_CLK\_POLARITY} \\ This parameter is \B{RD\_PORTS} bits wide, containing a clock polarity bit for each read port. -\item \B{RD\_TRANSPARENT} \\ -This parameter is \B{RD\_PORTS} bits wide, containing a transparent bit for each read port. +\item \B{RD\_TRANSPARENCY\_MASK} \\ +This parameter is \B{RD\_PORTS*WR\_PORTS} bits wide, containing a concatenation of all +\B{TRANSPARENCY\_MASK} values of the original {\tt \$memrd\_v2} cells. + +\item \B{RD\_COLLISION\_X\_MASK} \\ +This parameter is \B{RD\_PORTS*WR\_PORTS} bits wide, containing a concatenation of all +\B{COLLISION\_X\_MASK} values of the original {\tt \$memrd\_v2} cells. + +\item \B{RD\_CE\_OVER\_SRST} \\ +This parameter is \B{RD\_PORTS} bits wide, determining relative synchronous reset and enable priority for each read port. + +\item \B{RD\_INIT\_VALUE} \\ +This parameter is \B{RD\_PORTS*WIDTH} bits wide, containing the initial value for each synchronous read port. + +\item \B{RD\_ARST\_VALUE} \\ +This parameter is \B{RD\_PORTS*WIDTH} bits wide, containing the asynchronous reset value for each synchronous read port. + +\item \B{RD\_SRST\_VALUE} \\ +This parameter is \B{RD\_PORTS*WIDTH} bits wide, containing the synchronous reset value for each synchronous read port. \item \B{WR\_PORTS} \\ The number of write ports on this memory cell. +\item \B{WR\_WIDE\_CONTINUATION} \\ +This parameter is \B{WR\_PORTS} bits wide, containing a bitmask of ``wide continuation'' write ports. + \item \B{WR\_CLK\_ENABLE} \\ This parameter is \B{WR\_PORTS} bits wide, containing a clock enable bit for each write port. \item \B{WR\_CLK\_POLARITY} \\ This parameter is \B{WR\_PORTS} bits wide, containing a clock polarity bit for each write port. + +\item \B{WR\_PRIORITY\_MASK} \\ +This parameter is \B{WR\_PORTS*WR\_PORTS} bits wide, containing a concatenation of all +\B{PRIORITY\_MASK} values of the original {\tt \$memwr\_v2} cells. \end{itemize} -The {\tt \$mem} cell has the following ports: +The {\tt \$mem\_v2} cell has the following ports: \begin{itemize} \item \B{RD\_CLK} \\ @@ -451,6 +562,12 @@ This input is \B{RD\_PORTS}*\B{ABITS} bits wide, containing all address signals \item \B{RD\_DATA} \\ This input is \B{RD\_PORTS}*\B{WIDTH} bits wide, containing all data signals for the read ports. +\item \B{RD\_ARST} \\ +This input is \B{RD\_PORTS} bits wide, containing all asynchronous reset signals for the read ports. + +\item \B{RD\_SRST} \\ +This input is \B{RD\_PORTS} bits wide, containing all synchronous reset signals for the read ports. + \item \B{WR\_CLK} \\ This input is \B{WR\_PORTS} bits wide, containing all clock signals for the write ports. @@ -464,11 +581,11 @@ This input is \B{WR\_PORTS}*\B{ABITS} bits wide, containing all address signals This input is \B{WR\_PORTS}*\B{WIDTH} bits wide, containing all data signals for the write ports. \end{itemize} -The {\tt memory\_collect} pass can be used to convert discrete {\tt \$memrd}, {\tt \$memwr}, and {\tt \$meminit} cells -belonging to the same memory to a single {\tt \$mem} cell, whereas the {\tt memory\_unpack} pass performs the inverse operation. +The {\tt memory\_collect} pass can be used to convert discrete {\tt \$memrd\_v2}, {\tt \$memwr\_v2}, and {\tt \$meminit\_v2} cells +belonging to the same memory to a single {\tt \$mem\_v2} cell, whereas the {\tt memory\_unpack} pass performs the inverse operation. The {\tt memory\_dff} pass can combine asynchronous memory ports that are fed by or feeding registers into synchronous memory ports. -The {\tt memory\_bram} pass can be used to recognize {\tt \$mem} cells that can be implemented with a block RAM resource on an FPGA. -The {\tt memory\_map} pass can be used to implement {\tt \$mem} cells as basic logic: word-wide DFFs and address decoders. +The {\tt memory\_bram} pass can be used to recognize {\tt \$mem\_v2} cells that can be implemented with a block RAM resource on an FPGA. +The {\tt memory\_map} pass can be used to implement {\tt \$mem\_v2} cells as basic logic: word-wide DFFs and address decoders. \subsection{Finite State Machines} @@ -476,6 +593,23 @@ The {\tt memory\_map} pass can be used to implement {\tt \$mem} cells as basic l Add a brief description of the {\tt \$fsm} cell type. \end{fixme} +\subsection{Specify rules} + +\begin{fixme} +Add information about {\tt \$specify2}, {\tt \$specify3}, and {\tt \$specrule} cells. +\end{fixme} + +\subsection{Formal verification cells} + +\begin{fixme} +Add information about {\tt \$assert}, {\tt \$assume}, {\tt \$live}, {\tt \$fair}, {\tt \$cover}, {\tt \$equiv}, +{\tt \$initstate}, {\tt \$anyconst}, {\tt \$anyseq}, {\tt \$allconst}, {\tt \$allseq} cells. +\end{fixme} + +\begin{fixme} +Add information about {\tt \$ff} and {\tt \$\_FF\_} cells. +\end{fixme} + \section{Gates} \label{sec:celllib_gates} @@ -490,6 +624,7 @@ source tree. \begin{tabular}[t]{ll} Verilog & Cell Type \\ \hline +\lstinline[language=Verilog]; Y = A; & {\tt \$\_BUF\_} \\ \lstinline[language=Verilog]; Y = ~A; & {\tt \$\_NOT\_} \\ \lstinline[language=Verilog]; Y = A & B; & {\tt \$\_AND\_} \\ \lstinline[language=Verilog]; Y = ~(A & B); & {\tt \$\_NAND\_} \\ @@ -499,11 +634,21 @@ Verilog & Cell Type \\ \lstinline[language=Verilog]; Y = A | ~B; & {\tt \$\_ORNOT\_} \\ \lstinline[language=Verilog]; Y = A ^ B; & {\tt \$\_XOR\_} \\ \lstinline[language=Verilog]; Y = ~(A ^ B); & {\tt \$\_XNOR\_} \\ +\lstinline[language=Verilog]; Y = ~((A & B) | C); & {\tt \$\_AOI3\_} \\ +\lstinline[language=Verilog]; Y = ~((A | B) & C); & {\tt \$\_OAI3\_} \\ +\lstinline[language=Verilog]; Y = ~((A & B) | (C & D)); & {\tt \$\_AOI4\_} \\ +\lstinline[language=Verilog]; Y = ~((A | B) & (C | D)); & {\tt \$\_OAI4\_} \\ \lstinline[language=Verilog]; Y = S ? B : A; & {\tt \$\_MUX\_} \\ -\lstinline[language=Verilog]; Y = EN ? A : 'bz; & {\tt \$\_TBUF\_} \\ +\lstinline[language=Verilog]; Y = ~(S ? B : A); & {\tt \$\_NMUX\_} \\ +(see below) & {\tt \$\_MUX4\_} \\ +(see below) & {\tt \$\_MUX8\_} \\ +(see below) & {\tt \$\_MUX16\_} \\ +\lstinline[language=Verilog]; Y = EN ? A : 1'bz; & {\tt \$\_TBUF\_} \\ \hline \lstinline[language=Verilog]; always @(negedge C) Q <= D; & {\tt \$\_DFF\_N\_} \\ \lstinline[language=Verilog]; always @(posedge C) Q <= D; & {\tt \$\_DFF\_P\_} \\ +\lstinline[language=Verilog]; always @* if (!E) Q <= D; & {\tt \$\_DLATCH\_N\_} \\ +\lstinline[language=Verilog]; always @* if (E) Q <= D; & {\tt \$\_DLATCH\_P\_} \\ \end{tabular} \caption{Cell types for gate level logic networks (main list)} \label{tab:CellLib_gates} @@ -610,14 +755,88 @@ $ClkEdge$ & $SetLvl$ & $RstLvl$ & $EnLvl$ & Cell Type \\ \label{tab:CellLib_gates_dffsre} \end{table} -Tables~\ref{tab:CellLib_gates}, \ref{tab:CellLib_gates_dffe}, \ref{tab:CellLib_gates_adff}, \ref{tab:CellLib_gates_adffe}, \ref{tab:CellLib_gates_dffsr} and \ref{tab:CellLib_gates_dffsre} list all cell types used for gate level logic. The cell types -{\tt \$\_NOT\_}, {\tt \$\_AND\_}, {\tt \$\_NAND\_}, {\tt \$\_ANDNOT\_}, {\tt \$\_OR\_}, {\tt \$\_NOR\_}, -{\tt \$\_ORNOT\_}, {\tt \$\_XOR\_}, {\tt \$\_XNOR\_} and {\tt \$\_MUX\_} are used to model combinatorial logic. +\begin{table}[t] +\hfil +\begin{tabular}[t]{llll} +$EnLvl$ & $RstLvl$ & $RstVal$ & Cell Type \\ +\hline +\lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCH\_NN0\_} \\ +\lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCH\_NN1\_} \\ +\lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCH\_NP0\_} \\ +\lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCH\_NP1\_} \\ +\lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCH\_PN0\_} \\ +\lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCH\_PN1\_} \\ +\lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCH\_PP0\_} \\ +\lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCH\_PP1\_} \\ +\end{tabular} +\caption{Cell types for gate level logic networks (latches with reset)} +\label{tab:CellLib_gates_adlatch} +\end{table} + +\begin{table}[t] +\hfil +\begin{tabular}[t]{llll} +$EnLvl$ & $SetLvl$ & $RstLvl$ & Cell Type \\ +\hline +\lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCHSR\_NNN\_} \\ +\lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCHSR\_NNP\_} \\ +\lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCHSR\_NPN\_} \\ +\lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCHSR\_NPP\_} \\ +\lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCHSR\_PNN\_} \\ +\lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCHSR\_PNP\_} \\ +\lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCHSR\_PPN\_} \\ +\lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCHSR\_PPP\_} \\ +\end{tabular} +\caption{Cell types for gate level logic networks (latches with set and reset)} +\label{tab:CellLib_gates_dlatchsr} +\end{table} + +\begin{table}[t] +\hfil +\begin{tabular}[t]{llll} +$SetLvl$ & $RstLvl$ & Cell Type \\ +\hline +\lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_SR\_NN\_} \\ +\lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_SR\_NP\_} \\ +\lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_SR\_PN\_} \\ +\lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_SR\_PP\_} \\ +\end{tabular} +\caption{Cell types for gate level logic networks (SR latches)} +\label{tab:CellLib_gates_sr} +\end{table} + +Tables~\ref{tab:CellLib_gates}, \ref{tab:CellLib_gates_dffe}, \ref{tab:CellLib_gates_adff}, \ref{tab:CellLib_gates_adffe}, \ref{tab:CellLib_gates_dffsr}, \ref{tab:CellLib_gates_dffsre}, \ref{tab:CellLib_gates_adlatch}, \ref{tab:CellLib_gates_dlatchsr} and \ref{tab:CellLib_gates_sr} list all cell types used for gate level logic. The cell types +{\tt \$\_BUF\_}, {\tt \$\_NOT\_}, {\tt \$\_AND\_}, {\tt \$\_NAND\_}, {\tt \$\_ANDNOT\_}, +{\tt \$\_OR\_}, {\tt \$\_NOR\_}, {\tt \$\_ORNOT\_}, {\tt \$\_XOR\_}, {\tt \$\_XNOR\_}, +{\tt \$\_AOI3\_}, {\tt \$\_OAI3\_}, {\tt \$\_AOI4\_}, {\tt \$\_OAI4\_}, +{\tt \$\_MUX\_}, {\tt \$\_MUX4\_}, {\tt \$\_MUX8\_}, {\tt \$\_MUX16\_} and {\tt \$\_NMUX\_} are used to model combinatorial logic. The cell type {\tt \$\_TBUF\_} is used to model tristate logic. +The {\tt \$\_MUX4\_}, {\tt \$\_MUX8\_} and {\tt \$\_MUX16\_} cells are used to model wide muxes, and correspond to the following Verilog code: + +\begin{lstlisting}[language=Verilog] +// $_MUX4_ +assign Y = T ? (S ? D : C) : + (S ? B : A); +// $_MUX8_ +assign Y = U ? T ? (S ? H : G) : + (S ? F : E) : + T ? (S ? D : C) : + (S ? B : A); +// $_MUX16_ +assign Y = V ? U ? T ? (S ? P : O) : + (S ? N : M) : + T ? (S ? L : K) : + (S ? J : I) : + U ? T ? (S ? H : G) : + (S ? F : E) : + T ? (S ? D : C) : + (S ? B : A); +\end{lstlisting} + The cell types {\tt \$\_DFF\_N\_} and {\tt \$\_DFF\_P\_} represent d-type flip-flops. -The cell types {\tt \$\_DFFE\_NN\_}, {\tt \$\_DFFE\_NP\_}, {\tt \$\_DFFE\_PN\_} and {\tt \$\_DFFE\_PP\_} +The cell types {\tt \$\_DFFE\_[NP][NP]\_} implement d-type flip-flops with enable. The values in the table for these cell types relate to the following Verilog code template. @@ -627,8 +846,7 @@ following Verilog code template. Q <= D; \end{lstlisting} -The cell types {\tt \$\_DFF\_NN0\_}, {\tt \$\_DFF\_NN1\_}, {\tt \$\_DFF\_NP0\_}, {\tt \$\_DFF\_NP1\_}, -{\tt \$\_DFF\_PN0\_}, {\tt \$\_DFF\_PN1\_}, {\tt \$\_DFF\_PP0\_} and {\tt \$\_DFF\_PP1\_} implement +The cell types {\tt \$\_DFF\_[NP][NP][01]\_} implement d-type flip-flops with asynchronous reset. The values in the table for these cell types relate to the following Verilog code template, where \lstinline[mathescape,language=Verilog];$RstEdge$; is \lstinline[language=Verilog];posedge; if \lstinline[mathescape,language=Verilog];$RstLvl$; if \lstinline[language=Verilog];1;, and \lstinline[language=Verilog];negedge; @@ -642,8 +860,7 @@ otherwise. Q <= D; \end{lstlisting} -The cell types {\tt \$\_SDFF\_NN0\_}, {\tt \$\_SDFF\_NN1\_}, {\tt \$\_SDFF\_NP0\_}, {\tt \$\_SDFF\_NP1\_}, -{\tt \$\_SDFF\_PN0\_}, {\tt \$\_SDFF\_PN1\_}, {\tt \$\_SDFF\_PP0\_} and {\tt \$\_SDFF\_PP1\_} implement +The cell types {\tt \$\_SDFF\_[NP][NP][01]\_} implement d-type flip-flops with synchronous reset. The values in the table for these cell types relate to the following Verilog code template: @@ -732,21 +949,52 @@ otherwise. Q <= D; \end{lstlisting} +The cell types {\tt \$\_DLATCH\_N\_} and {\tt \$\_DLATCH\_P\_} represent d-type latches. + +The cell types {\tt \$\_DLATCH\_[NP][NP][01]\_} implement +d-type latches with reset. The values in the table for these cell types relate to the +following Verilog code template: + +\begin{lstlisting}[mathescape,language=Verilog] + always @* + if (R == $RstLvl$) + Q <= $RstVal$; + else if (E == $EnLvl$) + Q <= D; +\end{lstlisting} + +The cell types {\tt \$\_DLATCHSR\_[NP][NP][NP]\_} implement +d-type latches with set and reset. The values in the table for these cell types relate to the +following Verilog code template: + +\begin{lstlisting}[mathescape,language=Verilog] + always @* + if (R == $RstLvl$) + Q <= 0; + else if (S == $SetLvl$) + Q <= 1; + else if (E == $EnLvl$) + Q <= D; +\end{lstlisting} + +The cell types {\tt \$\_SR\_[NP][NP]\_} implement +sr-type latches. The values in the table for these cell types relate to the +following Verilog code template: + +\begin{lstlisting}[mathescape,language=Verilog] + always @* + if (R == $RstLvl$) + Q <= 0; + else if (S == $SetLvl$) + Q <= 1; +\end{lstlisting} + In most cases gate level logic networks are created from RTL networks using the {\tt techmap} pass. The flip-flop cells from the gate level logic network can be mapped to physical flip-flop cells from a Liberty file using the {\tt dfflibmap} pass. The combinatorial logic cells can be mapped to physical cells from a Liberty file via ABC \citeweblink{ABC} using the {\tt abc} pass. \begin{fixme} -Add information about {\tt \$assert}, {\tt \$assume}, {\tt \$live}, {\tt \$fair}, {\tt \$cover}, {\tt \$equiv}, -{\tt \$initstate}, {\tt \$anyconst}, {\tt \$anyseq}, {\tt \$allconst}, {\tt \$allseq} cells. -\end{fixme} - -\begin{fixme} -Add information about {\tt \$specify2}, {\tt \$specify3}, and {\tt \$specrule} cells. -\end{fixme} - -\begin{fixme} Add information about {\tt \$slice} and {\tt \$concat} cells. \end{fixme} @@ -757,16 +1005,3 @@ Add information about {\tt \$lut} and {\tt \$sop} cells. \begin{fixme} Add information about {\tt \$alu}, {\tt \$macc}, {\tt \$fa}, and {\tt \$lcu} cells. \end{fixme} - -\begin{fixme} -Add information about {\tt \$ff} and {\tt \$\_FF\_} cells. -\end{fixme} - -\begin{fixme} -Add information about {\tt \$\_DLATCH\_?\_}, and {\tt \$\_DLATCHSR\_???\_} cells. -\end{fixme} - -\begin{fixme} -Add information about {\tt \$\_AOI3\_}, {\tt \$\_OAI3\_}, {\tt \$\_AOI4\_}, {\tt \$\_OAI4\_}, and {\tt \$\_NMUX\_} cells. -\end{fixme} - diff --git a/manual/CHAPTER_Overview.tex b/manual/CHAPTER_Overview.tex index 83cfa5cc4..50a56137c 100644 --- a/manual/CHAPTER_Overview.tex +++ b/manual/CHAPTER_Overview.tex @@ -39,15 +39,15 @@ the RTL Intermediate Language (RTLIL). A more detailed description of this forma is given in the next section. There is also a text representation of the RTLIL data structure that can be -parsed using the ILANG Frontend. +parsed using the RTLIL Frontend. The design data may then be transformed using a series of passes that all operate on the RTLIL representation of the design. Finally the design in RTLIL representation is converted back to text by one of the backends, namely the Verilog Backend for generating Verilog netlists -and the ILANG Backend for writing the RTLIL data in the same format that is -understood by the ILANG Frontend. +and the RTLIL Backend for writing the RTLIL data in the same format that is +understood by the RTLIL Frontend. With the exception of the AST Frontend, which is called by the high-level HDL frontends and can't be called directly by the user, all program modules are @@ -67,13 +67,13 @@ in different stages of the synthesis. \tikzstyle{data} = [draw, fill=blue!10, ellipse, minimum height=3em, minimum width=7em, node distance=15em] \node[process] (vlog) {Verilog Frontend}; \node[process, dashed, fill=green!5] (vhdl) [right of=vlog] {VHDL Frontend}; - \node[process] (ilang) [right of=vhdl] {ILANG Frontend}; + \node[process] (ilang) [right of=vhdl] {RTLIL Frontend}; \node[data] (ast) [below of=vlog, node distance=5em, xshift=7.5em] {AST}; \node[process] (astfe) [below of=ast, node distance=5em] {AST Frontend}; \node[data] (rtlil) [below of=astfe, node distance=5em, xshift=7.5em] {RTLIL}; \node[process] (pass) [right of=rtlil, node distance=5em, xshift=7.5em] {Passes}; \node[process] (vlbe) [below of=rtlil, node distance=7em, xshift=-13em] {Verilog Backend}; - \node[process] (ilangbe) [below of=rtlil, node distance=7em, xshift=0em] {ILANG Backend}; + \node[process] (ilangbe) [below of=rtlil, node distance=7em, xshift=0em] {RTLIL Backend}; \node[process, dashed, fill=green!5] (otherbe) [below of=rtlil, node distance=7em, xshift=+13em] {Other Backends}; \draw[-latex] (vlog) -- (ast); @@ -92,8 +92,7 @@ in different stages of the synthesis. \section{The RTL Intermediate Language} -All frontends, passes and backends in Yosys operate on a design in RTLIL\footnote{The {\it Language} in {\it RTL Intermediate Language} -refers to the fact, that RTLIL also has a text representation, usually referred to as {\it Intermediate Language} (ILANG).} representation. +All frontends, passes and backends in Yosys operate on a design in RTLIL representation. The only exception are the high-level frontends that use the AST representation as an intermediate step before generating RTLIL data. @@ -231,6 +230,7 @@ generated twice. For modules with only a few parameters, a name directly contain is generated instead of a hash string.) \subsection{RTLIL::Cell and RTLIL::Wire} +\label{sec:rtlil_cell_wire} A module contains zero to many RTLIL::Cell and RTLIL::Wire objects. Objects of these types are used to model netlists. Usually the goal of all synthesis efforts is to convert @@ -276,6 +276,7 @@ The connections of ports to wires are coded by assigning an RTLIL::SigSpec to each cell port. The RTLIL::SigSpec data type is described in the next section. \subsection{RTLIL::SigSpec} +\label{sec:rtlil_sigspec} A ``signal'' is everything that can be applied to a cell port. I.e. @@ -296,6 +297,7 @@ RTLIL::SigSpec objects. Such pairs are needed in different locations. Therefore the type name RTLIL::SigSig was defined for such a pair. \subsection{RTLIL::Process} +\label{sec:rtlil_process} When a high-level HDL frontend processes behavioural code it splits it up into data path logic (e.g.~the expression {\tt a + b} is replaced by the output of an @@ -316,7 +318,7 @@ endmodule In this example there is no data path and therefore the RTLIL::Module generated by the frontend only contains a few RTLIL::Wire objects and an RTLIL::Process. -The RTLIL::Process in ILANG syntax: +The RTLIL::Process in RTLIL syntax: \begin{lstlisting}[numbers=left,frame=single,language=rtlil] process $proc$ff_with_en_and_async_reset.v:4$1 @@ -348,8 +350,9 @@ to update {\tt \textbackslash{}q}. An RTLIL::Process is a container for zero or more RTLIL::SyncRule objects and exactly one RTLIL::CaseRule object, which is called the {\it root case}. -An RTLIL::SyncRule object contains an (optional) synchronization condition (signal and edge-type) and zero or -more assignments (RTLIL::SigSig). The {\tt always} synchronization condition is used to break combinatorial +An RTLIL::SyncRule object contains an (optional) synchronization condition (signal and edge-type), zero or +more assignments (RTLIL::SigSig), and zero or more memory writes (RTLIL::MemWriteAction). +The {\tt always} synchronization condition is used to break combinatorial loops when a latch should be inferred instead. An RTLIL::CaseRule is a container for zero or more assignments (RTLIL::SigSig) @@ -362,7 +365,7 @@ also contains an RTLIL::SwitchRule object (lines $3 \dots 12$). Such an object i statement as it uses a control signal ({\tt \textbackslash{}reset} in this case) to determine which of its cases should be active. The RTLIL::SwitchRule object then contains one RTLIL::CaseRule object per case. In this example there is a case\footnote{The -syntax {\tt 1'1} in the ILANG code specifies a constant with a length of one bit (the first ``1''), +syntax {\tt 1'1} in the RTLIL code specifies a constant with a length of one bit (the first ``1''), and this bit is a one (the second ``1'').} for {\tt \textbackslash{}reset == 1} that causes {\tt \$0\textbackslash{}q[0:0]} to be set (lines 4 and 5) and a default case that in turn contains a switch that sets {\tt \$0\textbackslash{}q[0:0]} to the value of {\tt \textbackslash{}d} if {\tt @@ -445,6 +448,7 @@ pass calls a series of other passes that together perform this conversion in a w for most synthesis tasks. \subsection{RTLIL::Memory} +\label{sec:rtlil_memory} For every array (memory) in the HDL code an RTLIL::Memory object is created. A memory object has the following properties: diff --git a/manual/CHAPTER_Prog.tex b/manual/CHAPTER_Prog.tex index 3cbc95a19..49432f73b 100644 --- a/manual/CHAPTER_Prog.tex +++ b/manual/CHAPTER_Prog.tex @@ -5,13 +5,15 @@ This chapter contains some bits and pieces of information about programming yosys extensions. Also consult the section on programming in the ``Yosys Presentation'' (can be downloaded from the Yosys website as PDF) and don't -be afraid to ask questions on the Yosys Subreddit. +be afraid to ask questions on the YosysHQ Slack. -\section{The ``CodingReadme'' File} +\section{Guidelines} -The following is an excerpt of the {\tt CodingReadme} file from the Yosys source tree. +The {\tt guidelines} directory contains notes on various aspects of Yosys development. The files {\tt GettingStarted} and {\tt CodingStyle} may be of particular interest, and are reproduced here. -\lstinputlisting[title=CodingReadme,rangeprefix=--,rangesuffix=--,includerangemarker=false,linerange=snip-snap,numbers=left,frame=single]{../CodingReadme} +\lstinputlisting[title=GettingStarted,numbers=left,frame=single]{../guidelines/GettingStarted} + +\lstinputlisting[title=CodingStyle,numbers=left,frame=single]{../guidelines/CodingStyle} \section{The ``stubsnets'' Example Module} @@ -23,4 +25,3 @@ The following is the complete code of the ``stubsnets'' example module. It is in \lstinputlisting[title=Makefile,numbers=left,frame=single,language=make]{CHAPTER_Prog/Makefile} \lstinputlisting[title=test.v,numbers=left,frame=single,language=Verilog]{CHAPTER_Prog/test.v} - diff --git a/manual/CHAPTER_StateOfTheArt/simlib_yosys.v b/manual/CHAPTER_StateOfTheArt/simlib_yosys.v index 454c9a83f..ec209fa02 100644 --- a/manual/CHAPTER_StateOfTheArt/simlib_yosys.v +++ b/manual/CHAPTER_StateOfTheArt/simlib_yosys.v @@ -1,7 +1,7 @@ /* * yosys -- Yosys Open SYnthesis Suite * - * Copyright (C) 2012 Clifford Wolf <clifford@clifford.at> + * Copyright (C) 2012 Claire Xenia Wolf <claire@yosyshq.com> * * Permission to use, copy, modify, and/or distribute this software for any * purpose with or without fee is hereby granted, provided that the above diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex new file mode 100644 index 000000000..67eade8bf --- /dev/null +++ b/manual/CHAPTER_TextRtlil.tex @@ -0,0 +1,299 @@ +\chapter{RTLIL Text Representation} +\label{chapter:textrtlil} + +% Stolen from stackexchange: calculate indent based on given keyword, +% with some nice hrules added in. +\newlength{\myl} + +\newenvironment{indentgrammar}[1] + {\vspace{0.5cm}\hrule + \setlength{\myl}{\widthof{#1}+2em} + \grammarindent\the\myl + \begin{grammar}} + {\end{grammar} + \hrule} + +This appendix documents the text representation of RTLIL in extended Backus-Naur form (EBNF). + +The grammar is not meant to represent semantic limitations. That is, the grammar is ``permissive'', and later stages of processing perform more rigorous checks. + +The grammar is also not meant to represent the exact grammar used in the RTLIL frontend, since that grammar is specific to processing by lex and yacc, is even more permissive, and is somewhat less understandable than simple EBNF notation. + +Finally, note that all statements (rules ending in \texttt{-stmt}) terminate in an end-of-line. Because of this, a statement cannot be broken into multiple lines. + +\section{Lexical elements} + +\subsection{Characters} + +An RTLIL file is a stream of bytes. Strictly speaking, a ``character'' in an RTLIL file is a single byte. The lexer treats multi-byte encoded characters as consecutive single-byte characters. While other encodings \textit{may} work, UTF-8 is known to be safe to use. Byte order marks at the beginning of the file will cause an error. + +ASCII spaces (32) and tabs (9) separate lexer tokens. + +A \texttt{nonws} character, used in identifiers, is any character whose encoding consists solely of bytes above ASCII space (32). + +An \texttt{eol} is one or more consecutive ASCII newlines (10) and carriage returns (13). + +\subsection{Identifiers} + +There are two types of identifiers in RTLIL: + +\begin{itemize} + \item Publically visible identifiers + \item Auto-generated identifiers +\end{itemize} + +\begin{indentgrammar}{<autogen-id>} +<id> ::= <public-id> | <autogen-id> + +<public-id> ::= "\textbackslash" <nonws>$+$ + +<autogen-id> ::= "\textdollar" <nonws>$+$ +\end{indentgrammar} + +\subsection{Values} + +A \textit{value} consists of a width in bits and a bit representation, most significant bit first. Bits may be any of: +\begin{itemize} + \item \texttt{0}: A logic zero value + \item \texttt{1}: A logic one value + \item \texttt{x}: An unknown logic value (or don't care in case patterns) + \item \texttt{z}: A high-impedance value (or don't care in case patterns) + \item \texttt{m}: A marked bit (internal use only) + \item \texttt{-}: A don't care value +\end{itemize} + +An \textit{integer} is simply a signed integer value in decimal format. \textbf{Warning:} Integer constants are limited to 32 bits. That is, they may only be in the range $[-2147483648, 2147483648)$. Integers outside this range will result in an error. + +\begin{indentgrammar}{<binary-digit>} +<value> ::= <decimal-digit>$+$ \texttt{\textbf{'}} <binary-digit>$*$ + +<decimal-digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" + +<binary-digit> ::= "0" | "1" | "x" | "z" | "m" | "-" + +<integer> ::= "-"$?$ <decimal-digit>$+$ +\end{indentgrammar} + +\subsection{Strings} + +A string is a series of characters delimited by double-quote characters. Within a string, any character except ASCII NUL (0) may be used. In addition, certain escapes can be used: + +\begin{itemize} + \item \texttt{\textbackslash n}: A newline + \item \texttt{\textbackslash t}: A tab + \item \texttt{\textbackslash \textit{ooo}}: A character specified as a one, two, or three digit octal value +\end{itemize} + +All other characters may be escaped by a backslash, and become the following character. Thus: + +\begin{itemize} + \item \texttt{\textbackslash \textbackslash}: A backslash + \item \texttt{\textbackslash ''}: A double-quote + \item \texttt{\textbackslash r}: An 'r' character +\end{itemize} + +\subsection{Comments} + +A comment starts with a \texttt{\textbf{\#}} character and proceeds to the end of the line. All comments are ignored. + +\section{File} + +A file consists of an optional autoindex statement followed by zero or more modules. + +\begin{indentgrammar}{<design>} +<file> ::= <autoidx-stmt>$?$ <module>* +\end{indentgrammar} + +\subsection{Autoindex statements} + +The autoindex statement sets the global autoindex value used by Yosys when it needs to generate a unique name, e.g. \texttt{\textdollar{}flatten\textdollar{}N}. The N part is filled with the value of the global autoindex value, which is subsequently incremented. This global has to be dumped into RTLIL, otherwise e.g. dumping and running a pass would have different properties than just running a pass on a warm design. + +\begin{indentgrammar}{<autoidx-stmt>} +<autoidx-stmt> ::= "autoidx" <integer> <eol> +\end{indentgrammar} + +\subsection{Modules} + +Declares a module, with zero or more attributes, consisting of zero or more wires, memories, cells, processes, and connections. + +\begin{indentgrammar}{<module-body-stmt>} +<module> ::= <attr-stmt>$*$ <module-stmt> <module-body> <module-end-stmt> + +<module-stmt> ::= "module" <id> <eol> + +<module-body> ::= +(<param-stmt> + \alt <wire> + \alt <memory> + \alt <cell> + \alt <process> + \alt <conn-stmt>)$*$ + +<param-stmt> ::= "parameter" <id> <constant>$?$ <eol> + +<constant> ::= <value> | <integer> | <string> + +<module-end-stmt> ::= "end" <eol> +\end{indentgrammar} + +\subsection{Attribute statements} + +Declares an attribute with the given identifier and value. + +\begin{indentgrammar}{<attr-stmt>} +<attr-stmt> ::= "attribute" <id> <constant> <eol> +\end{indentgrammar} + +\subsection{Signal specifications} + +A signal is anything that can be applied to a cell port, i.e. a constant value, all bits or a selection of bits from a wire, or concatenations of those. + +\textbf{Warning:} When an integer constant is a sigspec, it is always 32 bits wide, 2's complement. For example, a constant of $-1$ is the same as \texttt{32'11111111111111111111111111111111}, while a constant of $1$ is the same as \texttt{32'1}. + +See Sec.~\ref{sec:rtlil_sigspec} for an overview of signal specifications. + +\begin{indentgrammar}{<sigspec>} +<sigspec> ::= +<constant> + \alt <wire-id> + \alt <sigspec> "[" <integer> (":" <integer>)$?$ "]" + \alt "\{" <sigspec>$*$ "\}" +\end{indentgrammar} + +\subsection{Connections} + +Declares a connection between the given signals. + +\begin{indentgrammar}{<conn-stmt>} +<conn-stmt> ::= "connect" <sigspec> <sigspec> <eol> +\end{indentgrammar} + +\subsection{Wires} + +Declares a wire, with zero or more attributes, with the given identifier and options in the enclosing module. + +See Sec.~\ref{sec:rtlil_cell_wire} for an overview of wires. + +\begin{indentgrammar}{<wire-option>} +<wire> ::= <attr-stmt>$*$ <wire-stmt> + +<wire-stmt> ::= "wire" <wire-option>$*$ <wire-id> <eol> + +<wire-id> ::= <id> + +<wire-option> ::= +"width" <integer> + \alt "offset" <integer> + \alt "input" <integer> + \alt "output" <integer> + \alt "inout" <integer> + \alt "upto" + \alt "signed" +\end{indentgrammar} + +\subsection{Memories} + +Declares a memory, with zero or more attributes, with the given identifier and options in the enclosing module. + +See Sec.~\ref{sec:rtlil_memory} for an overview of memory cells, and Sec.~\ref{sec:memcells} for details about memory cell types. + +\begin{indentgrammar}{<memory-option>} +<memory> ::= <attr-stmt>$*$ <memory-stmt> + +<memory-stmt> ::= "memory" <memory-option>$*$ <id> <eol> + +<memory-option> ::= +"width" <integer> + \alt "size" <integer> + \alt "offset" <integer> +\end{indentgrammar} + +\subsection{Cells} + +Declares a cell, with zero or more attributes, with the given identifier and type in the enclosing module. + +Cells perform functions on input signals. See Chap.~\ref{chapter:celllib} for a detailed list of cell types. + +\begin{indentgrammar}{<cell-body-stmt>} +<cell> ::= <attr-stmt>$*$ <cell-stmt> <cell-body-stmt>$*$ <cell-end-stmt> + +<cell-stmt> ::= "cell" <cell-type> <cell-id> <eol> + +<cell-id> ::= <id> + +<cell-type> ::= <id> + +<cell-body-stmt> ::= +"parameter" ("signed" | "real")$?$ <id> <constant> <eol> + \alt "connect" <id> <sigspec> <eol> + +<cell-end-stmt> ::= "end" <eol> +\end{indentgrammar} + +\subsection{Processes} + +Declares a process, with zero or more attributes, with the given identifier in the enclosing module. The body of a process consists of zero or more assignments, exactly one switch, and zero or more syncs. + +See Sec.~\ref{sec:rtlil_process} for an overview of processes. + +\begin{indentgrammar}{<switch-end-stmt>} +<process> ::= <attr-stmt>$*$ <proc-stmt> <process-body> <proc-end-stmt> + +<proc-stmt> ::= "process" <id> <eol> + +<process-body> ::= <assign-stmt>$*$ <switch>$?$ <assign-stmt>$*$ <sync>$*$ + +<assign-stmt> ::= "assign" <dest-sigspec> <src-sigspec> <eol> + +<dest-sigspec> ::= <sigspec> + +<src-sigspec> ::= <sigspec> + +<proc-end-stmt> ::= "end" <eol> + +\end{indentgrammar} + +\subsection{Switches} + +Switches test a signal for equality against a list of cases. Each case specifies a comma-separated list of signals to check against. If there are no signals in the list, then the case is the default case. The body of a case consists of zero or more switches and assignments. Both switches and cases may have zero or more attributes. + +\begin{indentgrammar}{<switch-end-stmt>} +<switch> ::= <switch-stmt> <case>$*$ <switch-end-stmt> + +<switch-stmt> := <attr-stmt>$*$ "switch" <sigspec> <eol> + +<case> ::= <attr-stmt>$*$ <case-stmt> <case-body> + +<case-stmt> ::= "case" <compare>$?$ <eol> + +<compare> ::= <sigspec> ("," <sigspec>)$*$ + +<case-body> ::= (<switch> | <assign-stmt>)$*$ + +<switch-end-stmt> ::= "end" <eol> +\end{indentgrammar} + +\subsection{Syncs} + +Syncs update signals with other signals when an event happens. Such an event may be: + +\begin{itemize} + \item An edge or level on a signal + \item Global clock ticks + \item Initialization + \item Always +\end{itemize} + +\begin{indentgrammar}{<dest-sigspec>} +<sync> ::= <sync-stmt> <update-stmt>$*$ + +<sync-stmt> ::= +"sync" <sync-type> <sigspec> <eol> + \alt "sync" "global" <eol> + \alt "sync" "init" <eol> + \alt "sync" "always" <eol> + +<sync-type> ::= "low" | "high" | "posedge" | "negedge" | "edge" + +<update-stmt> ::= "update" <dest-sigspec> <src-sigspec> <eol> +\end{indentgrammar} diff --git a/manual/CHAPTER_Verilog.tex b/manual/CHAPTER_Verilog.tex index d4cc55647..c1ecc0397 100644 --- a/manual/CHAPTER_Verilog.tex +++ b/manual/CHAPTER_Verilog.tex @@ -503,6 +503,8 @@ signal to the temporary signal in its \lstinline[language=C++]{RTLIL::CaseRule}/ \item Finally a \lstinline[language=C++]{RTLIL::SyncRule} is created for the \lstinline[language=C++]{RTLIL::Process} that assigns the temporary signals for the final values to the actual signals. % +\item A process may also contain memory writes. A \lstinline[language=C++]{RTLIL::MemWriteAction} is created for each of them. +% \item Calls to \lstinline[language=C++]{AST::AstNode::genRTLIL()} are generated for right hand sides as needed. When blocking assignments are used, \lstinline[language=C++]{AST::AstNode::genRTLIL()} is configured using global variables to use the temporary signals that hold the correct intermediate values whenever one of the previously assigned signals is used @@ -821,6 +823,9 @@ the \C{RTLIL::SyncRule}s that describe the output registers. This pass replaces the \C{RTLIL::SyncRule}s to d-type flip-flops (with asynchronous resets if necessary). % +\item {\tt proc\_dff} \\ +This pass replaces the \C{RTLIL::MemWriteActions}s with {\tt \$memwr} cells. +% \item {\tt proc\_clean} \\ A final call to {\tt proc\_clean} removes the now empty \C{RTLIL::Process} objects. \end{itemize} diff --git a/manual/PRESENTATION_ExAdv.tex b/manual/PRESENTATION_ExAdv.tex index ef8f64cec..6a426ff2b 100644 --- a/manual/PRESENTATION_ExAdv.tex +++ b/manual/PRESENTATION_ExAdv.tex @@ -890,7 +890,7 @@ Questions? \bigskip \bigskip \begin{center} -\url{http://www.clifford.at/yosys/} +\url{https://yosyshq.net/yosys/} \end{center} \end{frame} diff --git a/manual/PRESENTATION_ExOth.tex b/manual/PRESENTATION_ExOth.tex index 73f8bea2e..3f5113e3c 100644 --- a/manual/PRESENTATION_ExOth.tex +++ b/manual/PRESENTATION_ExOth.tex @@ -221,7 +221,7 @@ Questions? \bigskip \bigskip \begin{center} -\url{http://www.clifford.at/yosys/} +\url{https://yosyshq.net/yosys/} \end{center} \end{frame} diff --git a/manual/PRESENTATION_ExSyn.tex b/manual/PRESENTATION_ExSyn.tex index 655720ebc..d7cfdc6f2 100644 --- a/manual/PRESENTATION_ExSyn.tex +++ b/manual/PRESENTATION_ExSyn.tex @@ -509,7 +509,7 @@ Questions? \bigskip \bigskip \begin{center} -\url{http://www.clifford.at/yosys/} +\url{https://yosyshq.net/yosys/} \end{center} \end{frame} diff --git a/manual/PRESENTATION_Intro.tex b/manual/PRESENTATION_Intro.tex index 555ec9175..1c3b79fa0 100644 --- a/manual/PRESENTATION_Intro.tex +++ b/manual/PRESENTATION_Intro.tex @@ -231,7 +231,7 @@ as Qflow\footnote[frame]{\url{http://opencircuitdesign.com/qflow/}} for ASIC des \node[data] (rtlil) [below of=astfe, node distance=5em, xshift=7.5em] {RTLIL}; \node[process] (pass) [right of=rtlil, node distance=5em, xshift=7.5em] {Passes}; \node[process] (vlbe) [below of=rtlil, node distance=7em, xshift=-13em] {Verilog Backend}; - \node[process] (ilangbe) [below of=rtlil, node distance=7em, xshift=0em] {ILANG Backend}; + \node[process] (ilangbe) [below of=rtlil, node distance=7em, xshift=0em] {RTLIL Backend}; \node[process, fill=green!5] (otherbe) [below of=rtlil, node distance=7em, xshift=+13em] {Other Backends}; \draw[-latex] (vlog) -- (ast); @@ -260,7 +260,7 @@ The following slides cover an example project. This project contains three files \end{itemize} \vfill Direct link to the files: \\ \footnotesize -\url{https://github.com/cliffordwolf/yosys/tree/master/manual/PRESENTATION_Intro} +\url{https://github.com/YosysHQ/yosys/tree/master/manual/PRESENTATION_Intro} \end{frame} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -476,7 +476,7 @@ Command reference: \begin{itemize} \item Use ``{\tt help}'' for a command list and ``{\tt help \it command}'' for details. \item Or run ``{\tt yosys -H}'' or ``{\tt yosys -h \it command}''. -\item Or go to \url{http://www.clifford.at/yosys/documentation.html}. +\item Or go to \url{https://yosyshq.net/yosys/documentation.html}. \end{itemize} \bigskip @@ -484,7 +484,7 @@ Commands for design navigation and investigation: \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys] cd # a shortcut for 'select -module <name>' ls # list modules or objects in modules - dump # print parts of the design in ilang format + dump # print parts of the design in RTLIL format show # generate schematics using graphviz select # modify and view the list of selected objects \end{lstlisting} @@ -502,7 +502,7 @@ Commands for executing scripts or entering interactive mode: \begin{frame}[fragile]{\subsecname{} 2/3 \hspace{0pt plus 1 filll} (excerpt)} Commands for reading and elaborating the design: \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=ys] - read_ilang # read modules from ilang file + read_rtlil # read modules from RTLIL file read_verilog # read modules from Verilog file hierarchy # check, expand and clean up design hierarchy \end{lstlisting} @@ -534,7 +534,7 @@ Commands for writing the results: write_blif # write design to BLIF file write_btor # write design to BTOR file write_edif # write design to EDIF netlist file - write_ilang # write design to ilang file + write_rtlil # write design to RTLIL file write_spice # write design to SPICE netlist file write_verilog # write design to Verilog file \end{lstlisting} @@ -806,7 +806,7 @@ but also formal verification, reverse engineering, ...} \begin{itemize} \item Ongoing PhD project on coarse grain synthesis \\ {\setlength{\parindent}{0.5cm}\footnotesize -Johann Glaser and Clifford Wolf. Methodology and Example-Driven Interconnect +Johann Glaser and C. Wolf. Methodology and Example-Driven Interconnect Synthesis for Designing Heterogeneous Coarse-Grain Reconfigurable Architectures. In Jan Haase, editor, \it Models, Methods, and Tools for Complex Chip Design. Lecture Notes in Electrical Engineering. Volume 265, 2014, pp @@ -913,11 +913,11 @@ control logic because it is simpler than setting up a commercial flow. \begin{frame}{\subsecname} \begin{itemize} \item Website: \\ -\smallskip\hskip1cm\url{http://www.clifford.at/yosys/} +\smallskip\hskip1cm\url{https://yosyshq.net/yosys/} \bigskip \item Manual, Command Reference, Application Notes: \\ -\smallskip\hskip1cm\url{http://www.clifford.at/yosys/documentation.html} +\smallskip\hskip1cm\url{https://yosyshq.net/yosys/documentation.html} \bigskip \item Instead of a mailing list we have a SubReddit: \\ @@ -925,7 +925,7 @@ control logic because it is simpler than setting up a commercial flow. \bigskip \item Direct link to the source code: \\ -\smallskip\hskip1cm\url{https://github.com/cliffordwolf/yosys} +\smallskip\hskip1cm\url{https://github.com/YosysHQ/yosys} \end{itemize} \end{frame} @@ -950,7 +950,7 @@ Questions? \bigskip \bigskip \begin{center} -\url{http://www.clifford.at/yosys/} +\url{https://yosyshq.net/yosys/} \end{center} \end{frame} diff --git a/manual/PRESENTATION_Prog.tex b/manual/PRESENTATION_Prog.tex index a9416f82a..b0390cb99 100644 --- a/manual/PRESENTATION_Prog.tex +++ b/manual/PRESENTATION_Prog.tex @@ -22,7 +22,7 @@ \node[data] (rtlil) [below of=astfe, node distance=5em, xshift=7.5em] {RTLIL}; \node[process] (pass) [right of=rtlil, node distance=5em, xshift=7.5em] {Passes}; \node[process] (vlbe) [below of=rtlil, node distance=7em, xshift=-13em] {Verilog Backend}; - \node[process] (ilangbe) [below of=rtlil, node distance=7em, xshift=0em] {ILANG Backend}; + \node[process] (ilangbe) [below of=rtlil, node distance=7em, xshift=0em] {RTLIL Backend}; \node[process, fill=green!5] (otherbe) [below of=rtlil, node distance=7em, xshift=+13em] {Other Backends}; \draw[-latex] (vlog) -- (ast); @@ -105,8 +105,7 @@ For simplicity we only discuss this version of RTLIL in this presentation. \begin{frame}{\subsecname} \begin{itemize} -\item The {\tt dump} command prints the design (or parts of it) in ILANG format. This is -a text representation of RTLIL. +\item The {\tt dump} command prints the design (or parts of it) in the text representation of RTLIL. \bigskip \item The {\tt show} command visualizes how the components in the design are connected. @@ -591,7 +590,7 @@ Questions? \bigskip \bigskip \begin{center} -\url{http://www.clifford.at/yosys/} +\url{https://yosyshq.net/yosys/} \end{center} \end{frame} diff --git a/manual/PRESENTATION_Prog/Makefile b/manual/PRESENTATION_Prog/Makefile index 7e3cf814b..2ac8e5bed 100644 --- a/manual/PRESENTATION_Prog/Makefile +++ b/manual/PRESENTATION_Prog/Makefile @@ -16,6 +16,6 @@ test1.log: my_cmd.so mv test1.log_new test1.log test2.log: my_cmd.so - ../../yosys -Ql test2.log_new -m ./my_cmd.so -p 'test2' sigmap_test.v + ../../yosys -Ql test2.log_new -m ./my_cmd.so -p 'hierarchy -top test; test2' sigmap_test.v mv test2.log_new test2.log diff --git a/manual/command-reference-manual.tex b/manual/command-reference-manual.tex index 988f034b4..1aa0facb5 100644 --- a/manual/command-reference-manual.tex +++ b/manual/command-reference-manual.tex @@ -22,11 +22,11 @@ library to a target architecture. if no -script parameter is given, the following scripts are used: - for -liberty without -constr: + for -liberty/-genlib without -constr: strash; ifraig; scorr; dc2; dretime; strash; &get -n; &dch -f; &nf {D}; &put - for -liberty with -constr: + for -liberty/-genlib with -constr: strash; ifraig; scorr; dc2; dretime; strash; &get -n; &dch -f; &nf {D}; &put; buffer; upsize {D}; dnsize {D}; stime -p @@ -49,10 +49,10 @@ library to a target architecture. use different default scripts that are slightly faster (at the cost of output quality): - for -liberty without -constr: + for -liberty/-genlib without -constr: strash; dretime; map {D} - for -liberty with -constr: + for -liberty/-genlib with -constr: strash; dretime; map {D}; buffer; upsize {D}; dnsize {D}; stime -p @@ -60,7 +60,7 @@ library to a target architecture. strash; dretime; if for -sop: - strash; dretime; cover -I {I} -P {P} + strash; dretime; cover {I} {P} otherwise: strash; dretime; map @@ -69,8 +69,13 @@ library to a target architecture. generate netlists for the specified cell library (using the liberty file format). + -genlib <file> + generate netlists for the specified cell library (using the SIS Genlib + file format). + -constr <file> - pass this file with timing constraints to ABC. use with -liberty. + pass this file with timing constraints to ABC. + use with -liberty/-genlib. a constr file contains two lines: set_driving_cell <cell_name> @@ -167,7 +172,7 @@ library to a target architecture. preserve naming by an equivalence check between the original and post-ABC netlists (experimental). -When neither -liberty nor -lut is used, the Yosys standard cell library is +When no target cell library is specified the Yosys standard cell library is loaded into ABC before the ABC script is executed. Note that this is a logic optimization pass within Yosys that is calling ABC @@ -241,8 +246,8 @@ architecture. Only fully-selected modules are supported. specified). -dff - also pass $_ABC9_FF_ cells through to ABC. modules with many clock - domains are marked as such and automatically partitioned by ABC. + also pass $_DFF_[NP]_ cells through to ABC. modules with many clock + domains are supported and automatically partitioned by ABC. -nocleanup when this option is used, the temporary files created by this pass @@ -265,28 +270,64 @@ externally if you want to use ABC to convert your design into another format. [1] http://www.eecs.berkeley.edu/~alanmi/abc/ + check: + abc9_ops -check [-dff] (option if -dff) + + map: + abc9_ops -prep_hier [-dff] (option if -dff) + scc -specify -set_attr abc9_scc_id {} + abc9_ops -prep_bypass [-prep_dff] (option if -dff) + design -stash $abc9 + design -load $abc9_map + proc + wbflip + techmap -wb -map %$abc9 -map +/techmap.v A:abc9_flop + opt -nodffe -nosdff + abc9_ops -prep_dff_submod (only if -dff) + setattr -set submod "$abc9_flop" t:$_DFF_?_ %ci* %co* t:$_DFF_?_ %d (only if -dff) + submod (only if -dff) + setattr -mod -set whitebox 1 -set abc9_flop 1 -set abc9_box 1 *_$abc9_flop (only if -dff) + foreach module in design + rename <module-name>_$abc9_flop _TECHMAP_REPLACE_ (only if -dff) + abc9_ops -prep_dff_unmap (only if -dff) + design -copy-to $abc9 =*_$abc9_flop (only if -dff) + delete =*_$abc9_flop (only if -dff) + design -stash $abc9_map + design -load $abc9 + design -delete $abc9 + techmap -wb -max_iter 1 -map %$abc9_map -map +/abc9_map.v [-D DFF] (option if -dff) + design -delete $abc9_map + pre: - abc9_ops -check - scc -set_attr abc9_scc_id {} - abc9_ops -mark_scc -prep_delays -prep_xaiger [-dff] (option for -dff) + read_verilog -icells -lib -specify +/abc9_model.v + abc9_ops -break_scc -prep_delays -prep_xaiger [-dff] (option for -dff) abc9_ops -prep_lut <maxlut> (skip if -lut or -luts) - abc9_ops -prep_box [-dff] (skip if -box) - select -set abc9_holes A:abc9_holes - flatten -wb @abc9_holes - techmap @abc9_holes - abc9_ops -prep_dff (only if -dff) - opt -purge @abc9_holes + abc9_ops -prep_box (skip if -box) + design -stash $abc9 + design -load $abc9_holes + techmap -wb -map %$abc9 -map +/techmap.v + opt -purge aigmap - wbflip @abc9_holes + design -stash $abc9_holes + design -load $abc9 + design -delete $abc9 - map: + exe: + aigmap foreach module in selection abc9_ops -write_lut <abc-temp-dir>/input.lut (skip if '-lut' or '-luts') - abc9_ops -write_box <abc-temp-dir>/input.box - write_xaiger -map <abc-temp-dir>/input.sym <abc-temp-dir>/input.xaig - abc9_exe [options] -cwd <abc-temp-dir> [-lut <abc-temp-dir>/input.lut] -box <abc-temp-dir>/input.box + abc9_ops -write_box <abc-temp-dir>/input.box (skip if '-box') + write_xaiger -map <abc-temp-dir>/input.sym [-dff] <abc-temp-dir>/input.xaig + abc9_exe [options] -cwd <abc-temp-dir> -lut [<abc-temp-dir>/input.lut] -box [<abc-temp-dir>/input.box] read_aiger -xaiger -wideports -module_name <module-name>$abc9 -map <abc-temp-dir>/input.sym <abc-temp-dir>/output.aig - abc9_ops -reintegrate + abc9_ops -reintegrate [-dff] + + unmap: + techmap -wb -map %$abc9_unmap -map +/abc9_unmap.v + design -delete $abc9_unmap + design -delete $abc9_holes + delete =*_$abc9_byp + setattr -mod -unset abc9_box_id \end{lstlisting} \section{abc9\_exe -- use ABC9 for technology mapping} @@ -375,30 +416,56 @@ the `abc9' script pass. Only fully-selected modules are supported. check that the design is valid, e.g. (* abc9_box_id *) values are unique, (* abc9_carry *) is only given for one input/output port, etc. + -prep_hier + derive all used (* abc9_box *) or (* abc9_flop *) (if -dff option) + whitebox modules. with (* abc9_flop *) modules, only those containing + $dff/$_DFF_[NP]_ cells with zero initial state -- due to an ABC limitation + -- will be derived. + + -prep_bypass + create techmap rules in the '$abc9_map' and '$abc9_unmap' designs for + bypassing sequential (* abc9_box *) modules using a combinatorial box + (named *_$abc9_byp). bypassing is necessary if sequential elements (e.g. + $dff, $mem, etc.) are discovered inside so that any combinatorial paths + will be correctly captured. this bypass box will only contain ports that + are referenced by a simple path declaration ($specify2 cell) inside a + specify block. + + -prep_dff + select all (* abc9_flop *) modules instantiated in the design and store + in the named selection '$abc9_flops'. + + -prep_dff_submod + within (* abc9_flop *) modules, rewrite all edge-sensitive path + declarations and $setup() timing checks ($specify3 and $specrule cells) + that share a 'DST' port with the $_DFF_[NP]_.Q port from this 'Q' port to + the DFF's 'D' port. this is to prepare such specify cells to be moved + into the flop box. + + -prep_dff_unmap + populate the '$abc9_unmap' design with techmap rules for mapping *_$abc9_flop + cells back into their derived cell types (where the rules created by + -prep_hier will then map back to the original cell with parameters). + -prep_delays insert `$__ABC9_DELAY' blackbox cells into the design to account for certain required times. - -mark_scc + -break_scc for an arbitrarily chosen cell in each unique SCC of each selected module - (tagged with an (* abc9_scc_id = <int> *) attribute), temporarily mark all - wires driven by this cell's outputs with a (* keep *) attribute in order - to break the SCC. this temporary attribute will be removed on -reintegrate. + (tagged with an (* abc9_scc_id = <int> *) attribute) interrupt all wires + driven by this cell's outputs with a temporary $__ABC9_SCC_BREAKER cell + to break the SCC. -prep_xaiger prepare the design for XAIGER output. this includes computing the - topological ordering of ABC9 boxes, as well as preparing the - '<module-name>$holes' module that contains the logic behaviour of ABC9 - whiteboxes. + topological ordering of ABC9 boxes, as well as preparing the '$abc9_holes' + design that contains the logic behaviour of ABC9 whiteboxes. -dff consider flop cells (those instantiating modules marked with (* abc9_flop *)) during -prep_{delays,xaiger,box}. - -prep_dff - compute the clock domain and initial value of each flop in the design. - process the '$holes' module to support clock-enable functionality. - -prep_lut <maxlut> pre-compute the lut library by analysing all modules marked with (* abc9_lut=<area> *). @@ -522,8 +589,6 @@ This pass assumes negative hold time for the async FF inputs. For example when a reset deasserts with the clock edge, then the FF output will still drive the reset value in the next cycle regardless of the data-in value at the time of the clock edge. - -Currently only $adff, $dffsr, and $dlatch cells are supported by this pass. \end{lstlisting} \section{attrmap -- renaming attributes} @@ -606,27 +671,35 @@ Convert modules into blackbox modules (remove contents and set the blackbox module attribute). \end{lstlisting} +\section{bmuxmap -- transform \$bmux cells to trees of \$mux cells} +\label{cmd:bmuxmap} +\begin{lstlisting}[numbers=left,frame=single] + bmuxmap [selection] + +This pass transforms $bmux cells to trees of $mux cells. +\end{lstlisting} + \section{bugpoint -- minimize testcases} \label{cmd:bugpoint} \begin{lstlisting}[numbers=left,frame=single] - bugpoint [options] + bugpoint [options] [-script <filename> | -command "<command>"] -This command minimizes testcases that crash Yosys. It removes an arbitrary part -of the design and recursively invokes Yosys with a given script, repeating these -steps while it can find a smaller design that still causes a crash. Once this -command finishes, it replaces the current design with the smallest testcase it -was able to produce. +This command minimizes the current design that is known to crash Yosys with the +given script into a smaller testcase. It does this by removing an arbitrary part +of the design and recursively invokes a new Yosys process with this modified design +and the same script, repeating these steps while it can find a smaller design that +still causes a crash. Once this command finishes, it replaces the current design +with the smallest testcase it was able to produce. +In order to save the reduced testcase you must write this out to a file with +another command after `bugpoint` like `write_rtlil` or `write_verilog`. -It is possible to specify the kinds of design part that will be removed. If none -are specified, all parts of design will be removed. + -script <filename> | -command "<command>" + use this script file or command to crash Yosys. required. -yosys <filename> use this Yosys binary. if not specified, `yosys` is used. - -script <filename> - use this script to crash Yosys. required. - - -grep <string> + -grep "<string>" only consider crashes that place this string in the log file. -fast @@ -639,23 +712,37 @@ are specified, all parts of design will be removed. finishing. produces smaller and more useful testcases, but may fail to produce any testcase at all if the crash is related to dangling wires. +It is possible to constrain which parts of the design will be considered for +removal. Unless one or more of the following options are specified, all parts +will be considered. + -modules - try to remove modules. + try to remove modules. modules with a (* bugpoint_keep *) attribute + will be skipped. -ports - try to remove module ports. + try to remove module ports. ports with a (* bugpoint_keep *) attribute + will be skipped (useful for clocks, resets, etc.) -cells - try to remove cells. + try to remove cells. cells with a (* bugpoint_keep *) attribute will + be skipped. -connections try to reconnect ports to 'x. + -processes + try to remove processes. processes with a (* bugpoint_keep *) attribute + will be skipped. + -assigns try to remove process assigns from cases. -updates try to remove process updates from syncs. + + -runner "<prefix>" + child process wrapping command, e.g., "timeout 30", or valgrind. \end{lstlisting} \section{cd -- a shortcut for 'select -module <name>'} @@ -690,30 +777,28 @@ This is just a shortcut for 'select -clear'. This pass identifies the following problems in the current design: - - combinatorial loops - - - two or more conflicting drivers for one wire - - - used wires that do not have a driver + - combinatorial loops + - two or more conflicting drivers for one wire + - used wires that do not have a driver Options: - -noinit - Also check for wires which have the 'init' attribute set. + -noinit + also check for wires which have the 'init' attribute set - -initdrv - Also check for wires that have the 'init' attribute set and are not - driven by an FF cell type. + -initdrv + also check for wires that have the 'init' attribute set and are not + driven by an FF cell type - -mapped - Also check for internal cells that have not been mapped to cells of the - target architecture. + -mapped + also check for internal cells that have not been mapped to cells of the + target architecture - -allow-tbuf - Modify the -mapped behavior to still allow $_TBUF_ cells. + -allow-tbuf + modify the -mapped behavior to still allow $_TBUF_ cells - -assert - Produce a runtime error if any problems are found in the current design. + -assert + produce a runtime error if any problems are found in the current design \end{lstlisting} \section{chformal -- change formal constraints of the design} @@ -794,6 +879,16 @@ When commands are separated using the ';;;' token, this command will be executed in -purge mode between the commands. \end{lstlisting} +\section{clean\_zerowidth -- clean zero-width connections from the design} +\label{cmd:clean_zerowidth} +\begin{lstlisting}[numbers=left,frame=single] + clean_zerowidth [selection] + +Fixes the selected cells and processes to contain no zero-width connections. +Depending on the cell type, this may be implemented by removing the connection, +widening it to 1-bit, or removing the cell altogether. +\end{lstlisting} + \section{clk2fflogic -- convert clocked FFs to generic \$ff cells} \label{cmd:clk2fflogic} \begin{lstlisting}[numbers=left,frame=single] @@ -804,30 +899,32 @@ implicit global clock. This is useful for formal verification of designs with multiple clocks. \end{lstlisting} -\section{clkbufmap -- insert global buffers on clock networks} +\section{clkbufmap -- insert clock buffers on clock networks} \label{cmd:clkbufmap} \begin{lstlisting}[numbers=left,frame=single] clkbufmap [options] [selection] -Inserts global buffers between nets connected to clock inputs and their drivers. +Inserts clock buffers between nets connected to clock inputs and their drivers. In the absence of any selection, all wires without the 'clkbuf_inhibit' -attribute will be considered for global buffer insertion. +attribute will be considered for clock buffer insertion. Alternatively, to consider all wires without the 'buffer_type' attribute set to 'none' or 'bufr' one would specify: 'w:* a:buffer_type=none a:buffer_type=bufr %u %d' as the selection. -buf <celltype> <portname_out>:<portname_in> - Specifies the cell type to use for the global buffers + Specifies the cell type to use for the clock buffers and its port names. The first port will be connected to the clock network sinks, and the second will be connected - to the actual clock source. This option is required. + to the actual clock source. -inpad <celltype> <portname_out>:<portname_in> If specified, a PAD cell of the given type is inserted on clock nets that are also top module's inputs (in addition - to the global buffer). + to the clock buffer, if any). + +At least one of -buf or -inpad should be specified. \end{lstlisting} \section{connect -- create or remove connections} @@ -846,7 +943,7 @@ the -nounset option. Unconnect all existing drivers for the specified expression. - connect [-nomap] -port <cell> <port> <expr> + connect [-nomap] [-assert] -port <cell> <port> <expr> Connect the specified cell port to the specified cell port. @@ -858,6 +955,9 @@ this behavior. The connect command operates in one module only. Either only one module must be selected or an active module must be set using the 'cd' command. +The -assert option verifies that the connection already exists, instead of +making it. + This command does not operate on module with processes. \end{lstlisting} @@ -892,7 +992,7 @@ of JSON. Frontend responds with data or error message by replying with exactly -> {"method": "derive", "module": "<module-name">, "parameters": { "<param-name>": {"type": "[unsigned|signed|string|real]", "value": "<param-value>"}, ...}} - <- {"frontend": "[ilang|verilog|...]","source": "<source>"}} + <- {"frontend": "[rtlil|verilog|...]","source": "<source>"}} <- {"error": "<error-message>"} request for the module <module-name> to be derived for a specific set of parameters. <param-name> starts with \ for named parameters, and with $ @@ -1041,6 +1141,14 @@ selected wires, thus 'deleting' module ports. "Demote" inout ports to input or output ports, if possible. \end{lstlisting} +\section{demuxmap -- transform \$demux cells to \$eq + \$mux cells} +\label{cmd:demuxmap} +\begin{lstlisting}[numbers=left,frame=single] + demuxmap [selection] + +This pass transforms $demux cells to a bunch of equality comparisons. +\end{lstlisting} + \section{design -- save, restore and reset current design} \label{cmd:design} \begin{lstlisting}[numbers=left,frame=single] @@ -1102,61 +1210,10 @@ module that is then used as top module for this command. The Verilog front-end remembers defined macros and top-level declarations between calls to 'read_verilog'. This command resets this memory. -\end{lstlisting} -\section{determine\_init -- Determine the init value of cells} -\label{cmd:determine_init} -\begin{lstlisting}[numbers=left,frame=single] - determine_init [selection] + design -delete <name> -Determine the init value of cells that doesn't allow unknown init value. -\end{lstlisting} - -\section{dff2dffe -- transform \$dff cells to \$dffe cells} -\label{cmd:dff2dffe} -\begin{lstlisting}[numbers=left,frame=single] - dff2dffe [options] [selection] - -This pass transforms $dff cells driven by a tree of multiplexers with one or -more feedback paths to $dffe cells. It also works on gate-level cells such as -$_DFF_P_, $_DFF_N_ and $_MUX_. - - -unmap - operate in the opposite direction: replace $dffe cells with combinations - of $dff and $mux cells. the options below are ignored in unmap mode. - - -unmap-mince N - Same as -unmap but only unmap $dffe where the clock enable port - signal is used by less $dffe than the specified number - - -direct <internal_gate_type> <external_gate_type> - map directly to external gate type. <internal_gate_type> can - be any internal gate-level FF cell (except $_DFFE_??_). the - <external_gate_type> is the cell type name for a cell with an - identical interface to the <internal_gate_type>, except it - also has an high-active enable port 'E'. - Usually <external_gate_type> is an intermediate cell type - that is then translated to the final type using 'techmap'. - - -direct-match <pattern> - like -direct for all DFF cell types matching the expression. - this will use $__DFFE_* as <external_gate_type> matching the - internal gate type $_DFF_*_, and $__DFFSE_* for those matching - $_DFFS_*_, except for $_DFF_[NP]_, which is converted to - $_DFFE_[NP]_. -\end{lstlisting} - -\section{dff2dffs -- process sync set/reset with SR over CE priority} -\label{cmd:dff2dffs} -\begin{lstlisting}[numbers=left,frame=single] - dff2dffs [options] [selection] - -Merge synchronous set/reset $_MUX_ cells to create $__DFFS_[NP][NP][01], to be run before -dff2dffe for SR over CE priority. - - -match-init - Disallow merging synchronous set/reset that has polarity opposite of the - output wire's init attribute (if any). +Delete the design previously saved under the given name. \end{lstlisting} \section{dffinit -- set INIT param on FF cells} @@ -1187,10 +1244,76 @@ drives. (This is primarily used in FPGA flows.) the already defined initial value. \end{lstlisting} +\section{dfflegalize -- convert FFs to types supported by the target} +\label{cmd:dfflegalize} +\begin{lstlisting}[numbers=left,frame=single] + dfflegalize [options] [selection] + +Converts FFs to types supported by the target. + + -cell <cell_type_pattern> <init_values> + specifies a supported group of FF cells. <cell_type_pattern> + is a yosys internal fine cell name, where ? characters can be + as a wildcard matching any character. <init_values> specifies + which initialization values these FF cells can support, and can + be one of: + + - x (no init value supported) + - 0 + - 1 + - r (init value has to match reset value, only for some FF types) + - 01 (both 0 and 1 supported). + + -mince <num> + specifies a minimum number of FFs that should be using any given + clock enable signal. If a clock enable signal doesn't meet this + threshold, it is unmapped into soft logic. + + -minsrst <num> + specifies a minimum number of FFs that should be using any given + sync set/reset signal. If a sync set/reset signal doesn't meet this + threshold, it is unmapped into soft logic. + +The following cells are supported by this pass (ie. will be ingested, +and can be specified as allowed targets): + +- $_DFF_[NP]_ +- $_DFFE_[NP][NP]_ +- $_DFF_[NP][NP][01]_ +- $_DFFE_[NP][NP][01][NP]_ +- $_ALDFF_[NP][NP]_ +- $_ALDFFE_[NP][NP][NP]_ +- $_DFFSR_[NP][NP][NP]_ +- $_DFFSRE_[NP][NP][NP][NP]_ +- $_SDFF_[NP][NP][01]_ +- $_SDFFE_[NP][NP][01][NP]_ +- $_SDFFCE_[NP][NP][01][NP]_ +- $_SR_[NP][NP]_ +- $_DLATCH_[NP]_ +- $_DLATCH_[NP][NP][01]_ +- $_DLATCHSR_[NP][NP][NP]_ + +The following transformations are performed by this pass: +- upconversion from a less capable cell to a more capable cell, if the less capable cell is not supported (eg. dff -> dffe, or adff -> dffsr) +- unmapping FFs with clock enable (due to unsupported cell type or -mince) +- unmapping FFs with sync reset (due to unsupported cell type or -minsrst) +- adding inverters on the control pins (due to unsupported polarity) +- adding inverters on the D and Q pins and inverting the init/reset values + (due to unsupported init or reset value) +- converting sr into adlatch (by tying D to 1 and using E as set input) +- emulating unsupported dffsr cell by adff + adff + sr + mux +- emulating unsupported dlatchsr cell by adlatch + adlatch + sr + mux +- emulating adff when the (reset, init) value combination is unsupported by + dff + adff + dlatch + mux +- emulating adlatch when the (reset, init) value combination is unsupported by +- dlatch + adlatch + dlatch + mux +If the pass is unable to realize a given cell type (eg. adff when only plain dffis available), an error is raised. +\end{lstlisting} + \section{dfflibmap -- technology mapping of flip-flops} \label{cmd:dfflibmap} \begin{lstlisting}[numbers=left,frame=single] - dfflibmap [-prepare] -liberty <file> [selection] + dfflibmap [-prepare] [-map-only] [-info] -liberty <file> [selection] Map internal flip-flop cells to the flip-flop cells in the technology library specified in the given liberty file. @@ -1200,16 +1323,40 @@ first run this pass and then map the logic paths to the target technology. When called with -prepare, this command will convert the internal FF cells to the internal cell types that best match the cells found in the given -liberty file. +liberty file, but won't actually map them to the target cells. + +When called with -map-only, this command will only map internal cell +types that are already of exactly the right type to match the target +cells, leaving remaining internal cells untouched. + +When called with -info, this command will only print the target cell +list, along with their associated internal cell types, and the argumentsthat would be passed to the dfflegalize pass. The design will not be +changed. \end{lstlisting} -\section{dump -- print parts of the design in ilang format} +\section{dffunmap -- unmap clock enable and synchronous reset from FFs} +\label{cmd:dffunmap} +\begin{lstlisting}[numbers=left,frame=single] + dffunmap [options] [selection] + +This pass transforms FF types with clock enable and/or synchronous reset into +their base type (with neither clock enable nor sync reset) by emulating the clock +enable and synchronous reset with multiplexers on the cell input. + + -ce-only + unmap only clock enables, leave synchronous resets alone. + + -srst-only + unmap only synchronous resets, leave clock enables alone. +\end{lstlisting} + +\section{dump -- print parts of the design in RTLIL format} \label{cmd:dump} \begin{lstlisting}[numbers=left,frame=single] dump [options] [selection] Write the selected parts of the design to the console or specified file in -ilang format. +RTLIL format. -m also dump the module headers, even if only parts of a single @@ -1238,16 +1385,6 @@ Print all commands to log before executing them. Do not print all commands to log before executing them. (default) \end{lstlisting} -\section{ecp5\_ffinit -- ECP5: handle FF init values} -\label{cmd:ecp5_ffinit} -\begin{lstlisting}[numbers=left,frame=single] - ecp5_ffinit [options] [selection] - -Remove init values for FF output signals when equal to reset value. -If reset is not used, set the reset value to the init value, otherwise -unmap out the reset (if not an async reset). -\end{lstlisting} - \section{ecp5\_gsr -- ECP5: handle GSR} \label{cmd:ecp5_gsr} \begin{lstlisting}[numbers=left,frame=single] @@ -1278,14 +1415,6 @@ is a 4-tuple of source and sink cell type and port name. Add Efinix adders to fix carry chain if needed. \end{lstlisting} -\section{efinix\_gbuf -- Efinix: insert global clock buffers} -\label{cmd:efinix_gbuf} -\begin{lstlisting}[numbers=left,frame=single] - efinix_gbuf [options] [selection] - -Add Efinix global clock buffers to top module as needed. -\end{lstlisting} - \section{equiv\_add -- add a \$equiv cell} \label{cmd:equiv_add} \begin{lstlisting}[numbers=left,frame=single] @@ -1629,7 +1758,7 @@ outputs. This pass looks for subcircuits that are isomorphic to any of the modules in the given map file and replaces them with instances of this modules. The -map file can be a Verilog source file (*.v) or an ilang file (*.il). +map file can be a Verilog source file (*.v) or an RTLIL source file (*.il). -map <map_file> use the modules in this file as reference. This option can be used @@ -1684,7 +1813,7 @@ This pass can also be used for mining for frequent subcircuits. In this mode the following options are to be used instead of the -map option. -mine <out_file> - mine for frequent subcircuits and write them to the given ilang file + mine for frequent subcircuits and write them to the given RTLIL file -mine_cells_span <min> <max> only mine for subcircuits with the specified number of cells @@ -2121,9 +2250,9 @@ Merge GP_INV cells with GP_DFF* and GP_DLATCH* cells. In parametric designs, a module might exists in several variations with different parameter values. This pass looks at all modules in the current -design an re-runs the language frontends for the parametric modules as +design and re-runs the language frontends for the parametric modules as needed. It also resolves assignments to wired logic data types (wand/wor), -resolves positional module parameters, unroll array instances, and more. +resolves positional module parameters, unrolls array instances, and more. -check also check the design hierarchy. this generates an error when @@ -2249,23 +2378,6 @@ input will be folded into the DSP. In this scenario only, resetting the the accumulator to an arbitrary value can be inferred to use the {C,D} input. \end{lstlisting} -\section{ice40\_ffinit -- iCE40: handle FF init values} -\label{cmd:ice40_ffinit} -\begin{lstlisting}[numbers=left,frame=single] - ice40_ffinit [options] [selection] - -Remove zero init values for FF output signals. Add inverters to implement -nonzero init values. -\end{lstlisting} - -\section{ice40\_ffssr -- iCE40: merge synchronous set/reset into FF cells} -\label{cmd:ice40_ffssr} -\begin{lstlisting}[numbers=left,frame=single] - ice40_ffssr [options] [selection] - -Merge synchronous set/reset $_MUX_ cells into iCE40 FFs. -\end{lstlisting} - \section{ice40\_opt -- iCE40: perform simple optimizations} \label{cmd:ice40_opt} \begin{lstlisting}[numbers=left,frame=single] @@ -2277,7 +2389,7 @@ This command executes the following script: <ice40 specific optimizations> opt_expr -mux_undef -undriven [-full] opt_merge - opt_rmdff + opt_dff opt_clean while <changed design> \end{lstlisting} @@ -2321,26 +2433,28 @@ Map module inputs/outputs to PAD cells from a library. This pass can only map to very simple PAD cells. Use 'techmap' to further map the resulting cells to more sophisticated PAD cells. - -inpad <celltype> <portname>[:<portname>] + -inpad <celltype> <in_port>[:<ext_port>] Map module input ports to the given cell type with the given output port name. if a 2nd portname is given, the - signal is passed through the pad call, using the 2nd + signal is passed through the pad cell, using the 2nd portname as the port facing the module port. - -outpad <celltype> <portname>[:<portname>] - -inoutpad <celltype> <portname>[:<portname>] + -outpad <celltype> <out_port>[:<ext_port>] + -inoutpad <celltype> <io_port>[:<ext_port>] Similar to -inpad, but for output and inout ports. - -toutpad <celltype> <portname>:<portname>[:<portname>] + -toutpad <celltype> <oe_port>:<out_port>[:<ext_port>] Merges $_TBUF_ cells into the output pad cell. This takes precedence over the other -outpad cell. The first portname is the enable input - of the tristate driver. + of the tristate driver, which can be prefixed with `~` for negative + polarity enable. - -tinoutpad <celltype> <portname>:<portname>:<portname>[:<portname>] + -tinoutpad <celltype> <oe_port>:<in_port>:<out_port>[:<ext_port>] Merges $_TBUF_ cells into the inout pad cell. This takes precedence over the other -inoutpad cell. The first portname is the enable input of the tristate driver and the 2nd portname is the internal output - buffering the external signal. + buffering the external signal. Like with `-toutpad`, the enable can + be marked as negative polarity by prefixing the name with `~`. -ignore <celltype> <portname>[:<portname>]* Skips mapping inputs/outputs that are already connected to given @@ -2437,10 +2551,16 @@ options. do not print warnings for the specified experimental feature -expect <type> <regex> <expected_count> - expect log,warning or error to appear. In case of error return code is 0. + expect log, warning or error to appear. matched errors will terminate + with exit code 0. -expect-no-warnings gives error in case there is at least one warning that is not expected. + + -check-expected + verifies that the patterns previously set up by -expect have actually + been met, then clears the expected log list. If this is not called + manually, the check will happen at yosys exist time instead. \end{lstlisting} \section{ls -- list modules or objects in modules} @@ -2485,16 +2605,19 @@ is used then the $macc cell is mapped to $add, $sub, etc. cells instead. \section{memory -- translate memories to basic cells} \label{cmd:memory} \begin{lstlisting}[numbers=left,frame=single] - memory [-nomap] [-nordff] [-memx] [-bram <bram_rules>] [selection] + memory [-nomap] [-nordff] [-nowiden] [-nosat] [-memx] [-bram <bram_rules>] [selection] This pass calls all the other memory_* passes in a useful order: opt_mem - memory_dff [-nordff] (-memx implies -nordff) - opt_clean - memory_share + opt_mem_priority + opt_mem_feedback + memory_dff (skipped if called with -nordff or -memx) opt_clean + memory_share [-nowiden] [-nosat] + opt_mem_widen memory_memx (when called with -memx) + opt_clean memory_collect memory_bram -rules <bram_rules> (when called with -bram) memory_map (skipped if called with -nomap) @@ -2613,17 +2736,14 @@ This pass collects memories and memory ports and creates generic multiport memory cells. \end{lstlisting} -\section{memory\_dff -- merge input/output DFFs into memories} +\section{memory\_dff -- merge input/output DFFs into memory read ports} \label{cmd:memory_dff} \begin{lstlisting}[numbers=left,frame=single] memory_dff [options] [selection] -This pass detects DFFs at memory ports and merges them into the memory port. +This pass detects DFFs at memory read ports and merges them into the memory port. I.e. it consumes an asynchronous memory port and the flip-flops at its interface and yields a synchronous memory port. - - -nordfff - do not merge registers on read ports \end{lstlisting} \section{memory\_map -- translate multiport memories to basic cells} @@ -2656,34 +2776,42 @@ This pass adds additional circuitry that emulates the Verilog simulation behavior for out-of-bounds memory reads and writes. \end{lstlisting} +\section{memory\_narrow -- split up wide memory ports} +\label{cmd:memory_narrow} +\begin{lstlisting}[numbers=left,frame=single] + memory_narrow [options] [selection] + +This pass splits up wide memory ports into several narrow ports. +\end{lstlisting} + \section{memory\_nordff -- extract read port FFs from memories} \label{cmd:memory_nordff} \begin{lstlisting}[numbers=left,frame=single] memory_nordff [options] [selection] This pass extracts FFs from memory read ports. This results in a netlist -similar to what one would get from calling memory_dff with -nordff. +similar to what one would get from not calling memory_dff. \end{lstlisting} \section{memory\_share -- consolidate memory ports} \label{cmd:memory_share} \begin{lstlisting}[numbers=left,frame=single] - memory_share [selection] + memory_share [-nosat] [-nowiden] [selection] This pass merges share-able memory ports into single memory ports. The following methods are used to consolidate the number of memory ports: - - When write ports are connected to async read ports accessing the same - address, then this feedback path is converted to a write port with - byte/part enable signals. - - When multiple write ports access the same address then this is converted to a single write port with a more complex data and/or enable logic path. + - When multiple read or write ports access adjacent aligned addresses, they are + merged to a single wide read or write port. This transformation can be + disabled with the "-nowiden" option. + - When multiple write ports are never accessed at the same time (a SAT solver is used to determine this), then the ports are merged into a single - write port. + write port. This transformation can be disabled with the "-nosat" option. Note that in addition to the algorithms implemented in this pass, the $memrd and $memwr cells are also subject to generic resource sharing passes (and other @@ -2890,27 +3018,27 @@ This pass calls all the other opt_* passes in a useful order. This performs a series of trivial optimizations and cleanups. This pass executes the other passes in the following order: - opt_expr [-mux_undef] [-mux_bool] [-undriven] [-clkinv] [-fine] [-full] [-keepdc] + opt_expr [-mux_undef] [-mux_bool] [-undriven] [-noclkinv] [-fine] [-full] [-keepdc] opt_merge [-share_all] -nomux do opt_muxtree opt_reduce [-fine] [-full] opt_merge [-share_all] - opt_share (-full only) - opt_rmdff [-keepdc] [-sat] + opt_share (-full only) + opt_dff [-nodffe] [-nosdff] [-keepdc] [-sat] (except when called with -noff) opt_clean [-purge] - opt_expr [-mux_undef] [-mux_bool] [-undriven] [-clkinv] [-fine] [-full] [-keepdc] + opt_expr [-mux_undef] [-mux_bool] [-undriven] [-noclkinv] [-fine] [-full] [-keepdc] while <changed design> When called with -fast the following script is used instead: do - opt_expr [-mux_undef] [-mux_bool] [-undriven] [-clkinv] [-fine] [-full] [-keepdc] + opt_expr [-mux_undef] [-mux_bool] [-undriven] [-noclkinv] [-fine] [-full] [-keepdc] opt_merge [-share_all] - opt_rmdff [-keepdc] [-sat] + opt_dff [-nodffe] [-nosdff] [-keepdc] [-sat] (except when called with -noff) opt_clean [-purge] - while <changed design in opt_rmdff> + while <changed design in opt_dff> Note: Options in square brackets (such as [-keepdc]) are passed through to the opt_* commands when given to 'opt'. @@ -2941,6 +3069,35 @@ This pass pushes inverters through $reduce_* cells if this will reduce the overall gate count of the circuit \end{lstlisting} +\section{opt\_dff -- perform DFF optimizations} +\label{cmd:opt_dff} +\begin{lstlisting}[numbers=left,frame=single] + opt_dff [-nodffe] [-nosdff] [-keepdc] [-sat] [selection] + +This pass converts flip-flops to a more suitable type by merging clock enables +and synchronous reset multiplexers, removing unused control inputs, or potentially +removes the flip-flop altogether, converting it to a constant driver. + + -nodffe + disables dff -> dffe conversion, and other transforms recognizing clock enable + + -nosdff + disables dff -> sdff conversion, and other transforms recognizing sync resets + + -simple-dffe + only enables clock enable recognition transform for obvious cases + + -sat + additionally invoke SAT solver to detect and remove flip-flops (with + non-constant inputs) that can also be replaced with a constant driver + + -keepdc + some optimizations change the behavior of the circuit with respect to + don't-care bits. for example in 'a+0' a single x-bit in 'a' will cause + all result bits to be set to x. this behavior changes when 'a+0' is + replaced by 'a'. the -keepdc option disables all such optimizations. +\end{lstlisting} + \section{opt\_expr -- perform const folding and simple expression rewriting} \label{cmd:opt_expr} \begin{lstlisting}[numbers=left,frame=single] @@ -2958,8 +3115,8 @@ It also performs some simple expression rewriting. -undriven replace undriven nets with undef (x) constants - -clkinv - optimize clock inverters by changing FF types + -noclkinv + do not optimize clock inverters by changing FF types -fine perform fine-grain optimizations @@ -3015,6 +3172,38 @@ full set of inputs) or optimizations such as xilinx_dffopt. This pass performs various optimizations on memories in the design. \end{lstlisting} +\section{opt\_mem\_feedback -- convert memory read-to-write port feedback paths to write enables} +\label{cmd:opt_mem_feedback} +\begin{lstlisting}[numbers=left,frame=single] + opt_mem_feedback [selection] + +This pass detects cases where an asynchronous read port is only connected via +a mux tree to a write port with the same address. When such a connection is +found, it is replaced with a new condition on an enable signal, allowing +for removal of the read port. +\end{lstlisting} + +\section{opt\_mem\_priority -- remove priority relations between write ports that can never collide} +\label{cmd:opt_mem_priority} +\begin{lstlisting}[numbers=left,frame=single] + opt_mem_priority [selection] + +This pass detects cases where one memory write port has priority over another +even though they can never collide with each other -- ie. there can never be +a situation where a given memory bit is written by both ports at the same +time, for example because of always-different addresses, or mutually exclusive +enable signals. In such cases, the priority relation is removed. +\end{lstlisting} + +\section{opt\_mem\_widen -- optimize memories where all ports are wide} +\label{cmd:opt_mem_widen} +\begin{lstlisting}[numbers=left,frame=single] + opt_mem_widen [options] [selection] + +This pass looks for memories where all ports are wide and adjusts the base +memory width up until that stops being the case. +\end{lstlisting} + \section{opt\_merge -- consolidate identical cells} \label{cmd:opt_merge} \begin{lstlisting}[numbers=left,frame=single] @@ -3062,19 +3251,6 @@ input with the original control signals OR'ed together. alias for -fine \end{lstlisting} -\section{opt\_rmdff -- remove DFFs with constant inputs} -\label{cmd:opt_rmdff} -\begin{lstlisting}[numbers=left,frame=single] - opt_rmdff [-keepdc] [-sat] [selection] - -This pass identifies flip-flops with constant inputs and replaces them with -a constant driver. - - -sat - additionally invoke SAT solver to detect and remove flip-flops (with - non-constant inputs) that can also be replaced with a constant driver -\end{lstlisting} - \section{opt\_share -- merge mutually exclusive cells of the same type that share an input signal} \label{cmd:opt_share} \begin{lstlisting}[numbers=left,frame=single] @@ -3221,7 +3397,7 @@ on partly selected designs. do not run any of the memory_* passes -rdff - do not pass -nordff to 'memory_dff'. This enables merging of FFs into + call 'memory_dff'. This enables merging of FFs into memory read ports. -nokeepdc @@ -3244,19 +3420,27 @@ The following commands are executed by this synthesis command: opt_expr -keepdc opt_clean check - opt -keepdc + opt -noff -keepdc wreduce -keepdc [-memx] - memory_dff [-nordff] + memory_dff (if -rdff) memory_memx (if -memx) opt_clean memory_collect - opt -keepdc -fast + opt -noff -keepdc -fast check: stat check \end{lstlisting} +\section{printattrs -- print attributes of selected objects} +\label{cmd:printattrs} +\begin{lstlisting}[numbers=left,frame=single] + printattrs [selection] + +Print all attributes of the selected objects. +\end{lstlisting} + \section{proc -- translate processes to netlists} \label{cmd:proc} \begin{lstlisting}[numbers=left,frame=single] @@ -3272,19 +3456,27 @@ This pass calls all the other proc_* passes in the most common order. proc_mux proc_dlatch proc_dff + proc_memwr proc_clean + opt_expr -keepdc This replaces the processes in the design with multiplexers, flip-flops and latches. The following options are supported: + -nomux + Will omit the proc_mux pass. + -global_arst [!]<netname> This option is passed through to proc_arst. -ifx This option is passed through to proc_mux. proc_rmdead is not executed in -ifx mode. + + -noopt + Will omit the opt_expr pass. \end{lstlisting} \section{proc\_arst -- detect asynchronous resets} @@ -3344,6 +3536,14 @@ This pass extracts the 'init' actions from processes (generated from Verilog respective wire. \end{lstlisting} +\section{proc\_memwr -- extract memory writes from processes} +\label{cmd:proc_memwr} +\begin{lstlisting}[numbers=left,frame=single] + proc_memwr [selection] + +This pass converts memory writes in processes into $memwr cells. +\end{lstlisting} + \section{proc\_mux -- convert decision trees to multiplexers} \label{cmd:proc_mux} \begin{lstlisting}[numbers=left,frame=single] @@ -3374,6 +3574,78 @@ a later assignment to the same signal and removes them. This pass identifies unreachable branches in decision trees and removes them. \end{lstlisting} +\section{qbfsat -- solve a 2QBF-SAT problem in the circuit} +\label{cmd:qbfsat} +\begin{lstlisting}[numbers=left,frame=single] + qbfsat [options] [selection] + +This command solves an "exists-forall" 2QBF-SAT problem defined over the currently +selected module. Existentially-quantified variables are declared by assigning a wire +"$anyconst". Universally-quantified variables may be explicitly declared by assigning +a wire "$allconst", but module inputs will be treated as universally-quantified +variables by default. + + -nocleanup + Do not delete temporary files and directories. Useful for debugging. + + -dump-final-smt2 <file> + Pass the --dump-smt2 option to yosys-smtbmc. + + -assume-outputs + Add an "$assume" cell for the conjunction of all one-bit module output wires. + + -assume-negative-polarity + When adding $assume cells for one-bit module output wires, assume they are + negative polarity signals and should always be low, for example like the + miters created with the `miter` command. + + -nooptimize + Ignore "\minimize" and "\maximize" attributes, do not emit "(maximize)" or + "(minimize)" in the SMT-LIBv2, and generally make no attempt to optimize anything. + + -nobisection + If a wire is marked with the "\minimize" or "\maximize" attribute, do not + attempt to optimize that value with the default iterated solving and threshold + bisection approach. Instead, have yosys-smtbmc emit a "(minimize)" or "(maximize)" + command in the SMT-LIBv2 output and hope that the solver supports optimizing + quantified bitvector problems. + + -solver <solver> + Use a particular solver. Choose one of: "z3", "yices", and "cvc4". + (default: yices) + + -solver-option <name> <value> + Set the specified solver option in the SMT-LIBv2 problem file. + + -timeout <value> + Set the per-iteration timeout in seconds. + (default: no timeout) + + -O0, -O1, -O2 + Control the use of ABC to simplify the QBF-SAT problem before solving. + + -sat + Generate an error if the solver does not return "sat". + + -unsat + Generate an error if the solver does not return "unsat". + + -show-smtbmc + Print the output from yosys-smtbmc. + + -specialize + If the problem is satisfiable, replace each "$anyconst" cell with its + corresponding constant value from the model produced by the solver. + + -specialize-from-file <solution file> + Do not run the solver, but instead only attempt to replace each "$anyconst" + cell in the current module with a constant value provided by the specified file. + + -write-solution <solution file> + If the problem is satisfiable, write the corresponding constant value for each + "$anyconst" cell from the model produced by the solver to the specified file. +\end{lstlisting} + \section{qwp -- quadratic wirelength placer} \label{cmd:qwp} \begin{lstlisting}[numbers=left,frame=single] @@ -3420,6 +3692,12 @@ the language version (and before file names) to set additional verilog defines. Load the specified VHDL files. (Requires Verific.) + read {-f|-F} <command-file> + +Load and execute the specified command file. (Requires Verific.) +Check verific command for more information about supported commands in file. + + read -define <macro>[=<value>].. Set global Verilog/SystemVerilog defines. @@ -3483,24 +3761,10 @@ Load modules from a BLIF file into the current design. multi-bit port 'name'. \end{lstlisting} -\section{read\_ilang -- read modules from ilang file} +\section{read\_ilang -- (deprecated) alias of read\_rtlil} \label{cmd:read_ilang} \begin{lstlisting}[numbers=left,frame=single] - read_ilang [filename] - -Load modules from an ilang file to the current design. (ilang is a text -representation of a design in yosys's internal format.) - - -nooverwrite - ignore re-definitions of modules. (the default behavior is to - create an error message if the existing module is not a blackbox - module, and overwrite the existing module if it is a blackbox module.) - - -overwrite - overwrite existing modules with the same name - - -lib - only create empty blackbox modules +See `help read_rtlil`. \end{lstlisting} \section{read\_json -- read JSON file} @@ -3544,6 +3808,26 @@ Read cells from liberty file as modules into current design. set the specified attribute (to the value 1) on all loaded modules \end{lstlisting} +\section{read\_rtlil -- read modules from RTLIL file} +\label{cmd:read_rtlil} +\begin{lstlisting}[numbers=left,frame=single] + read_rtlil [filename] + +Load modules from an RTLIL file to the current design. (RTLIL is a text +representation of a design in yosys's internal format.) + + -nooverwrite + ignore re-definitions of modules. (the default behavior is to + create an error message if the existing module is not a blackbox + module, and overwrite the existing module if it is a blackbox module.) + + -overwrite + overwrite existing modules with the same name + + -lib + only create empty blackbox modules +\end{lstlisting} + \section{read\_verilog -- read modules from Verilog file} \label{cmd:read_verilog} \begin{lstlisting}[numbers=left,frame=single] @@ -3560,6 +3844,9 @@ Verilog-2005 is supported. enable support for SystemVerilog assertions and some Yosys extensions replace the implicit -D SYNTHESIS with -D FORMAL + -nosynthesis + don't add implicit -D SYNTHESIS + -noassert ignore assert() statements @@ -3701,8 +3988,8 @@ recommended to use a simulator (for example Icarus Verilog) for checking the syntax of the code, rather than to rely on read_verilog for that. Depending on if read_verilog is run in -formal mode, either the macro -SYNTHESIS or FORMAL is defined automatically. In addition, read_verilog -always defines the macro YOSYS. +SYNTHESIS or FORMAL is defined automatically, unless -nosynthesis is used. +In addition, read_verilog always defines the macro YOSYS. See the Yosys README file for a list of non-standard Verilog features supported by the Yosys Verilog front-end. @@ -3952,7 +4239,7 @@ This command identifies strongly connected components (aka logic loops) in the design. -expect <num> - expect to find exactly <num> SSCs. A different number of SSCs will + expect to find exactly <num> SCCs. A different number of SCCs will produce an error. -max_depth <num> @@ -3977,6 +4264,9 @@ design. -select replace the current selection with a selection of all cells and wires that are part of a found logic loop + + -specify + examine specify rules to detect logic loops in whitebox/blackbox cells \end{lstlisting} \section{scratchpad -- get/set values in the scratchpad} @@ -4040,6 +4330,7 @@ in the scope of (and thus, relative to) the wires' owning module(s). This \label{cmd:select} \begin{lstlisting}[numbers=left,frame=single] select [ -add | -del | -set <name> ] {-read <filename> | <selection>} + select [ -unset <name> ] select [ <assert_option> ] {-read <filename> | <selection>} select [ -list | -write <filename> | -count | -clear ] select -module <modname> @@ -4062,6 +4353,9 @@ described here. under the given name (see @<name> below). to save the current selection, use "select -set <name> %" + -unset <name> + do not modify the current selection. instead remove a previously saved + selection under the given name (see @<name> below). -assert-none do not modify the current selection. instead assert that the given selection is empty. i.e. produce an error if any object matching the @@ -4132,6 +4426,8 @@ Pushing (selecting) object when in -module mode: <obj_pattern> select the specified object(s) from the current module +By default, patterns will not match black/white-box modules or theircontents. To include such objects, prefix the pattern with '='. + A <mod_pattern> can be a module name, wildcard expression (*, ?, [..]) matching module names, or one of the following: @@ -4318,17 +4614,6 @@ This command replaces undef (x) constants with defined (0/1) constants. replace undef in cell parameters \end{lstlisting} -\section{sf2\_iobs -- SF2: insert IO buffers} -\label{cmd:sf2_iobs} -\begin{lstlisting}[numbers=left,frame=single] - sf2_iobs [options] [selection] - -Add SF2 I/O buffers and global buffers to top module as needed. - - -clkbuf - Insert PAD->global_net clock buffers -\end{lstlisting} - \section{share -- perform sat-based resource sharing} \label{cmd:share} \begin{lstlisting}[numbers=left,frame=single] @@ -4410,7 +4695,7 @@ to a graphics file (usually SVG or PostScript). generate a .dot file, or other <format> strings such as 'svg' or 'ps' to generate files in other formats (this calls the 'dot' command). - -lib <verilog_or_ilang_file> + -lib <verilog_or_rtlil_file> Use the specified library file for determining whether cell ports are inputs or outputs. This option can be used multiple times to specify more than one library. @@ -4453,7 +4738,7 @@ to a graphics file (usually SVG or PostScript). (including inout ports) are on the right side. -pause - wait for the use to press enter to before returning + wait for the user to press enter to before returning -enum enumerate objects with internal ($-prefixed) names @@ -4546,6 +4831,9 @@ This command simulates the circuit using the given top-level module. -vcd <filename> write the simulation results to the given VCD file + -fst <filename> + write the simulation results to the given FST file + -clock <portname> name of top-level clock input @@ -4564,15 +4852,45 @@ This command simulates the circuit using the given top-level module. -zinit zero-initialize all uninitialized regs and memories + -timescale <string> + include the specified timescale declaration in the vcd + -n <integer> - number of cycles to simulate (default: 20) + number of clock cycles to simulate (default: 20) -a - include all nets in VCD output, not just those with public names + use all nets in VCD/FST operations, not just those with public names -w writeback mode: use final simulation state as new init state + -r + read simulation results file (file formats supported: FST) + + -scope + scope of simulation top model + + -at <time> + sets start and stop time + + -start <time> + start co-simulation in arbitary time (default 0) + + -stop <time> + stop co-simulation in arbitary time (default END) + + -sim + simulation with stimulus from FST (default) + + -sim-cmp + co-simulation expect exact match + + -sim-gold + co-simulation, x in simulation can match any value in FST + + -sim-gate + co-simulation, x in FST can match any value in simulation + -d enable debug output \end{lstlisting} @@ -4588,7 +4906,7 @@ primitives. The following internal cell types are mapped by this pass: $not, $pos, $and, $or, $xor, $xnor $reduce_and, $reduce_or, $reduce_xor, $reduce_xnor, $reduce_bool $logic_not, $logic_and, $logic_or, $mux, $tribuf - $sr, $ff, $dff, $dffsr, $adff, $dlatch + $sr, $ff, $dff, $dffe, $dffsr, $dffsre, $adff, $adffe, $aldff, $aldffe, $sdff, $sdffe, $sdffce, $dlatch, $adlatch, $dlatchsr \end{lstlisting} \section{splice -- create explicit splicing cells} @@ -4652,6 +4970,15 @@ This command splits multi-bit nets into single-bit nets. and split nets so that no driver drives only part of a net. \end{lstlisting} +\section{sta -- perform static timing analysis} +\label{cmd:sta} +\begin{lstlisting}[numbers=left,frame=single] + sta [options] [selection] + +This command performs static timing analysis on the design. (Only considers +paths within a single module, so the design must be flattened.) +\end{lstlisting} + \section{stat -- print some statistics} \label{cmd:stat} \begin{lstlisting}[numbers=left,frame=single] @@ -4780,6 +5107,8 @@ The following commands are executed by this synthesis command: opt_expr opt_clean check + opt -nodffe -nosdff + fsm (unless -nofsm) opt wreduce peepopt @@ -4788,8 +5117,6 @@ The following commands are executed by this synthesis command: alumacc (unless -noalumacc) share (unless -noshare) opt - fsm (unless -nofsm) - opt -fast memory -nomap opt_clean @@ -4857,12 +5184,12 @@ The following commands are executed by this synthesis command: opt -fast -mux_undef -undriven -fine -full memory_map opt -undriven -fine - dff2dffe -direct-match $_DFF_* opt -fine techmap -map +/techmap.v opt -full clean -purge setundef -undriven -zero + dfflegalize -cell $_DFF_P_ x abc -markgroups -dff -D 1 (only if -retime) map_luts: @@ -4878,6 +5205,7 @@ The following commands are executed by this synthesis command: hierarchy -check stat check -noinit + blackbox =A:whitebox vout: write_verilog -nodec -attr2comment -defparam -renameprefix syn_ <file-name> @@ -4915,6 +5243,9 @@ This command runs synthesis for Anlogic FPGAs. -nolutram do not use EG_LOGIC_DRAM16X4 cells in output netlist + -nobram + do not use EG_PHY_BRAM or EG_PHY_BRAM32K cells in output netlist + The following commands are executed by this synthesis command: @@ -4931,6 +5262,12 @@ The following commands are executed by this synthesis command: coarse: synth -run coarse + map_bram: (skip if -nobram) + memory_bram -rules +/anlogic/brams.txt + techmap -map +/anlogic/brams_map.v + setundef -zero -params t:EG_PHY_BRAM + setundef -zero -params t:EG_PHY_BRAM32K + map_lutram: (skip if -nolutram) memory_bram -rules +/anlogic/lutrams.txt techmap -map +/anlogic/lutrams_map.v @@ -4947,8 +5284,8 @@ The following commands are executed by this synthesis command: abc -dff -D 1 (only if -retime) map_ffs: + dfflegalize -cell $_DFFE_P??P_ r -cell $_SDFFE_P??P_ r -cell $_DLATCH_N??_ r techmap -D NO_LUT -map +/anlogic/cells_map.v - dffinit -strinit SET RESET -ff AL_MAP_SEQ q REGSET -noreinit opt_expr -mux_undef simplemap @@ -4968,6 +5305,7 @@ The following commands are executed by this synthesis command: hierarchy -check stat check -noinit + blackbox =A:whitebox edif: write_edif <file-name> @@ -5057,6 +5395,7 @@ The following commands are executed by this synthesis command: hierarchy -check stat check -noinit + blackbox =A:whitebox json: write_json <file-name> @@ -5123,6 +5462,7 @@ The following commands are executed by this synthesis command: hierarchy -check stat check -noinit + blackbox =A:whitebox vlog: write_verilog -noexpr -attr2comment <file-name> @@ -5158,6 +5498,9 @@ This command runs synthesis for ECP5 FPGAs. -noflatten do not flatten design before synthesis + -dff + run 'abc'/'abc9' with -dff option + -retime run 'abc' with '-dff -D 1' options @@ -5177,7 +5520,7 @@ This command runs synthesis for ECP5 FPGAs. do not use PFU muxes to implement LUTs larger than LUT4s -asyncprld - use async PRLD mode to implement DLATCH and DFFSR (EXPERIMENTAL) + use async PRLD mode to implement ALDFF (EXPERIMENTAL) -abc2 run two passes of 'abc' for slightly improved logic density @@ -5207,6 +5550,8 @@ The following commands are executed by this synthesis command: opt_expr opt_clean check + opt -nodffe -nosdff + fsm opt wreduce peepopt @@ -5219,8 +5564,6 @@ The following commands are executed by this synthesis command: chtype -set $mul t:$__soft_mul (unless -nodsp) alumacc opt - fsm - opt -fast memory -nomap opt_clean @@ -5243,25 +5586,24 @@ The following commands are executed by this synthesis command: abc -dff -D 1 (only if -retime) map_ffs: - dff2dffs opt_clean - dff2dffe -direct-match $_DFF_* -direct-match $__DFFS_* - techmap -D NO_LUT [-D ASYNC_PRLD] -map +/ecp5/cells_map.v + dfflegalize -cell $_DFF_?_ 01 -cell $_DFF_?P?_ r -cell $_SDFF_?P?_ r [-cell $_DFFE_??_ 01 -cell $_DFFE_?P??_ r -cell $_SDFFE_?P??_ r] [-cell $_ALDFF_?P_ x -cell $_ALDFFE_?P?_ x] [-cell $_DLATCH_?_ x] ($_ALDFF_*_ only if -asyncprld, $_DLATCH_* only if not -asyncprld, $_*DFFE_* only if not -nodffe) + zinit -all w:* t:$_DFF_?_ t:$_DFFE_??_ t:$_SDFF* (only if -abc9 and -dff) + techmap -D NO_LUT -map +/ecp5/cells_map.v opt_expr -undriven -mux_undef simplemap - ecp5_ffinit ecp5_gsr attrmvcp -copy -attr syn_useioff opt_clean map_luts: abc (only if -abc2) - techmap -map +/ecp5/latches_map.v - abc -lut 4:7 -dress + techmap -map +/ecp5/latches_map.v (skip if -asyncprld) + abc -dress -lut 4:7 clean map_cells: - techmap -map +/ecp5/cells_map.v (with -D NO_LUT in vpr mode) + techmap -map +/ecp5/cells_map.v (skip if -vpr) opt_lut_ins -tech ecp5 clean @@ -5270,6 +5612,7 @@ The following commands are executed by this synthesis command: hierarchy -check stat check -noinit + blackbox =A:whitebox blif: opt_clean -purge (vpr mode) @@ -5345,8 +5688,8 @@ The following commands are executed by this synthesis command: abc -dff -D 1 (only if -retime) map_ffs: + dfflegalize -cell $_DFFE_????_ 0 -cell $_SDFFE_????_ 0 -cell $_SDFFCE_????_ 0 -cell $_DLATCH_?_ x techmap -D NO_LUT -map +/efinix/cells_map.v - dffinit -strinit SET RESET -ff AL_MAP_SEQ q REGSET -noreinit opt_expr -mux_undef simplemap @@ -5359,7 +5702,8 @@ The following commands are executed by this synthesis command: clean map_gbuf: - efinix_gbuf + clkbufmap -buf $__EFX_GBUF O:I + techmap -map +/efinix/gbuf_map.v efinix_fixcarry clean @@ -5367,6 +5711,7 @@ The following commands are executed by this synthesis command: hierarchy -check stat check -noinit + blackbox =A:whitebox edif: write_edif <file-name> @@ -5375,6 +5720,149 @@ The following commands are executed by this synthesis command: write_json <file-name> \end{lstlisting} +\section{synth\_gatemate -- synthesis for Cologne Chip GateMate FPGAs} +\label{cmd:synth_gatemate} +\begin{lstlisting}[numbers=left,frame=single] + synth_gatemate [options] + +This command runs synthesis for Cologne Chip AG GateMate FPGAs. + + -top <module> + use the specified module as top module. + + -vlog <file> + write the design to the specified verilog file. Writing of an output + file is omitted if this parameter is not specified. + + -json <file> + write the design to the specified JSON file. Writing of an output file + is omitted if this parameter is not specified. + + -run <from_label>:<to_label> + only run the commands between the labels (see below). An empty + from label is synonymous to 'begin', and empty to label is + synonymous to the end of the command list. + + -noflatten + do not flatten design before synthesis. + + -nobram + do not use CC_BRAM_20K or CC_BRAM_40K cells in output netlist. + + -noaddf + do not use CC_ADDF full adder cells in output netlist. + + -nomult + do not use CC_MULT multiplier cells in output netlist. + + -nomx8, -nomx4 + do not use CC_MX{8,4} multiplexer cells in output netlist. + + -dff + run 'abc' with -dff option + + -retime + run 'abc' with '-dff -D 1' options + + -noiopad + disable I/O buffer insertion (useful for hierarchical or + out-of-context flows). + + -noclkbuf + disable automatic clock buffer insertion. + +The following commands are executed by this synthesis command: + + begin: + read_verilog -lib -specify +/gatemate/cells_sim.v +/gatemate/cells_bb.v + hierarchy -check -top <top> + + prepare: + proc + flatten + tribuf -logic + deminout + opt_expr + opt_clean + check + opt -nodffe -nosdff + fsm + opt + wreduce + peepopt + opt_clean + muxpack + share + techmap -map +/cmp2lut.v -D LUT_WIDTH=4 + opt_expr + opt_clean + + map_mult: (skip if '-nomult') + techmap -map +/gatemate/mul_map.v + + coarse: + alumacc + opt + memory -nomap + opt_clean + + map_bram: (skip if '-nobram') + memory_bram -rules +/gatemate/brams.txt + setundef -zero -params t:$__CC_BRAM_CASCADE t:$__CC_BRAM_40K_SDP t:$__CC_BRAM_20K_SDP t:$__CC_BRAM_20K_TDP t:$__CC_BRAM_40K_TDP + techmap -map +/gatemate/brams_map.v + + map_ffram: + opt -fast -mux_undef -undriven -fine + memory_map + opt -undriven -fine + + map_gates: + techmap -map +/techmap.v -map +/gatemate/arith_map.v + opt -fast + + map_io: (skip if '-noiopad') + iopadmap -bits -inpad CC_IBUF Y:I -outpad CC_OBUF A:O -toutpad CC_TOBUF ~T:A:O -tinoutpad CC_IOBUF ~T:Y:A:IO + clean + + map_regs: + opt_clean + dfflegalize -cell $_DFFE_????_ x -cell $_DLATCH_???_ x + techmap -map +/gatemate/reg_map.v + opt_expr -mux_undef + simplemap + opt_clean + + map_muxs: + muxcover -mux4 -mux8 + opt -full + techmap -map +/gatemate/mux_map.v + + map_luts: + abc -dress -lut 4 + clean + + map_cells: + techmap -map +/gatemate/lut_map.v + clean + + map_bufg: (skip if '-noclkbuf') + clkbufmap -buf CC_BUFG O:I + clean + + check: + hierarchy -check + stat -width + check -noinit + blackbox =A:whitebox + + vlog: + opt_clean -purge + write_verilog -noattr <file-name> + + json: + write_json <file-name> +\end{lstlisting} + \section{synth\_gowin -- synthesis for Gowin FPGAs} \label{cmd:synth_gowin} \begin{lstlisting}[numbers=left,frame=single] @@ -5389,6 +5877,11 @@ This command runs synthesis for Gowin FPGAs. This work is experimental. write the design to the specified Verilog netlist file. writing of an output file is omitted if this parameter is not specified. + -json <file> + write the design to the specified JSON netlist file. writing of an + output file is omitted if this parameter is not specified. + This disables features not yet supported by nexpnr-gowin. + -run <from_label>:<to_label> only run the commands between the labels (see below). an empty from label is synonymous to 'begin', and empty to label is @@ -5415,11 +5908,17 @@ This command runs synthesis for Gowin FPGAs. This work is experimental. -noiopads do not emit IOB at top level ports + -noalu + do not use ALU cells + + -abc9 + use new ABC9 flow (EXPERIMENTAL) + The following commands are executed by this synthesis command: begin: - read_verilog -lib +/gowin/cells_sim.v + read_verilog -specify -lib +/gowin/cells_sim.v hierarchy -check -top <top> flatten: (unless -noflatten) @@ -5438,7 +5937,7 @@ The following commands are executed by this synthesis command: map_lutram: (skip if -nolutram) memory_bram -rules +/gowin/lutrams.txt techmap -map +/gowin/lutrams_map.v - determine_init + setundef -params -zero t:RAM16S4 map_ffram: opt -fast -mux_undef -undriven -fine @@ -5449,12 +5948,11 @@ The following commands are executed by this synthesis command: techmap -map +/techmap.v -map +/gowin/arith_map.v opt -fast abc -dff -D 1 (only if -retime) - splitnets + iopadmap -bits -inpad IBUF O:I -outpad OBUF I:O -toutpad TBUF ~OEN:I:O -tinoutpad IOBUF ~OEN:O:I:IO (unless -noiopads) map_ffs: - dff2dffs -match-init opt_clean - dff2dffe -direct-match $_DFF_* -direct-match $__DFFS_* + dfflegalize -cell $_DFF_?_ 0 -cell $_DFFE_?P_ 0 -cell $_SDFF_?P?_ r -cell $_SDFFE_?P?P_ r -cell $_DFF_?P?_ r -cell $_DFFE_?P?P_ r techmap -map +/gowin/cells_map.v opt_expr -mux_undef simplemap @@ -5468,16 +5966,19 @@ The following commands are executed by this synthesis command: opt_lut_ins -tech gowin setundef -undriven -params -zero hilomap -singleton -hicell VCC V -locell GND G - iopadmap -bits -inpad IBUF O:I -outpad OBUF I:O -toutpad TBUF OEN:I:O -tinoutpad IOBUF OEN:O:I:IO (unless -noiopads) + splitnets -ports (only if -vout used) clean + autoname check: hierarchy -check stat check -noinit + blackbox =A:whitebox vout: - write_verilog -decimal -attr2comment -defparam -renameprefix gen <file-name> + write_verilog -simple-lhs -decimal -attr2comment -defparam -renameprefix gen <file-name> + write_json <file-name> \end{lstlisting} \section{synth\_greenpak4 -- synthesis for GreenPAK4 FPGAs} @@ -5534,7 +6035,7 @@ The following commands are executed by this synthesis command: opt -undriven -fine techmap -map +/techmap.v -map +/greenpak4/cells_latch.v dfflibmap -prepare -liberty +/greenpak4/gp_dff.lib - opt -fast + opt -fast -noclkinv -noff abc -dff -D 1 (only if -retime) map_luts: @@ -5561,6 +6062,7 @@ The following commands are executed by this synthesis command: hierarchy -check stat check -noinit + blackbox =A:whitebox json: write_json <file-name> @@ -5600,6 +6102,9 @@ This command runs synthesis for iCE40 FPGAs. -noflatten do not flatten design before synthesis + -dff + run 'abc'/'abc9' with -dff option + -retime run 'abc' with '-dff -D 1' options @@ -5652,6 +6157,8 @@ The following commands are executed by this synthesis command: opt_expr opt_clean check + opt -nodffe -nosdff + fsm opt wreduce peepopt @@ -5672,8 +6179,6 @@ The following commands are executed by this synthesis command: chtype -set $mul t:$__soft_mul (if -dsp) alumacc opt - fsm - opt -fast memory -nomap opt_clean @@ -5695,12 +6200,10 @@ The following commands are executed by this synthesis command: ice40_opt map_ffs: - dff2dffe -direct-match $_DFF_* - techmap -D NO_LUT -D NO_ADDER -map +/ice40/cells_map.v + dfflegalize -cell $_DFF_?_ 0 -cell $_DFFE_?P_ 0 -cell $_DFF_?P?_ 0 -cell $_DFFE_?P?P_ 0 -cell $_SDFF_?P?_ 0 -cell $_SDFFCE_?P?P_ 0 -cell $_DLATCH_?_ x -mince -1 + techmap -map +/ice40/ff_map.v opt_expr -mux_undef simplemap - ice40_ffinit - ice40_ffssr ice40_opt -full map_luts: @@ -5710,14 +6213,14 @@ The following commands are executed by this synthesis command: simplemap (if -noabc or -flowmap) techmap -map +/gate2lut.v -D LUT_WIDTH=4 (only if -noabc) flowmap -maxlut 4 (only if -flowmap) - abc -dress -lut 4 (skip if -noabc) + abc -dress -lut 4 (skip if -noabc) ice40_wrapcarry -unwrap - techmap -D NO_LUT -map +/ice40/cells_map.v + techmap -map +/ice40/ff_map.v clean - opt_lut -dlogic SB_CARRY:I0=2:I1=1:CI=0 + opt_lut -dlogic SB_CARRY:I0=1:I1=2:CI=3 -dlogic SB_CARRY:CO=3 map_cells: - techmap -map +/ice40/cells_map.v (with -D NO_LUT in vpr mode) + techmap -map +/ice40/cells_map.v (skip if -vpr) clean check: @@ -5725,6 +6228,7 @@ The following commands are executed by this synthesis command: hierarchy -check stat check -noinit + blackbox =A:whitebox blif: opt_clean -purge (vpr mode) @@ -5745,11 +6249,11 @@ The following commands are executed by this synthesis command: This command runs synthesis for Intel FPGAs. - -family <max10 | arria10gx | cyclone10lp | cyclonev | cycloneiv | cycloneive> + -family <max10 | cyclone10lp | cycloneiv | cycloneive> generate the synthesis netlist for the specified family. MAX10 is the default target if no family argument specified. For Cyclone IV GX devices, use cycloneiv argument; for Cyclone IV E, use cycloneive. - Cyclone V and Arria 10 GX devices are experimental. + For Cyclone V and Cyclone 10 GX, use the synth_intel_alm backend instead. -top <module> use the specified module as top module (default='top') @@ -5809,14 +6313,16 @@ The following commands are executed by this synthesis command: opt -fast -mux_undef -undriven -fine -full memory_map opt -undriven -fine - dff2dffe -direct-match $_DFF_* - opt -fine techmap -map +/techmap.v opt -full clean -purge setundef -undriven -zero abc -markgroups -dff -D 1 (only if -retime) + map_ffs: + dfflegalize -cell $_DFFE_PN0P_ 01 + techmap -map +/intel/common/ff_map.v + map_luts: abc -lut 4 clean @@ -5824,13 +6330,13 @@ The following commands are executed by this synthesis command: map_cells: iopadmap -bits -outpad $__outpad I:O -inpad $__inpad O:I (if -iopads) techmap -map +/intel/max10/cells_map.v - dffinit -highlow -ff dffeas q power_up clean -purge check: hierarchy -check stat check -noinit + blackbox =A:whitebox vqm: write_verilog -attr2comment -defparam -nohex -decimal -renameprefix syn_ <file-name> @@ -5843,6 +6349,496 @@ The following commands are executed by this synthesis command: WARNING: THE 'synth_intel' COMMAND IS EXPERIMENTAL. \end{lstlisting} +\section{synth\_intel\_alm -- synthesis for ALM-based Intel (Altera) FPGAs.} +\label{cmd:synth_intel_alm} +\begin{lstlisting}[numbers=left,frame=single] + synth_intel_alm [options] + +This command runs synthesis for ALM-based Intel FPGAs. + + -top <module> + use the specified module as top module + + -family <family> + target one of: + "cyclonev" - Cyclone V (default) + "arriav" - Arria V (non-GZ) "cyclone10gx" - Cyclone 10GX + + -vqm <file> + write the design to the specified Verilog Quartus Mapping File. Writing of an + output file is omitted if this parameter is not specified. Implies -quartus. + + -noflatten + do not flatten design before synthesis; useful for per-module area statistics + + -quartus + output a netlist using Quartus cells instead of MISTRAL_* cells + + -dff + pass DFFs to ABC to perform sequential logic optimisations (EXPERIMENTAL) + + -run <from_label>:<to_label> + only run the commands between the labels (see below). an empty + from label is synonymous to 'begin', and empty to label is + synonymous to the end of the command list. + + -nolutram + do not use LUT RAM cells in output netlist + + -nobram + do not use block RAM cells in output netlist + + -nodsp + do not map multipliers to MISTRAL_MUL cells + + -noiopad + do not instantiate IO buffers + + -noclkbuf + do not insert global clock buffers + +The following commands are executed by this synthesis command: + + begin: + read_verilog -specify -lib -D <family> +/intel_alm/common/alm_sim.v + read_verilog -specify -lib -D <family> +/intel_alm/common/dff_sim.v + read_verilog -specify -lib -D <family> +/intel_alm/common/dsp_sim.v + read_verilog -specify -lib -D <family> +/intel_alm/common/mem_sim.v + read_verilog -specify -lib -D <family> +/intel_alm/common/misc_sim.v + read_verilog -specify -lib -D <family> -icells +/intel_alm/common/abc9_model.v + read_verilog -lib +/intel/common/altpll_bb.v + read_verilog -lib +/intel_alm/common/megafunction_bb.v + hierarchy -check -top <top> + + coarse: + proc + flatten (skip if -noflatten) + tribuf -logic + deminout + opt_expr + opt_clean + check + opt -nodffe -nosdff + fsm + opt + wreduce + peepopt + opt_clean + share + techmap -map +/cmp2lut.v -D LUT_WIDTH=6 + opt_expr + opt_clean + techmap -map +/mul2dsp.v [...] (unless -nodsp) + alumacc + iopadmap -bits -outpad MISTRAL_OB I:PAD -inpad MISTRAL_IB O:PAD -toutpad MISTRAL_IO OE:O:PAD -tinoutpad MISTRAL_IO OE:O:I:PAD A:top (unless -noiopad) + techmap -map +/intel_alm/common/arith_alm_map.v -map +/intel_alm/common/dsp_map.v + opt + memory -nomap + opt_clean + + map_bram: (skip if -nobram) + memory_bram -rules +/intel_alm/common/bram_<bram_type>.txt + techmap -map +/intel_alm/common/bram_<bram_type>_map.v + + map_lutram: (skip if -nolutram) + memory_bram -rules +/intel_alm/common/lutram_mlab.txt (for Cyclone V / Cyclone 10GX) + + map_ffram: + memory_map + opt -full + + map_ffs: + techmap + dfflegalize -cell $_DFFE_PN0P_ 0 -cell $_SDFFCE_PP0P_ 0 + techmap -map +/intel_alm/common/dff_map.v + opt -full -undriven -mux_undef + clean -purge + clkbufmap -buf MISTRAL_CLKBUF Q:A (unless -noclkbuf) + + map_luts: + techmap -map +/intel_alm/common/abc9_map.v + abc9 [-dff] -maxlut 6 -W 600 + techmap -map +/intel_alm/common/abc9_unmap.v + techmap -map +/intel_alm/common/alm_map.v + opt -fast + autoname + clean + + check: + hierarchy -check + stat + check + blackbox =A:whitebox + + quartus: + rename -hide w:*[* w:*]* + setundef -zero + hilomap -singleton -hicell __MISTRAL_VCC Q -locell __MISTRAL_GND Q + techmap -D <family> -map +/intel_alm/common/quartus_rename.v + + vqm: + write_verilog -attr2comment -defparam -nohex -decimal <file-name> +\end{lstlisting} + +\section{synth\_machxo2 -- synthesis for MachXO2 FPGAs. This work is experimental.} +\label{cmd:synth_machxo2} +\begin{lstlisting}[numbers=left,frame=single] + synth_machxo2 [options] + +This command runs synthesis for MachXO2 FPGAs. + + -top <module> + use the specified module as top module + + -blif <file> + write the design to the specified BLIF file. writing of an output file + is omitted if this parameter is not specified. + + -edif <file> + write the design to the specified EDIF file. writing of an output file + is omitted if this parameter is not specified. + + -json <file> + write the design to the specified JSON file. writing of an output file + is omitted if this parameter is not specified. + + -run <from_label>:<to_label> + only run the commands between the labels (see below). an empty + from label is synonymous to 'begin', and empty to label is + synonymous to the end of the command list. + + -noflatten + do not flatten design before synthesis + + -noiopad + do not insert IO buffers + + -vpr + generate an output netlist (and BLIF file) suitable for VPR + (this feature is experimental and incomplete) + + +The following commands are executed by this synthesis command: + + begin: + read_verilog -lib -icells +/machxo2/cells_sim.v + hierarchy -check -top <top> + + flatten: (unless -noflatten) + proc + flatten + tribuf -logic + deminout + + coarse: + synth -run coarse + + fine: + memory_map + opt -full + techmap -map +/techmap.v + opt -fast + + map_ios: (unless -noiopad) + iopadmap -bits -outpad $__FACADE_OUTPAD I:O -inpad $__FACADE_INPAD O:I -toutpad $__FACADE_TOUTPAD ~T:I:O -tinoutpad $__FACADE_TINOUTPAD ~T:O:I:B A:top + attrmvcp -attr src -attr LOC t:$__FACADE_OUTPAD %x:+[O] t:$__FACADE_TOUTPAD %x:+[O] t:$__FACADE_TINOUTPAD %x:+[B] + attrmvcp -attr src -attr LOC -driven t:$__FACADE_INPAD %x:+[I] + + map_ffs: + dfflegalize -cell $_DFF_P_ 0 + + map_luts: + abc -lut 4 -dress + clean + + map_cells: + techmap -map +/machxo2/cells_map.v + clean + + check: + hierarchy -check + stat + blackbox =A:whitebox + + blif: + opt_clean -purge (vpr mode) + write_blif -attr -cname -conn -param <file-name> (vpr mode) + write_blif -gates -attr -param <file-name> (non-vpr mode) + + edif: + write_edif <file-name> + + json: + write_json <file-name> +\end{lstlisting} + +\section{synth\_nexus -- synthesis for Lattice Nexus FPGAs} +\label{cmd:synth_nexus} +\begin{lstlisting}[numbers=left,frame=single] + synth_nexus [options] + +This command runs synthesis for Lattice Nexus FPGAs. + + -top <module> + use the specified module as top module + + -family <device> + run synthesis for the specified Nexus device + supported values: lifcl, lfd2nx + + -json <file> + write the design to the specified JSON file. writing of an output file + is omitted if this parameter is not specified. + + -vm <file> + write the design to the specified structural Verilog file. writing of + an output file is omitted if this parameter is not specified. + + -run <from_label>:<to_label> + only run the commands between the labels (see below). an empty + from label is synonymous to 'begin', and empty to label is + synonymous to the end of the command list. + + -noflatten + do not flatten design before synthesis + + -dff + run 'abc'/'abc9' with -dff option + + -retime + run 'abc' with '-dff -D 1' options + + -noccu2 + do not use CCU2 cells in output netlist + + -nodffe + do not use flipflops with CE in output netlist + + -nolram + do not use large RAM cells in output netlist + note that large RAM must be explicitly requested with a (* lram *) + attribute on the memory. + + -nobram + do not use block RAM cells in output netlist + + -nolutram + do not use LUT RAM cells in output netlist + + -nowidelut + do not use PFU muxes to implement LUTs larger than LUT4s + + -noiopad + do not insert IO buffers + + -nodsp + do not infer DSP multipliers + + -abc9 + use new ABC9 flow (EXPERIMENTAL) + +The following commands are executed by this synthesis command: + + begin: + read_verilog -lib -specify +/nexus/cells_sim.v +/nexus/cells_xtra.v + hierarchy -check -top <top> + + coarse: + proc + flatten + tribuf -logic + deminout + opt_expr + opt_clean + check + opt -nodffe -nosdff + fsm + opt + wreduce + peepopt + opt_clean + share + techmap -map +/cmp2lut.v -D LUT_WIDTH=4 + opt_expr + opt_clean + techmap -map +/mul2dsp.v [...] (unless -nodsp) + techmap -map +/nexus/dsp_map.v (unless -nodsp) + alumacc + opt + memory -nomap + opt_clean + + map_lram: (skip if -nolram) + memory_bram -rules +/nexus/lrams.txt + setundef -zero -params t:$__NX_PDPSC512K + techmap -map +/nexus/lrams_map.v + + map_bram: (skip if -nobram) + memory_bram -rules +/nexus/brams.txt + setundef -zero -params t:$__NX_PDP16K + techmap -map +/nexus/brams_map.v + + map_lutram: (skip if -nolutram) + memory_bram -rules +/nexus/lutrams.txt + setundef -zero -params t:$__NEXUS_DPR16X4 + techmap -map +/nexus/lutrams_map.v + + map_ffram: + opt -fast -mux_undef -undriven -fine + memory_map -iattr -attr !ram_block -attr !rom_block -attr logic_block -attr syn_ramstyle=auto -attr syn_ramstyle=registers -attr syn_romstyle=auto -attr syn_romstyle=logic + opt -undriven -fine + + map_gates: + techmap -map +/techmap.v -map +/nexus/arith_map.v + iopadmap -bits -outpad OB I:O -inpad IB O:I -toutpad OBZ ~T:I:O -tinoutpad BB ~T:O:I:B A:top (skip if '-noiopad') + opt -fast + abc -dff -D 1 (only if -retime) + + map_ffs: + opt_clean + dfflegalize -cell $_DFF_P_ 01 -cell $_DFF_PP?_ r -cell $_SDFF_PP?_ r -cell $_DLATCH_?_ x [-cell $_DFFE_PP_ 01 -cell $_DFFE_PP?P_ r -cell $_SDFFE_PP?P_ r] ($_*DFFE_* only if not -nodffe) + zinit -all w:* t:$_DFF_?_ t:$_DFFE_??_ t:$_SDFF* (only if -abc9 and -dff + techmap -D NO_LUT -map +/nexus/cells_map.v + opt_expr -undriven -mux_undef + simplemap + attrmvcp -copy -attr syn_useioff + opt_clean + + map_luts: + techmap -map +/nexus/latches_map.v + abc -dress -lut 4:5 + clean + + map_cells: + techmap -map +/nexus/cells_map.v + setundef -zero + hilomap -singleton -hicell VHI Z -locell VLO Z + clean + + check: + autoname + hierarchy -check + stat + check -noinit + blackbox =A:whitebox + + json: + write_json <file-name> + + vm: + write_verilog <file-name> +\end{lstlisting} + +\section{synth\_quicklogic -- Synthesis for QuickLogic FPGAs} +\label{cmd:synth_quicklogic} +\begin{lstlisting}[numbers=left,frame=single] + synth_quicklogic [options] +This command runs synthesis for QuickLogic FPGAs + + -top <module> + use the specified module as top module + + -family <family> + run synthesis for the specified QuickLogic architecture + generate the synthesis netlist for the specified family. + supported values: + - pp3: PolarPro 3 + + -blif <file> + write the design to the specified BLIF file. writing of an output file + is omitted if this parameter is not specified. + + -verilog <file> + write the design to the specified verilog file. writing of an output file + is omitted if this parameter is not specified. + + -abc + use old ABC flow, which has generally worse mapping results but is less + likely to have bugs. + +The following commands are executed by this synthesis command: + + begin: + read_verilog -lib -specify +/quicklogic/cells_sim.v +/quicklogic/pp3_cells_sim.v + read_verilog -lib -specify +/quicklogic/lut_sim.v + hierarchy -check -top <top> + + coarse: + proc + flatten + tribuf -logic + deminout + opt_expr + opt_clean + check + opt -nodffe -nosdff + fsm + opt + wreduce + peepopt + opt_clean + share + techmap -map +/cmp2lut.v -D LUT_WIDTH=4 + opt_expr + opt_clean + alumacc + pmuxtree + opt + memory -nomap + opt_clean + + map_ffram: + opt -fast -mux_undef -undriven -fine + memory_map -iattr -attr !ram_block -attr !rom_block -attr logic_block -attr syn_ramstyle=auto -attr syn_ramstyle=registers -attr syn_romstyle=auto -attr syn_romstyle=logic + opt -undriven -fine + + map_gates: + techmap + opt -fast + muxcover -mux8 -mux4 + + map_ffs: + opt_expr + dfflegalize -cell $_DFFSRE_PPPP_ 0 -cell $_DLATCH_?_ x + techmap -map +/quicklogic/pp3_cells_map.v -map +/quicklogic/pp3_ffs_map.v + opt_expr -mux_undef + + map_luts: + techmap -map +/quicklogic/pp3_latches_map.v + read_verilog -lib -specify -icells +/quicklogic/abc9_model.v + techmap -map +/quicklogic/abc9_map.v + abc9 -maxlut 4 -dff + techmap -map +/quicklogic/abc9_unmap.v + clean + + map_cells: + techmap -map +/quicklogic/pp3_lut_map.v + clean + + check: + autoname + hierarchy -check + stat + check -noinit + + iomap: + clkbufmap -inpad ckpad Q:P + iopadmap -bits -outpad outpad A:P -inpad inpad Q:P -tinoutpad bipad EN:Q:A:P A:top + + finalize: + setundef -zero -params -undriven + hilomap -hicell logic_1 A -locell logic_0 A -singleton A:top + opt_clean -purge + check + blackbox =A:whitebox + + blif: + write_blif -attr -param -auto-top + + verilog: + write_verilog -noattr -nohex <file-name> +\end{lstlisting} + \section{synth\_sf2 -- synthesis for SmartFusion2 and IGLOO2 FPGAs} \label{cmd:synth_sf2} \begin{lstlisting}[numbers=left,frame=single] @@ -5907,6 +6903,7 @@ The following commands are executed by this synthesis command: abc -dff -D 1 (only if -retime) map_ffs: + dfflegalize -cell $_DFFE_PN?P_ x -cell $_SDFFCE_PN?P_ x -cell $_DLATCH_PN?_ x techmap -D NO_LUT -map +/sf2/cells_map.v opt_expr -mux_undef simplemap @@ -5920,13 +6917,15 @@ The following commands are executed by this synthesis command: clean map_iobs: - sf2_iobs [-clkbuf] (unless -noiobs) + clkbufmap -buf CLKINT Y:A [-inpad CLKBUF Y:PAD] (unless -noiobs, -inpad only passed if -clkbuf) + iopadmap -bits -inpad INBUF Y:PAD -outpad OUTBUF D:PAD -toutpad TRIBUFF E:D:PAD -tinoutpad BIBUF E:Y:D:PAD (unless -noiobs clean check: hierarchy -check stat check -noinit + blackbox =A:whitebox edif: write_edif -gndvccy <file-name> @@ -5978,10 +6977,6 @@ compatible with 7-Series Xilinx devices. write the design to the specified BLIF file. writing of an output file is omitted if this parameter is not specified. - -vpr - generate an output netlist (and BLIF file) suitable for VPR - (this feature is experimental and incomplete) - -ise generate an output netlist suitable for ISE @@ -6052,6 +7047,8 @@ The following commands are executed by this synthesis command: opt_expr opt_clean check + opt -nodffe -nosdff + fsm opt wreduce [-keepdc] (option for '-widemux') peepopt @@ -6076,8 +7073,6 @@ The following commands are executed by this synthesis command: alumacc share opt - fsm - opt -fast memory -nomap opt_clean @@ -6094,33 +7089,34 @@ The following commands are executed by this synthesis command: techmap -map +/xilinx/lutrams_map.v map_ffram: - simplemap t:$dff t:$adff t:$mux - dff2dffs [-match-init] (-match-init for xc6s only) opt -fast -full memory_map fine: - dff2dffe -direct-match $_DFF_* -direct-match $__DFFS_* - muxcover <internal options> ('-widemux' only) + simplemap t:$mux ('-widemux' only) + muxcover <internal options> ('-widemux' only) opt -full xilinx_srl -variable -minlen 3 (skip if '-nosrl') techmap -map +/techmap.v -D LUT_SIZE=[46] [-map +/xilinx/mux_map.v] -map +/xilinx/arith_map.v opt -fast map_cells: - iopadmap -bits -outpad OBUF I:O -inpad IBUF O:I -toutpad $__XILINX_TOUTPAD OE:I:O -tinoutpad $__XILINX_TINOUTPAD OE:O:I:IO A:top (skip if '-noiopad') + iopadmap -bits -outpad OBUF I:O -inpad IBUF O:I -toutpad OBUFT ~T:I:O -tinoutpad IOBUF ~T:O:I:IO A:top (skip if '-noiopad') techmap -map +/techmap.v -map +/xilinx/cells_map.v clean map_ffs: - techmap -map +/xilinx/{family}_ff_map.v ('-abc9' only) + dfflegalize -cell $_DFFE_?P?P_ 01 -cell $_SDFFE_?P?P_ 01 -cell $_DLATCH_?P?_ 01 (for xc6v, xc7, xcu, xcup) + zinit -all w:* t:$_SDFFE_* ('-dff' only) + techmap -map +/xilinx/ff_map.v ('-abc9' only) map_luts: - opt_expr -mux_undef - abc -luts 2:2,3,6:5[,10,20] [-dff] [-D 1] (option for 'nowidelut', '-dff', '-retime') + opt_expr -mux_undef -noclkinv + abc -luts 2:2,3,6:5[,10,20] [-dff] [-D 1] (option for '-nowidelut', '-dff', '-retime') clean + techmap -map +/xilinx/ff_map.v (only if not '-abc9') xilinx_srl -fixed -minlen 3 (skip if '-nosrl') - techmap -map +/xilinx/lut_map.v -map +/xilinx/cells_map.v -map +/xilinx/{family}_ff_map.v -D LUT_WIDTH=[46] + techmap -map +/xilinx/lut_map.v -map +/xilinx/cells_map.v -D LUT_WIDTH=[46] xilinx_dffopt [-lut4] opt_lut_ins -tech xilinx @@ -6133,6 +7129,7 @@ The following commands are executed by this synthesis command: hierarchy -check stat -tech xilinx check -noinit + blackbox =A:whitebox edif: write_edif -pvector bra @@ -6164,7 +7161,7 @@ the standard $argc and $argv variables. techmap [-map filename] [selection] This pass implements a very simple technology mapper that replaces cells in -the design with implementations given in form of a Verilog or ilang source +the design with implementations given in form of a Verilog or RTLIL source file. -map filename @@ -6207,7 +7204,9 @@ file. When a module in the map file has the 'techmap_celltype' attribute set, it will match cells with a type that match the text value of this attribute. Otherwise -the module name will be used to match the cell. +the module name will be used to match the cell. Multiple space-separated cell +types can be listed, and wildcards using [] will be expanded (ie. "$_DFF_[PN]_" +is the same as "$_DFF_P_ $_DFF_N_"). When a module in the map file has the 'techmap_simplemap' attribute set, techmap will use 'simplemap' (see 'help simplemap') to map cells matching the module. @@ -6276,6 +7275,10 @@ modules in the map file: When a parameter with this name exists, it will be set to the type name of the cell that matches the module. + _TECHMAP_CELLNAME_ + When a parameter with this name exists, it will be set to the name + of the cell that matches the module. + _TECHMAP_CONSTMSK_<port-name>_ _TECHMAP_CONSTVAL_<port-name>_ When this pair of parameters is available in a module for a port, then @@ -6401,12 +7404,12 @@ cell types. Use for example 'all /$add' for all cell types except $add. -s {positive_integer} use this value as rng seed value (default = unix time). - -f {ilang_file} - don't generate circuits. instead load the specified ilang file. + -f {rtlil_file} + don't generate circuits. instead load the specified RTLIL file. -w {filename_prefix} don't test anything. just generate the circuits and write them - to ilang files with the specified prefix + to RTLIL files with the specified prefix -map {filename} pass this option to techmap. @@ -6535,7 +7538,7 @@ different compilation units. Additional -D<macro>[=<value>] options may be added after the option indicating the language version (and before file names) to set additional verilog defines. -The macros SYNTHESIS and VERIFIC are defined implicitly. +The macros YOSYS, SYNTHESIS, and VERIFIC are defined implicitly. verific -formal <verilog-file>.. @@ -6548,6 +7551,32 @@ Like -sv, but define FORMAL instead of SYNTHESIS. Load the specified VHDL files into Verific. + verific {-f|-F} <command-file> + +Load and execute the specified command file. + +Command file parser supports following commands: + +define - defines macro + -u - upper case all identifier (makes Verilog parser case insensitive) + -v - register library name (file) + -y - register library name (directory) + +incdir - specify include dir + +libext - specify library extension + +liborder - add library in ordered list + +librescan - unresolved modules will be always searched starting with the first + library specified by -y/-v options. + -f/-file - nested -f option + -F - nested -F option + + parse mode: + -ams + +systemverilogext + +v2k + +verilog1995ext + +verilog2001ext + -sverilog + + verific [-work <libname>] {-sv|-vhdl|...} <hdl-file> Load the specified Verilog/SystemVerilog/VHDL file into the specified library. @@ -6652,11 +7681,74 @@ bindings (for Yosys and/or Verific developers): Dump the Verific netlist as a verilog file. -Use Symbiotic EDA Suite if you need Yosys+Verifc. -https://www.symbioticeda.com/seda-suite + verific [-work <libname>] -pp [options] <filename> [<module>].. + +Pretty print design (or just module) to the specified file from the +specified library. (default library when -work is not present: "work") + +Pretty print options: + + -verilog + Save output for Verilog/SystemVerilog design modules (default). + + -vhdl + Save output for VHDL design units. + + + verific -app <application>.. + +Execute YosysHQ formal application on loaded Verilog files. + +Application options: + + -module <module> + Run formal application only on specified module. + + -blacklist <filename[:lineno]> + Do not run application on modules from files that match the filename + or filename and line number if provided in such format. + Parameter can also contain comma separated list of file locations. + + -blfile <file> + Do not run application on locations specified in file, they can represent filename + or filename and location in file. -Contact office@symbioticeda.com for free evaluation -binaries of Symbiotic EDA Suite. +Applications: + + WARNING: Applications only available in commercial build. + + + verific -template <name> <top_module>.. + +Generate template for specified top module of loaded design. + +Template options: + + -out + Specifies output file for generated template, by default output is stdout + + -chparam name value + Generate template using this parameter value. Otherwise default parameter + values will be used for templat generate functionality. This option + can be specified multiple times to override multiple parameters. + String values must be passed in double quotes ("). + +Templates: + + WARNING: Templates only available in commercial build. + + + + verific -cfg [<name> [<value>]] + +Get/set Verific runtime flags. + + +Use YosysHQ Tabby CAD Suite if you need Yosys+Verific. +https://www.yosyshq.com/ + +Contact office@yosyshq.com for free evaluation +binaries of YosysHQ Tabby CAD Suite. \end{lstlisting} \section{verilog\_defaults -- set default options for read\_verilog} @@ -6855,6 +7947,9 @@ Write a BTOR description of the current design. -i <filename> Create additional info file with auxiliary information + + -x + Output symbols for internal netnames (starting with '$') \end{lstlisting} \section{write\_cxxrtl -- convert design to C++ RTL simulation} @@ -6862,25 +7957,189 @@ Write a BTOR description of the current design. \begin{lstlisting}[numbers=left,frame=single] write_cxxrtl [options] [filename] -Write C++ code for simulating the design. The generated code requires a driver; -the following simple driver is provided as an example: +Write C++ code that simulates the design. The generated code requires a driver +that instantiates the design, toggles its clock, and interacts with its ports. + +The following driver may be used as an example for a design with a single clock +driving rising edge triggered flip-flops: #include "top.cc" int main() { cxxrtl_design::p_top top; + top.step(); while (1) { - top.p_clk.next = value<1> {1u}; + /* user logic */ + top.p_clk.set(false); top.step(); - top.p_clk.next = value<1> {0u}; + top.p_clk.set(true); top.step(); } } +Note that CXXRTL simulations, just like the hardware they are simulating, are +subject to race conditions. If, in the example above, the user logic would run +simultaneously with the rising edge of the clock, the design would malfunction. + +This backend supports replacing parts of the design with black boxes implemented +in C++. If a module marked as a CXXRTL black box, its implementation is ignored, +and the generated code consists only of an interface and a factory function. +The driver must implement the factory function that creates an implementation of +the black box, taking into account the parameters it is instantiated with. + +For example, the following Verilog code defines a CXXRTL black box interface for +a synchronous debug sink: + + (* cxxrtl_blackbox *) + module debug(...); + (* cxxrtl_edge = "p" *) input clk; + input en; + input [7:0] i_data; + (* cxxrtl_sync *) output [7:0] o_data; + endmodule + +For this HDL interface, this backend will generate the following C++ interface: + + struct bb_p_debug : public module { + value<1> p_clk; + bool posedge_p_clk() const { /* ... */ } + value<1> p_en; + value<8> p_i_data; + wire<8> p_o_data; + + bool eval() override; + bool commit() override; + + static std::unique_ptr<bb_p_debug> + create(std::string name, metadata_map parameters, metadata_map attributes); + }; + +The `create' function must be implemented by the driver. For example, it could +always provide an implementation logging the values to standard error stream: + + namespace cxxrtl_design { + + struct stderr_debug : public bb_p_debug { + bool eval() override { + if (posedge_p_clk() && p_en) + fprintf(stderr, "debug: %02x\n", p_i_data.data[0]); + p_o_data.next = p_i_data; + return bb_p_debug::eval(); + } + }; + + std::unique_ptr<bb_p_debug> + bb_p_debug::create(std::string name, cxxrtl::metadata_map parameters, + cxxrtl::metadata_map attributes) { + return std::make_unique<stderr_debug>(); + } + + } + +For complex applications of black boxes, it is possible to parameterize their +port widths. For example, the following Verilog code defines a CXXRTL black box +interface for a configurable width debug sink: + + (* cxxrtl_blackbox, cxxrtl_template = "WIDTH" *) + module debug(...); + parameter WIDTH = 8; + (* cxxrtl_edge = "p" *) input clk; + input en; + (* cxxrtl_width = "WIDTH" *) input [WIDTH - 1:0] i_data; + (* cxxrtl_width = "WIDTH" *) output [WIDTH - 1:0] o_data; + endmodule + +For this parametric HDL interface, this backend will generate the following C++ +interface (only the differences are shown): + + template<size_t WIDTH> + struct bb_p_debug : public module { + // ... + value<WIDTH> p_i_data; + wire<WIDTH> p_o_data; + // ... + static std::unique_ptr<bb_p_debug<WIDTH>> + create(std::string name, metadata_map parameters, metadata_map attributes); + }; + +The `create' function must be implemented by the driver, specialized for every +possible combination of template parameters. (Specialization is necessary to +enable separate compilation of generated code and black box implementations.) + + template<size_t SIZE> + struct stderr_debug : public bb_p_debug<SIZE> { + // ... + }; + + template<> + std::unique_ptr<bb_p_debug<8>> + bb_p_debug<8>::create(std::string name, cxxrtl::metadata_map parameters, + cxxrtl::metadata_map attributes) { + return std::make_unique<stderr_debug<8>>(); + } + +The following attributes are recognized by this backend: + + cxxrtl_blackbox + only valid on modules. if specified, the module contents are ignored, + and the generated code includes only the module interface and a factory + function, which will be called to instantiate the module. + + cxxrtl_edge + only valid on inputs of black boxes. must be one of "p", "n", "a". + if specified on signal `clk`, the generated code includes edge detectors + `posedge_p_clk()` (if "p"), `negedge_p_clk()` (if "n"), or both (if + "a"), simplifying implementation of clocked black boxes. + + cxxrtl_template + only valid on black boxes. must contain a space separated sequence of + identifiers that have a corresponding black box parameters. for each + of them, the generated code includes a `size_t` template parameter. + + cxxrtl_width + only valid on ports of black boxes. must be a constant expression, which + is directly inserted into generated code. + + cxxrtl_comb, cxxrtl_sync + only valid on outputs of black boxes. if specified, indicates that every + bit of the output port is driven, correspondingly, by combinatorial or + synchronous logic. this knowledge is used for scheduling optimizations. + if neither is specified, the output will be pessimistically treated as + driven by both combinatorial and synchronous logic. + The following options are supported by this backend: + -print-wire-types, -print-debug-wire-types + enable additional debug logging, for pass developers. + + -header + generate separate interface (.h) and implementation (.cc) files. + if specified, the backend must be called with a filename, and filename + of the interface is derived from filename of the implementation. + otherwise, interface and implementation are generated together. + + -namespace <ns-name> + place the generated code into namespace <ns-name>. if not specified, + "cxxrtl_design" is used. + + -nohierarchy + use design hierarchy as-is. in most designs, a top module should be + present as it is exposed through the C API and has unbuffered outputs + for improved performance; it will be determined automatically if absent. + + -noflatten + don't flatten the design. fully flattened designs can evaluate within + one delta cycle if they have no combinatorial feedback. + note that the debug interface and waveform dumps use full hierarchical + names for all wires even in flattened designs. + + -noproc + don't convert processes to netlists. in most designs, converting + processes significantly improves evaluation performance at the cost of + slight increase in compilation time. + -O <level> - set the optimization level. the default is -O5. higher optimization + set the optimization level. the default is -O6. higher optimization levels dramatically decrease compile and run time, and highest level possible for a design should be used. @@ -6888,19 +8147,45 @@ The following options are supported by this backend: no optimization. -O1 - elide internal wires if possible. + unbuffer internal wires if possible. -O2 like -O1, and localize internal wires if possible. -O3 - like -O2, and elide public wires not marked (*keep*) if possible. + like -O2, and inline internal wires if possible. -O4 - like -O3, and localize public wires not marked (*keep*) if possible. + like -O3, and unbuffer public wires not marked (*keep*) if possible. -O5 - like -O4, and run `splitnets -driver; opt_clean -purge` first. + like -O4, and localize public wires not marked (*keep*) if possible. + + -O6 + like -O5, and inline public wires not marked (*keep*) if possible. + + -g <level> + set the debug level. the default is -g4. higher debug levels provide + more visibility and generate more code, but do not pessimize evaluation. + + -g0 + no debug information. the C API is disabled. + + -g1 + include bare minimum of debug information necessary to access all design + state. the C API is enabled. + + -g2 + like -g1, but include debug information for all public wires that are + directly accessible through the C++ interface. + + -g3 + like -g2, and include debug information for public wires that are tied + to a constant or another public wire. + + -g4 + like -g3, and compute debug information on demand for all public wires + that were optimized out. \end{lstlisting} \section{write\_edif -- write design to EDIF netlist file} @@ -6925,6 +8210,9 @@ Write the current design to an EDIF netlist file. -attrprop create EDIF properties for cell attributes + -keep + create extra KEEP nets by allowing a cell to drive multiple nets. + -pvector {par|bra|ang} sets the delimiting character for module port rename clauses to parentheses, square brackets, or angle brackets. @@ -6961,18 +8249,14 @@ Inside a script the input file can also can a here-document: Write a FIRRTL netlist of the current design. The following commands are executed by this command: pmuxtree + bmuxmap + demuxmap \end{lstlisting} -\section{write\_ilang -- write design to ilang file} +\section{write\_ilang -- (deprecated) alias of write\_rtlil} \label{cmd:write_ilang} \begin{lstlisting}[numbers=left,frame=single] - write_ilang [filename] - -Write the current design to an 'ilang' file. (ilang is a text representation -of a design in yosys's internal format.) - - -selected - only write selected parts of the design. +See `help write_rtlil`. \end{lstlisting} \section{write\_intersynth -- write design to InterSynth netlist file} @@ -6987,7 +8271,7 @@ a tool for Coarse-Grain Example-Driven Interconnect Synthesis. do not generate celltypes and conntypes commands. i.e. just output the netlists. this is used for postsilicon synthesis. - -lib <verilog_or_ilang_file> + -lib <verilog_or_rtlil_file> Use the specified library file for determining whether cell ports are inputs or outputs. This option can be used multiple times to specify more than one library. @@ -6996,7 +8280,7 @@ a tool for Coarse-Grain Example-Driven Interconnect Synthesis. only write selected modules. modules must be selected entirely or not at all. -http://www.clifford.at/intersynth/ +http://bygone.clairexen.net/intersynth/ \end{lstlisting} \section{write\_json -- write design to a JSON file} @@ -7017,8 +8301,17 @@ Write a JSON netlist of the current design. The general syntax of the JSON output created by this command is as follows: { + "creator": "Yosys <version info>", "modules": { <module_name>: { + "attributes": { + <attribute_name>: <attribute_value>, + ... + }, + "parameter_default_values": { + <parameter_name>: <parameter_value>, + ... + }, "ports": { <port_name>: <port_details>, ... @@ -7027,6 +8320,10 @@ The general syntax of the JSON output created by this command is as follows: <cell_name>: <cell_details>, ... }, + "memories": { + <memory_name>: <memory_details>, + ... + }, "netnames": { <net_name>: <net_details>, ... @@ -7043,13 +8340,16 @@ Where <port_details> is: { "direction": <"input" | "output" | "inout">, "bits": <bit_vector> + "offset": <the lowest bit index in use, if non-0> + "upto": <1 if the port bit indexing is MSB-first> } -And <cell_details> is: +The "offset" and "upto" fields are skipped if their value would be 0.They don't affect connection semantics, and are only used to preserve originalHDL bit indexing.And <cell_details> is: { "hide_name": <1 | 0>, "type": <cell_type>, + "model": <AIG model name, if -aig option used>, "parameters": { <parameter_name>: <parameter_value>, ... @@ -7068,11 +8368,26 @@ And <cell_details> is: }, } +And <memory_details> is: + + { + "hide_name": <1 | 0>, + "attributes": { + <attribute_name>: <attribute_value>, + ... + }, + "width": <memory width> + "start_offset": <the lowest valid memory address> + "size": <memory size> + } + And <net_details> is: { "hide_name": <1 | 0>, "bits": <bit_vector> + "offset": <the lowest bit index in use, if non-0> + "upto": <1 if the port bit indexing is MSB-first> } The "hide_name" fields are set to 1 when the name of this cell or net is @@ -7099,8 +8414,13 @@ For example the following Verilog code: Translates to the following JSON output: { + "creator": "Yosys 0.9+2406 (git sha1 fb1168d8, clang 9.0.1 -fPIC -Os)", "modules": { "test": { + "attributes": { + "cells_not_processed": "00000000000000000000000000000001", + "src": "test.v:1.1-4.10" + }, "ports": { "x": { "direction": "input", @@ -7116,33 +8436,34 @@ Translates to the following JSON output: "hide_name": 0, "type": "foo", "parameters": { - "Q": 1337, - "P": 42 + "P": "00000000000000000000000000101010", + "Q": "00000000000000000000010100111001" }, "attributes": { - "keep": 1, - "src": "test.v:2" + "keep": "00000000000000000000000000000001", + "module_not_derived": "00000000000000000000000000000001", + "src": "test.v:3.1-3.55" }, "connections": { - "C": [ 2, 2, 2, 2, "0", "1", "0", "1" ], + "A": [ 3, 2 ], "B": [ 2, 3 ], - "A": [ 3, 2 ] + "C": [ 2, 2, 2, 2, "0", "1", "0", "1" ] } } }, "netnames": { - "y": { + "x": { "hide_name": 0, - "bits": [ 3 ], + "bits": [ 2 ], "attributes": { - "src": "test.v:1" + "src": "test.v:1.19-1.20" } }, - "x": { + "y": { "hide_name": 0, - "bits": [ 2 ], + "bits": [ 3 ], "attributes": { - "src": "test.v:1" + "src": "test.v:1.22-1.23" } } } @@ -7208,6 +8529,18 @@ Future version of Yosys might add support for additional fields in the JSON format. A program processing this format must ignore all unknown fields. \end{lstlisting} +\section{write\_rtlil -- write design to RTLIL file} +\label{cmd:write_rtlil} +\begin{lstlisting}[numbers=left,frame=single] + write_rtlil [filename] + +Write the current design to an RTLIL file. (RTLIL is a text representation +of a design in yosys's internal format.) + + -selected + only write selected parts of the design. +\end{lstlisting} + \section{write\_simplec -- convert design to simple C code} \label{cmd:write_simplec} \begin{lstlisting}[numbers=left,frame=single] @@ -7332,8 +8665,12 @@ Options: use the given template file. the line containing only the token '%%' is replaced with the regular output of this command. + -solver-option <option> <value> + emit a `; yosys-smt2-solver-option` directive for yosys-smtbmc to write + the given option as a `(set-option ...)` command in the SMT-LIBv2. + [1] For more information on SMT-LIBv2 visit http://smt-lib.org/ or read David -R. Cok's tutorial: http://www.grammatech.com/resources/smt/SMTLIBTutorial.pdf +R. Cok's tutorial: https://smtlib.github.io/jSMTLIB/SMTLIBTutorial.pdf --------------------------------------------------------------------------- @@ -7415,6 +8752,10 @@ Write the current design to an SPICE netlist file. -pos net_name set the net name for constant 1 (default: Vdd) + -buf DC|subckt_name + set the name for jumper element (default: DC) + (used to connect different nets) + -nc_prefix prefix for not-connected nets (default: _NC) @@ -7452,6 +8793,9 @@ module inputs and outputs are output using cell type and port '-' and with Write the current design to a Verilog file. + -sv + with this option, SystemVerilog constructs like always_comb are used + -norename without this option all internal object names (the ones with a dollar instead of a backslash prefix) are changed to short names in the @@ -7493,6 +8837,9 @@ Write the current design to a Verilog file. deactivates this feature and instead will write string constants as binary numbers. + -simple-lhs + Connection assignments with simple left hand side without concatenations. + -extmem instead of initializing memories using assignments to individual elements, use the '$readmemh' function to read initialization data @@ -7530,15 +8877,19 @@ this command is called on a design with RTLIL processes. write_xaiger [options] [filename] Write the top module (according to the (* top *) attribute or if only one module -is currently selected) to an XAIGER file. Any non $_NOT_, $_AND_, $_ABC9_FF_, ornon (* abc9_box_id *) cells will be converted into psuedo-inputs and -pseudo-outputs. Whitebox contents will be taken from the '<module-name>$holes' -module, if it exists. +is currently selected) to an XAIGER file. Any non $_NOT_, $_AND_, (optionally +$_DFF_N_, $_DFF_P_), or non (* abc9_box *) cells will be converted into psuedo- +inputs and pseudo-outputs. Whitebox contents will be taken from the equivalent +module in the '$abc9_holes' design, if it exists. -ascii write ASCII version of AIGER format -map <filename> write an extra file with port and box symbols + + -dff + write $_DFF_[NP]_ cells \end{lstlisting} \section{xilinx\_dffopt -- Xilinx: optimize FF control signal usage} diff --git a/manual/literature.bib b/manual/literature.bib index 372e882ac..86652eb46 100644 --- a/manual/literature.bib +++ b/manual/literature.bib @@ -1,7 +1,7 @@ @inproceedings{intersynth, title={Example-driven interconnect synthesis for heterogeneous coarse-grain reconfigurable logic}, - author={Clifford Wolf and Johann Glaser and Florian Schupfer and Jan Haase and Christoph Grimm}, + author={C. Wolf and Johann Glaser and Florian Schupfer and Jan Haase and Christoph Grimm}, booktitle={FDL Proceeding of the 2012 Forum on Specification and Design Languages}, pages={194--201}, year={2012} @@ -9,7 +9,7 @@ @incollection{intersynthFdlBookChapter, title={Methodology and Example-Driven Interconnect Synthesis for Designing Heterogeneous Coarse-Grain Reconfigurable Architectures}, - author={Johann Glaser and Clifford Wolf}, + author={Johann Glaser and C. Wolf}, booktitle={Advances in Models, Methods, and Tools for Complex Chip Design --- Selected contributions from FDL'12}, editor={Jan Haase}, publisher={Springer}, @@ -18,14 +18,14 @@ } @unpublished{BACC, - author = {Clifford Wolf}, + author = {C. Wolf}, title = {Design and Implementation of the Yosys Open SYnthesis Suite}, note = {Bachelor Thesis, Vienna University of Technology}, year = {2013} } @unpublished{VerilogFossEval, - author = {Clifford Wolf}, + author = {C. Wolf}, title = {Evaluation of Open Source Verilog Synthesis Tools for Feature-Completeness and Extensibility}, note = {Unpublished Student Research Paper, Vienna University of Technology}, year = {2012} diff --git a/manual/manual.tex b/manual/manual.tex index 75f087eca..1914df989 100644 --- a/manual/manual.tex +++ b/manual/manual.tex @@ -51,7 +51,7 @@ % Hyperlinks \usepackage[colorlinks,hyperindex,plainpages=false,% pdftitle={Yosys Manual},% -pdfauthor={Clifford Wolf},% +pdfauthor={Claire Xenia Wolf},% %pdfkeywords={keyword},% pdfpagelabels,% pagebackref,% @@ -75,6 +75,9 @@ bookmarksopen=false% \usetikzlibrary{through} \usetikzlibrary{shapes.geometric} +\usepackage{calc} +\usepackage[nounderscore]{syntax} + \lstset{basicstyle=\ttfamily} \def\B#1{{\tt\textbackslash{}#1}} @@ -134,7 +137,7 @@ bookmarksopen=false% \bf\Huge Yosys Manual \bigskip -\large Clifford Wolf +\large Claire Xenia Wolf \end{center} \vfil\null @@ -214,6 +217,7 @@ YOSYS & Yosys Open SYnthesis Suite \\ \label{commandref} \input{command-reference-manual} +\include{CHAPTER_TextRtlil} \include{CHAPTER_Appnotes} % \include{CHAPTER_StateOfTheArt} diff --git a/manual/presentation.tex b/manual/presentation.tex index 63b963bbd..7aba33c8b 100644 --- a/manual/presentation.tex +++ b/manual/presentation.tex @@ -80,8 +80,8 @@ \end{centering}} \title{Yosys Open SYnthesis Suite} -\author{Clifford Wolf} -\institute{http://www.clifford.at/yosys/} +\author{Claire Xenia Wolf} +\institute{https://yosyshq.net/yosys/} \usetheme{Madrid} \usecolortheme{seagull} @@ -124,7 +124,7 @@ writing extensions to Yosys using the C++ API. \section{About me} \begin{frame}{About me} -Hi! I'm Clifford Wolf. +Hi! I'm Claire Xenia Wolf. \bigskip I like writing open source software. For example: diff --git a/manual/weblinks.bib b/manual/weblinks.bib index d5f83315d..23ddbc38b 100644 --- a/manual/weblinks.bib +++ b/manual/weblinks.bib @@ -1,20 +1,20 @@ @misc{YosysGit, - author = {Clifford Wolf}, + author = {Claire Xenia Wolf}, title = {{Yosys Open SYnthesis Suite (YOSYS)}}, - note = {\url{http://github.com/cliffordwolf/yosys}} + note = {\url{http://github.com/YosysHQ/yosys}} } @misc{YosysTestsGit, - author = {Clifford Wolf}, + author = {Claire Xenia Wolf}, title = {{Yosys Test Bench}}, - note = {\url{http://github.com/cliffordwolf/yosys-tests}} + note = {\url{http://github.com/YosysHQ/yosys-tests}} } @misc{VlogHammer, - author = {Clifford Wolf}, + author = {Claire Xenia Wolf}, title = {{VlogHammer Verilog Synthesis Regression Tests}}, - note = {\url{http://github.com/cliffordwolf/VlogHammer}} + note = {\url{http://github.com/YosysHQ/VlogHammer}} } @misc{Icarus, |