diff --git a/.gitignore b/.gitignore index e6598ba..979527c 100644 --- a/.gitignore +++ b/.gitignore @@ -19,7 +19,8 @@ # these rules might exclude image files for figures etc. # *.ps # *.eps -# *.pdf +*.pdf +*.jpg ## Generated if empty string is given at "Please type another file name for output:" .pdf diff --git a/main.tex b/main.tex index 49b0939..1b4c999 100644 --- a/main.tex +++ b/main.tex @@ -3,13 +3,24 @@ \usepackage[landscape]{geometry} \usepackage[procnames]{listings} \usepackage[parfill]{parskip} -\usepackage{fixltx2e} \usepackage[T1]{fontenc} \usepackage{lmodern} \usepackage{graphicx} - +\usepackage{adjustbox} +\usepackage[table]{xcolor} \input{scala.tex} +\def \themecolor{blue} +\def \tingecolor{white} + +% Color Pallete +\colorlet{codebgcolor}{\themecolor!20} +\colorlet{darkcolor}{\themecolor!90!\tingecolor!60} +\colorlet{normalcolor}{\themecolor!80!\tingecolor!50} +\colorlet{lightcolor}{\themecolor!70!\tingecolor!40} + +\pagecolor{\themecolor!50!white!20} + % Remove section numbering \setcounter{secnumdepth}{0} @@ -40,12 +51,14 @@ \newcommand*\ruleline[1]{\par\noindent\raisebox{.8ex}{\makebox[\linewidth]{\hrulefill\hspace{1ex}\raisebox{-.8ex}{#1}\hspace{1ex}\hrulefill}}} \renewcommand{\tabcolsep}{.5mm} +\newcommand*\highlightbox[2]{\noindent\adjustbox{bgcolor=#1,minipage=[t]{\linewidth}}{ #2 }} + \ruleline{\Large{\textbf{Chisel3 Cheat Sheet}}} \begin{center} Version 0.5 (beta): \today \end{center} - -\fbox{ \parbox{0.95\columnwidth} { +\vspace{1em} +\fcolorbox{red}{yellow}{ \parbox{0.95\columnwidth} { \subsection{Notation In This Document}: \subsubsection{For Functions and Constructors}: \newline Arguments given as \texttt{kwd:type} (name and type(s)) \newline @@ -58,372 +71,403 @@ \subsubsection{For Operators}: \newline \phantom{x} maximum possible values of \texttt{x} } } -\section{Basic Chisel Constructs } \hrulefill -\subsection{Chisel Wire Operators}: -\begin{scala} -// Allocate a as wire of type UInt() -val x = Wire(UInt()) -x := y // Connect wire y to wire x -\end{scala} - -\subsection{When } executes blocks conditionally by \verb$Bool$, \newline -\phantom{x} and is equivalent to Verilog \verb$if$ -\begin{scala} -when(condition1) { - // run if condition1 true and skip rest -} .elsewhen(condition2) { - // run if condition2 true and skip rest -} .otherwise { - // run if none of the above ran +\section{Basic Chisel Constructs } \hrulefill \\ +\highlightbox{normalcolor}{ + \subsection{Chisel Wire Operators}: + \begin{scala}^^J + // Allocate a as wire of type UInt()^^J + val x = Wire(UInt())^^J + x := y // Connect wire y to wire x^^J + \end{scala} + \subsection{When } executes blocks conditionally by \lstinline|Bool|, \newline + \phantom{x} and is equivalent to Verilog \lstinline|if| + \begin{scala}^^J + when(condition1) \{^^J + \ \ // run if condition1 true and skip rest^^J + \} .elsewhen(condition2) \{^^J + \ \ // run if condition2 true and skip rest^^J + \} .otherwise \{^^J + \ \ // run if none of the above ran^^J + \}^^J + \end{scala} + \subsection{Switch } executes blocks conditionally by data + \begin{scala}^^J + switch(x) \{^^J + \ \ is(value1) \{^^J + \ \ \ \ // run if x === value1^^J + \ \ \}^^J + \ \ is(value2) \{^^J + \ \ \ \ // run if x === value2^^J + \ \ \}^^J + \}^^J + \end{scala} + \subsection{Enum } generates value literals for enumerations \newline + \lstinline|val s1::s2::| ... \lstinline|::sn::Nil| \newline + \lstinline| = Enum(nodeType:UInt, n:Int)| \newline + \begin{tabular}{l l l} + & \lstinline|s1|, \lstinline|s2|, ..., \lstinline|sn| & will be created as \lstinline|nodeType| literals \\ + & & with distinct values \\ + & \lstinline|nodeType| & type of \lstinline|s1|, \lstinline|s2|, ..., \lstinline|sn| \\ + & \lstinline|n| & element count \\ + \end{tabular} + \subsection{Math Helpers}: \newline + \begin{tabular}{l l} + \lstinline|log2Ceil(in:Int): Int| & $log_2(\texttt{in})$ rounded up \\ + \lstinline|log2Floor(in:Int): Int| & $log_2(\texttt{in})$ rounded down \\ + \lstinline|isPow2(in:Int): Boolean| & \lstinline|True| if \lstinline|in| is a power of 2 \\ + \end{tabular} } -\end{scala} - -\subsection{Switch } executes blocks conditionally by data -\begin{scala} -switch(x) { - is(value1) { - // run if x === value1 - } - is(value2) { - // run if x === value2 - } -} -\end{scala} - -\subsection{Enum } generates value literals for enumerations \newline -\verb$val s1::s2::$ ... \verb$::sn::Nil$ \newline -\verb$ = Enum(nodeType:UInt, n:Int)$ \newline -\begin{tabular}{l l l} -& \verb$s1$, \verb$s2$, ..., \verb$sn$ & will be created as \verb$nodeType$ literals \\ -& & with distinct values \\ -& \verb$nodeType$ & type of \verb$s1$, \verb$s2$, ..., \verb$sn$ \\ -& \verb$n$ & element count \\ -\end{tabular} - -\subsection{Math Helpers}: \newline -\begin{tabular}{l l} -\verb$log2Ceil(in:Int): Int$ & $log_2(\texttt{in})$ rounded up \\ -\verb$log2Floor(in:Int): Int$ & $log_2(\texttt{in})$ rounded down \\ -\verb$isPow2(in:Int): Boolean$ & \verb$True$ if \verb$in$ is a power of 2 \\ -\end{tabular} - \columnbreak -\section{Basic Data Types } \hrulefill -\subsubsection{Constructors}: \newline -\begin{tabular*}{\columnwidth}{@{\extracolsep{\fill} } l l} -\verb$Bool()$ & type, boolean value \\ -\verb$true.B$ or \verb$false.B$ & literal values \\ -\verb$UInt(32.W)$ & type 32-bit unsigned \\ -\verb$UInt()$ & type, width inferred \\ -\verb$77.U$ or \verb$"hdead".U$ & unsigned literals \\ -\verb$1.U(16.W)$ & literal with forced width \\ -\verb$SInt()$ or \verb$SInt(64.W)$ & like UInt \\ -\verb$-3.S$ or \verb$"h-44".S$ & signed literals \\ -\verb$3.S(2.W)$ & signed 2-bits wide {\em value -1} \\ -\end{tabular*} - -\subsubsection{Bits, UInt, SInt Casts}: reinterpret cast except for:\newline -\begin{tabular*}{\columnwidth}{@{\extracolsep{\fill} } l l l} -\verb$UInt$ $\rightarrow$ \verb$SInt$ & Zero-extend to SInt & \\ -\end{tabular*} +\section{Basic Data Types} \hrulefill \\ +\highlightbox{normalcolor}{ + \subsubsection{Constructors}: \newline + \begin{tabular*}{\columnwidth}{@{\extracolsep{\fill} } l l} + \lstinline|Bool()| & type, boolean value \\ + \lstinline|true.B| or \lstinline|false.B| & literal values \\ + \lstinline|UInt(32.W)| & type 32-bit unsigned \\ + \lstinline|UInt()| & type, width inferred \\ + \lstinline|77.U| or \lstinline|"hdead".U| & unsigned literals \\ + \lstinline|1.U(16.W)| & literal with forced width \\ + \lstinline|SInt()| or \lstinline|SInt(64.W)| & like UInt \\ + \lstinline|-3.S| or \lstinline|"h-44".S| & signed literals \\ + \lstinline|3.S(2.W)| & signed 2-bits wide {\em value -1} \\ + \end{tabular*} + % + \subsubsection{Bits, UInt, SInt Casts}: reinterpret cast except for:\newline + \begin{tabular*}{\columnwidth}{@{\extracolsep{\fill} } l l l} + \lstinline|UInt -->| \lstinline|SInt| & Zero-extend to SInt & \\ + \end{tabular*} +} -\section{State Elements } \hrulefill\ -\subsection{Registers } retain state until updated \newline -\verb$val my_reg = Reg(UInt(32.W))$ \newline -Flavors \newline -\begin{tabular}{l l l} -& \verb$RegInit(7.U(32.w))$ & reg with initial value 7 \\ -& \verb$RegNext(next_val)$ & update each clock, no init\\ -& \verb$RegEnable(next, enable)$ & update, with enable gate \\ -\end{tabular} -\subsubsection{Updating}: assign to latch new value on next clock: \newline -\verb$my_reg := next_val$ -\subsection{Read-Write Memory } provide addressable memories \newline -\verb$val my_mem = Mem(n:Int, out:Data)$ \newline -\begin{tabular}{l l l} -& \verb$out$ & memory element type \\ -& \verb$n$ & memory depth (elements) \\ -\end{tabular} -\subsubsection{Using}: access elements by indexing: \newline -\verb$val readVal = my_mem(addr:UInt/Int)$ \newline -\phantom{x} for synchronous read: assign output to \verb$Reg$ \newline -\verb$mu_mem(addr:UInt/Int) := y$ -\section{Modules } \hrulefill -\subsubsection{Defining}: subclass \verb$Module$ with elements, code: -\begin{scala} -class Accum(width:Int) extends Module { - val io = IO(new Bundle { - val in = Input(UInt(width.W)) - val out = Output(UInt(width.W)) - }) - val sum = Reg(UInt()) - sum := sum + io.in - io.out := sum +\section{State Elements } \hrulefill \\ +\highlightbox{lightcolor}{ + % + \subsection{Registers } retain state until updated \newline + \lstinline[columns=fixed]|val my_reg = Reg(UInt(32.W))| \newline + Flavors \newline + \begin{tabular}{l l l} + & \lstinline|RegInit(7.U(32.w))| & reg with initial value 7 \\ + & \lstinline|RegNext(next_val)| & update each clock, no init\\ + & \lstinline|RegEnable(next,enable)| & update, with enable gate \\ + \end{tabular} + % + \subsubsection{Updating}: assign to latch new value on next clock: \newline + \lstinline|my_reg := next_val| + % + \subsection{Read-Write Memory } provide addressable memories \newline + \lstinline|val my_mem = Mem(n:Int, out:Data)| \newline + \begin{tabular}{l l l} + & \lstinline|out| & memory element type \\ + & \lstinline|n| & memory depth (elements) \\ + \end{tabular} + % + \subsubsection{Using}: access elements by indexing: \newline + \lstinline|val readVal = my_mem(addr:UInt/Int)| \newline + \phantom{x} for synchronous read: assign output to \lstinline[columns=fixed]|Reg| \newline + \lstinline|mu_mem(addr:UInt/Int) := y| } -\end{scala} -\subsubsection{Usage}: access elements using dot notation: \newline -\phantom{x} (code inside a \verb$Module$ is always running) -\begin{scala} -val my_module = Module(new Accum(32)) -my_module.io.in := some_data -val sum := my_module.io.out -\end{scala} +\section{Modules } \hrulefill \newline +\highlightbox{normalcolor}{ + \subsubsection{Defining}: subclass \lstinline|Module| with elements, code: + \begin{scala}^^J + class Accum(width:Int) extends Module \{^^J + \ \ val io = IO(new Bundle \{^^J + \ \ \ \ val in = Input(UInt(width.W))^^J + \ \ \ \ val out = Output(UInt(width.W))^^J + \ \ \})^^J + \ \ val sum = Reg(UInt())^^J + \ \ sum := sum + io.in^^J + \ \ io.out := sum^^J + \}^^J + \end{scala} + \subsubsection{Usage}: access elements using dot notation: \newline + \phantom{x} (code inside a \lstinline|Module| is always running) + \begin{scala}^^J + val my_module = Module(new Accum(32))^^J + my_module.io.in := some_data^^J + val sum := my_module.io.out^^J + \end{scala} +} \columnbreak -\subsubsection{Operators}: \newline +\section{Operators}: \hrulefill \newline \newline +{ +\rowcolors{2}{normalcolor}{lightcolor} \begin{tabular*}{\columnwidth}{@{\extracolsep{\fill} } l l l} +\rowcolor{darkcolor} Chisel & Explanation & Width \\ +\lstinline|!x| & Logical NOT & \lstinline|1| \\ +\lstinline|x && y| & Logical AND & \lstinline|1| \\ +\lstinline|x || y| & Logical OR & \lstinline|1| \\ \hline +\lstinline|x(n)| & Extract bit, \lstinline|0| is LSB & \lstinline|1| \\ +\lstinline|x(n, m)| & Extract bitfield & \lstinline|n - m + 1| \\ +\lstinline|x << y| & Dynamic left shift & \lstinline|w(x) + maxVal(y)| \\ +\lstinline|x >> y| & Dynamic right shift & \lstinline|w(x) - minVal(y)| \\ +\lstinline|x << n| & Static left shift & \lstinline|w(x) + n| \\ +\lstinline|x >> n| & Static right shift & \lstinline|w(x) - n| \\ +\lstinline|Fill(n, x)| & Replicate \lstinline|x|, \lstinline|n| times & \lstinline|n * w(x)| \\ +\lstinline|Cat(x, y)| & Concatenate bits & \lstinline|w(x) + w(y)| \\ +\lstinline|Mux(c, x, y)| & If \lstinline|c|, then \lstinline|x|; else \lstinline|y| & \lstinline|max(w(x), w(y))| \\ \hline -\verb$!x$ & Logical NOT & \verb$1$ \\ -\verb$x && y$ & Logical AND & \verb$1$ \\ -\verb$x || y$ & Logical OR & \verb$1$ \\ -\hline -\verb$x(n)$ & Extract bit, \verb$0$ is LSB & \verb$1$ \\ -\verb$x(n, m)$ & Extract bitfield & \verb$n - m + 1$ \\ -\verb$x << y$ & Dynamic left shift & \verb$w(x) + maxVal(y)$ \\ -\verb$x >> y$ & Dynamic right shift & \verb$w(x) - minVal(y)$ \\ -\verb$x << n$ & Static left shift & \verb$w(x) + n$ \\ -\verb$x >> n$ & Static right shift & \verb$w(x) - n$ \\ -\verb$Fill(n, x)$ & Replicate \verb$x$, \verb$n$ times & \verb$n * w(x)$ \\ -\verb$Cat(x, y)$ & Concatenate bits & \verb$w(x) + w(y)$ \\ -\verb$Mux(c, x, y)$ & If \verb$c$, then \verb$x$; else \verb$y$ & \verb$max(w(x), w(y))$ \\ +\lstinline|~x| & Bitwise NOT & \lstinline|w(x)| \\ +\lstinline|x & y| & Bitwise AND & \lstinline|max(w(x), w(y))| \\ +\lstinline|x | y| & Bitwise OR & \lstinline|max(w(x), w(y))| \\ +\lstinline|x ^ y| & Bitwise XOR & \lstinline|max(w(x), w(y))| \\ \hline -\verb$~x$ & Bitwise NOT & \verb$w(x)$ \\ -\verb$x & y$ & Bitwise AND & \verb$max(w(x), w(y))$ \\ -\verb$x | y$ & Bitwise OR & \verb$max(w(x), w(y))$ \\ -\verb$x ^ y$ & Bitwise XOR & \verb$max(w(x), w(y))$ \\ +\lstinline|x === y| & Equality{\small\textcolor{red}{(triple equals)}} & \lstinline|1| \\ +\lstinline|x != y| & Inequality & \lstinline|1| \\ +\lstinline|x =/= y| & Inequality & \lstinline|1| \\ \hline -\verb$x === y$ & Equality{\small\textcolor{red}{(triple equals)}} & \verb$1$ \\ -\verb$x != y$ & Inequality & \verb$1$ \\ -\verb$x =/= y$ & Inequality & \verb$1$ \\ +\lstinline|x + y| & Addition & \lstinline|max(w(x),w(y))| \\ +\lstinline|x +% y| & Addition & \lstinline|max(w(x),w(y))| \\ +\lstinline|x +& y| & Addition & \lstinline|max(w(x),w(y))+1| \\ +\lstinline|x - y| & Subtraction & \lstinline|max(w(x),w(y))| \\ +\lstinline|x -% y| & Subtraction & \lstinline|max(w(x),w(y))| \\ +\lstinline|x -& y| & Subtraction & \lstinline|max(w(x),w(y))+1| \\ +\lstinline|x * y| & Multiplication & \lstinline|w(x)+w(y)| \\ +\lstinline|x / y| & Division & \lstinline|w(x)| \\ +\lstinline|x % y| & Modulus & \lstinline|bits(maxVal(y)-1)| \\ \hline -\verb$x + y$ & Addition & \verb$max(w(x),w(y))$ \\ -\verb$x +% y$ & Addition & \verb$max(w(x),w(y))$ \\ -\verb$x +& y$ & Addition & \verb$max(w(x),w(y))+1$ \\ -\verb$x - y$ & Subtraction & \verb$max(w(x),w(y))$ \\ -\verb$x -% y$ & Subtraction & \verb$max(w(x),w(y))$ \\ -\verb$x -& y$ & Subtraction & \verb$max(w(x),w(y))+1$ \\ -\verb$x * y$ & Multiplication & \verb$w(x)+w(y)$ \\ -\verb$x / y$ & Division & \verb$w(x)$ \\ -\verb$x % y$ & Modulus & \verb$bits(maxVal(y)-1)$ \\ +\lstinline|x > y| & Greater than & \lstinline|1| \\ +\lstinline|x >= y| & Greater than or equal & \lstinline|1| \\ +\lstinline|x < y| & Less than & \lstinline|1| \\ +\lstinline|x <= y| & Less than or equal & \lstinline|1| \\ \hline -\verb$x > y$ & Greater than & \verb$1$ \\ -\verb$x >= y$ & Greater than or equal & \verb$1$ \\ -\verb$x < y$ & Less than & \verb$1$ \\ -\verb$x <= y$ & Less than or equal & \verb$1$ \\ -\hline -\verb$x >> y$ & Arithmetic right shift & \verb$w(x) - minVal(y)$ \\ -\verb$x >> n$ & Arithmetic right shift & \verb$w(x) - n$ \\ +\lstinline|x >> y| & Arithmetic right shift & \lstinline|w(x) - minVal(y)| \\ +\lstinline|x >> n| & Arithmetic right shift & \lstinline|w(x) - n| \\ \end{tabular*} - +} \subsubsection{UInt bit-reduction methods}: \newline -\begin{tabular*}{\columnwidth}{@{\extracolsep{\fill} } l l l} +{\rowcolors{2}{normalcolor}{lightcolor} +\begin{tabular*}{\columnwidth}{ l l c} +\rowcolor{darkcolor} Chisel & Explanation & Width \\ -\hline -\hline -\verb$x.andR$ & AND-reduce & \verb$1$ \\ -\verb$x.orR$ & OR-reduce & \verb$1$ \\ -\verb$x.xorR$ & XOR-reduce & \verb$1$ \\ +\lstinline|x.andR | & AND-reduce & \lstinline|1| \\ +\lstinline|x.orR | & OR-reduce & \lstinline|1| \\ +\lstinline|x.xorR | & XOR-reduce & \lstinline|1| \\ \end{tabular*} +} \newline As an example to apply the andR method to an SInt use x.asUInt.andR - \newline \newline \newline + \newline \newline \columnbreak -\section{Hardware Generation } \hrulefill -\subsection{Functions } provide block abstractions for code. Scala -functions that instantiate or return Chisel types are code generators. -\subsection{Also}: Scala's \verb$if$ and \verb$for$ can be used to control hardware generation -and are equivalent to Verilog \verb$generate if$/\verb$for$ -\begin{scala} -val number = Reg(if(can_be_negative) SInt() - else UInt()) -\end{scala} -will create a Register of type SInt or UInt depending on the value of a -Scala variable - -\section{Aggregate Types } \hrulefill -\subsection{Bundle } contains \verb$Data$ types indexed by name -\subsubsection{Defining}: subclass \verb$Bundle$, define components: -\begin{scala} -class MyBundle extends Bundle { - val a = Bool() - val b = UInt(32.W) +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Hardware Generation } \hrulefill \\ +\highlightbox{normalcolor}{ + \subsection{Functions } provide block abstractions for code. Scala + functions that instantiate or return Chisel types are code generators. + \subsection{Also}: Scala's \lstinline|if| and \lstinline|for| can be used to control hardware generation + and are equivalent to Verilog \lstinline|generate if|/\lstinline|for| + \begin{scala}^^J + val number=Reg(if(can_be_negative) SInt()^^J + else UInt())^^J + \end{scala} + will create a Register of type SInt or UInt depending on the value of a \\ + Scala variable } -\end{scala} -\subsubsection{Constructor}: instantiate \verb$Bundle$ subclass: \newline -\verb$val my_bundle = new MyBundle()$ -\subsubsection{Inline defining}: define a \verb$Bundle$ type: -\begin{scala} -val my_bundle = new Bundle { - val a = Bool() - val b = UInt(32.W) +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Aggregate Types } \hrulefill \\ +\highlightbox{lightcolor}{ + \subsection{Bundle } contains \lstinline|Data| types indexed by name + \subsubsection{Defining}: subclass \lstinline|Bundle|, define components: + \begin{scala}^^J + class MyBundle extends Bundle \{^^J + \ \ val a = Bool()^^J + \ \ val b = UInt(32.W)^^J + \}^^J + \end{scala} + \subsubsection{Constructor}: instantiate \lstinline|Bundle| subclass:\\ + \lstinline|val my_bundle = new MyBundle()| + \subsubsection{Inline defining}: define a \lstinline|Bundle| type: + \begin{scala}^^J + val my_bundle = new Bundle \{ ^^J + \ \ val a = Bool()^^J + \ \ val b = UInt(32.W)^^J + \} ^^J + \end{scala} + \subsubsection{Using}: access elements through dot notation: + \begin{scala}^^J + val bundleVal = my_bundle.a^^J + my_bundle.a := Bool(true)^^J + \end{scala} +} +\newline \newline +\highlightbox{normalcolor}{ + \subsection{Vec } is an indexable vector of \lstinline|Data| types \\ + \lstinline|val myVec = Vec(elts:Iterable[Data])| + \begin{tabular}{l l l} + & \lstinline|elts| & initial element \lstinline|Data| (vector depth inferred) + \end{tabular} + \lstinline|val myVec = Vec.fill(n:Int) {gen:Data}| + \begin{tabular}{l l l} + & \lstinline|n| & vector depth (elements) \\ + & \lstinline|gen| & initial element \lstinline|Data|, called once per element + \end{tabular} + \subsubsection{Using}: access elements by dynamic or static indexing: \\ + \lstinline|readVal := myVec(ind:Data/idx:Int)| + \lstinline|myVec(ind:Data/idx:Int) := writeVal| + \subsubsection{Functions}: (\lstinline|T| is the \lstinline|Vec| element's type) \newline + \begin{tabular}{l l l} + & \lstinline|.forall(p:T=>Bool): Bool| & AND-reduce \lstinline|p| on all elts \\ + & \lstinline|.exists(p:T=>Bool): Bool| & OR-reduce \lstinline|p| on all elts \\ + & \lstinline|.contains(x:T): Bool| & \lstinline|True| if this contains \lstinline|x| \\ + & \lstinline|.count(p:T=>Bool): UInt| & count elts where \lstinline|p| is \lstinline|True| \\ + \end{tabular} + \begin{tabular}{l l l} + & \lstinline|.indexWhere(p:T=>Bool): UInt| & \\ + & \lstinline|.lastIndexWhere(p:T=>Bool): UInt| & \\ + & \lstinline|.onlyIndexWhere(p:T=>Bool): UInt| & \\ + \end{tabular} } -\end{scala} -\subsubsection{Using}: access elements through dot notation: \newline -\verb$val bundleVal = my_bundle.a$ \newline -\verb$my_bundle.a := Bool(true)$ - -\subsection{Vec } is an indexable vector of \verb$Data$ types \newline -\verb$val myVec = Vec(elts:Iterable[Data])$ \newline -\begin{tabular}{l l l} -& \verb$elts$ & initial element \verb$Data$ (vector depth inferred) \\ -\end{tabular} - -\verb$val myVec = Vec.fill(n:Int) {gen:Data}$ \newline -\begin{tabular}{l l l} -& \verb$n$ & vector depth (elements) \\ -& \verb$gen$ & initial element \verb$Data$, called once per element \\ -\end{tabular} -\subsubsection{Using}: access elements by dynamic or static indexing: \newline -\verb$readVal := myVec(ind:Data/idx:Int)$ \newline -\verb$myVec(ind:Data/idx:Int) := writeVal$ -\subsubsection{Functions}: (\verb$T$ is the \verb$Vec$ element's type) \newline -\begin{tabular}{l l l} -& \verb$.forall(p:T=>Bool): Bool$ & AND-reduce \verb$p$ on all elts \\ -& \verb$.exists(p:T=>Bool): Bool$ & OR-reduce \verb$p$ on all elts \\ -& \verb$.contains(x:T): Bool$ & \verb$True$ if this contains \verb$x$ \\ -& \verb$.count(p:T=>Bool): UInt$ & count elts where \verb$p$ is \verb$True$ \\ -\end{tabular} -\begin{tabular}{l l l} -& \verb$.indexWhere(p:T=>Bool): UInt$ & \\ -& \verb$.lastIndexWhere(p:T=>Bool): UInt$ & \\ -& \verb$.onlyIndexWhere(p:T=>Bool): UInt$ & \\ -\end{tabular} - -\section{Standard Library: Function Blocks } \hrulefill -\subsection{Stateless}: \newline -\verb$PopCount(in:Bits/Seq[Bool]): UInt$ \newline -\phantom{x} Returns number of hot (= 1) bits in \verb$in$ - -\verb$Reverse(in:UInt): UInt$ \newline -\phantom{x} Reverses the bit order of \verb$in$ - -\verb$UIntToOH(in:UInt, [width:Int]): Bits$ \newline -\begin{tabular}{l l l} -& \multicolumn{2}{l}{Returns the one-hot encoding of \texttt{in}} \\ -& \verb$width$ & {\em(optional, else inferred)} output width \\ -\end{tabular} - -\verb$OHToUInt(in:Bits/Seq[Bool]): UInt$ \newline -\phantom{x} Returns the \verb$UInt$ representation of one-hot \verb$in$ - -\verb$Counter(n:Int]): UInt$ \newline -\phantom{x} .inc() bumps counter returning true when n reached \newline -\phantom{x} .value returns current value - -\verb$PriorityEncoder(in:Bits/Iterable[Bool]): UInt$ \newline -\phantom{x} Returns the position the least significant \verb$1$ in \verb$in$ - -\verb$PriorityEncoderOH(in:Bits): UInt$ \newline -\phantom{x} Returns the position of the hot bit in \verb$in$ - -\verb$Mux1H(in:Iterable[(Data, Bool]): Data$ \newline -\verb$Mux1H(sel:Bits/Iterable[Bool],$ \newline -\verb$ in:Iterable[Data]): Data$ \newline -\verb$PriorityMux(in:Iterable[(Bool, Bits]): Bits$ \newline -\verb$PriorityMux(sel:Bits/Iterable[Bool],$ \newline -\verb$ in:Iterable[Bits]): Bits$ \newline -\begin{tabular}{l l l} -& \multicolumn{2}{l}{A mux tree with either a one-hot select or multiple} \\ -& \multicolumn{2}{l}{\phantom{x} selects (where the first inputs are prioritized)} \\ -& \verb$in$ & iterable of combined input and select \verb$(Bool, Bits)$ \\ -& & tuples or just mux input \verb$Bits$ \\ -& \verb$sel$ & select signals or bitvector, one per input \\ -\end{tabular} - -\subsection{Stateful}: \newline -\verb$LFSR16([increment:Bool]): UInt$ \newline -\begin{tabular}{l l l} -& \multicolumn{2}{l}{16-bit LFSR (to generate pseudorandom numbers)} \\ -& \verb$increment$ & {\em(optional, default True)} shift on next clock \\ -\end{tabular} - -\verb$ShiftRegister(in:Data, n:Int, [en:Bool]): Data$ \newline -\begin{tabular}{l l l} -& \multicolumn{2}{l}{Shift register, returns \texttt{n}-cycle delayed input \texttt{in}} \\ -& \verb$en$ & {\em(optional, default True)} enable \\ -\end{tabular} - -\section{Standard Library: Interfaces } \hrulefill -\subsection{DecoupledIO } \mbox{is a \texttt{Bundle} with a ready-valid interface} -\subsubsection{Constructor}: \newline -\verb$Decoupled(gen:Data)$ \newline -\begin{tabular}{l l l} -& \verb$gen$ & Chisel \verb$Data$ to wrap ready-valid protocol around \\ -\end{tabular} -\subsubsection{Interface}: \newline -\begin{tabular}{c c l l} -& (in) & \verb$.ready$ & ready \verb$Bool$ \\ -& (out) & \verb$.valid$ & valid \verb$Bool$ \\ -& (out) & \verb$.bits$ & data \\ -\end{tabular} - -\subsection{ValidIO } is a \verb$Bundle$ with a valid interface -\subsubsection{Constructor}: \newline -\verb$Valid(gen:Data)$ \newline -\begin{tabular}{l l l} -& \verb$gen$ & Chisel \verb$Data$ to wrap valid protocol around \\ -\end{tabular} -\subsubsection{Interface}: \newline -\begin{tabular}{c c l l} -& (out) & \verb$.valid$ & valid \verb$Bool$ \\ -& (out) & \verb$.bits$ & data \\ -\end{tabular} - -\subsection{Queue } is a \verb$Module$ providing a hardware queue -\subsubsection{Constructor}: \newline -\verb$Queue(enq:DecoupledIO, entries:Int)$ \newline -\begin{tabular}{l l l} -& \verb$enq$ & \verb$DecoupledIO$ source for the queue \\ -& \verb$entries$ & size of queue \\ -\end{tabular} -\subsubsection{Interface}: \newline -\begin{tabular}{l l l} -& \verb$.io.enq$ & \verb$DecoupledIO$ source (flipped) \\ -& \verb$.io.deq$ & \verb$DecoupledIO$ sink \\ -& \verb$.io.count$ & \verb$UInt$ count of elements in the queue \\ -\end{tabular} -\subsection{Pipe } is a \verb$Module$ delaying input data -\subsubsection{Constructor}: \newline -\verb$Pipe(enqValid:Bool, enqBits:Data, [latency:Int])$ \newline -\verb$Pipe(enq:ValidIO, [latency:Int])$ \newline -\begin{tabular}{l l l} -& \verb$enqValid$ & input data, valid component \\ -& \verb$enqBits$ & input data, data component \\ -& \verb$enq$ & input data as \verb$ValidIO$ \\ -& \verb$latency$ & {\em(optional, default 1)} cycles to delay data by \\ -\end{tabular} -\subsubsection{Interface}: \newline -\begin{tabular}{l l l} -& \verb$.io.enq$ & \verb$ValidIO$ source (flipped) \\ -& \verb$.io.deq$ & \verb$ValidIO$ sink \\ -\end{tabular} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Standard Library: Function Blocks } \hrulefill \\ +\highlightbox{lightcolor}{ + \subsection{Stateless}: \newline + \lstinline|PopCount(in:Bits/Seq[Bool]): UInt| \newline + \phantom{x} Returns number of hot (= 1) bits in \lstinline|in|\\ + \lstinline|Reverse(in:UInt): UInt| \newline + \phantom{x} Reverses the bit order of \lstinline|in|\\ + \lstinline|UIntToOH(in:UInt, [width:Int]): Bits| \newline + \begin{tabular}{l l l} + & \multicolumn{2}{l}{Returns the one-hot encoding of \texttt{in}} \\ + & \lstinline|width| & {\em(optional, else inferred)} output width \\ + \end{tabular} + % + \lstinline|OHToUInt(in:Bits/Seq[Bool]): UInt| \newline + \phantom{x} Returns the \lstinline|UInt| representation of one-hot \lstinline|in|\\ + % + \lstinline|Counter(n:Int]): UInt| \newline + \phantom{x} .inc() bumps counter returning true when n reached \newline + \phantom{x} .value returns current value\\ + % + \lstinline|PriorityEncoder(in:Bits/Iterable[Bool]): UInt| \newline + \phantom{x} Returns the position the least significant \lstinline|1| in \lstinline|in|\\ + % + \lstinline|PriorityEncoderOH(in:Bits): UInt| \newline + \phantom{x} Returns the position of the hot bit in \lstinline|in|\\ + % + \lstinline|Mux1H(in:Iterable[(Data, Bool]): Data| \newline + \lstinline|Mux1H(sel:Bits/Iterable[Bool],| \newline + \lstinline|\ \ \ \ \ \ in:Iterable[Data]): Data| \newline + \lstinline|PriorityMux(in:Iterable[(Bool, Bits]): Bits| \newline + \lstinline|PriorityMux(sel:Bits/Iterable[Bool],| \newline + \lstinline|\ \ \ \ \ \ \ \ \ \ \ \ \ in:Iterable[Bits]): Bits| \newline + \begin{tabular}{l l l} + & \multicolumn{2}{l}{A mux tree with either a one-hot select or multiple} \\ + & \multicolumn{2}{l}{\phantom{x} selects (where the first inputs are prioritized)} \\ + & \lstinline|in| & iterable of combined input and select\lstinline|(Bool, Bits)|\\ + & & tuples or just mux input \lstinline|Bits| \\ + & \lstinline|sel| & select signals or bitvector, one per input \\ + \end{tabular} +} +\newline \newline +\highlightbox{normalcolor}{ + \subsection{Stateful}: \newline + \lstinline|LFSR16([increment:Bool]): UInt| \newline + \begin{tabular}{l l l} + & \multicolumn{2}{l}{16-bit LFSR (to generate pseudorandom numbers)} \\ + & \lstinline|increment| & {\em(optional, default True)} shift on next clock \\ + \end{tabular} + \lstinline|ShiftRegister(in:Data, n:Int, [en:Bool]): Data| \newline + \begin{tabular}{l l l} + & \multicolumn{2}{l}{Shift register, returns \texttt{n}-cycle delayed input \texttt{in}} \\ + & \lstinline|en| & {\em(optional, default True)} enable \\ + \end{tabular} +} +\newline \newline +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Standard Library: Interfaces } \hrulefill \\ +\highlightbox{lightcolor}{ + \subsection{DecoupledIO } \mbox{is a \texttt{Bundle} with a ready-valid interface} + \subsubsection{Constructor}: \newline + \lstinline|Decoupled(gen:Data)| \newline + \begin{tabular}{l l l} + & \lstinline|gen| & Chisel \lstinline|Data| to wrap ready-valid protocol around \\ + \end{tabular} + \subsubsection{Interface}: \newline + \begin{tabular}{c c l l} + & (in) & \lstinline|.ready| & ready \lstinline|Bool| \\ + & (out) & \lstinline|.valid| & valid \lstinline|Bool| \\ + & (out) & \lstinline|.bits| & data \\ + \end{tabular} +} -\subsection{Arbiters } are \verb$Module$s connecting multiple producers\newline -\phantom{x} to one consumer \newline -\verb$Arbiter$ prioritizes lower producers \newline -\verb$RRArbiter$ runs in round-robin order -\subsubsection{Constructor}: \newline -\verb$Arbiter(gen:Data, n:Int)$ \newline -\begin{tabular}{l l l} -& \verb$gen$ & data type \\ -& \verb$n$ & number of producers \\ -\end{tabular} -\subsubsection{Interface}: \newline -\begin{tabular}{l l l} -& \verb$.io.in$ & \verb$Vec$ of \verb$DecoupledIO$ inputs (flipped) \\ -& \verb$.io.out$ & \verb$DecoupledIO$ output \\ -& \verb$.io.chosen$ & \verb$UInt$ input index on \verb$.io.out$, \\ -& & does not imply output is valid \\ -\end{tabular} +\highlightbox{normalcolor}{ + \subsection{ValidIO } is a \lstinline|Bundle| with a valid interface + \subsubsection{Constructor}: \newline + \lstinline|Valid(gen:Data)| \newline + \begin{tabular}{l l l} + & \lstinline|gen| & Chisel \lstinline|Data| to wrap valid protocol around \\ + \end{tabular} + \subsubsection{Interface}: \newline + \begin{tabular}{c c l l} + & (out) & \lstinline|.valid| & valid \lstinline|Bool| \\ + & (out) & \lstinline|.bits| & data \\ + \end{tabular} +} +\newline \newline +\highlightbox{lightcolor}{ + \subsection{Queue } is a \lstinline|Module| providing a hardware queue + \subsubsection{Constructor}: \newline + \lstinline|Queue(enq:DecoupledIO, entries:Int)| \newline + \begin{tabular}{l l l} + & \lstinline|enq| & \lstinline|DecoupledIO| source for the queue \\ + & \lstinline|entries| & size of queue \\ + \end{tabular} + \subsubsection{Interface}: \newline + \begin{tabular}{l l l} + & \lstinline|.io.enq| & \lstinline|DecoupledIO| source (flipped) \\ + & \lstinline|.io.deq| & \lstinline|DecoupledIO| sink \\ + & \lstinline|.io.count| & \lstinline|UInt| count of elements in the queue \\ + \end{tabular} +} +\newline \newline +\highlightbox{normalcolor}{ + \subsection{Pipe }is a \lstinline|Module| delaying input data + \subsubsection{Constructor}: \newline + \lstinline|Pipe(enqValid:Bool, enqBits:Data, [latency:Int])| \newline + \lstinline|Pipe(enq:ValidIO, [latency:Int])| \newline + \begin{tabular}{l l l} + & \lstinline|enqValid| & input data, valid component \\ + & \lstinline|enqBits| & input data, data component \\ + & \lstinline|enq| & input data as \lstinline|ValidIO| \\ + & \lstinline|latency| & {\em(optional, default 1)} cycles to delay data by \\ + \end{tabular} + \subsubsection{Interface}: \newline + \begin{tabular}{l l l} + & \lstinline|.io.enq| & \lstinline|ValidIO| source (flipped) \\ + & \lstinline|.io.deq| & \lstinline|ValidIO| sink \\ + \end{tabular} +} +\newline \newline +\highlightbox{lightcolor}{ + \subsection{Arbiters } are \lstinline|Module|s connecting multiple producers\newline + \phantom{x} to one consumer \newline + \lstinline|Arbiter| prioritizes lower producers \newline + \lstinline|RRArbiter| runs in round-robin order + % + \subsubsection{Constructor}: \newline + \lstinline|Arbiter(gen:Data, n:Int)| \newline + \begin{tabular}{l l l} + & \lstinline|gen| & data type \\ + & \lstinline|n| & number of producers \\ + \end{tabular} + \subsubsection{Interface}: \newline + \begin{tabular}{l l l} + & \lstinline|.io.in| & \lstinline|Vec| of \lstinline|DecoupledIO| inputs (flipped) \\ + & \lstinline|.io.out| & \lstinline|DecoupledIO| output \\ + & \lstinline|.io.chosen| & \lstinline|UInt| input index on \lstinline|.io.out|, \\ + & & does not imply output is valid \\ + \end{tabular} +} \end{multicols} \end{document} diff --git a/scala.tex b/scala.tex index 03d17ed..9951c27 100644 --- a/scala.tex +++ b/scala.tex @@ -1,6 +1,15 @@ + % "define" Scala -\usepackage[T1]{fontenc} -\usepackage{microtype} +\usepackage[T1]{fontenc} +\usepackage{microtype} +\usepackage{xcolor} + +\definecolor{commentcolor}{rgb}{0,0.6,0} +\definecolor{gray}{rgb}{0.5,0.5,0.5} +\definecolor{stringcolor}{rgb}{0.58,0,0.82} +\definecolor{light-gray}{gray}{0.75} +\definecolor{keywordcolor}{rgb}{0,0,1} +\definecolor{procnamecolor}{rgb}{1,0,0} \sbox0{\small\ttfamily A} \edef\mybasewidth{\the\wd0 } @@ -21,29 +30,24 @@ morestring=[b]""" } -\usepackage{color} -\definecolor{dkgreen}{rgb}{0,0.6,0} -\definecolor{gray}{rgb}{0.5,0.5,0.5} -\definecolor{mauve}{rgb}{0.58,0,0.82} -\definecolor{light-gray}{gray}{0.75} - % Default settings for code listings \lstset{language=scala, + backgroundcolor = \color{codebgcolor}, showstringspaces=false, columns=fixed, % basewidth=\mybasewidth, basicstyle={\small\ttfamily}, numbers=none, numberstyle=\footnotesize\color{gray}, % identifierstyle=\color{red}, - keywordstyle=\color{blue}, - commentstyle=\color{dkgreen}, - stringstyle=\color{mauve}, + keywordstyle=\color{keywordcolor}, + commentstyle=\color{commentcolor}, + stringstyle=\color{stringcolor}, breakatwhitespace=true, procnamekeys={def, val, var, class, trait, object, extends}, - procnamestyle=\ttfamily\color{red}, - frame=leftline, + procnamestyle=\ttfamily\color{procnamecolor}, + frame=none, rulecolor=\color{light-gray}, - xleftmargin=2mm, + xleftmargin=0mm, aboveskip=2pt, belowskip=2pt, }