From: Claire Wolf <clifford@clifford.at>
Date: Tue, 28 Jan 2020 08:41:08 +0000 (+0100)
Subject: Merge pull request #1553 from whitequark/manual-dffx
X-Git-Tag: working-ls180~848
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=8f40113826b6c53117d08fa1347ef8be35ccac1a;p=yosys.git

Merge pull request #1553 from whitequark/manual-dffx

Document $dffe, $dffsr, $_DFFE_*, $_DFFSR_* cells
---

8f40113826b6c53117d08fa1347ef8be35ccac1a
diff --cc manual/CHAPTER_CellLib.tex
index 00a88cc82,6367a4b37..55abd9b96
--- a/manual/CHAPTER_CellLib.tex
+++ b/manual/CHAPTER_CellLib.tex
@@@ -145,61 -175,10 +145,61 @@@ 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},
- an input port \B{D} and an output port \B{Q}. The following parameters are available for \$dff
+ 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:
  
  \begin{itemize}