From: whitequark Date: Wed, 4 Dec 2019 11:06:05 +0000 (+0000) Subject: manual: document behavior of many comb cells more precisely. X-Git-Tag: working-ls180~933^2~1 X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=ec4c9267b384030b487e66a77e4cc4ef600e876f;p=yosys.git manual: document behavior of many comb cells more precisely. --- diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex index 0106059b6..00a88cc82 100644 --- a/manual/CHAPTER_CellLib.tex +++ b/manual/CHAPTER_CellLib.tex @@ -65,6 +65,11 @@ Verilog & Cell Type \\ \label{tab:CellLib_unary} \end{table} +For the unary cells that output a logical value ({\tt \$reduce\_and}, {\tt \$reduce\_or}, +{\tt \$reduce\_xor}, {\tt \$reduce\_xnor}, {\tt \$reduce\_bool}, {\tt \$logic\_not}), +when the \B{Y\_WIDTH} parameter is greater than 1, the output is zero-extended, +and only the least significant bit varies. + Note that {\tt \$reduce\_or} and {\tt \$reduce\_bool} actually represent the same logic function. But the HDL frontends generate them in different situations. A {\tt \$reduce\_or} cell is generated when the prefix {\tt |} operator is being used. A @@ -97,41 +102,6 @@ The width of the output port \B{Y}. Table~\ref{tab:CellLib_binary} lists all cells for binary RTL operators. -\subsection{Multiplexers} - -Multiplexers are generated by the Verilog HDL frontend for {\tt -?:}-expressions. Multiplexers are also generated by the {\tt proc} pass to map the decision trees -from RTLIL::Process objects to logic. - -The simplest multiplexer cell type is {\tt \$mux}. Cells of this type have a \B{WIDTH} parameter -and data inputs \B{A} and \B{B} and a data output \B{Y}, all of the specified width. This cell also -has a single bit control input \B{S}. If \B{S} is 0 the value from the \B{A} input is sent to -the output, if it is 1 the value from the \B{B} input is sent to the output. So the {\tt \$mux} -cell implements the function \lstinline[language=Verilog]; Y = S ? B : A;. - -The {\tt \$pmux} cell is used to multiplex between many inputs using a one-hot select signal. Cells -of this type have a \B{WIDTH} and a \B{S\_WIDTH} parameter and inputs \B{A}, \B{B}, and \B{S} and -an output \B{Y}. The \B{S} input is \B{S\_WIDTH} bits wide. The \B{A} input and the output are both -\B{WIDTH} bits wide and the \B{B} input is \B{WIDTH}*\B{S\_WIDTH} bits wide. When all bits of -\B{S} are zero, the value from \B{A} input is sent to the output. If the $n$'th bit from \B{S} is -set, the value $n$'th \B{WIDTH} bits wide slice of the \B{B} input is sent to the output. When more -than one bit from \B{S} is set the output is undefined. Cells of this type are used to model -``parallel cases'' (defined by using the {\tt parallel\_case} attribute or detected by -an optimization). - -The {\tt \$tribuf} cell is used to implement tristate logic. Cells of this type have a \B{WIDTH} -parameter and inputs \B{A} and \B{EN} and an output \B{Y}. The \B{A} input and \B{Y} output are -\B{WIDTH} bits wide, and the \B{EN} input is one bit wide. When \B{EN} is 0, the output \B{Y} -is not driven. When \B{EN} is 1, the value from \B{A} input is sent to the \B{Y} output. Therefore, -the {\tt \$tribuf} cell implements the function \lstinline[language=Verilog]; Y = EN ? A : 'bz;. - -Behavioural code with cascaded {\tt if-then-else}- and {\tt case}-statements -usually results in trees of multiplexer cells. Many passes (from various -optimizations to FSM extraction) heavily depend on these multiplexer trees to -understand dependencies between signals. Therefore optimizations should not -break these multiplexer trees (e.g.~by replacing a multiplexer between a -calculated signal and a constant zero with an {\tt \$and} gate). - \begin{table}[t!] \hfil \begin{tabular}[t]{ll} @@ -175,6 +145,57 @@ Verilog & Cell Type \\ \label{tab:CellLib_binary} \end{table} +The {\tt \$shl} and {\tt \$shr} cells implement logical shifts, whereas the {\tt \$sshl} and +{\tt \$sshr} cells implement arithmetic shifts. The {\tt \$shl} and {\tt \$sshl} cells implement +the same operation. All four of these cells interpret the second operand as unsigned, and require +\B{B\_SIGNED} to be zero. + +Two additional shift operator cells are available that do not directly correspond to any operator +in Verilog, {\tt \$shift} and {\tt \$shiftx}. The {\tt \$shift} cell performs a right logical shift +if the second operand is positive (or unsigned), and a left logical shift if it is negative. +The {\tt \$shiftx} cell performs the same operation as the {\tt \$shift} cell, but the vacated bit +positions are filled with undef (x) bits, and corresponds to the Verilog indexed part-select expression. + +For the binary cells that output a logical value ({\tt \$logic\_and}, {\tt \$logic\_or}, +{\tt \$eqx}, {\tt \$nex}, {\tt \$lt}, {\tt \$le}, {\tt \$eq}, {\tt \$ne}, {\tt \$ge}, +{\tt \$gt}), when the \B{Y\_WIDTH} parameter is greater than 1, the output is zero-extended, +and only the least significant bit varies. + +\subsection{Multiplexers} + +Multiplexers are generated by the Verilog HDL frontend for {\tt +?:}-expressions. Multiplexers are also generated by the {\tt proc} pass to map the decision trees +from RTLIL::Process objects to logic. + +The simplest multiplexer cell type is {\tt \$mux}. Cells of this type have a \B{WIDTH} parameter +and data inputs \B{A} and \B{B} and a data output \B{Y}, all of the specified width. This cell also +has a single bit control input \B{S}. If \B{S} is 0 the value from the \B{A} input is sent to +the output, if it is 1 the value from the \B{B} input is sent to the output. So the {\tt \$mux} +cell implements the function \lstinline[language=Verilog]; Y = S ? B : A;. + +The {\tt \$pmux} cell is used to multiplex between many inputs using a one-hot select signal. Cells +of this type have a \B{WIDTH} and a \B{S\_WIDTH} parameter and inputs \B{A}, \B{B}, and \B{S} and +an output \B{Y}. The \B{S} input is \B{S\_WIDTH} bits wide. The \B{A} input and the output are both +\B{WIDTH} bits wide and the \B{B} input is \B{WIDTH}*\B{S\_WIDTH} bits wide. When all bits of +\B{S} are zero, the value from \B{A} input is sent to the output. If the $n$'th bit from \B{S} is +set, the value $n$'th \B{WIDTH} bits wide slice of the \B{B} input is sent to the output. When more +than one bit from \B{S} is set the output is undefined. Cells of this type are used to model +``parallel cases'' (defined by using the {\tt parallel\_case} attribute or detected by +an optimization). + +The {\tt \$tribuf} cell is used to implement tristate logic. Cells of this type have a \B{WIDTH} +parameter and inputs \B{A} and \B{EN} and an output \B{Y}. The \B{A} input and \B{Y} output are +\B{WIDTH} bits wide, and the \B{EN} input is one bit wide. When \B{EN} is 0, the output \B{Y} +is not driven. When \B{EN} is 1, the value from \B{A} input is sent to the \B{Y} output. Therefore, +the {\tt \$tribuf} cell implements the function \lstinline[language=Verilog]; Y = EN ? A : 'bz;. + +Behavioural code with cascaded {\tt if-then-else}- and {\tt case}-statements +usually results in trees of multiplexer cells. Many passes (from various +optimizations to FSM extraction) heavily depend on these multiplexer trees to +understand dependencies between signals. Therefore optimizations should not +break these multiplexer trees (e.g.~by replacing a multiplexer between a +calculated signal and a constant zero with an {\tt \$and} gate). + \subsection{Registers} D-Type Flip-Flops are represented by {\tt \$dff} cells. These cells have a clock port \B{CLK},