chisel-book-chinese.tex

\documentclass[%draft,
    10pt,
    headinclude, footexclude,
    % twoside, % this produces strange margins!
    openright, % for new chapters
    notitlepage,
    cleardoubleempty,
    headsepline,
    pointlessnumbers,
    bibtotoc, idxtotoc,
    ]{scrbook}

% iPad Air 2 resolution: 1536 x 2048
% 1.3333 ratio (4:3)
% LeeSeshia is 15,73 ? 20,96 cm, ratio 1.332
%\setlength{\paperwidth}{15.73cm} \setlength{\paperheight}{20.96cm}
\setlength{\paperwidth}{15.72cm} \setlength{\paperheight}{20.95cm}
%\typearea{calc} % without BCOR results to a DIV of 8 for 11pt
\typearea[1cm]{18} % TODO: check if 1 cm is the correct number

\usepackage{scrlayer-scrpage}
\setkomafont{pagehead}{\scshape\small}
\setkomafont{pagenumber}{\scshape\small}


\newif\ifbook
%\booktrue % comment out for the eBook version

\ifbook
\else
\cfoot{\hyperlink{contents}{{\textnormal{Contents}}}}
\fi



\usepackage{CJKutf8}
\usepackage{pslatex} % -- times instead of computer modern, especially for the plain article class
\usepackage[colorlinks=true,bookmarks=false]{hyperref}
\usepackage{booktabs}
\usepackage{graphicx}
\usepackage{xcolor}
\usepackage{multirow}
\usepackage{cite}
\usepackage{dirtree}
\usepackage{pdfpages}
% For alignment on tables
\usepackage{dcolumn}
\newcommand{\cc}[1]{\multicolumn{1}{c}{#1}}

\newcommand{\code}[1]{{\small{\texttt{#1}}}}
\newcommand{\codefoot}[1]{{\footnotesize{\texttt{#1}}}}

% fatter TT font
\renewcommand*\ttdefault{txtt}
% another TT, suggested by Alex
% \usepackage{inconsolata}
% \usepackage[T1]{fontenc} % needed as well?

\usepackage[procnames]{listings}


\ifbook
\hypersetup{
  linkcolor  = black,
  citecolor  = black,
  urlcolor   = black,
  colorlinks = black,
  bookmarks=false,
}
\else
\hypersetup{
  linkcolor  = blue,
  citecolor  = blue,
  urlcolor   = blue,
  colorlinks = true,
  bookmarks=true,
}
\fi

% not really used
\newenvironment{comment}
{ \vspace{-0.1in}
  \begin{quotation}
  \noindent
  \small \em
  \rule{\linewidth}{0.5pt}\\
}
{
  \\
  \rule{\linewidth}{0.5pt}
  \end{quotation}
}

\newcommand{\scale}{0.7}

\input{shared/chisel.tex}

\newcommand{\todo}[1]{{\emph{TODO: #1}}}
\newcommand{\martin}[1]{{\color{blue} Martin: #1}}
\newcommand{\myref}[2]{\href{#1}{#2}}

\ifbook
\renewcommand{\myref}[2]{{#2}{\footnote{\url{#1}}}}
\fi

% uncomment following for final submission
\renewcommand{\todo}[1]{}
\renewcommand{\martin}[1]{}

\begin{document}


\ifbook
\else
\includepdf{chisel-cover.pdf}
\newpage
\thispagestyle{empty}
~
\newpage
\fi



\begin{flushleft}
\pagestyle{empty}
\ \\
\vspace{1cm}
{\usekomafont{title}\mdseries\huge Digital Design with Chisel}
\cleardoublepage
\end{flushleft}
\newpage


\begin{flushleft}
\pagestyle{empty}
\ \\
\vspace{1cm}
{\usekomafont{title}\Huge Digital Design with Chisel\\
\bigskip
\bigskip
\bigskip
\bigskip
\bigskip
%{\large\itshape Beta Edition}\\
\bigskip
{\usekomafont{title}\huge Martin Schoeberl}
\medskip\\
%{\large\itshape martin@jopdesign.com}

}

%\vspace{10cm} \emph{Version: \today}
\newpage
\end{flushleft}

\thispagestyle{empty}
\begin{flushleft}
{\small

%\lowertitleback{
Copyright \copyright{} 2016--2019 Martin Schoeberl
  \medskip\\
  \begin{tabular}{lp{.8\textwidth}}
    \raisebox{-12pt}{\includegraphics[height=18pt]{figures/cc_by_sa}} &
     This work is licensed under a Creative Commons Attribution-ShareAlike
     4.0 International License.
     \url{http://creativecommons.org/licenses/by-sa/4.0/}\\
  \end{tabular}
%}

\medskip

Email: \url{martin@jopdesign.com}\\
Visit the source at \url{https://github.com/schoeberl/chisel-book}
\medskip

Published 2019 by Kindle Direct Publishing,\\
\url{https://kdp.amazon.com/}
\medskip
\medskip


\textbf{Library of Congress Cataloging-in-Publication Data}
\medskip

Schoeberl, Martin
\begin{quote}
Digital Design with Chisel\\
Martin Schoeberl\\
Includes bibliographical references.\\ \todo{and index. \\}
ISBN 9781689336031
\end{quote}

\bigskip


Manufactured in the United States of America.

Typeset by Martin Schoeberl.}
\end{flushleft}

\frontmatter

\phantomsection
\hypertarget{contents}{}
\tableofcontents


\begingroup
\let\cleardoublepage\clearpage
\listoffigures
\listoftables
\lstlistoflistings
\endgroup

%\chapter*{Foreword}
%
%Here comes the text.
%
%\bigskip
%
%Jonathan Bachrach, designer of Chisel

\chapter{Preface}

% This text goes on the backside of the book, and in Amazon description
% 该文本在书本的背面，和亚马逊的介绍

This book is an introduction to digital design with the focus on using the hardware construction language Chisel. Chisel brings advances from software engineering, such as object-orientated and functional languages, into digital design.

This book addresses hardware designers and software engineers. Hardware designers, with knowledge of Verilog or VHDL, 

can upgrade their productivity with a modern language for their next ASIC or FPGA design. 

Software engineers, with knowledge of object-oriented and functional programming, can leverage their knowledge to program hardware, for example, FPGA accelerators executing in the cloud.

The approach of this book is to present small to medium-sized typical hardware components to explore digital design with Chisel.

这本书是一个专注于使用硬件构建语言chisel进行数字设计的导论。Chisel带来了软件工程的优势，像是面向对象和函数编程，进入数字设计。

这本书是给硬件设计师和软件工程师的。硬件设计师，有着Verilog或VHDL的知识，可以通过新型语言增加生产力，用于下一个ASIC或是FPDA设计。

软件工程师，有着面向对象语言和函数编程的知识，可以把这些知识用于生产硬件，例如，云FPGA。

这本书的方法是呈现小型到中型大小的典型硬件部分，去探索使用chisel做数字设计。


% about me, backside

%Martin Schoeberl is Associate Professor at the Technical University of Denmark, where he is teaching digital electronics and computer architecture. His research interest is on hard real-time systems, time-predictable computer architecture, and real-time Java. He has more than 100 publications in peer reviewed journals, conferences, and books.

%Martin has been four times at UC Berkeley on research stays, where he has picked up Chisel and was in close contact with the developers of Chisel. He lead the research project T-CREST where most of the components have been written in Chisel.

\section*{Acknowledgements}

I want to thank everyone who has worked on Chisel for creating such
a cool hardware construction language. Chisel is so joyful to use and
therefore worth writing a book about.
I am thankful to the whole Chisel community, which is so welcoming and friendly
and never tired to answer questions on Chisel.

I would also like to thank my students in the last years of an advanced computer
architecture course where most of them picked up Chisel for the final project.
Thank you for moving out of your comfort zone and taking up the journey of
learning and using a bleeding-edge hardware description language.
Many of your questions have helped to shape this book.

我想感谢所有在chisel上进行开发的人，他们创造了这样一个酷的硬件构建语言。chisel使用起来非常愉快，
于是写这样一本书很值得。

我很感谢整个chisel社区，非常对外欢迎友好，并且我从不对在chisel问问题感到疲惫。

我也想感谢去年在我的高级计算机架构课上的学生，他们大多数选择使用chisel作为最终项目。
感谢你们走出舒适区，走入了学习和使用前沿的硬件构建语言。
你们大多数的问题帮助规范了这本书。


\mainmatter

\chapter{Introduction}
\label{sec:intro}

This book is an introduction to digital system design using a modern hardware
construction language, \myref{https://chisel.eecs.berkeley.edu/}{Chisel}~\cite{chisel:dac2012}.
In this book, we focus on a higher abstraction level than usual in digital design books,
to enable you to build more complex, interacting digital systems in a shorter time.

这本书是一个使用现代硬件构建语言Chisel做数字系统设计的导论, 
\myref{https://chisel.eecs.berkeley.edu/}{Chisel}~\cite{chisel:dac2012}。
在这本书，我们聚焦在比平常的硬件设计更高抽象层，
使在短时间搭建更为复杂和交互性的硬件系统变得可能。

This book and Chisel are targeting two groups of developers:
(1) hardware designers and (2) software programmers.
Hardware designers who are fluid in VHDL or Verilog and using other languages such as Python,
Java, or Tcl to generate hardware can move to a single hardware construction language
where hardware generation is part of the language and
Software programmers may become interested in hardware design,
e.g., as future chips from Intel will include programmable hardware to speed up programs.
It is perfectly fine to use Chisel as your first hardware description language.

这本书和Chisel的目标群体是两种开发者：
（1）硬件设计者 （2）软件编程者

硬件设计者，精通VHDL或是Verilog，使用其它语言，像是Python, Java, 或是TCL/TK去生成硬件，使其变成一个硬件建造语言，这样，生成硬件作为语言的一部分。

软件编程者，对硬件设计有兴趣的软件程序员，例如，像是Intel未来的芯片会添加可编程硬件用来提高程序速度。


Chisel brings advances in software engineering, such as object-orientated
and functional languages, into digital design.
Chisel does not only allow to express hardware at the register-transfer level
but allows you to write hardware generators.

Chisel将诸如面向对象和函数式语言之类的软件工程的优势引入数字系统设计。
Chisel不仅仅允许表示硬件在寄存器传输的抽象层，而且允许你编写硬件生成器。

Hardware is now commonly described with a hardware description language.
The time of drawing hardware components, even with CAD tools, is
over. Some high-level schematics can give an overview of the system but are
not intended to describe the system.

硬件现在普遍通过硬件描述语言进行描述。绘制硬件部件，甚至利用CAD工具的时代已经过去了。
一些高层次的原理图可以给你一个系统的整体概述，但它们并不用来描述系统。

The two most common hardware description languages are Verilog and VHDL.
Both languages are old, contain many legacies, and have a moving line of what
constructs of the language are synthesizable to hardware.
Do not get me wrong: VHDL and Verilog are perfectly able to describe a hardware
block that can be synthesized into an
\myref{https://en.wikipedia.org/wiki/Application-specific_integrated_circuit}{ASIC}.
For hardware design in Chisel, Verilog serves as an intermediate language
for testing and synthesis.

两个最常用的硬件描述语言是Verilog和VHDL。
这两个语言是古老的，包括大量规则，并且在综合到硬件的构建语言之间有一个变动的规则。
别理解错我的意思：VHDL和Verilog可以完美描述用于综合成\myref{https://en.wikipedia.org/wiki/Application-specific_integrated_circuit}{ASIC}的硬件模块。
对于Chisel的硬件设计，verilog充当一个测试和综合的中间语言。

This book is not a general introduction to hardware design and the fundamentals of it.
For an introduction of the basics in digital design, such as how to build a gate out of
CMOS transistors, refer to other digital design books.
However, this book intends to teach digital design at an abstraction level that is
current practice to describe ASICs or designs targeting
\myref{https://en.wikipedia.org/wiki/Field-programmable_gate_array}{FPGA}s.\footnote{As the author is more familiar with FPGAs
than ASICs as target technology, some design optimizations shown in this book are
targeting FPGA technology.}
As prerequisites for this book, we assume basic knowledge of
\myref{https://en.wikipedia.org/wiki/Boolean_algebra}{Boolean algebra} and the
\myref{https://en.wikipedia.org/wiki/Binary_number}{binary number system}.
Furthermore, some programming experience in any programming language
is assumed. No knowledge of Verilog or VHDL is needed.
Chisel can be your first programming language to describe digital hardware.
As the build process in the examples is based on \code{sbt} and \code{make}
basic knowledge of the command-line interface (CLI, also called terminal or
Unix shell) will be helpful.

这本书不是对硬件的设计和基础一般性介绍。
对有关数字设计基础知识的介绍，例如如何使用CMOS晶体管搭建一个门电路，你要参考其它数字设计书。
但是，这本书的目的是教你在一个抽象层中进行数字设计，作为当今描述ASIC或是设计
\myref{https://en.wikipedia.org/wiki/Field-programmable_gate_array}{FPGA}的例子。
\footnote{因为作者相比于ASIC，更熟悉FPGA一些，书中的一些优化是针对FPGA的技术}
作为这本书的前置需求，我们假设你有一些基本的\myref{https://en.wikipedia.org/wiki/Boolean_algebra}{Boolean algebra}和\myref{https://en.wikipedia.org/wiki/Binary_number}{binary number system}的知识。
更多的，一些任意编程语言的编程经验也是需要的。不需要Verilog或是VHDL的知识。
Chisel能够成为你的第一个编程语言用来描述数字硬件。
作为例子中的搭建过程是基于\code{sbt}和\code{make}，基本的命令行界面知识（CLI，又称terminal或是Unix shell）会是有用的。

Chisel itself is not a big language. The basic constructs fit on
\myref{https://chisel.eecs.berkeley.edu/doc/chisel-cheatsheet3.pdf}{one page}
and can be learned within a few days.
Therefore, this book is not a big book, as well.
Chisel is for sure smaller than VHDL and Verilog, which carry many legacies.
The power of Chisel comes from the embedding of Chisel within
\myref{https://www.scala-lang.org/}{Scala}, which itself in an expressive language.
Chisel inherits the feature from Scala being ``a language that grows on you''~\cite{Scala}.
However, Scala is not the topic of this book.

Chisel用来本身不是一个大的语言。基本的部分在这里\myref{https://chisel.eecs.berkeley.edu/doc/chisel-cheatsheet3.pdf}{one page}， 可以在数日内学习。
于是，这本书也不是一本大书。Chisel应该是比VHDL和Verilog更小, 
继承很多规则。Chisel的力量来自于它是嵌入在\myref{https://www.scala-lang.org/}{Scala}里的，Scala本身是一个有力的语言。
Chisel继承Scala作为``a language that grows on you''~\cite{Scala}的特性
但是，Scala不是本书的话题。

% We provide a short section on Scala for hardware designers, but
%A general introduction to Scala is better served by
The textbook by Odersky et al.~\cite{Scala} provides a general introduction
to Scala.

我们提供了一个短的章节给硬件设计者，但是Odersky~\cite{Scala}提供了一个更好的Scala导论。

This book is a tutorial in digital design and the Chisel language; it is not
a Chisel language reference, nor is it a book on complete chip design.

这本书是一个数字设计和Chisel语言的教学，不是Chisel语言的参考书籍也不是一本完整的芯片设计书

All code examples shown in this book are extracted from complete programs
that have been compiled and tested. Therefore, the code shall not contain
any syntax errors. The code examples are available from the
\myref{https://github.com/schoeberl/chisel-book}{GitHub repository}
of this book.
Besides showing Chisel code, we have also tried to show useful designs and
principles of good hardware description style.

所有的书中代码例子来自经过编译和测试过的程序。所以，代码不应该含有任何语法问题。
代码例子在本书的\myref{https://github.com/schoeberl/chisel-book}{GitHub repository}里。除了提供Chisel代码以外，我也试图提供有用的设计和好的硬件描述风格的规则。


This book is optimized for reading on a laptop or tablet (e.g., an iPad).
We include links to further reading in the running text, mostly to
\myref{https://en.wikipedia.org/}{Wikipedia} articles.

这本书在笔电或是平板上为阅读经过了优化。我们在字里行间提供了链接，大多数是\myref{https://en.wikipedia.org/}{Wikipedia}的文章。

\section{Installing Chisel and FPGA Tools}

Chisel is a Scala library, and the easiest way to install Chisel and Scala is
with \code{sbt}, the Scala build tool. Scala itself depends on the installation
of the \myref{https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html}{Java JDK 1.8}.

Chisel是一个Scala库，安装Chisel和Scala最简单的方法时通过\code{sbt}, Scala Build Tool。
Scala本身依赖于安装\myref{https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html}{Java JDK 1.8}。

On Mac OS X, with the packet manager \myref{https://brew.sh/}{Homebrew},
\code{sbt} is installed with:

在Mac OS X中，通过包管理软件\myref{https://brew.sh/}{Homebrew}，sbt可以通过此命令安装

\begin{verbatim}
$ brew install sbt
\end{verbatim}

\noindent For Ubuntu, which is based on Debian, programs are usually installed from a
Debian file (.deb). However, as of the time of this writing \code{sbt} is not
available as a ready to install package. Therefore, the installation process
is a little bit more involved:

对于基于Debian的Ubuntu系统，软件通常通过.deb文件进行安装。
然而，当编写本文时，\code{sbt}还不能通过这种方法安装。
因此，安装过程有点麻烦：

\begin{verbatim}
echo "deb https://dl.bintray.com/sbt/debian /" | \
  sudo tee -a /etc/apt/sources.list.d/sbt.list
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 \
  --recv 2EE0EA64E40A89B84B2DF73499E82A75642AC823
sudo apt-get update
sudo apt-get install sbt
\end{verbatim}

Chisel and Scala can also be installed and used under Windows.
\code{sbt} can be installed with a Windows installer, see:
\myref{https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Windows.html}{Installing sbt on Windows}.

Chisel和Scala也支持Windows操作系统。
\code{sbt} 可以使用windows安装器安装，参照：
\myref{https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Windows.html}{在windows安装sbt}.

To build hardware for an FPGA, you need a synthesize tool. The two major
FPGA vendors, Intel\footnote{former Altera} and Xilinx, provide free versions of
their tools that cover small to medium-sized FPGAs. Those medium-sized
FPGAs are large enough to build multicore RISC style processors.
Intel provides the \myref{https://www.altera.com/products/design-software/fpga-design/quartus-prime/download.html}{Quartus Prime Lite Edition} and Xilinx the
\myref{https://www.xilinx.com/products/design-tools/vivado/vivado-webpack.html}{Vivado Design Suite, WebPACK Edition}.

为了构建FPGA硬件，你需要综合工具。两大主要的FPGA工具供应商，Intel\footnote{曾经是Altera}和Xilinx都提供了他们免费的工具，涵盖了小容量到中等容量大小的FPGA。
其中，中等规模的FPGA已经足够容纳多核RISC架构处理器。
Intel提供了\myref{https://www.altera.com/products/design-software/fpga-design/quartus-prime/download.html}{Quartus Prime Lite Edition} 
和\myref{https://www.xilinx.com/products/design-tools/vivado/vivado-webpack.html}{Vivado Design Suite, WebPACK Edition}。


\section{Hello World}

Each book on a programming language shall start with a minimal example,
called the \emph{Hello World} example. Following code is the first approach:

每一本编程语言书都会从叫做\emph{Hello World}的最小例子开始。以下代码是第一种方法。


\shortlist{src/main/scala/HelloScala.scala}


\noindent Compiling and executing this short program with \code{sbt}

编译、执行这个简短的程序通过\code{sbt}：

\begin{chisel}
$ sbt "runMain HelloScala"
\end{chisel}

\noindent leads to the expected output of a Hello World program:

随后，Hello World程序输出了预期的内容：

\begin{chisel}
[info] Running HelloScala
Hello Chisel World!
\end{chisel}

\noindent However, is this Chisel? Is this hardware generated to print a string?
No, this is plain Scala code and not a representative Hello World
program for a hardware design.

然而，这就是Chisel吗？这个硬件被生成用于出书字符串吗？并不是这样，这里实际上是解释了Scala代码，并不代表着硬件设计的Hello World程序。


\section{Chisel Hello World}

What is then the equivalent of a Hello World program for a hardware design?
The minimal useful and visible design? A blinking LED is the hardware (or even
embedded software) version of Hello World. If a LED blinks, we are ready to
solve bigger problems!

那么Hello World程序等价的硬件设计是什么？是最小的可用并且可视的设计？一个闪烁的LED是硬件（或者嵌入式软件）版本的Hello World。 
如果一个LED闪烁，我们就可以解决更大的问题。

\longlist{code/hello.txt}{A hardware Hello World in Chisel}{lst:chisel:hello}

Listing~\ref{lst:chisel:hello} shows a blinking LED, described in Chisel.
It is not important that you understand the details of this code example.
We will cover those in the following chapters. Just note that the circuit is
usually clocked with a high frequency, e.g., 50 MHz, and we need a counter
to derive timing in the Hz range to achieve a visible blinking. In the above
example, we count from 0 up to 25000000-1 and then toggle the blinking signal
(\code{blkReg := \textasciitilde blkReg}) and restart the counter (\code{cntReg := 0.U}).
That hardware then blinks the LED at 1~Hz.

F~\ref{fig:chisel:hello}展现的是一个通过Chisel描述的闪烁LED。你是否理解这个代码案例的细节是不重要的。我们将会介绍这些内容在以下的章节中。
仅仅需要注意这个电路通常有着高频率的时钟，例如50MHz，我们需要一个计数器来分频得到Hz级别的频率来实现可视化的闪烁。在这个例子中我们从0计数到25000000-1然后触发闪烁信号(\code{blkReg := \textasciitilde blkReg}) 
然后复位计数器 (\code{cntReg := 0.U})。这个硬件以1~Hz频率闪烁LED。

\section{An IDE for Chisel}

This book makes no assumptions about your programming environment or editor to use.
Learning of the basics should be easy with just using \code{sbt} at the command line
and an editor of your choice. In the tradition of other books, all commands that you
shall type in a shell/terminal/CLI are preceded by a \code{\$} character, which you
shall not type in. As an example, here is the Unix \code{ls} command, which lists files in
the current folder:

这本书没有假设你的编程环境和使用的编辑器。
在命令行中使用\code{sbt}同时使用一个你偏好的编辑器可以很容易的入门。在其他传统的书籍中，
所有你需要键入终端的命令之前会有一个\code{\$}字符，这个字符你不需要输入。一个例子，Unix的列出当前文件夹下的文件\code{ls}
命令：

\begin{verbatim}
$ ls
\end{verbatim}

That said, an integrated development environment (IDE), where a compiler is running in
the background, can speed up coding. As Chisel is a Scala library, all IDEs
that support Scala are also good IDEs for Chisel.
It is possible in \myref{https://www.eclipse.org/}{Eclipse} and
\myref{https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html}{IntelliJ}
to generate a project from the sbt project configuration in \code{build.sbt}.
You can create an Eclipse project via

也就是说，一个编译器后台运行的集成开发环境(IDE)，可以加速编程。因为Chisel是一个Scala库，所有的IDEs都支持Scala，也支持Chisel。
在 \myref{https://www.eclipse.org/}{Eclipse} 和
\myref{https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html}{IntelliJ}中生成一个包含\code{build.sbt}配置文件的sbt工程是可行了。
你可以创建一个Eclipse工程通过

\begin{verbatim}
$ sbt eclipse
\end{verbatim}
and import that project into Eclipse.\footnote{This function needs the Eclipse plugin for sbt.}
In IntelliJ you can create a new project from existing sources and then select from \code{build.sbt}.
或者导入一个工程入Eclipse。\footnote{This function needs the Eclipse plugin for sbt.}
在InterlliJ中你可以创建一个工程从已经存在的源码中，然后选择\code{build.sbt}文件。


\myref{https://code.visualstudio.com/}{Visual Studio Code} with
\myref{https://marketplace.visualstudio.com/items?itemName=scalameta.metals/}{Scala Metals} requires
no setup beyond installing Visual Studio Code and the Scala Metals plugin. Scala Metals knows how to
set up everything including but not limited to code completion, Chisel source code download and
building based on \code{build.sbt}.

\myref{https://code.visualstudio.com/}{Visual Studio Code} 和
\myref{https://marketplace.visualstudio.com/items?itemName=scalameta.metals/}{Scala Metals}只需要
 安装VS code和Scala Metals插件。Scala Metals知道如何去设置所有的东西不包括但不限于代码补全，Chisel源代码下载和基于\code{build.sbt}的配置。

\section{Source Access and eBook Features}

This book is open source and hosted at GitHub: \myref{https://github.com/schoeberl/chisel-book}{chisel-book}.
All Chisel code examples, shown in this book, are included in the repository.
The code compiles with a recent version of Chisel, and many examples also include a test bench.
We collect larger Chisel examples in the accompanying repository \myref{https://github.com/schoeberl/chisel-examples}{chisel-examples}. If you find an error or typo in the book, a GitHub pull request is the most convenient way to incorporate your improvement.
You can also provide feedback or comments for improvements by filing an issue on GitHub
or sending a plain, old school email.
这本书是在GitHub: \myref{https://github.com/schoeberl/chisel-book}{chisel-book}上开源。书中所有的Chisel例子都包含在该仓库中。
这些代码通过最近的Chisel版面编译，很多例子都包含了test bench。
我们收集了很多Chisel例子在\myref{https://github.com/schoeberl/chisel-examples}{chisel-examples}仓库里。如果你找到了错误或者笔误，可以提交pull request。
你可以在github上记录一个issue来提供反馈或者评论或者发送一个简单的学校邮件。


This book is freely available as a PDF eBook and in classical printed form.
The eBook version features links to further resources
and \myref{https://www.wikipedia.org/}{Wikipedia} entries.
We use Wikipedia entries for background information (e.g., binary number system)
that does not directly fit into this book.
We optimized the format of the eBook for reading on a tablet, such as an iPad.

这本书有免费的古典印刷体PDF电子版。
电子书提供了更多的资源和\myref{https://www.wikipedia.org/}{Wikipedia}入口。
我们使用Wikipedia来说明与本书部直接相关的背景知识(例如二进制数字系统)。
我们优化了电子书的排版，以方便便携式设备阅读，例如ipad。

\section{Further Reading}

Here a list of further reading for digital design and Chisel:
这儿例出了关于数字电路设计和Chisel更深层次的读物：

\begin{itemize}
\item \myref{http://www.cambridge.org/es/academic/subjects/engineering/circuits-and-systems/digital-design-systems-approach}{Digital Design: A Systems Approach}, by William J. Dally and R. Curtis Harting,
is a modern textbook on digital design. It is available in two versions: using Verilog or VHDL as a hardware description language.
\end{itemize}

\myref{http://www.cambridge.org/es/academic/subjects/engineering/circuits-and-systems/digital-design-systems-approach}{Digital Design: A Systems Approach}, 作者是William J. Dally 和 R. Curtis Harting,
，是一本现代的数字设计的教科书。它有两个版本，使用Verilog或是VHDL作为硬件描述语言。

\end{itemize}
The official Chisel documentation and further documents are available online:
Chisel官方文档和之后的文档都会更新到网上：

\begin{itemize}
\item The \myref{https://chisel.eecs.berkeley.edu/}{Chisel} home page is the official starting point to
download and learn Chisel.

\myref{https://chisel.eecs.berkeley.edu/}{Chisel}主页是开始安装和学习chisel的地方。


\item The \myref{https://github.com/ucb-bar/chisel-tutorial}{Chisel Tutorial} provides a ready setup
project containing small exercises with testers and solutions.

\myref{https://github.com/ucb-bar/chisel-tutorial}{Chisel Tutorial} 提供了一个准备安装的项目，
包括小的测试和解决答案的练习。


\item The \myref{https://github.com/freechipsproject/chisel3/wiki}{Chisel Wiki} contains
a short users guide to Chisel and links to further information.

\item \myref{https://github.com/freechipsproject/chisel3/wiki}{Chisel Wiki}包含了小的chisel的用户手册
和更多信息的链接。


\item The \myref{https://github.com/freechipsproject/chisel-testers}{Chisel Testers} are in
their repository that contains a Wiki documentation.

\item \myref{https://github.com/freechipsproject/chisel-testers}{Chisel Testers} 包括在他们的仓库，
包含了一个wiki文档。

\item The \myref{https://github.com/ucb-bar/generator-bootcamp}{Generator Bootcamp} is
a Chisel course focusing on hardware generators, as a Jupyter notebook

\item \myref{https://github.com/ucb-bar/generator-bootcamp}{Generator Bootcamp} 是chisel课程，专注在硬件生成器，
作为jupyter notebook。

\item A \myref{https://github.com/ccelio/chisel-style-guide}{Chisel Style Guide} by Christopher Celio.
\end{itemize}

\item \myref{https://github.com/ccelio/chisel-style-guide}{Chisel Style Guide}，作者是Christopher Celio。
\end{itemize}

\section{Exercise}

Each chapter ends with a hands-on exercise. For the introduction exercise, we will use an
FPGA board to get one \myref{https://en.wikipedia.org/wiki/Light-emitting_diode}{LED} blinking.
As a first step clone (or fork) the \myref{https://github.com/schoeberl/chisel-examples}{chisel-examples}
repository from GitHub.
The Hello World example is in the folder \code{hello-world}, set up as
a minimal project. You can explore the Chisel code of the blinking LED
in \code{src/main/scala/Hello.scala}.
Compile the blinking LED with the following steps:
每个章节结尾都有手写的练习题。为了介绍练习，我们通常会使用一个FPGA板子上的一颗LED。
第一步clone或者fork\myref{https://github.com/schoeberl/chisel-examples}{chisel-examples}仓库。 
Hello World例子在\code{hello-world}文件夹里，是一个最小的工程。你可以探索LED闪烁的Chisel代码在\code{src/main/scala/Hello.scala}。
按下下述步骤编译LED闪烁工程：

\begin{chisel}
$ git clone https://github.com/schoeberl/chisel-examples.git
$ cd chisel-examples/hello-world/
$ make
\end{chisel}

After some initial downloading of Chisel components, this will produce the Verilog file \code{Hello.v}.
Explore this Verilog file. You will see that it contains two inputs \code{clock} and \code{reset}
and one output \code{io\_led}. When you compare this Verilog file with the Chisel module,
you will notice that the Chisel module does not contain \code{clock} or \code{reset}.
Those signals are implicitly generated, and in most designs, it is convenient not to need to
deal with these low-level details. Chisel provides register components, and those
are connected automatically to \code{clock} and \code{reset} (if needed).

在Chisel部分下载完成之后，程序会产出一个Verilog文件\code{Hello.v}。
浏览这个Verilog文件，你会看到电路包含两个输入\code{clock}和\code{reset}
和一个输出\code{io\_led}。当你对比Verilog文件和Chisel模块时，你将会发现Chisel模块申明时不包含\code{clock}和\code{reset}。
这些信号是隐式生成的，在大部分设计中处理这些底层细节是不方便的。Chisel提供的寄存器如果需要，会自动连接\code{clock}和\code{reset}.

The next step is to set up an FPGA project file for the synthesize tool, assign the pins,
and compile\footnote{The real process is more elaborated with following steps: synthesizing the logic,
performing place and route, performing timing analysis, and generating a bitfile.
However, for the purpose of this introduction example we simply call it ``compile''
your code.} the Verilog code, and configure the FPGA with the resulting bitfile.
We cannot provide the details of these steps. Please consult the manual of
your Intel Quartus or Xilinx Vivado tool.
However, the examples repository contains some ready to use Quartus
projects in folder \code{quartus} for several popular FPGA boards (e.g., DE2-115).
If the repository contains support for your board, start Quartus, open the project,
compile it by pressing the \emph{Play} button, and configure the FPGA board
with the \emph{Programmer} button and one of the LEDs should blink.
下一步是建立FPGA工程文件，分配引脚，然后编译Verilog代码，最后利用生成的bit文件烧写进FPGA。
我们无法提供这些步骤的详细过程。请参考你的EDA工具手册。
然而，例程仓库里面包含了一些针对几个流行的FPGA的Quartus可用的工程在\code{quartus}文件夹中。
如果仓库支持的板子包括你的FPGA，启动Quartus，打开工程，编译，烧录，然后一个LED将会闪烁。

{\bf Gratulation! You managed to get your first design in Chisel running in an FPGA!}
{\bf 厉害了！你成功在FPGA上运行了你第一个Chisel电路！}

If the LED is not blinking, check the status of reset. On the DE2-115 configuration,
the reset input is connected to SW0.
如果LED没有闪烁，检查reset的状态。在DE2-115配置中，reset的输入连接SW0.

Now change the blinking frequency to a slower or a faster value and
rerun the build process. Blinking frequencies and also blinking patterns
communicate different ``emotions''. E.g., a slow blinking LED signals that
everything is ok, a fast blinking LED signals an alarm state.
Explore which frequencies express best those two different emotions.
现在改变闪烁的频率然后重新运行一遍构建工程。闪烁的频率和闪烁的方式可以预示不同的状态。例如一个缓慢的闪烁信代表一切正常，一个快速的闪烁信号代表一个报警。
探索哪个频率对应这两个不同的动作。

As a more challenging extension to the exercise, generate the following blinking pattern:
the LED shall be on for 200~ms every second. For this pattern, you might
decouple the change of the LED blinking from the counter reset.
You will need a second constant where you change the state of the
\code{blkReg} register. What kind of emotion does this pattern produce?
Is it alarming or more like a sign-of-live signal?
一个更具有挑战性的练习，生成一个下述的闪烁模式：
LED一秒中亮200~ms。对于这个模式，你可以会从计数器复位来分离LED的闪烁。你将会需要第二个常量来改变\code{blkReg}寄存器的状态。这个模式会产生什么种类的状态呢？
是警报还是更像一个正常运行的信号呢？



\chapter{Basic Components}

In this section, we introduce the basic components for digital design:
combinational circuits and flip-flops.
These essential elements can be combined to build larger, more interesting circuits.

在这个章节，我们介绍数字设计的组成部分。这些基本的组成部分可以被合并到更大，更有趣的电路中。

\section{Signal Types and Constants}

Chisel provides three data types to describe signals, combinational logic, and registers:
\code{Bits}, \code{UInt}, and \code{SInt}. \code{UInt} and \code{SInt} extend \code{Bits},
and all three types represent a vector of bits. \code{UInt} gives this vector of
bits the meaning of an unsigned integer and \code{SInt} of a signed
integer.\footnote{The type \codefoot{Bits} in the current version of Chisel is missing operations and
therefore not very useful for user code.}
Chisel uses \myref{https://en.wikipedia.org/wiki/Two\%27s\_complement}{two's complement}
as signed integer representation.
Here is the definition for different types, an 8-bit \code{Bits}, an 8-bit unsigned integer, and a 10-bit
signed integer:

Chisel提供了三种数据类型用来描述型号，组合逻辑，和寄存器：\code{Bits}， \code{UInt}，和\code{SInt}。
\code{UInt}和code{SInt}是\code{Bits}的拓展，并且所有的三种类型代表bits的矢量。
\code{UInt}表示这个bits的矢量是一个无符号的整型，\code{SInt}表示一个有符号的整型。
\footnote{\codefoot{Bits}类型在本Chisel版本是遗失的操作，并且不是特别在使用者的代码中有用.}
Chisel使用\myref{https://en.wikipedia.org/wiki/Two\%27s\_complement}{two's complement}表示有符号数的整型。
以下是不同类型的定义，8位\code{Bits}，8位无符号整型，和一个10位有符号整型：


\shortlist{code/types.txt}

\noindent The width of a vector of bits is defined by a Chisel width type (\code{Width}).
The following expression casts the Scala integer \code{n} to a Chisel \code{width},
which is used for the definition of the \code{Bits} vector:

Bits的矢量宽度被Chisel的width类型(\code{Width})定义。以下表示把scala的整型\code{n}转换成Chisel的\code{width}，用于\code{Bits}矢量的定义。

\shortlist{code/n_w.txt}

\noindent Constants can be defined by using a Scala integer and converting it to a Chisel type:

常量可以通过Scala整型定义并把它转换成Chisel类型。定义一个为0的UInt常量，和定义一个为03的SInt常量。

\shortlist{code/constants.txt}

\noindent Constants can also be defined with a width, by using the Chisel width type:

常量也可以随着宽度被定义，使用Chisel的width类型。 定义一个4位的常量8。

\shortlist{code/const_width.txt}

\noindent If you find the notion of 8.U and 4.W a little bit funny, consider it as a variant of an integer
constant with a type. This notation is similar to 8L, representing a long integer constant in C, Java, and Scala.

当你发现8.U和4.W的表示方式有些有趣，你可以认为它是一个整型常量附带一个类型。这个表示方式类似于8L，代表一个C，Java或Scala中的长整型。

Chisel benefits from Scala's type inference and in many places type information can be left out.
The same is also valid for bit widths. In many cases, Chisel will automatically infer the correct width.
Therefore, a Chisel description of hardware is more concise and better readable than VHDL or
Verilog.

Chisel受益于Scala的类型推断，并且很多地方类型信息可以被省略。类似的也适用于位宽。
在很多时候，Chisel会自动推断正确的宽度。于是，chisel描述的硬件语言比VHDL或Verilog更加简洁和可读。

For constants defined in other bases than decimal, the constant is defined in a string with
a preceding \code{h} for hexadecimal (base 16), \code{o} for octal (base 8), and \code{b}
for binary (base 2). The following example shows the definition of constant 255 in different
bases. In this example we omit the bit width and Chisel infers the minimum width to fit
the constants in, in this case 8 bits.

对于以其它作为基底的十进制以外的常量，常量被定义为字符串，开头\code{h}是16进制，\code{o}是8进制，\code{b}是2进制。
以下的例子表明了常量255的定义，在不同的基底。在这个例子，我们省略了位宽，chisel推断了最小宽度用来表示常量，在这个例子是8位。（16进制表示255， 8进制表示255， 二进制表示255）


\shortlist{code/const_base.txt}

\noindent The above code shows how to use an underscore to group digits in the
string that represents a constant. The underscore is ignored.

以上代码也表示了如何使用下划线去群组数字来标识常量。下划线是被忽略的。

To represent logic values, Chisel defines the type \code{Bool}.
\code{Bool} can represent a \emph{true} or \emph{false} value.
The following code shows the definition of type \code{Bool} and the definition of
\code{Bool} constants, by converting the Scala Boolean constants \code{true}
and \code{false} to Chisel \code{Bool} constants.

为了表示逻辑值，Chisel定义了\code{Bool}类型。Bool可以表示\emph{true}或\emph{false}值。
以下的代码表示了\code{Bool}类型的定义以及\code{Bool}常量的定义，通过转换Scala Boolean常量\code{true}和\code{false}， 到Chisel的\code{Bool}类型。


\shortlist{code/bool.txt}


\section{Combinational Circuits}

Chisel uses \myref{https://en.wikipedia.org/wiki/Boolean_algebra}{Boolean algebra} operators,
as they are defined in C, Java, Scala, and several other programming languages,
to described combinational circuits: \code{\&} is the AND operator and \code{|} is
the OR operator.
Following line of code defines a circuit that combines signals \code{a} and \code{b} with \emph{and}
gates and combines the result with signal \code{c} with \emph{or} gates.

Chisel使用\myref{https://en.wikipedia.org/wiki/Boolean_algebra}{Boolean algebra}操作符，
和C，Java，Scala和可能很多其它编程语言中定义的一样，去描述组合电路。
以下代码定义了一个对\code{a}和\code{b}进行\emph{and}逻辑，然后把它的结果和\code{c}进行\emph{or}逻辑的电路：


\shortlist{code/logic.txt}

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/logic}
  \caption{Logic for the expression \code{(a \& b) | c}.
  The wires can be a single bit or multiple bits. The Chisel expression, and the schematics are the same.}
  \label{fig:logic}
\end{figure}


Figure~\ref{fig:logic} shows the schematic of this combinatorial expression.
Note that this circuit may be for a vector of bits and not only single wires
that are combined with the AND and OR circuits.

Figure~\ref{fig:logic} 表明了这个组合逻辑的表达的草图。
注意到这个电路可能用来表示一个向量的bits，并不仅是单独的AND和OR组成的线路。

In this example, we do not define the type nor the width of signal \code{logic}.
Both are inferred from the type and width of the expression.
The standard logic operations in Chisel are:

在这个例子，我们不定义类型或是信号\code{logic}的宽度。两个都是从类型和表达式位宽推演过来的.
标准Chisel的逻辑操作是：


\shortlist{code/bool_ops.txt}

1. 按位与
2. 按位或
3. 按位异或
4. 按位取反（译者：这个和！有区别的，注意）

\noindent The arithmetic operations use the standard operators:

\noindent 算术操作使用标准操作符

\shortlist{code/arith_ops.txt}

算术操作使用标准操作符1. 加法 2. 减法 3. 相反数 4. 乘法 5. 除法 6. 余数：

\noindent The resulting width of the operation is the maximum width of the operators for
addition and subtraction, the sum of the two widths for the multiplication, and usually
the width of the numerator for divide and modulo operations.\footnote{The exact
details are available in the \myref{https://github.com/freechipsproject/firrtl/blob/master/spec/spec.pdf}{FIRRTL specification}.}

加法和减法操作结果的宽度是操作数的最大宽度，乘法操作结果的库纳杜是两个操作数的位宽加和, 除法和余数操作的结果是被除数的位宽。
\footnote{ \myref{https://github.com/freechipsproject/firrtl/blob/master/spec/spec.pdf}{FIRRTL specification}.}

A signal can also first be defined as a \code{Wire} of some type. Afterward, we can assign a
value to the wire with the \code{:=} update operator.

一个信号也可以先被定义为某种类型的\code{Wire}。随后，我们可以给这个wire赋一个值，使用\code{:=}。

\shortlist{code/wire.txt}

A single bit can be extracted as follows:

一个简单的bit可以被如下提取：

\shortlist{code/single_bit.txt}

\noindent A subfield can be extracted from end to start position:

\noindent 一个分割可以从终点到起点提取：

\shortlist{code/sub_field.txt}

\noindent Bit fields are concatenated with \code{Cat}.

\noindent bit域通过\code{Cat}合并.

\shortlist{code/concat.txt}

Table~\ref{tab:operators} shows the full list of operators
(see also \myref{https://github.com/freechipsproject/chisel3/wiki/Builtin-Operators}{builtin operators}).
The Chisel operator precedence is determined by the evaluation order of the circuit,
which follows the \myref{https://docs.scala-lang.org/tour/operators.html}{Scala operator precedence}.
If in doubt, it is always a good praxis to use parentheses.\footnote{The operator precedence in
Chisel is a side effect of the hardware elaboration when the tree of hardware nodes
is created by executing the Scala operators. The Scala operator precedence is similar but
not identical to Java/C. Verilog has the same operator precedence as C, but VHDL
has a different one. Verilog has precedence ordering for logic operations, but in VHDL
those operators have the same precedence and are evaluated from left to right.}

Table~\ref{tab:operators}表示了操作符号的全列表
(查看\myref{https://github.com/freechipsproject/chisel3/wiki/Builtin-Operators}{builtin operators})。
Chisel操作符优先级取决于电路的赋值顺序，遵守\myref{https://docs.scala-lang.org/tour/operators.html}{Scala operator precedence}。
如果有疑问的话，使用括号是一个好的习惯。\footnote{在chisel里操作符号的优先级是硬件优化的副产品，因为硬件节点数
是通过执行scala操作符创建的。Scala操作符的先后顺序与Java/C类似但是不等同。Verilog和C有着同样的操作符优先级，但是VHDL与之不同。
Verilog有逻辑上的操作符优先级，但是VHDL里，这些操作符的优先级是等同的，按照从左到右的顺序}


Table~\ref{tab:functions} shows various functions defined on and for Chisel data types.
表格~\ref{tab:functions} 表明了不同函数在根据chisel类型做的定义。

\begin{table}
 \centering
 \label{tab:operators}
  \begin{tabular}{lll}
    \toprule
    Operator & Description & Data types \\
    \midrule
    \code{* / \%} & multiplication, division, modulus & UInt, SInt \\
    \code{+ -} & addition, subtraction & UInt, SInt \\
    \code{=== =/=} & equal, not equal & UInt, SInt, returns Bool \\
    \code{> >= < <=} & comparison & UInt, SInt, returns Bool \\
    \code{<< >>} & shift left, shift right (sign extend on SInt) & UInt, SInt \\
    \code{\~} & NOT & UInt, SInt, Bool \\
    \code{\& | \^} & AND, OR, XOR & UInt, SInt, Bool \\
    \code{!} & logical NOT & Bool \\
    \code{\&\& ||} & logical AND, OR & Bool \\
    \bottomrule 
  \end{tabular} 
  \caption{Chisel defined hardware operators.}
\end{table}

\begin{table}
 \centering
 \label{tab:functions}
  \begin{tabular}{lll}
    \toprule
    Function & Description & Data types \\
    \midrule
    \code{v.andR v.orR v.xorR} & AND, OR, XOR reduction & UInt, SInt, returns Bool \\
    \code{v(n)} & extraction of a single bit & UInt, SInt \\
    \code{v(end, start)} & bitfield extraction & UInt, SInt \\
    \code{Fill(n, v)} & bitstring replication, n times & UInt, SInt \\
    \code{Cat(a, b, ...)} & bit field concatenation & UInt, SInt \\
    \bottomrule 
  \end{tabular} 
  \caption{Chisel defined hardware functions, invoked on \code{v}.}
\end{table}                                            
    

\subsection{Multiplexer}

A \myref{https://en.wikipedia.org/wiki/Multiplexer}{multiplexer} is a circuit that selects between alternatives.
In the most basic form, it selects between two alternatives. Figure~\ref{fig:mux} shows
such a 2:1 multiplexer, or mux for short. Depending on the value of the
select signal (\code{sel}) signal \code{y} will represent signal \code{a} or
signal \code{b}.

\myref{https://en.wikipedia.org/wiki/Multiplexer}{复用器}是一个选择选项的电路。
在最基本的形式，它在二者选择其一。图2.2~\ref{fig:mux}表示一个二选一复用器，或是用mux简单表示。
取决于选择信号(\code{sel})，\code{y}会表示信号\code{a}或是信号\code{b}。


\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/mux}
  \caption{A basic 2:1 multiplexer.}
  \label{fig:mux}
\end{figure}

A multiplexer can be built from logic.
However, as multiplexing  is such a standard operation, Chisel provides a multiplexer,

一个复用器可以通过逻辑简单搭建。但是，复用是一个常用操作，Chisel提供了一个复用器。

\shortlist{code/mux.txt}

\noindent where \code{a} is selected when the \code{sel} is \code{true.B}, otherwise \code{b}
is selected. The type of \code{sel} is a Chisel \code{Bool}; the inputs \code{a} and \code{b}
can be any Chisel base type or aggregate (bundles or vectors) as long as they are the same
type.

这里如果\code{sel}是\code{true.B}的话，选择\code{a}，反之选择\code{b}。
\code{sel}的类型是Chisel\code{Bool}， \code{a}和\code{b}作为输入可以是任何Chisel基本类型或是集合（捆束或是矢量），
只要它们的类型相同。

With logical and arithmetical operations and a multiplexer, every combinational
circuit can be described. However, Chisel provides further components and control abstractions
for a more elegant description of a combinational circuit, which are described in
a later chapter.

通过逻辑和算术操作，一个复用器，每个组合电路都能被描述。
但是，Chisel提供了更多部分和控制的抽象用来更优雅地描述组合电路，这些在稍后章节讲。


The second basic component needed to describe a digital circuit is a state element,
also called register, which is described next.

第二个需要描述一个数字电路的基本组成部分是一个状态单元，又称寄存器，下边讲。

\section{Registers}

Chisel provides a register, which is a collection of
\myref{https://en.wikipedia.org/wiki/Flip-flop\_(electronics)\#D\_flip-flop}{D flip-flops}.
The register is implicitly connected to a global clock and is updated on the rising edge.
When an initialization value is provided at the declaration of the register,
it uses a synchronous reset connected to a global reset signal.

Chisel提供了一个寄存器，这是一个\myref{https://en.wikipedia.org/wiki/Flip-flop\_(electronics)\#D\_flip-flop}{D flip-flops}的集合。这个寄存器隐含连接到一个总时钟，并且上升触发。当一个初始值随着在寄存器声明的时候被提供，它使用的是一个同步复位，连接到总复位信号。

A register can be any Chisel type that can be represented as a collection of bits.
Following code defines an 8-bit register, initialized with 0 at reset:

一个寄存器可以是任何bits集合的Chisel类型。下边的代码定义了一个八位寄存器，在复位初始化为0。


\shortlist{code/register.txt}

\noindent An input is connected to the register with the \code{:=} update operator and
the output of the register can be used just with the name in an expression:

一个输入连接到寄存器，通过\code{:=}更新操作数，输出的寄存器可以使用表达式通过名字调用。

\shortlist{code/reg_con.txt}

\noindent A register can also be connected to its input at the definition:

寄存器也可以连接到它的输入使用如下定义: 

\shortlist{code/reg_next.txt}

\noindent A register can also be connected to its input and a constant as
initial value at the definition:

也可以连接到它的输入并使用一个常量作为初始值作为定义:

\shortlist{code/reg_both.txt}

\noindent To distinguish between signals representing combinational logic and registers,
a common practice is to postfix register names with \code{Reg}.
Another common practice, coming from Java and Scala, is to use
\myref{https://en.wikipedia.org/wiki/Camel_case}{camelCase} for
identifier consisting of several words. The convention is to start
functions and variables with a lower case and classes (types) with
an upper case.

为了区分表示组合逻辑和寄存器的信号，一个常见的方式是在寄存器前边加上前缀\code{Reg}。
另一个常见的方式，来自Java和Scala，是去使用\myref{https://en.wikipedia.org/wiki/Camel_case}，由几个单词组成的标识。
这个方式是函数和变量用首字母小写，类用首字母大写。


\subsection{Counting}

Counting is a fundamental operation in digital systems. On might count events.
However, more often counting is used to define a time interval. Counting the
clock cycles and triggering an action when the time interval has expired.

计数是一个非常基本的操作在数字系统。计数可能时常发生。
但是，经常计数是被使用去定义一个时间间隔。
计数时钟，并引发一个操作，当时间间隔过期的时候。


A simple approach is counting up to a value. However, in computer science,
and digital design, counting starts at 0. Therefore, if we want to count till
10, we count from 0 to 9. The following code shows such a counter that counts
till 9 and wraps around to 0 when reaching 9.

一个简单的方式是计数到一个值。但是，在计算机科学和数字设计，计数从0开始。于是，如果我们想要数到10，我们是从0数到9.以下代码表示一个计数器，数到9，并返回到0当数到9的时候。


\shortlist{code/counter.txt}

\section{Structure with Bundle and Vec}

Chisel provides two constructs to group related signals: (1) a \code{Bundle} to group
signals of different types and (2) a \code{Vec} to represent an indexable collection of signals
of the same type.
\code{Bundle}s and \code{Vec}s can be arbitrarily nested.

Chisel提供两个集成小组相关的信号：(1) 一个是\code{Bundle}， 组织不同类型信号 和 
(2) 一个是 \code{Vec}， 去代表一个可索引的相同类型的信号。
\code{Bundle}s和\code{Vec}s可以任意交织。


A Chisel bundle groups several signals. The entire bundle can be referenced
as a whole, or individual fields can be accessed by their name.
We can define a bundle (collection of signals) by defining a class that
extends \code{Bundle} and list the fields as \code{val}s within the constructor block.

Chisel捆束多个信号。整个bundle可以被整体引用，或是通过他们的名字分别访问。
我们可以定义一个捆束（信号的集合），通过定义一个类型，拓展了\code{Bundle}，
并在域内通过\code{val}列出。


\shortlist{code/bundle.txt}

\noindent To use a bundle, we create it with \code{new} and wrap it into a \code{Wire}.
The fields are accessed with the dot notation:

\noindent 为了使用捆束，我们使用\code{new}，并把它包裹进\code{Wire}。域通过点标识访问。


\shortlist{code/bundle_use.txt}

Dot notation is common in object-oriented languages, where \code{x.y} means
\code{x} is a reference to an object and \code{y} is a field of that object.
As Chisel is object-oriented, we use dot notation to access fields in a bundle.
A bundle is similar to a \code{struct} in C, a \code{record} in VHDL, or a
\code{struct} in SystemVerilog.
A bundle can also be referenced as a whole:

点标识是面向对象语言的常见做法，\code{x.y}意味着\code{x}是一个对象的引用，\code{y}是那个对象的域。
因为Chisel是面向对象的，我们使用点标识去访问捆束的域。
一个捆束类似于C语言的\code{struct}，VHDL的\code{record}，或是SystemVerilog的\code{struct}。
捆束可以整体被引用。

\shortlist{code/bundle_ref.txt}

A Chisel \code{Vec} represents a collection of signals of the same type (a vector).
Each element can be accessed by an index. A Chisel \code{Vec} is similar
to array data structures in other programing languages.\footnote{The name \codefoot{Array}
is already used in Scala.}
A \code{Vec} is created by calling the constructor with two parameters: the
number of elements and the type of the elements. A combinational \code{Vec}
needs to be wrapped into a \code{Wire}

Chisel的\code{Vec}代表一系列相同类型的信号。
每个元素可以通过索引访问。Chisel的\code{Vec}类似于一串数据结构在其它编程语言。\footnote{ \codefoot{Array}
已经在scala中被使用。}
\code{Vec}通过使用两个参数传入构造函数：元素的数量和元素的类型。组合逻辑 \code{Vec}
需要被打包进\code{Wire}。


\noindent Individual elements are accessed with \code{(index)}.
\noindent 单一元素通过\code{(index)}被访问到。

\shortlist{code/vec_access.txt}

A vector wrapped into a \code{Wire} is a multiplexer.
We can also wrap a vector into a register to define an array of registers.
Following example defines a register file for a processor; 32 registers
each 32-bits wide, as for a classic 32-bit 
\myref{https://en.wikipedia.org/wiki/Reduced_instruction_set_computer}{RISC}
processor, like the 32-bit version of \myref{https://en.wikipedia.org/wiki/RISC-V}{RISC-V}.

被包裹进\code{Wire}的向量是一个复用器。
我们也可以把向量传入寄存器去定义一列寄存器。
以下例子定义了用于处理器的寄存器文件；32位寄存器，每个寄存器有32位宽，例如经典的32位
\myref{https://en.wikipedia.org/wiki/Reduced_instruction_set_computer}{RISC}处理器，
或是32-bit版本的\myref{https://en.wikipedia.org/wiki/RISC-V}{RISC-V}。

\shortlist{code/reg_file.txt}

\noindent An element of that register file is accessed with an index and used as a normal register.
\noindent 寄存器的一个元素通过索引访问，并用作正常寄存器。

\shortlist{code/reg_file_access.txt}

We can freely mix bundles and vectors. When creating a vector with a bundle
type, we need to pass a prototype for the vector fields. Using our
\code{Channel}, which we defined above, we can create a vector of channels with:

我们可以随意混搭捆束和向量。当创造一个有着捆束类型的向量，我们需要把这个类型传入向量域。
使用我们的\code{Channel}，像我们以上定义的，我们可以创建一个向量的通道通过：

\shortlist{code/vec_bundle.txt}

\noindent A bundle may as well contain a vector:
\noindent 一个捆束可能包含一个向量：

\shortlist{code/bundle_vec.txt}

When we want a register of a bundle type that needs a reset value,
we first create a \code{Wire} of that bundle, set the individual fields
as needed, and then passing this bundle to a \code{RegInit}:

当我们想要一个需要reset值的寄存器的类型，我们首先创造一个具有那个捆束的\code{Wire}，设置单独的域，
然后把捆束传给\code{RegInit}。

\shortlist{code/bundle_reg_init.txt}

With combinations of \code{Bundle}s and \code{Vec}s we can define our own data
structures, which are powerful abstractions.
通过\code{Bundle}和\code{Vec}的组合，我们可以定义我们自己的数据结构，这个是有力的抽象。

\section{Chisel Generates Hardware}

After seeing some initial Chisel code, it might look similar to classic programming
languages such as Java or C. However, Chisel (or any other hardware description
language) does define hardware components. While in a software program one
line of code after the other is executed, in hardware all lines of code
\emph{execute in parallel}.

在看到一些Chisel代码，可能看起来和经典编程语言像是Java或C比较相似。但是，Chisel（或是其它硬件描述语言）
描述了硬件部分。而在软件项目中，一行代码在前一行过后执行，而硬件执行全部\emph{execute in parallel}。

It is essential to keep in mind that Chisel code does generate hardware.
Try to imagine, or draw on a sheet of paper, the individual blocks that
are generated by your Chisel circuit description.
Each creation of a component adds hardware; each assignment statement
generates gates and/or flip-flops.

必须记住，Chisel代码确实会生成硬件。
尝试想象或画在纸上的单个模块，通过您的Chisel电路描述生成。
每次创建组件都会添加硬件。每个赋值声明产生门和/或触发器。

More technically, when Chisel executes your code it runs as a Scala program, and
by executing the Chisel statements, it \emph{collects} the hardware components
and connects those nodes. This network of hardware nodes is the hardware,
which can spill out Verilog code for ASIC or FPGA synthesis or can be
tested with a Chisel tester.
The network of hardware nodes is what is executed in fully parallel.


从技术上讲，Chisel执行代码时，它将作为Scala程序运行，并且
通过执行Chisel语句，它\emph{collects}硬件组件
并连接这些节点。硬件节点网络就是硬件，
可能会溢出用于ASIC或FPGA综合的Verilog代码，或者
用Chisel测试仪测试。
硬件节点网络是完全并行执行的。

For a software engineer imagine this immense parallelism that you can
create in hardware without needing to partition your application into threads
and getting the locking correct for the communication.


对于软件工程师，可以想象一下，您可以
在硬件中创建，而无需将应用程序划分为线程
并正确锁定通信。

\section{Exercise}

In the introduction you implemented a blinking LED on an FPGA board
(from \myref{https://github.com/schoeberl/chisel-examples}{chisel-examples}), which is a reasonable
hardware \emph{Hello World} example. It used only internal state, a single LED output, and no input.
Copy that project into a new folder and extend it by adding some inputs to the \code{io} \code{Bundle}
with \code{val sw = Input(UInt(2.W))}.

在导论中，你补充了一个闪烁的LED在一个FPGA板上（来自chisel-example），这个是一个类似硬件Hello world的例子。它只是使用内部的状态，一个LED输出，没有输入。把那个项目复制到一个新的文件夹，并使用val sw = Input(UInt(2.W))添加一些输入到io捆束。


\shortlist{code/basic_exercise.txt}

\noindent For those switches, you also need to assign and list the fields as pin names for the FPGA board.
You can find examples of pin assignments in the Quartus project files of the ALU project
(e.g., for the \myref{https://github.com/schoeberl/chisel-examples/blob/master/quartus/altde2-115/alu.qsf}{DE2-115
FPGA board}).

对于这些开关，你也可以给FPGA板上的PIN分配名字。你可以找到管脚命名的例子在Quartus项目文件中的ALU项目（例如，DE2-115 FPGA 板子）
(e.g., for the \myref{https://github.com/schoeberl/chisel-examples/blob/master/quartus/altde2-115/alu.qsf}{DE2-115
FPGA board})。

When you have defined those inputs and the pin assignment, start with a simple test:
drop all blinking logic from the design and connect one switch to the LED output;
compile and configure the FPGA device. Can you switch the LED on an off with the switch?
If yes, you have now inputs available. If not, you need to debug your FPGA configuration.
The pin assignment can also be done with the GUI version of the tool.

当你已经定义了这些输入和管脚分配，开始一个简单的测试：关掉设计中所有闪烁逻辑，连接其中一个到LED输出；编译并设置FPGA期间。你可以通过开关把LED打开并关闭吗？如果是对的，你就有了可用的输入。如果没有，你需要给你的FPGA设置debug。这个也可以通过GUI版本的工具完成。


Now use two switches and implement one of the basic combinational functions,
e.g., AND two switches and show the result on the LED. Change the function.
The next step involves three input switches to implement a multiplexer: one acts as
a select signal, and the other two are the two inputs for the 2:1 multiplexer.

现在使用两个开关并完成一个基本的组合电路函数，例如，二输入与门并在LED显示结果。改变函数。下一步包括三输入开关来完成一个复用器，一个充当选择信号，另外两个充当双输入复用器的输入。


Now you have been able to implement simple combinational functions and test them
in real hardware in an FPGA. As a next step, we will take a first look at how the build
process works to generate an FPGA configuration. Furthermore, we will also
explore a simple testing framework from Chisel, which allows you to test circuits
without configuring an FPGA and toggle switches.

现在你已经可以补充简单的组合函数并在一个实际的FPGA进行简单的测试。作为下一步，我们会看一下搭建过程如何生成FPGA设置。更多地，我们也会探索一个简单的Chisel测试框架，这允许你不去设置FPGA和开关来测试电路。


\chapter{Build Process and Testing}

To get started with more interesting Chisel code we first need to learn how to compile
Chisel programs, how to generate Verilog code for execution in an FPGA, and how
to write tests for debugging and to verify that our circuits are correct.

为了开始更有趣的Chisel代码，我们第一需要学习如何编译Chisel程序，如何生成Verilog代码用来在FPGA执行，和如何写测试用于debug和验证我们的电路是正确的。


Chisel is written in Scala, so any build process that supports Scala is possible
with a Chisel project. One popular build tool for Scala is \myref{https://www.scala-sbt.org/}{sbt},
which stands for the Scala interactive build tool.
Besides driving the build and test process, \code{sbt} also downloads the correct
version of Scala and the Chisel libraries.

Chisel是用Scala写的，所以任何的支持Scala的搭建过程适用于Chisel项目。
一个受欢迎的Scala搭建工具是\myref{https://www.scala-sbt.org/}{sbt}，sbt是Scala interactive Build Tool的简写。
除了驱动搭建和测试过程，\code{sbt}也下载正确的Scala版本和Chisel 库。


\section{Building your Project with sbt}

The Scala library that represents Chisel and the Chisel testers are automatically
downloaded during the build process from a Maven repository.
The libraries are referenced by \code{build.sbt}. It is possible to configure \code{build.sbt}
with \code{latest.release} to always use the most actual version of Chisel.
However, this means on each build the version is looked up from the Maven
repository. This lookup needs an Internet connection for the build to succeed.
Better use a dedicated version of Chisel and all other Scala libraries in your \code{build.sbt}.
Maybe sometimes it is also good to be able to write hardware code and test it without an Internet connection.
For example, it is cool to do hardware design on a plane.

Scala 库中表示Chisel和Chisel测试器的部分，是通过搭建过程从一个Maven仓库中下载的。
库文件通过build.sbt被引用。
它可以通过build.sbt设置，使用\code{latest.release}总是用最新的Chisel版本。
但是，这意味这每次搭建都要查看Maven仓库。
查看需要互联网连接，为了搭建成功。
最好使用一个特定的Chisel版本，所有其它的Scala库在你的\code{build.sbt}。
可能有的时候你能够手写硬件代码并且在无网络连接的情况下测试是值得提倡的。
例如，帅气地在飞机上进行硬件设计。


\subsection{Source Organization}

\code{sbt} inherits the source convention from the \myref{https://maven.apache.org/}{Maven}
build automation tool. Maven also organizes repositories of open-source Java libraries.\footnote{That is
also the place where you downloaded the Chisel library on your first build:
\url{https://mvnrepository.com/artifact/edu.berkeley.cs/chisel3}.}

sbt继承来自于\myref{https://maven.apache.org/}{Maven}自动化搭建工具的源文件法则。
Maven也管理者开源Java函数库的仓库。\footnote{:
\url{https://mvnrepository.com/artifact/edu.berkeley.cs/chisel3}.}

\begin{figure}
\dirtree{%
.1 project.
.2 src.
.3 main.
.4 scala.
.5 package.
.6 sub-package.
.3 test.
.4 scala.
.5 package.
.2 target.
.2 generated.
}
\caption{Source tree of a Chisel project (using \code{sbt})}
\label{fig:folders}
\end{figure}

Figure~\ref{fig:folders} shows the organization of the source tree of a typical Chisel project.
The root of the project is the project home, which contains \code{build.sbt}.
It may also include a \code{Makefile} for the build process, a README, and a LICENSE file.
Folder \code{src} contains all source code. From there it is split between \code{main},
containing the hardware sources and \code{test} containing testers.
Chisel inherits from Scala, which inherits from Java the organization of source
in \myref{https://en.wikipedia.org/wiki/Java_package}{packages}.
Packages organize your Chisel code into namespaces. Packages can also contain
sub-packages.
The folder \code{target} contains the class files and other generated files.
I recommend to also use a folder for generated Verilog files, which is usually
call \code{generated}.

Figure~\ref{fig:folders}表示了一个常见的Chisel项目的源文件树的结构。
项目的根目录是项目home地址，这里包含了build.sbt。
也可以包含一个Makefile用于搭建过程，一个README，和一个LICENSE文件。
文件夹sec包含了所有源代码。
在这里，main包含硬件源代码和test包含测试器，有一个分叉。
Chisel继承自Scala，Scala继承自Java的源文件软件包的结构。
软件包把你的Chisel代码组织成命名空间。软件包也可以包括下属软件包。
文件夹target包括类文件和其它产生的文件。
我也推荐用一个文件放置生成的Verilog文件，这个文件夹一般称为generated。


To use the facility of namespaces in Chisel, you need to declare that a class/module
is defined in a package, in this example in \code{mypacket}:

为了使用Chisel命名空间的工具，你需要声明类或模块在软件包被定义，在这个例子里，在mypack:

\shortlist{code/packet.txt}

\noindent Note that in this example we see the import of the \code{chisel3} packet
to use Chisel classes.

注意在这个例子我们看到引入chisel3软件包，和使用chisel类型。

To use the module \code{Abc} in a different context (packet name space),
the components of packet \code{mypacket} need to be imported. The underscore
(\_) acts as wildcard, meaning that all classes of \code{mypacket} are imported.

为了使用Abc模块在一个不同的地方（软件包命名空间），软件包的mypack需要被引用。下划线（_）充当万用字元，意味着所有mypack的类都要被引用。


\shortlist{code/usepacket.txt}

\noindent It is also possible to not import all types from \code{mypacket},
but use the fully qualified name \code{mypack.Abc} to refer to the module
\code{Abc} in packet \code{mypack}.

也可以不去引用来自mypack的所有类别，而是使用全名mypack.Abc代表mypack中的模块Abc

\shortlist{code/usepacket2.txt}

\noindent It is also possible to import just a single class and create an instance of it:

也可以引用一个单个的类并去创建它。

\shortlist{code/usepacket3.txt}


\subsection{Running sbt}

A Chisel project can be compiled and executed with a simple \code{sbt} command:

一个Chisel项目可以被编译并执行通过一个简单的sbt命令：

\begin{verbatim}
$ sbt run
\end{verbatim}

This command will compile all your Chisel code from the source tree and searches
for classes that contain an \code{object} that includes a \code{main} method, or simpler
that extends \code{App}. If there is more than one such object, all objects are listed and
one can be selected.
You can also directly specify the object that shall be executed as a parameter to \code{sbt}:

这个命令会编译你所有的源文件树下的Chisel代码并搜索含有object和含有main方法的类别，或是简化的App。
如果由多余一个类似的对象，所有的对象都会被列出以及可选。
你也可以直接执行被传入sbt作为参数的对象：


\begin{verbatim}
$ sbt "runMain mypacket.MyObject"
\end{verbatim}

Per default \code{sbt} searches only the \code{main} part of the source tree and not
the \code{test} part.\footnote{This is a convention form Java/Scala that the test folder contains
unit tests and not objects with a \codefoot{main}.} However, Chisel testers, as described here,
contain a \code{main}, but shall be placed in the \code{test} part of the source tree.
To execute a \code{main} in the tester tree use following \code{sbt} command:

根据默认sbt只是搜索main部分的源文件树而不是测试部分。
但是，Chisel测试器，在这里描述的，含有一个main，但是应该放在源文件树的test部分。
为了执行测试树的main，使用如下sbt命令：

\begin{verbatim}
$ sbt "test:runMain mypacket.MyTester"
\end{verbatim}

Now that we know the basic structure of a Chisel project and how to compile and run it
with \code{sbt}, we can continue with a simple testing framework.

现在我们知道了Chisel项目的基本构成和如何使用sbt编译运行，我们可以继续开始一个简单的测试框架了。
    
\section{Testing with Chisel}

Tests of hardware designs are usually called \myref{https://www.xilinx.com/support/documentation/sw_manuals/xilinx10/isehelp/ise_c_simulation_test_bench.htm}{test benches}.
The test bench instantiates the design under test (DUT), drives input ports, observes output ports,
and compares them with expected values.

测试硬件设计一般称为testbench。
这些testbench初始化被测试的设计（DUT），驱动输入端口，观察输出端口，与它们和期待值比较。

Chisel provides test benches in the form of a \code{PeekPokeTester}.
One strength of Chisel is that it can use the full power of Scala to write those
test benches. One can, for example, code the expected functionality of the hardware
in a software simulator and compare the simulation of the hardware with the
software simulation. This method is very efficient when testing an implementation
of a processor~\cite{lipsi:arcs2018}.

Chisel提供的testbench叫PeekPokeTester。
其中Chisel的一个优势是它能够全力使用Scala写入这些testbench。
一个人，比方说，可以在软件模拟器编写期望的硬件功能，并把硬件仿真和软件仿真进行比较。
这个方法是非常有效的，当测试写好的处理器的时候。

To use the \code{PeekPokeTester}, following packages need to be imported:

使用PeekPokeTester，以下软件包需要引入：

\shortlist{code/test_import.txt}

\noindent Testing a circuit contains (at least) three components: (1) the device under test (often
called DUT), (2) the testing logic, also called test bench, and (3) the tester objects
that contains the \code{main} function to start the testing.

测试电路需要（至少）三个部分：1. 接受测试的器件（经常称为DUT）2. 测试逻辑，也称testbench 3. 包含main函数的测试对象用来开始测试。

The following code shows our simple design under test. It contains two input
ports and one output port, all with a 2-bit width. The circuit does a bit-wise AND
to it returns on the output:

以下代码表明了我们简单的接受测试的设计。它包含输入端口和一个输出端口，全是2位宽的。这个电路执行按位AND并返回给输出：

\shortlist{code/test_dut.txt}

\noindent The test bench for this DUT extends \code{PeekPokeTester} and has
the DUT as a parameter for the constructor:

该DUT的testbench拓展了\code{PeekPokeTester}，并把DUT作为建造器的参数：

\shortlist{code/test_bench_simple.txt}

\noindent A \code{PeekPokeTester} can set input values with \code{poke()} and
read back output values with \code{peek()}. The tester advances the simulation by one
step (= one clock cycle) with \code{step(1)}.
We can print the values of the outputs with \code{println()}.

\noindent \code{PeekPokeTester} 可以使用\code{poke()}设置初始值，并通过\code{peek()}读出数值。
测试器通过进一步的\code{step(1)}声明，增加一个周期过后的数值。
我们可以使用\code{println()}打印输出。

The test is created and run with the following tester main:
测试建立，并通过以下运行：

\shortlist{code/test_main_simple.txt}

\noindent When you run the test, you will see the results printed to the terminal
(besides other information):
\noindent 当你运行测试，你会看见除了其它信息以外，打印到端口的结果。

\begin{verbatim}
[info] [0.004] SEED 1544207645120
[info] [0.008] Result is: 0
[info] [0.009] Result is: 2
test DeviceUnderTest Success: 0 tests passed in 7 cycles
taking 0.021820 seconds
[info] [0.010] RAN 2 CYCLES PASSED
\end{verbatim}

\noindent We see that 0 AND 1 results in 0; 3 AND 2 results in 2.
Besides manually inspecting printouts, which is an excellent starting point, we can also
express our expectations in the test bench itself with \code{expect()},
having the output port and the expected value as parameters.
The following example shows testing with \code{expect()}:

\noindent 我们看到0和1的与是0；3和2的与是2。
除此之外手动查看结果，这个是一个极好的开始点，我们也可以在测试台上使用\code{expect()}，
用来表示我们的期待值，放在输出端口，并传入期待值。
以下的例子是使用\code{expect()}作为测试的例子。

\shortlist{code/test_bench.txt}

\noindent Executing this test does not print out any values from the hardware,
but that all tests passed as all expect values are correct.

\noindent 执行测试不打印出任何硬件的值，
但是所有通过期待值的测试代表正确。

\begin{verbatim}
[info] [0.001] SEED 1544208437832
test DeviceUnderTest Success: 2 tests passed in 7 cycles
taking 0.018000 seconds
[info] [0.009] RAN 2 CYCLES PASSED
\end{verbatim}

\noindent A failed test, when either the DUT or the test bench contains an error,
produces an error message describing the difference between the expected and actual
value. In the following, we changed the test bench to expect a 4, which is an error:

\noindent 一个失败的测试，当DUT或是测试台包含了一个错误，
产生了一个错误消息，描述了期待值和实际值的差异。在以下，我们把测试台的期待值为4，产生了一个错误：

\begin{verbatim}
[info] [0.002] SEED 1544208642263
[info] [0.011] EXPECT AT 2   io_out got 0 expected 4 FAIL
test DeviceUnderTest Success: 1 tests passed in 7 cycles
taking 0.022101 seconds
[info] [0.012] RAN 2 CYCLES FAILED FIRST AT CYCLE 2
\end{verbatim}

In this section, we described the basic testing facility with Chisel for simple tests.
However, in Chisel, the full power of Scala is available to write testers.
\todo{Have a link to the not yet written section for: We will show these possibilities later.}

在本节中，我们描述了Chisel用于简单测试的基本测试工具。
但是，在Chisel中，Scala的全部功能可用于编写测试人员。

\myref{http://www.scalatest.org/}{ScalaTest} is a testing tool for Scala (and Java),
which we can use to run Chisel testers.
To use it, include the library in your \code{build.sbt} with the following line:

\myref{http://www.scalatest.org/}{ScalaTest} 是一个Scala(和Java)的测试工具，
我们可以用来运行Chisel测试。
为了使用它，把下边这段放在\code{build.sbt}里边：

\begin{verbatim}
libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.5" % "test"
\end{verbatim}

\noindent 测试通常在\code{src/test/scala}被找到，使用以下：

\begin{verbatim}
$ sbt test
\end{verbatim}

\noindent A minimal test (a testing hello world) to test a Scala Integer
addition:

\noindent 一个最小测试（测试hello world）来测试Scala整型

\shortlist{code/scalatest_hello_world.txt}

\noindent Although Chisel testing is more heavyweight than unit testing of Scala programs,
we can wrap a Chisel test into a ScalaTest class. For the \code{Tester} shown
before this is:

\noindent尽管Chisel测试比Scala程序的单元测试更重要，我们可以将Chisel测试包装到ScalaTest类中。对于显示的Tester
在此之前：

\shortlist{code/scalatest_simple.txt}

The main benefit of this exercise is to be able to run all tests with a simple
\code{sbt test} (instead of a running \code{main}). You can run just a single
test with \code{sbt}, as follows:

这个练习的主要好处是可以通过\code{sbt test}运行所有的测试（而不是\code{main}）。你可以只是使用一个简单的\code{sbt}进行测试，
像是如下

\begin{verbatim}
$ sbt "testOnly SimpleSpec"
\end{verbatim}

\section{Exercises}

For this exercise, we will revisit the blinking LED from
\myref{https://github.com/schoeberl/chisel-examples}{chisel-examples}
and explore Chisel testing. \todo{Also use the ALU example.}

对于这个测试，我们需要重温一下闪烁LED从\myref{https://github.com/schoeberl/chisel-examples}{chisel-examples}
并探索Chisel测试。

\subsection{A Minimal Project}

First, let us find out what a minimal Chisel project is. Explore the files in the
\myref{https://github.com/schoeberl/chisel-examples/tree/master/hello-world}{Hello World}
example.
The \code{Hello.scala} is the single hardware source file.
It contains the hardware description of the blinking LED (\code{class Hello})
and an \code{App} that generates the Verilog code.

首先，我们先看一下什么是做小Chisel项目。探索文件\myref{https://github.com/schoeberl/chisel-examples/tree/master/hello-world}{你好世界}。
例子。
这个代码\code{Hello.scala}是一个简单硬件源代码。
它包含了(\code{class Hello})的硬件描述，和一个\code{App}用来生成verilog代码。

Each file starts with the import of Chisel and related packages:

每个文件以引用chisel和相关包裹开始：

\shortlist{code/import.txt}

\noindent Then follows the hardware description, as shown in Listing~\ref{lst:chisel:hello}.
To generate the Verilog description, we need an application. A Scala object that \code{extends App}
is an application that implicitly generates the main function where the application starts.
The only action of this application is to create a new \code{HelloWorld} object and pass it
to the Chisel driver \code{execute} function. The first argument is an array of Strings,
where build options can be set (e.g., the output folder). The following code will
generate the Verilog file \code{Hello.v}.

\noindent 以下硬件描述，像是~\ref{lst:chisel:hello}出现的。
为了生成一个Verilog描述，我们需要一个应用。Scala对象\code{extends App}
是一个应用，直接在应用开始的地方隐式生成主函数。
这个的唯一举动是生成一个新的\code{HelloWorld}对象，并把它传入Chisel驱动\code{execute}函数。
这个的第一个参数是一个字符串的数组，





\shortlist{code/generate.txt}

\noindent Run the generation of the example manually with

\noindent 手动运行例子通过

\begin{chisel}
$ sbt "runMain Hello"
\end{chisel}

and explore the generated \code{Hello.v} with an editor. The generated Verilog code may not be
very readable, but we can find out some details. The file starts with a module \code{Hello},
which is the same name as our Chisel module. We can identify our LED port as
\code{output io\_led}. Pin names are the Chisel names with a prepended \code{io\_}.
Besides our LED pin, the module also contains \code{clock} and \code{reset} input signals.
Those two signals are added automatically by Chisel.

并使用编辑器去探索生成的\code{Hello.v}。生成的Verilog代码可能不是很可读，但是我们可以找到一些细节。这个文件以\code{Hello}模块开头，
这个和我们的Chisel模块同名。我们可以检查我们的LED端口为\code{output io\_led}。引脚名字是Chisel的名字前置\code{io\_}。
除了我们的LED引脚，这个模块也包含了\code{clock}和\code{reset}输入信号。
这两个信号被chisel自动添加。

Furthermore, we can identify the definition of our two registers \code{cntReg} and \code{blkReg}.
We may also find the reset and update of those registers at the end of the module definition.
Note, that Chisel generates a synchronous reset.

更多地，我们可以检查我们的两个寄存器\code{cntReg}和\code{blkReg}。我们也可以发现reset和这些寄存器的更新，
在模块定义的后边。注意到，Chisel生成了一个同步复位。

For \code{sbt} to be able to fetch the correct Scala compiler and the Chisel library,
we need a \code{build.sbt}:

为了让\code{sbt} 可以抓取正确的scala编译器和chisel library，我们需要\code{build.sbt}：

\begin{chisel}
scalaVersion := "2.11.7"

resolvers ++= Seq(
  Resolver.sonatypeRepo("snapshots"),
  Resolver.sonatypeRepo("releases")
)

libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "3.1.2"
\end{chisel}

\noindent Note that in this example, we have a concrete Chisel version number to avoid checking on
each run for a new version (which will fail if we are not connected to the Internet,
e.g., when doing hardware design during a flight).
Change the \code{build.sbt} configuration to use the latest Chisel version by changing the
library dependency to

\noindent 注意到在这个例子中，我们有一个具体的Chisel版本数字，防止每次运行的时候检查最新版本（如果不联网的话会失败，
例如，我们在飞机上）。
更改\code{build.sbt}设置去使用最新Chisel版本，通过更改library的依赖

\begin{chisel}
libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "latest.release"
\end{chisel}

\noindent and rerun the build with \code{sbt}. Is there a newer version of Chisel
available and will it be automatically downloaded?

\noindent 并且使用\code{sbt}重新运行build。如何一个最新版本的chisel，并且自动下载呢？

For convenience, the project also contains a \code{Makefile}.
It just contains the \code{sbt} command, so we do not need to remember it and
can generate the Verilog code with:

为了方便，这个项目也包含了一个\code{Makefile}。它包含了\code{sbt}的命令，所以我们不需要记得自动更新的方式，
并且可以自动生成verilog代码：

\begin{chisel}
make
\end{chisel}

%The project also contains a
%\myref{https://github.com/schoeberl/chisel-examples/blob/master/hello-world/verilog/hello_top.v}{Verilog top level},
%which wires the reset signal to 0.
%This works for our example in an FPGA, as registers usually power up 0.
Besides a \code{README} file, the example project also contains project
files for different FPGA board. E.g., in
\myref{https://github.com/schoeberl/chisel-examples/tree/master/hello-world/quartus/altde2-115}{quartus/altde2-115} 
you can find the two project files to define a Quartus project for the DE2-115 board.
The main definitions (source files, device, pin assignments) can be found in a plain text file
\myref{https://github.com/schoeberl/chisel-examples/blob/master/hello-world/quartus/altde2-115/hello.qsf}{hello.qsf}.
Explore the file and find out which pins are connected to which signals.
If you need to adapt the project to a different board, there is where the changes are applied.
If you have Quartus installed, open that project, compile with the green \emph{Play} button,
and then configure the FPGA.

%这个项目也包含了一个
%\myref{https://github.com/schoeberl/chisel-examples/blob/master/hello-world/verilog/hello_top.v}{Verilog顶层},
%它把reset信号置为0.
%这个对于我们的FPGA例子是行得通的，因为寄存器通常是置为零的。
除了\code{README}文件，这个工程的例子也包含了对于不同FPGA的项目文件。
例如，在\myref{https://github.com/schoeberl/chisel-examples/tree/master/hello-world/quartus/altde2-115}{quartus/altde2-115}
你可以发现两个项目文件去定义针对于DE2-115板子的Quartus项目。
主要定义（源文件，器件，针脚定义）可以在
\myref{https://github.com/schoeberl/chisel-examples/blob/master/hello-world/quartus/altde2-115/hello.qsf}{hello.qsf}
发现文本文件。
探索文件并发现哪个针脚连接哪些信号。
如果你需要采用一个不同开发板的项目，这里需要做出一些改变。
如果你安装了Quartus，打开哪个项目，使用\emph{Play}compiler项目，然后在FPGA上进行设置。


Note that the \emph{Hello World} is a minimal Chisel project.
More realistic projects have their source files organized in packages and contain testers.
The next exercise will explore such a project.

注意到\emph{Hello World}是一个最小Chisel项目。
更多实际的项目在源文件上组织成一个包裹，并包含测试器。
下个测试将会探索这样的项目。

\subsection{A Testing Exercise}

In the last chapter's exercise, you have extended the blinking LED example with some input
to build an AND gate and a multiplexer and run this hardware in an FPGA.
We will now use this example and test the functionality with a Chisel tester
to automate testing and also to be independent of an FPGA.
Use your designs from the previous chapter and add a Chisel tester to test the functionality.
Try to enumerate all possible inputs and test the output with \code{except()}.

在上一章的练习中，您通过一些输入扩展了LED闪烁的示例
来构建一个“与”门和一个多路复用器，并在FPGA中运行该硬件。
现在，我们将使用此示例，并使用Chisel测试仪测试功能
自动化测试并独立于FPGA。
使用上一章中的设计并添加Chisel测试器以测试功能。
尝试枚举所有可能的输入，并使用except测试输出。

Testing within Chisel can speed up the debugging of your design.
However, it is always a good idea to synthesize your design for an FPGA and run tests
with the FPGA. There you can perform a reality check on the size of your design (usually
in LUTs and flip-flops) and your performance of your design in maximum clocking frequency.
As a reference point, a textbook style pipelined RISC processor may consume about 3000
4-bit LUTs and may run around 100~MHz in a low-cost FPGA (Intel Cyclone or
Xilinx Spartan).


在Chisel中进行测试可以加快设计的调试速度。
但是，将您的设计综合到FPGA并运行测试始终是一个好主意。
FPGA。在那里，您可以检查设计的大小（通常是
（在LUT和触发器中），以及您在最大时钟频率下的设计性能。
作为参考，教科书式流水RISC处理器可能消耗约3000
4位LUT，可以在低成本FPGA（Intel Cyclone或
Xilinx Spartan）。


\chapter{Components}

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/components}
  \caption{A design consisting of a hierarchy of components.}
  \label{fig:components}
\end{figure}


A larger digital design is structured into a set of components, often in
a hierarchical way. Each component has an interface with input and output
wires, usually called ports. These are similar to input and output pins on an integrated circuit (IC).
Components are connected by wiring up the inputs and outputs.
Components may contain subcomponents to build the hierarchy.
The outermost component, which is connected to physical pins
on a chip, is called the top-level component.

一个大的数字设计是一系列组件部分构建而成的，经常是以层级的方式。
每个组件部分都有一个输入输出的接口，经常被称作端口。
这些和IC中的输入输出引脚类似。组成部分被输入和输出连接。
组件可能含有下属组件用来构建层级。最外层的组件，连接到芯片的物理引脚，称为上层组件。

Figure~\ref{fig:components} shows an example design. Component C has
three input ports and two output ports. The component itself is assembled out
of two subcomponents: B and C, which are connected to the inputs and
outputs of C. One output of A is connected to an input of B.
Component D is at the same hierarchy level as component C and connected
to it.

图4.1表明了一个示例设计。
C组件由两个输入端口和一个输出端口。
组件本身分为两个下属组件：A和B，连接到输入和C的输出。
A的一个输出连接到B的输入。
组件D和组件C有着相同层级，并且互相连接。


In this chapter, we will explain how components are described in Chisel and
provide several examples of standard components.
Those standard components serve two purposes: (1) they provide examples
of Chisel code and (2) they provide a library of components ready to be reused
in your design.

在本章节我们会解释组件在Chisel如何被描述，并提供一些标准组件的例子。
这些标准组件充当两个作用：1.他们提供Chisel代码的例子。
2. 他们提供组件库，为你的设计重新使用。

\section{Components in Chisel are Modules}

Hardware components are called modules in Chisel. Each module extends
the class \code{Module} and contains a field \code{io} for the interface.
The interface is defined by a \code{Bundle} that is wrapped into a call to \code{IO()}.

硬件组件在Chisel里称为module。每个module拓展了\code{Module}类，并包含了一个界面的\code{io}域。
界面通过\code{Bundle}进行定义，被包裹进\code{IO()}。

The \code{Bundle} contains fields to represent input and output ports of
the module. The direction is given by wrapping a field into either a call to \code{Input()}
or \code{Output()}. The direction is from the view of the component itself.

\code{Bundle}包含了域去表示模块的输入和输出端口。方向通过呼叫\code{Input()}或是\code{Output()}来决定方向。
方向是从组成部分本身来说的。

The following code shows the definition of the two example components A and B from
Figure~\ref{fig:components}:

以下代码表明了组成部分A和B从Figure~\ref{fig:components}：

\shortlist{code/components_ab.txt}

\noindent Component A has two inputs, named \code{a} and \code{b}, and two
outputs, named \code{x} and \code{y}. For the ports of component B
we chose the names \code{in1}, \code{in2}, and \code{out}.

\noindent 组成部分有两个输入，命名为\code{a}和\code{b}，和两个输出，命名为\code{x}和\code{y}。
对于组成部分B，我们选取名称\code{in1}，\code{in2}，和\code{out}。

All ports use an unsigned integer (\code{UInt}) with a bit width of 8.
As this example code is about connecting components and building a
hierarchy, we do not show any implementation within the components.
The implementation of the component is written at the place where
the comments states ``function of X''.

所有的端口使用位宽为8的(\code{UInt})非符号整型，作为这个例子的代码，是关于连接组成部分和搭建层级，
我们不编写这个部分的内部。这个部分的编写作为常见形式``X的函数''。

As we have no function associated with those example components,
we used generic port names. For a real design use descriptive
port names, such as \code{data}, \code{valid}, or \code{ready}.

因为我们对于这些例子部分没有函数，我们使用原本端口名称。对于一个真正的设计，我们使用描述性的端口名称，
例如\code{data}，\code{valid}或是\code{ready}。

Component C has three input and two output ports. It is built out of
components A and B. We show how A and B are connected to the ports
of C and also the connection between an output port of A and an
input port of B:

组成部分C有三个输入和两个输出端口。它来自组成部分A和B。我们表明A和B如何连接到C的端口，
以及A作为输出和和B作为输入如何连接。

\shortlist{code/components_c.txt}

Components are created with \code{new}, e.g., \code{new CompA()}, and need to be wrapped
into a call to \code{Module()}. The reference to that module is stored in a local variable,
in this example \code{val compA = Module(new CompA())}.

组成部分使用\code{new}进行创建，例如，\code{new CompA()}，需要被包裹进\code{Module()}。
引用那个模块作为本地变量存入，在这个例子\code{val compA = Module(new CompA())}。

With this reference, we can access the IO ports by dereferencing the \code{io} field of the module
and the individual fields of the IO \code{Bundle}.

有了这个引用，我们可以通过IO，访问模块的\code{io}域和单独IO域下的\code{Bundle}。

The simplest component in our design has just an input port, named \code{in}, and
an output port named \code{out}.

我们设计中最简单的部分只是一个输入端口，命名为\code{in}和输出端口\code{out}。

\shortlist{code/components_d.txt}

The final missing piece of our example design is the top-level component, which itself
is assembled out of components C and D:

最后我们的例子缺少的一部分是顶层部分，它本身由C和D组成。

\shortlist{code/components_top.txt}

Good component design is similar to the good design of functions or methods in
software design. One of the main questions is how much functionality shall we put into
a component and how large should a component be. The two extremes are tiny
components, such an adder, and huge components, such as a full microprocessor,

良好的组件设计类似于以下功能或方法的良好设计：
软件设计。主要问题之一是我们应该投入多少功能
组件以及组件应多大。这两个极端很小
组件，例如加法器，以及庞大的组件，例如完整的微处理器，

Beginners in hardware design often start with tiny components.
The problem is that digital design books use tiny components to show the principles.
But the sizes of the examples (in those books, and also in this book) is small
to fit into a page and to not distract by too many details.

硬件设计的初学者通常从微型组件开始。
问题在于数字设计书使用微小的组件来显示原理。
但是示例的大小（在这些书以及本书中）都很小
以适合页面并且不会分散太多细节。

The interface to a component is a little bit verbose (with types, names, directions,
IO construction). As a rule of thumb, I would propose that the core of the component,
the function, should be at least as long as the interface of the component.


组件的界面有点冗长（包括类型，名称，方向，
IO建设）。根据经验，我建议组件的核心是
功能，应至少与组件的接口一样长。

For tiny components, such as a counter, Chisel provides a more lightweight
way to describe them as functions that return hardware.


对于细微的部件（例如计数器），Chisel提供了更轻巧的功能
将它们描述为返回硬件的函数的方式。


\section{An Arithmetic Logic Unit}

One of the central components for circuits that compute, e.g., a microprocessor, is an
\myref{https://en.wikipedia.org/wiki/Arithmetic_logic_unit}{arithmetic-logic unit},
or ALU for short. Figure~\ref{fig:alu} shows the symbol of an ALU.

我们的一个核心计算的电路部分，例如，微处理器，是\myref{https://en.wikipedia.org/wiki/Arithmetic_logic_unit}{arithmetic-logic unit}，
或是简单来说是ALU。Figure~\ref{fig:alu}表示了ALU的符号。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/alu}
  \caption{An arithmetic logic unit, or ALU for short.}
  \label{fig:alu}
\end{figure}

The ALU has two data inputs, labeled \code{A} and \code{B} in the figure, one function input \code{fn},
and an output, labeled {Y}. The ALU operates on \code{A} and \code{B} and provides the result
at the output. The input \code{fn} selects the operation on \code{A} and \code{B}.
The operations are usually some arithmetic, such as addition and subtraction, and some logical
functions such as and, or, xor. That's why it is called ALU.

ALU有两个数据输入，图中标明为\code{A}和\code{B}，一个函数的输入\code{fn}，
一个的输出labeled {Y}。 ALU操作在\code{A}和\code{B}，并且提供结果给输出。
\code{fn}选取了\code{A}和\code{B}进行操作。
这个操作经常是一些算法，例如加法和减法，并且一些逻辑性函数例如，和，或，异或。
那是为什么被称为ALU。

The function input \code{fn} selects the operation. The ALU is usually a combinational
circuit without any state elements. An ALU might also have additional outputs to signal properties
of the result, such as zero or the sign.

函数输入\code{fn}选取操作。ALU经常是一个组合逻辑电路，没有任何的状态元素。
一个ALU可能有一些额外的输出对于信号结果的属性，例如0或是正负符号。

The following code shows an ALU with 16-bit inputs and outputs that supports: addition, subtraction, or, and and
operation, selected by a 2-bit \code{fn} signal.

以下的代码表明了一个具有16位输入和输出的ALU，支持加法，减法，或，和与操作，通过二位的\code{fn}信号。

\shortlist{code/components_alu.txt}

\noindent In this example, we use a new Chisel construct, the \code{switch/is} construct to describe
the table that selects the output of our ALU.
To use this utility function, we need to import another Chisel package:

\noindent 在这个例子，我们使用new Chisel的结构，\code{switch/is}用于表示选取我们的ALU的输出表。
为了使用这个函数，我们需要引入其它chisel包裹：

\shortlist{code/components_util.txt}

\section{Bulk Connections}

For connecting components with multiple IO ports, Chisel provides the
bulk connection operator \code{<>}. This operator connects parts of bundles
in both directions. Chisel uses the names of the leave fields for the connection.
If a name is missing, it is not connected.

为了连接具有多个IO端口的组件，Chisel提供了
批量连接运算符\code{<>}。 该运算符在双方连接束。 Chisel使用离开字段的名称进行连接。
如果缺少名称，则表示未连接。


As an example, let us assume we build a pipelined processor. The fetch
stage has a following interface:

作为一个例子，让我们假定，我们搭建一个流水线的处理器。抓取阶段有一个如下的接口：

\shortlist{code/bundle_fetch.txt}

\noindent The next stage is the decode stage.

\noindent 下一阶段是译码阶段。

\shortlist{code/bundle_decode.txt}

\noindent The final stage of our simple processor is the execute stage.

\noindent 我们的简单处理器的最后阶段是执行。

\shortlist{code/bundle_execute.txt}

To connect all three stages we need just two \code{<>} operators.
We can also connect the port of a submodule with the parent module.

为了连接三个阶段，我们需要两个\code{<>}操作符。
我们也可以使用它连接父模块下的子模块端口。


\shortlist{code/bundle_connect.txt}


\section{Lightweight Components with Functions}

Modules are the general way to structure your hardware description.
However, there is some boilerplate code when declaring a module and when instantiating and
connecting it.


模块是构造硬件描述的通用方法。
但是，有一些样板代码在声明模块以及实例化连接的时候可以去使用。

A lightweight way to structure your hardware is to use functions.
Scala functions can take Chisel (and Scala) parameters and return generated hardware.
As a simple example, we generate an adder:

构造硬件的轻型方法是使用功能。
Scala函数可以采用Chisel（和Scala）参数并返回生成的硬件。
作为一个简单的示例，我们生成一个加法器：

\shortlist{code/components_fn_def.txt}

\noindent We can then create two adders by simply calling the function \code{adder}.

\noindent 我们可以接下来创造两个加法器，通过呼叫函数\code{adder}.

\shortlist{code/components_fn_use.txt}

\noindent Note that this is a \emph{hardware generator}. You are not executing any add operation
during elaboration, but create two adders (hardware instances). The adder is an artificial example
to keep it simple. Chisel has already an adder generation function, like \code{+(that: UInt)}.

\noindent 注意到这个是\emph{hardware generator}。你不只是在生成过程中执行任何相加操作，而是建造两个加法器（硬件模块）。
加法器是一个人工的例子，去使它变得简单。chisel本身就有加法器生成函数，像是\code{+(that: UInt)}。

Functions as lightweight hardware generators can also contain state (including a register).
Following example returns a one clock cycle delay element (a register).
If a function has just a single statement, we can write it in one line and omit the curly
braces ({}).

函数作为轻量级硬件生成器，也可以包含状态，包括几个寄存器。
以下例子返回了一个时钟周期的元素（一个寄存器）。
如果一个函数只是一个单一的声明，我们可以把它用一行写入，并忽略括号({})。

\shortlist{code/components_fn_delay.txt}

\noindent By calling the function with the function itself as parameter, this generated a two
clock cycle delay.

\noindent 通过呼叫这个函数，传入这个函数本身，这产生两个周期的延迟。

\shortlist{code/components_fn_2delay.txt}

\noindent Again, this is a too short example to be useful, as \code{RegNext()}
already is that function creating the register for the delay.

\noindent 再次，这个例子太短，以致于不够有用, 像 \code{RegNext()}
已经是那个函数，创造一个延时。

Functions can be declared as part of a \code{Module}. However, functions that shall be
used in different modules are better placed into a Scala object that collects utility
functions.

可以将函数声明为Module的一部分。但是，函数应
最好将用于不同模块的模块放置在一个收集实用程序的Scala对象中
。

\chapter{Combinational Building Blocks}

In this chapter, we explore various combinational circuits, basic building blocks that we can
use to construct more complex systems.
In principle, all combinational circuits can be described with Boolean equations.
However, more often, a description in the form of a table is more efficient.
We let the synthesize tool extract and minimize the Boolean equations.
Two basic circuits, best described in a table form, are a decoder and an encoder.

在本章节，我们探索各种组合电路，基本的建造模块，我们可以用来构建更加复杂的系统·。
基本上所有的组合电路都能通过布尔算式被编写。
但是，更常见的情况，一个表格的描述是更为有效的。
我们让综合工具抓取并缩小布尔算式。
两个基本电路，最好是通过表格方式描述，一个是译码器，另一个是编码器。

\section{Combinational Circuits}

Before describing some standard combinational building blocks, we will explore
how combinational circuits can be expressed in Chisel.
The simplest form is a Boolean expression, which can be assigned a name:

在我们描述一些标准的组合建造模块，我们会探索组合电路如何在Chisel种被表示。
最简单的是布尔算式，这个可以通过给名字分配：

\shortlist{code/comb_bool.txt}

\noindent The Boolean expression is given a name (\code{e}) by assigning it
to a Scala value. The expression can be reused in other expressions:

布尔逻辑表达式通过给一个名字（a）一个Scala值。这个表达式可以在其它表达式重新使用：

\shortlist{code/comb_use.txt}

Such an expression is considered fixed. A reassignment to \code{e}
with \code{=} would result in a Scala compiler error: \code{reassignment to val}.
A try with the Chisel operator \code{:=}, as shown below,

这样的表达式被认为是固定的。
通过=给e命名会导致Scala编译器错误：reassignment to val。
尝试Chisel操作符:=, 像是如下，

\shortlist{code/comb_error.txt}

\noindent results in a runtime exception: \code{Cannot reassign to read-only}.

导致runtime例外：不能重新分配给只读。

Chisel also supports describing combinational circuits with conditional updates.
Such a circuit is declared as a \code{Wire}. Then you uses conditional operations,
such as \code{when}, to describe the logic of the circuit.
The following code declares a \code{Wire} \code{w} of type \code{UInt} and assigns a default
value of \code{0}. The \code{when} block takes a Chisel \code{Bool} and reassigns
\code{3} to \code{w} if \code{cond} is \code{true.B}.

Chisel也支持描述组合电路通过条件性更新。
这样的电路先被声明为一个Wire，然后使用条件操作，例如when，然后描述电路的逻辑。
接下来的代码表明了类型UInt的Wire，并把它分配给默认值0。
when部分接受一个Chisel的Bool，并重新分配给w，如果条件true.B。

\shortlist{code/comb_wire.txt}

\noindent The logic of the circuit is a multiplexer, where the two inputs are the constants
\code{0} and \code{3} and the condition \code{cond} the select signal.
Keep in mind that we describe hardware circuits and not a software program with conditional
execution.

电路的逻辑是一个复用器，这里两个输入是0和3， 然后条件cond是选择信号。
记住我们描述硬件电路，而不是使用软件程序中的条件执行。

The Chisel condition construct \code{when} also has a form of \emph{else}, it is called
\code{otherwise}. With assigning a value under any condition we can omit the default
value assignment:

Chisel条件建造when也有一个else的类型，它是otherwise。
在某些条件下通过给一个值分配，我们可以忽略默认值：

\shortlist{code/comb_otherwise.txt}

Chisel also supports a chain of conditionals (a if/elseif/else chain) with \code{.elsewhen}:

Chisel也支持一链条的条件（a if elseif else链条）通过\code{.elsewhen}：

\shortlist{code/comb_elsewhen.txt}

Note the `.' in \code{.elsewhen} that is needed to chain methods in Scala.
Those \code{.elsewhen} branches can be arbitrary long.
However, if the chain of conditions depends on a single signal, it is better
to use the \code{switch} statement, which is introduced in the following
subsection with a decoder circuit.

记住.elsewhen中的"."在scala的链式方法是需要的。
这些“.elsewhen”分支可以是任意长的。
但是，如果条件链条取决于一个单个的信号，最好用switch声明，这个会在下边的译码器电路介绍。

For more complex combinational circuits it might be practical to assign
a default value to a \code{Wire}. A default assignment can be combined with the wire
declaration with \code{WireDefault}.\footnote{In the current version of Chisel
it is called WireInit, but will change to \code{WireDefault} with the release of Chisel 3.2}

对于更复杂的组合电路，可能设给Wire一个默认值更加有效。一个默认的声明可以通过wire声明，使用\code{WireDefault}。
\footnote{在目前chisel的版本称为WireInit, 但是会切换到\code{WireDefault}，通过chisel3.2的释放}。

\shortlist{code/comb_wiredefault.txt}

One might question why using \code{when}, \code{.elsewhen}, and \code{otherwise}
when Scala has \code{if}, \code{else if}, and \code{else}? Those statements are for
conditional execution of Scala code, not generating Chisel (multiplexer) hardware.
Those Scala conditionals have their use in Chisel when we write circuit generators,
which take parameters to conditionally generate \emph{different} hardware instances.

有人可能会问，为什么使用\code{when}，\code{.elsewhen}, 和\code{otherwise}，Scala用的是\code{if}，\code{else if}和\code{else}。
这些声明式对于Scala代码的条件执行，不是用于生成Chisel（复用器）的硬件。
这些Scala条件分支在Chisel中写电路生成器的时候有用处，它会采取变量，并条件化生成不同的硬件部分。


\section{Decoder}

A \myref{https://en.wikipedia.org/wiki/Binary_decoder}{decoder}
converts a binary number of $n$ bits to an $m$-bit signal, where $m \leq 2^n$.
The output is one-hot encoded (where exactly one bit is one).


A \myref{https://en.wikipedia.org/wiki/Binary_decoder}{decoder}把$n$位的二进制码转化位$m$位的信号，这里$m \leq 2^n$。
输出是独热码（这里1位对应的就是1）。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/decoder}
  \caption{A 2-bit to 4-bit decoder.}
  \label{fig:decoder}
\end{figure}

Figure~\ref{fig:decoder} shows a 2-bit to 4-bit decoder. We can describe the function
of the decoder with a truth table, such as Table~\ref{tab:decoder}.

图5.1表示了一个二位到四位的译码器，译码器的功能可以在真知表中被描述，像是表5.2。

\begin{table}
 \centering
 \label{tab:decoder}
  \begin{tabular}{rr}
    \toprule
    a & b \\
    \midrule
    00 & 0001 \\
    01 & 0010 \\
    10 & 0100 \\
    11 & 1000 \\
    \bottomrule 
  \end{tabular} 
  \caption{Truth table for a 2 to 4 decoder.}
\end{table}

A Chisel \code{switch} statement describes the logic as a truth table.
The \code{switch} statement is not part of the core Chisel language.
Therefore, we need to include the elements of the package \code{chisel.util}.

\code{switch}的chisel声明描述逻辑，作为一个真值表。
\code{switch}声明不是chisel语言的一部分。
于是，我们需要使用\code{chisel.util}的元素。

\shortlist{code/encdec_util.txt}

\noindent The following code introduces the \code{switch} statement of Chisel to describe a decoder:

下边的代码引用Chisel的switch声明去描述一个译码器：

\shortlist{code/encdec_dec.txt}

\noindent The above \code{switch} statement lists all possible values of the \code{sel} signal
and assigns the decoded value to the \code{result} signal.
Note that even if we enumerate all possible input values, Chisel still needs us to assign a
default value, as we do by assigning 0 to \code{result}.
This assignment will never be active and therefore optimized away by the backend tool.
It is intended to avoid situations with incomplete assignments for combinational circuits
(in Chisel a \code{Wire}) that will result in unintended latches in hardware description
languages such as VHDL and Verilog. Chisel does not allow incomplete assignments.

以上\code{switch}声明列出所有\code{sel}信号的可能值，并把译码的值赋值到\code{result}t信号。
注意，即使我们列举了所有可能的输入值，Chisel仍旧需要我们去赋值一个默认值，我们把\code{result}设为0。
这个赋值从来不会被激发，于是在后端工具被优化掉。
这个是用来防止组合电路的非完全赋值的情况（在Chisel是\code{Wire}），这样会导致硬件描述语言像是VHDL和Verilog的不想要的锁存器。
Chisel不允许非完全赋值。

In the example before we used unsigned integers for the signals. Maybe a clearer representation
of an encode circuit uses the binary notation:

在我们使用无符号整型的信号之前，一个可能更为清晰的编码器电路使用二进制表述：

\shortlist{code/encdec_decbin.txt}

\todo{from Luca: for very small examples. What if the one-hot input is 256 wires? Can Chisel capture that? Or I need 256 lines? I would suggest to put an additional example. Maybe there is something like the for loop in VHDL.}

A table gives a very readable representation of the decoder function but is also
a little bit verbose.
When examining the table, we see a regular structure: a 1 is shifted left by the number
represented by \code{sel}. Therefore, we can express a decoder with the Chisel shift
operation \code{<<}.

一个表格提供了更为刻度的译码器函数表示方式，但是这也变得拖沓。
当检查表格的时候，我们看到了一个常见的结构：1被向左移动了\code{sel}个单位。
于是，我们可以表达一个译码器通过Chisel移位操作\code{<<}。

\shortlist{code/encdec_shift.txt}

Decoders are used as a building block for a multiplexer by using the output as an enable
with an AND gate for the multiplexer data input. However, in Chisel, we do not need to construct
a multiplexer, as a \code{Mux} is available in the core library.
Decoders can also be used for address decoding, and then the outputs are used as
select signals, e.g., different IO devices connected to a microprocessor. 

译码器作为一个由复用器组成的部分，输出结果和使能，选用一个与门选择信号作为输入。
但是，在Chisel我们不需要搭建复用器，尽管库的\code{Mux}是可用的。
译码器可以用来翻译地址，然后输出是被选择的信号，例如，不同的IO器件连接到一个处理器。


\section{Encoder}

An \myref{https://en.wikipedia.org/wiki/Encoder_(digital)}{encoder}
converts a one-hot encoded input signal into a binary encoded output signal.
The encoder does the inverse operation of a decoder.

编码器把独热码输入信号转换为二进制编码形式作为输出。编码器是译码器的反向操作。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/encoder}
  \caption{A 4-bit to 2-bit encoder.}
  \label{fig:encoder}
\end{figure}


\begin{table}
 \centering
 \label{tab:encoder}
  \begin{tabular}{rr}
    \toprule
    a & b \\
    \midrule
    0001 & 00 \\
    0010 & 01 \\
    0100 & 10 \\
    1000 & 11 \\
    ???? & ?? \\
    \bottomrule 
  \end{tabular} 
  \caption{Truth table for a 4 to 2 encoder.}
\end{table}

Figure~\ref{fig:encoder} shows a 4-bit one-hot input to a 2-bit binary output encoder, and
Table~\ref{tab:encoder} shows the truth table of the encode function. However, an encoder
works only as expected when the input signal is one-hot coded. For all other input values, the output
is undefined. As we cannot describe a function with undefined outputs, we use a default
assignment that catches all undefined input patterns.

图5.2~\ref{fig:encoder}表明了一个4位独热码输入到一个二进制输出的编码器，表5.3~\ref{tab:encoder}是编码函数的真值表。
但是，编码器只在输入信号是独热码的时候工作。
对于其它的输入值，输出是未定义的。
所以我们不能描述一个有着未定义的函数作为输出，我们使用默认值赋值，抓取所有的未经定义的输入形式

The following Chisel code assigns a default value of 00 and then uses the switch statement
for the legal input values.

下边的Chisel代码赋值默认00，然后使用switch声明作为合法输入。

\shortlist{code/encdec_enc.txt}

\section{Exercise}

Describe a combinational circuit to convert a 4-bit binary input to the encoding of a
\myref{https://en.wikipedia.org/wiki/Seven-segment_display}{7-segment display}.

描述一个组合电路，用来转换4位二进制输入作为myref{https://en.wikipedia.org/wiki/Seven-segment_display}{7位输出}的编码。

You can either define the codes for the decimal digits, which was the initial
usage of a 7-segment display or additionally, define encodings for the remaining bit pattern
to be able to display all 16 values of a single digit in
\myref{https://en.wikipedia.org/wiki/Hexadecimal}{hexadecimal}.
When you have an FPGA board with a 7-segment display, connect 4 switches or
buttons to the input of your circuit and the output to the 7-segment display.

你可以定义十进制的代码，这个是有着7段显示作用的，或是额外地定义剩余的字节类型编码，
使其能够显示所有的16个单一数字\myref{https://en.wikipedia.org/wiki/Hexadecimal}{hexadecimal}。
当你有了一个具有七段编码的FPGA开发板，把它们连接到4个跳变或是按钮，到你的电路输入，和7段显示的输出。

\chapter{Sequential Building Blocks}

Sequential circuits are circuits where the output depends on the input \emph{and}
previous values. As we are interested in synchronous design (clocked designs),
we mean synchronous sequential circuits when we talk about sequential
circuits.\footnote{We can also build sequential circuits with asynchronous logic and
feedback, but this is a specific niche topic and cannot be expressed in Chisel.}
To build sequential circuits, we need elements that can store state:
the so-called registers.

时序电路的输出取决于输入和前一个值。
因为我们感兴趣的是同步设计（时钟设计），我们说时序电路，我们说的是同步时序电路。
为了搭建时序电路，我们需要储存状态的元素，所以我们称为寄存器。

\section{Registers}

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/register}
  \caption{A D flip-flop based register.}
  \label{fig:register}
\end{figure}

The fundamental elements for building sequential circuits are registers. A register is a collection
of \myref{https://en.wikipedia.org/wiki/Flip-flop_(electronics)\#D_flip-flop}{D flip-flops}.
A D flip-flop captures the value of its input at the rising edge of the clock and stores
it at its output. Alternatively, in other words: the register updates its output with the value of the input on the rising edge of the clock.

最基本的搭建时序电路的元素是寄存器。
寄存器是D触发器的集合。
D触发器在时钟上升沿抓取它的输入，并把它作为输出储存起来。
或者用另一句话，寄存器在时钟上升沿更新其输出，变为输入值。

Figure~\ref{fig:register} shows the schematic symbol of a register. It contains an input
\code{D} and an output \code{Q}. Each register also contains an input for a \code{clock} signal.
As this global clock signal is connected to all registers in a synchronous circuit, it is usually
not drawn in the schematic. The little triangle on the bottom of the box symbolizes the
clock input and tells us that this is a register.

图6.1表明寄存器的草图符号。
它包含输入D和输出Q。每个寄存器也包含了时钟信号作为输入。
在一个同步时序电路，作为全局时钟信号连接到所有寄存器，它一般在草图不画。
一个小的三角形在盒子的代表时钟输入，告诉我们这是一个寄存器。

We omit the clock signal in the following
drawings. The omission of the global clock signal is also reflected by Chisel where no explicit
connection of a signal to the register's clock input is needed.

我们忽略了以下图像的时钟信号。在chisel是不明确表示连入寄存器的时钟信号的，
这是省略表示总时钟信号的做法。

In Chisel a register with input \code{d} and output \code{q} is defined with:

在Chisel一个寄存器输入\code{d}和输出\code{q}被被定义为：

\shortlist{code/sequ_reg.txt}

\noindent Note that we do not need to connect a clock to the register, Chisel implicitly does this.
A register's input and output can be arbitrary complex types
made out of a combination of vectors and bundles.

这里注明一下，我们不需要给寄存器连接时钟，这个在Chisel内部间接完成。 
寄存器的输入和输出可以是任何来自于vector和bundle组合的复杂类型。


A register can also be defined and used in two steps:

寄存器也可以被定义和两步使用：

\shortlist{code/sequ_reg2.txt}

First, we define the register and give it a name. Second, we connect the signal
\code{delayIn} to the input of the register. Note also that the name of the register
contains the string \code{Reg}. To easily distinguish between combinational
circuits and sequential circuits, it is common practice to have the marker
\code{Reg} as part of to the name. Also, note that names in Scala (and therefore
also in Chisel) are usually in
\myref{https://en.wikipedia.org/wiki/Camel_case}{CamelCase}.
Variable names start with lowercase and classes start with upper case.

首先我们定义了寄存器并给它一个名字，其次我们连接了信号\code{delayIn}给寄存器的输入。
注意寄存器的名字是\code{Reg}开始的。
为了简单区分组合电路和时序电路的元素，一般常用的方式是在开头添加\code{Reg}的名字作为开头。
并且记得scala的名字（同样适用于chisel）经常以\myref{https://en.wikipedia.org/wiki/Camel_case}{CamelCase}的形式。
变量名称以小写开头，接下来的类别以首字母大写的形式。

A register can also be initialized on reset. The \code{reset} signal is, as the \code{clock} signal,
implicit in Chisel. We supply the reset value, e.g., zero, as a parameter to the register
constructor \code{RegInit}. The input for the register is connected with a Chisel
assignment statement.

一个寄存器也可以被复位初始化。\code{reset}信号是像\code{clock}信号一样，在Chisel是隐性的。我们提供了复位值，例如，零，
作为一个参数传给寄存器构造器\code{RegInit}。寄存器的输入是通过Chisel赋值声明连入的。

\shortlist{code/sequ_reg_init.txt}

The default implementation of reset in Chisel is a synchronous
reset.\footnote{Support for asynchronous reset is currently under development}
For a synchronous reset no change is needed on a D flip-flop, just a multiplexer
needs to be added to the input that selects between the initialization value under
reset and the data values.

Chisel的默认重置是同步复位。\footnote{目前非同步复位}
对于一个同步复位，不需要在D触发器需要改变，只是一个复用器需要被添加到输入，用于选取复位数值和数据数值。


\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/register-reset}
  \caption{A D flip-flop based register with a synchronous reset.}
  \label{fig:register-reset}
\end{figure}

Figure~\ref{fig:register-reset} shows the schematics of a register with a synchronous reset
where the reset drives the multiplexer. However, as synchronous reset is used quite often
modern FPGAs flip-flops contain a synchronous reset (and set) input to not wast LUT
resources for the multiplexer.

图片~\ref{fig:register-reset}表明一个具有同步复位的寄存器草图，这里同步复位驱动复用器。
但是，一个同步复位经常被使用，是因为现代FPGA包含一个重置（和设置）是用来不浪费复用器的LUT资源。

Sequential circuits change their value over time. Therefore, their behavior can be described
by a diagram showing the signals over time. Such a diagram is called a waveform or
\myref{https://en.wikipedia.org/wiki/Digital_timing_diagram}{timing diagram}.

时序电路不断地改变数值。于是，他们的行为可以被通过图像表示不同时间下的信号。这样的图像被称为波形图或是
\myref{https://en.wikipedia.org/wiki/Digital_timing_diagram}{时序图}。

\todo{from Luca: Do readers know about timing diagrams?}

\begin{figure}
  \centering
  \includegraphics[scale=1]{figures/reg_wave}
  \caption{A waveform diagram for a register with a reset.}
  \label{fig:register-wave}
\end{figure}

Figure~\ref{fig:register-wave} shows a waveform for the register with a reset
and some input data applied to it.
Time advances from left to right. On top of the figure, we see the clock that drives our circuit.
In the first clock cycle, before a reset, the register is undefined. In the second clock cycle reset
is asserted high, and on the rising edge of this clock cycle (labeled B) the register
captures the initial value of \code{0}. Input \code{inVal} is ignored. In the next clock cycle
\code{reset} is \code{0}, and the value of \code{inVal} is captured on the next rising
edge (labeled C). From then on \code{reset} stays \code{0}, as it should be, and the
register output follows the input signal with one clock cycle delay.

Figure~\ref{fig:register-wave} 表明了一个具有重置和输入数据的寄存器波形图。
时间按照从左到右的顺序。在图片的上边，我们看到有时钟驱动我们的电路。
在第一个时钟周期，在重置之前，寄存器是未定义的。在第二个时钟周期插入高电位，以及在时钟周期的上升沿（标为B），
寄存器捕捉了\code{0}的初始值。\code{inVal}的输入是被忽略的。在下一个周期，\code{reset}是\code{0}，
并且\code{inVal}在下一个上升沿（标为C）被捕捉到。从此\code{reset}呆在\code{0}，结果应该是，
寄存器的输出跟随输入信号，在一个周期延迟。

Waveforms are an excellent tool to specify the behavior of a circuit graphically.
Especially in more complex circuits where many operations happen in parallel
and data move pipelined through the circuit, timing diagrams are convenient.
Chisel testers can also produce waveforms during testing that can be displayed
with a waveform viewer and used for debugging.


波形是以图形方式指定电路行为的出色工具。
特别是在许多操作并行发生的更复杂的电路中
并且数据通过电路流水线传输，时序图很方便。
chisel测试器还可以在测试过程中产生可显示的波形
带有波形查看器并用于debug，其功能应为
最好将用于不同模块的模块放置在一个收集实用程序的Scala对象中
职能。

A typical design pattern is a register with an enable signal. Only when the enable signal
is \code{true} (high), the register captures the input; otherwise, it keeps its old value.
The enable can be implemented, similar to the synchronous reset, with
a multiplexer at the input of the register. One input to the multiplexer is the feedback of the
output of the register.

一个典型的寄存器类型是一个寄存器和一个使能信号。只有当使能信号是\code{true}（高）的时候，寄存器抓取输入；
否则的话，它保持原有的值。
使能信号可以通过类似于同步复位，在输入端前置复用器的方式被补充。
其中一个复用器的输入是寄存器输出的反馈。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/register-enable}
  \caption{A D flip-flop based register with an enable signal.}
  \label{fig:register-enable}
\end{figure}

Figure~\ref{fig:register-enable} shows the schematics of a register with enable.
As this is also a common design pattern, modern FPGA flip-flops contain a
dedicated enable input, and no additional resources are needed.

图片~\ref{fig:register-enable}表明一个具有使能信号的草图。
这个是一个常见的设计类型，当代的FPGA触发器包含一个

\begin{figure}
  \centering
  \includegraphics[scale=1]{figures/reg_en_wave}
  \caption{A waveform diagram for a register with an enable signal.}
  \label{fig:register-en-wave}
\end{figure}

Figure~\ref{fig:register-en-wave} shows an example waveform for a register
with enable. Most of the time, enable it high (\code{true}) and the register
follows the input with one clock cycle delay. Only in the fourth clock cycle
\code{enable} is low, and the register keeps its value (5) at rising edge D.

图片~\ref{fig:register-en-wave}表明了一个波形图例子，用于含有使能信号的寄存器。
大多数时间，使其变为高位(\code{true})，寄存器遵守输入的一个周期延迟。只是在第四个周期\code{enable}
是低位的，于是寄存器在在上升沿D（5）保持他的值。

A register with an enable can be described in a few lines of Chisel code
with a conditional update:

一个具有使能的寄存器可以通过数行chisel码和一个条件更新被描述：

\shortlist{code/sequ_reg_ena.txt}

\noindent A register with enable can also be reset:

\noindent 具有使能的寄存器也可以被重置：

\shortlist{code/sequ_reg_init_ena.txt}

A register can also be part of an expression. Following circuit detects the rising edge
of a signal by comparing its current value with the one from the last clock cycle.

一个寄存器也可以是表达式的一部分。以下电路检测了信号的上升沿，通过比较其当前值和上周期的值。

\shortlist{code/sequ_reg_rising.txt}

Now that we have explored all basic uses of a register, we put those registers to
good use and build more interesting sequential circuits.


现在，我们已经探索了寄存器的所有基本用途，我们将这些寄存器放入
善用并构建更有趣的时序电路。

\section{Counters}
\label{sec:counter}

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/counter}
  \caption{An adder and a register result in counter.}
  \label{fig:counter}
\end{figure}

One of the most basic sequential circuits is a counter. In its simplest form, a counter is a register
where the output is connected to an adder and the adder's output is connected to the input
of the register. Figure~\ref{fig:counter} shows such a free-running counter.

计数器是最基本的时序电路之一。以最简单的形式，计数器就是寄存器
输出连接到加法器，而加法器的输出连接到输入
寄存器。图counter显示了这样一个自由运行的计数器。

A free-running counter with a 4-bit register counts from 0 to 15 and then wraps around
to 0 again. A counter shall also be reset to a known value.

具有4位寄存器的自由运行计数器从0到15计数，然后回绕
再次设为0。计数器也应重置为已知值。

\shortlist{code/sequ_free_counter.txt}

\noindent When we want to count events, we use a condition to  increment the counter.

\noindent 当我们想要去计数事件的时候，我们使用条件去增加计数器读数。

\shortlist{code/sequ_event_counter.txt}

\subsection{Counting Up and Down}

To count up to a value and then restart with \code{0}, we need to compare
the counter value with a maximum constant, e.g., with a \code{when}
conditional statement.

要计算一个值，然后使用\code{0}重新启动，我们需要比较
具有最大常数的计数器值，例如带有\code{when}
有条件的声明。

\shortlist{code/when_counter.txt}

\noindent We can also use a multiplexer for our counter:

\noindent 我们也可以使用复用器作为一个计数器的增加读数：

\shortlist{code/mux_counter.txt}

\noindent If we are in the mood of counting down, we start (reset the counter register)
with the maximum value and reset the counter to that value when reaching 0.

\noindent如果我们有倒数的想法，我们开始（重置计数器寄存器）
设置为最大值，并在达到0时将计数器重置为该值。

\shortlist{code/down_counter.txt}

\noindent As we are writing and using more counters, we can
define a function with a parameter to generate a counter for us.

\noindent 当我们写入和使用更多的计数器的时候，我们可以定义一个具有参数的函数去为我们生成计数器。

\shortlist{code/function_counter.txt}

\noindent The last statement of the function \code{genCounter} is the return
value of the function, in this example, the counting register \code{cntReg}.

\noindent 最后的函数声明\code{genCounter}返回了函数数值，在这个例子，
是计数器寄存器\code{cntReg}。

Note, that in all the examples our counter had values between \code{0} and
\code{N}, including \code{N}. If we want to count 10 clock cycles we need
to set \code{N} to 9. Setting \code{N} to 10 would be a classic example of an
\myref{https://en.wikipedia.org/wiki/Off-by-one_error}{off-by-one error}.

注意，所有的例子里，我们的计数器在\code{0}和\code{N}，包括\code{N}都有数值。
如果我们想要数10个时钟周期，我们需要把\code{N}设为9。
把\code{N}设为10可能会成为一个经典的例子，
产生\myref{https://en.wikipedia.org/wiki/Off-by-one_error}{off-by-one错误}

\subsection{Generating Timing with Counters}

Besides counting events, counters are often used to generate timing.
A synchronous circuit runs with a clock with a fixed frequency.
The circuit proceeds in those clock ticks. There is no notion of time in a digital
circuit other than counting clock ticks. If we know the clock frequency, we
can generate circuits that generate timed events, such as blinking a LED
at some frequency as we have shown in the Chisel ``Hello World'' example.

除了计数时间，计数经常被使用去生成延迟。
一个同步电路使用一个时钟和特定的频率。
电路在这些时钟变化中生成结果。
在数字电路中没有时间的概念，除了计算时钟周期。
如果我们知道时钟频率，我们可以生成电路用于生成时间性事件，类似在一些特定频率闪烁LED，
像是我们前边知道的Chisel``Hello World''例子。

A common practice is to generate single-cycle \emph{ticks} with a frequency $f_{tick}$
that we need in our circuit. That tick occurs every $n$ clock cycles,
where $n = f_{clock}/f_{tick}$ and the tick is precisely one clock cycle long.
This tick is \emph{not} used as a derived clock, but as an enable signal for
registers in the circuit that shall logically operate at frequency $f_{tick}$.
Figure~\ref{fig:tick-wave} shows an example of a tick generated every
3 clock cycles.

一个常见的生成单个具有频率$f_{tick}$的我们电路中需要的\emph{ticks}的方式。
每隔$n$个周期发生一次tick，这里$n = f_{clock}/f_{tick}$, tick是被设为一个时钟的长度。
这个tick是、emph{不}用做推演的时钟的，而是作为一个作为电路的使能信号，逻辑上在$f_{tick}$下操作。
~\ref{fig:tick-wave}表明一个每三个周期产生tick的例子。

\begin{figure}
  \centering
  \includegraphics[scale=1]{figures/tick_wave}
  \caption{A waveform diagram for the generation of a slow frequency tick.}
  \label{fig:tick-wave}
\end{figure}

In the following circuit, we describe a counter that counts from \code{0}
to the maximum value of \code{N - 1}. When the maximum value is reached,
the \code{tick} is \code{true} for a single cycle, and the counter is reset to \code{0}.
When we count from \code{0} to \code{N - 1}, we generate one logical tick
every \code{N} clock cycles.

在下边的这个例子，我们介绍了一个计数器，从\code{0}数到最大值\code{N - 1}。
当达到最大值的时候，\code{tick}在一个单周期内变为\code{true}，计数器被重置为\code{0}。
当我们从\code{0}数到\code{N - 1}, 我们每\code{N}时钟周期生成一个逻辑tick。


\shortlist{code/sequ_tick_gen.txt}

\noindent This logical timing of one tick every $n$ clock cycles can then be used
to advance other parts of our circuit with this slower, logical clock.
In the following code, we use just another counter that increments by \code{1}
every $n$ clock cycles.

\noindent 每隔$n$时钟生成一个逻辑上的tick可以被使用区增加其它电路中的时钟部分，通过这个慢的逻辑电路。
在下边的代码，我们使用另一个计数器，每过$n$时钟周期增加\code{1}单位。

\shortlist{code/sequ_tick_counter.txt}

Examples of the usage of this slower \emph{logical} clock are: blinking an LED,
generating the baud rate for a serial bus, generating signals for 7-segment
display multiplexing, and subsampling input values for debouncing of buttons
and switches. 

使用这个更慢的\emph{logical}时钟的场景: 闪烁一个lED，对于一个序列串口胜场波特率，
生成7段显示复用器信号，向下采样输入值用于防止上下抖动。

Although width inference should size the registers, it is better to explicitly
specify the width with the type at register definition or with the
initialization value. Explicit width definition can avoid surprises when a reset value of \code{0.U}
results in a counter with a width of a single bit.

尽管位宽推断应该规定寄存器尺寸大小，但是更明确位宽，通过寄存器的类型的定义，或是通过初始值的方式，是更好的。
定义明确的位宽可以防止当重置为\code{0.U}的时候，产生一个位宽为1的意外。

\subsection{The Nerd Counter}

Many of us feel like being a \myref{https://en.wikipedia.org/wiki/Nerd}{nerd}, sometimes.
For example, we want to design a highly optimized version of our counter/tick generation.
A standard counter needs following resources: one register, one adder (or subtractor),
and a comparator. We cannot do much about the register or the adder. If we count
up, we need to compare against a number, which is a bit string. The comparator
can be built out of inverters for the zeros in the bit string and a large AND gate.
When counting down to zero, the comparator is a large NOR gate, which might be
a little bit cheaper than the comparator against a constant in an ASIC.
In an FPGA, where logic is built out of lookup tables, there is no difference between comparing
against a 0 or 1 bit. The resource requirement is the same for the up and down counter.

我们很多人有时会感觉自己像一个\myref{https://en.wikipedia.org/wiki/Nerd}{nerd}。
例如，我们想要设计一个超级优化的计数器。
一个标准的计数器需要以下资源：一个寄存器，一个加法器（或是减法器），一个比较器。
我们不能再寄存器或是加法器做很多。如果我们向上数，我们需要比较一个目标数，这是一个字符。
比较器可以从0开始反向生成一个字符，然后一个大的与们。
当我们向下数零的时候，比较器是一个大的或非们，这个从AISC的角度是更加便宜的。
在FPGA，逻辑来源于查找表，所以在比较1或是0的时候就没什么区别了，此时向上数和向下数对于资源的要求是一样的。


However, there is still one more trick a clever hardware designer can pull off.
Counting up or down needed a comparison against all counting bits, so far.
What if we count from N-2 down to -1? A negative number has the most significant bit
set to 1, and a positive number has this bit set to 0. We need to check this bit only to detect
that our counter reached -1. Here it is, the counter created by a nerd:

但是，这里仍然有一个小窍门，硬件设计者可以借鉴。
目前向上数或向下数需要与所有的计数位比较。
当你向下数太多会发生什么？
那种情况，计数变为负数。探测一个负数只是简单比较最高位“a”就好。

\shortlist{code/nerd_counter.txt}

\section{Memory}

A memory can be built out of a collection of registers, in Chisel a \code{Reg} of a \code{Vec}.
However, this is expensive in hardware, and larger memory structures are built
as \myref{https://en.wikipedia.org/wiki/Static_random-access_memory}{SRAM}.
For an ASIC, a memory compiler constructs memories.
FPGAs contain on-chip memory blocks, also called block RAMs.
Those on-chip memory blocks can be combined for larger memories.
Memories in an FPGA usually have one read and one write port, or
two ports where the direction can be switched.

存储器可以通过一系列的寄存器搭建，在chisel，一个\code{Vec}的\code{Reg}。
但是，这个在硬件上是昂贵的，更大的存储器是通过\myref{https://en.wikipedia.org/wiki/Static_random-access_memory}{SRAM}搭建的。
对于一个ASIC, 存储器编译器构建出存储器。
FPGA自带片上存储单元，也称为模块化RAM。
这些片上存储单元可以组合成为更大的存储器。
FPGA上的存储器一般有一个读端和一个写端，或者可以切换方向的两个端口。

FPGAs (and also ASICs) usually support synchronous memories.
Synchronous memories have registers on their inputs (read and write address, write data,
and write enable). That means the read data is available one clock
cycle after setting the address.

FPGA（或是ASIC）经常支持同步存储器。
同步存储器在输入上具有寄存器(读和写地址，写数据，写使能)。
那意味着读数据在设置地址后的一个周期的是可用的。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/memory}
  \caption{A synchronous memory.}
  \label{fig:memory}
\end{figure}

Figure~\ref{fig:memory} shows the schematics of such a synchronous memory.
The memory is dual-ported with one read port and one write port.
The read port has a single input, the read address (\code{rdAddr}) and
one output, the read data (\code{rdData}).
The write port has three inputs: the address (\code{wrAddr}), the data
to be written (\code{wrData}), and a write enable (\code{wrEna}).
Note that for all inputs, there is a register within the memory showing the
synchronous behavior.

~\ref{fig:memory}图片表明了这样一个同步存储器的草图。
这个存储器是双端口的，具有一个读出和写入端口。
这个读出端口有一个单一输入，读出地址(\code{rdAddr})和一个输出数据(\code{rdData})。
写入端口有三个输入：地址(\code{wrAddr})，写入的数据(\code{wrData})，和写入使能(\code{wrEna})。
注意到对于所有的输入，存储器的寄存器表明了同步的行为。

To support on-chip memory, Chisel provides the memory constructor \code{SyncReadMem}.
Listing~\ref{lst:memory} shows a component \code{Memory} that implements
1~KB of memory with byte-wide input and output data and a write enable.

为了支持片上存储，chisel提供了存储器构建器\code{SyncReadMem}。
~\ref{lst:memory}表明了\code{Memory}的构成去支持1KB的存储器，具有字节位宽的输入和输出数据，和一个写入使能。

\longlist{code/memory.txt}{1 KB of synchronous memory.}{lst:memory}

An interesting question is which value is returned from a read when in the same clock
cycle a new value is written the same address that is read out.
We are interested in the read-during-write behavior of the memory.
There are three possibilities: the newly written value, the old value, or undefined
(which might be a mix of some bits from the old value and some of the newly written data).
Which possibility is available in an FPGA depends on the FPGA type and
sometimes can be specified.

一个有趣的问题是，在同一时钟中，从读取返回哪个值
循环将一个新值写入与读出相同的地址。
我们对内存的read-during-write行为感兴趣。
有三种可能：新写入的值，旧值或未定义
（这可能是旧值中的一些位与一些新写入的数据的混合）。
FPGA中可用的可能性取决于FPGA类型和
有时可以指定。

Chisel documents that the read data is undefined.

Chisel档案中读取数据是未定义的。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/memory-forwarding}
  \caption{A synchronous memory with forwarding for a defined read-during-write behavior.}
  \label{fig:memory:forwarding}
\end{figure}

If we want to read out the newly written value, we can build a forwarding
circuit that detects that the addresses are equal and \emph{forwards} the
write data. Figure~\ref{fig:memory:forwarding} shows the memory with
the forwarding circuit. Read and write addresses are compared and gated with
the write enable to select between the forwarding path of the write data or the
memory read data. The write data is delayed by one clock cycle with a register.

如果我们想要读出新写入的值，我们可以搭建一个前递电路，能够检查出相同地址情况下\emph{forwards}出写入数值。
~\ref{fig:memory:forwarding}表明具有前递电路的存储器。读出和写入地址会相互比较，并受到写入使能控制，去选择
写入数据的前递路径，或是存储器读取数据。这个写入数据是受到一个周期的寄存器延迟。

Listing~\ref{lst:memory:forward} shows the Chisel code for a synchronous memory
including the forwarding circuit. We need to store the write data into a register
(\code{wrDataReg}) to be available in the next clock cycle the synchronous
memory also has a one clock cycle latency.
We compare the two input addresses (\code{wrAddr} and \code{rdAddr})
and check if \code{wrEna} is true for the forwarding condition.
That condition is also delayed by one clock cycle.
A multiplexer selects between the forwarding (write) data or the read
data from memory.

列表~\ref{lst:memory:forward} 表明一个具有同步存储器，包含前馈电路的Chisel代码。
我们需要存储写入数据到一个寄存器(\code{wrDataReg})，使之在下个周期变得有效，同步存储器也有一个周期的延迟。
我们比较了两个写入地址(\code{wrAddr} 和 \code{rdAddr})并且去检查，看\code{wrEna}是否为真，在前馈的条件下。
那个条件也受到一个周期的延迟。
一个复用器在前馈写入数据和读出数据做出选择。

\longlist{code/memory_forwarding.txt}{A memory with a forwarding circuit.}{lst:memory:forward}

Chisel also provides \code{Mem}, which represents a memory with synchronous
write and an asynchronous read. As this memory type is usually not directly available
in an FPGA, the synthesize tool will build it out of flip-flops.
Therefore, we recommend using \code{SyncReadMem}.

Chisel也提供了\code{Mem}，代表了一个具有同步写入和同步读出的存储器。但是这个存储器一般不在FPGA可以使用，
综合工具会把它变为触发器。于是，我们推荐使用\code{SyncReadMem}。

\section{Exercise}

Use the 7-segment encoder from the last exercise and add a 4-bit counter as input
to switch the display from \code{0} to \code{F}. When you directly connect this
counter to the clock of the FPGA board, you will see all 16 numbers
overlapped (all 7 segments will light up).
Therefore, you need to slow down the counting. Create a second
counter that can generate a single-cycle \emph{tick} signal every 500 milliseconds.
Use that signal as enable signal for the 4-bit counter.

使用来自上一章的7段编码器并添加一个4位计数器作为输入，去切换显示，从\code{0}到\code{F}。
当你直接连接这个计数器到FPGA的时钟，你会看到所有的16个数字相互交叠(所有的7段显示一起亮)。
于是，你需要调慢计数。创建一个秒计数器，每个周期生成一个\emph{tick}，每过500毫秒。
使用那个信号作为使能信号，用于4位计数器。

\todo{Luca: More exercises would be nice. Maybe in the future?}

\chapter{Finite-State Machines}

A finite-state machine (FSM) is a basic building block in digital design.
An FSM can be described as a set of \emph{states} and conditional (guarded)
\emph{state transitions} between states. 
An FSM has an initial state, which is set on reset.
FSMs are also called synchronous sequential circuits.

有限状态机（FSM）是一个数字电路中的基本的搭建模块。一个FSM可以被描述为一个\emph{states}和（有限制的）状态条件
\emph{state transitions}。
一个FSM有一个初始状态，这是在reset中被确定的。
FSMs也被称为同步时序电路。


An implementation of an FSM consists of three parts: (1) a register that holds the current state,
(2) combinational logic that computes the next state that depends on the current
state and the input, and (3) combinational logic that computes the output of the FSM.

FSM的实现包括三个部分：(1) 一个具有现在状态的寄存器,
(2) 组合逻辑根据目前状态和输入计算下个状态,  
(3) 组合逻辑能够计算FSM的输出。

In principle, every digital circuit that contains a register or other memory elements
to store state can be described as a single FSM. However, this might
not be practical, e.g., try to describe your laptop as a single FSM.
In the next chapter, we describe how to build larger systems
out of smaller FSMs by combining them into communicating FSMs.

原则上，每个数字电路包含一个寄存器或是其它存储器元件去储存状态，可以被称为一个FSM。
但是，着可能不实用，例如，把你的电脑描述为一个FSM。
下个章节，我们描述如何通过组合小的FSM进行通信FSM，搭建更大的系统。

\section{Basic Finite-State Machine}

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/fsm}
  \caption{A finite state machine (Moore type).}
  \label{fig:fsm}
\end{figure}

Figure~\ref{fig:fsm} shows the schematics of an FSM. The register contains the current \code{state}.
The next state logic computes the next state value (\code{next\_state})
from the current \code{state} and the input (\code{in}).
On the next clock tick, \code{state} becomes \code{next\_state}.
The output logic computes the output (\code{out}). As the output depends on the current
state only, this state machine is called a
\myref{https://en.wikipedia.org/wiki/Moore_machine}{Moore machine}.

图片~\ref{fig:fsm} 表明FSM的草图. 寄存器包含目前的\code{state}.
通过\code{state}和输入(\code{in})用来计算下个状态的状态逻辑(\code{next\_state})。
在下个时钟, \code{state} 变为 \code{next\_state}.
输出逻辑计算输出 (\code{out}). 因为输出只取决于目前状态，这样的状态机被称为
\myref{https://en.wikipedia.org/wiki/Moore_machine}{Moore machine}.

A \myref{https://en.wikipedia.org/wiki/State_diagram}{state diagram}
describes the behavior of such an FSM visually.
In a state diagram, individual states are depicted as circles labeled
with the state names.
State transitions are shown with arrows between states.
The guard (or condition) when this transition is taken is drawn as a label
for the arrow.

\myref{https://en.wikipedia.org/wiki/State_diagram}{state diagram}
使用图形描述FSM的行为。
在状态图中，单独的状态被画成标注状态名字的圆圈。
状态转移被描述为状态之间的箭头。
当这个转移被采取的时候，改转移条件会在箭头上被标出。

Figure~\ref{fig:diag-moore} shows the state diagram of a simple example FSM.
The FSM has three states: \emph{green}, \emph{orange}, and \emph{red},
indicating a level of alarm. The FSM starts at the \emph{green} level.
When a \emph{bad event} happens the alarm level is switched to \emph{orange}.
On a second bad event, the alarm level is switched to \emph{red}.
In that case, we want to ring a bell; \emph{ring bell} it the only output of this FSM.
We add the output to the \emph{red} state.
The alarm can be reset with a \emph{clear} signal.

~\ref{fig:diag-moore}图片表明了一个简单FSM的例子图表。
这个FSM有三个状态：\emph{green}, \emph{orange}, and \emph{red}，
表明闹铃的等级。FSM以绿色等级为开始，当\emph{bad event}发生的时候，闹铃等级切换到\emph{orange}。
在下一个坏的时刻，闹铃等级被切换到\emph{red}。
在那种情况下，我们想要响铃；\emph{ring bell}是唯一的FSM的输出。
我们在\emph{red}状态下增加输出。
然后响铃可以被重置到\emph{clear}信号。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/state-diag-moore}
  \caption{The state diagram of an alarm FSM.}
  \label{fig:diag-moore}
\end{figure}

Although a state diagram may be visually pleasing and the function of an FSM
can be grasped quickly, a state table may be quicker to write down.
Table~\ref{tab:state:table} shows the state table for our alarm FSM.
We list the current state, the input values, the resulting next state, and
the output value for the current state. In principle, we would need to
specify all possible inputs for all possible states. This table would have
$3 \times 4 = 12$ rows. We simplify the table by indicating that the \emph{clear}
input is a don't care when a \emph{bad event} happens. That means
\emph{bad event} has priority over \emph{clear}. The output column
has some repetition. If we have a larger FSM and/or more outputs, we
can split the table into two, one for the next state logic and one for the
output logic.

尽管状态图看起来很舒服，一个FSM可以被快速掌握，那么状态表可以更快地写下来。
~\ref{tab:state:table}图标表明我们的闹铃FSM的状态表。
我们列出了当前状态，输入值，和接下来的状态，和当前状态的输出值。原则上，我们需要
列出所有可能状态下的所有输入值。这个表格可以有3*4=12列。我们把这个表格进行简化，
当\emph{bad event}发生的时候，输入\emph{clear}是不管的。那意味着\emph{bad event}对于\emph{clear}
有优先级。输出列有一些重复。如果我们有一个更大的FSM或是更多输出，我们可以把列表分为两个，一个用于计算下个状态逻辑，
一个用于计算输出逻辑。


\begin{table}
\centering
\caption{State table for the alarm FSM.}
\begin{tabular}{ccccc}
\toprule
& \multicolumn{2}{c}{Input} \\
\cmidrule{2-3}
State &  Bad event & Clear & Next state & Ring bell \\
\midrule
green & 0 & 0 & green & 0 \\
green & 1 & - & orange & 0 \\
orange & 0 & 0 & orange & 0 \\
orange & 1 & - & red & 0 \\
orange & 0 & 1 & green & 0 \\
red & 0 & 0 & red & 1 \\
red & 0 & 1 & green & 1 \\
\bottomrule
\end{tabular}
\label{tab:state:table}
\end{table}

Finally, after all the design of our warning level FSM, we shall code it in Chisel.
Listing~\ref{lst:fsm:alarm} shows the Chisel code for the alarm FSM.
Note, that we use the Chisel type \code{Bool} for the inputs and the
output of the FSM.
To use \code{Enum} and the \code{switch} control instruction, we need to
import \code{chisel3.util.\_}.

最后，得到我们的等级警报FSM设计，我们使用chisel写下代码。
~\ref{lst:fsm:alarm}表明了闹铃FSM的Chisel代码。
注意到，我们使用Chisel的\code{Bool}作为输入和输出类型。
为了使用\code{Enum}和\code{switch}控制指令，我们需要引入
\code{chisel3.util.\_}。

\longlist{code/simple_fsm.txt}{The Chisel code for the alarm FSM.}{lst:fsm:alarm}

The complete Chisel code for this simple FSM fits into one page.
Let us step through the individual parts.
The FSM has two input and a single output signal, captured in a Chisel \code{Bundle}:
%

这个简单的FSM的Chisel完整代码可以放得下一页纸。
让我们从独立的部分开始。
这个FSM有两个输入和一个输出信号，在Chisel\code{Bundle}打包：

\shortlist{code/simple_fsm_io.txt}

\noindent Quite some work has been spent in optimal state encoding. Two common options
are binary or one-hot encoding. However, we leave those low-level decisions to
the synthesize tool and aim for readable code.\footnote{In the current version
of Chisel the \code{Enum} type represents states in binary encoding.
If we want a different encoding, e.g., one-hot encoding, we can define Chisel
constants for the state names.}
Therefore, we use an enumeration type with symbolic names for the states:

\noindent 尽管曾经在最佳状态编码上进行过一些研究。两种常用选择是二进制或是读热码。但是，我们把这些底层决定交给综合工具，
并实现可读代码。\footnote{在目前的版本，\code{Enum}代表二进制编码的状态。
如果我们想要另一种编码，例如，独热码，我们为状态名称定义chisel常量。}
于是，我们使用了\code{Enum}类和符号化名字用于表示状态：

\shortlist{code/simple_fsm_states.txt}

\noindent The individual state values are described as a list where the individual
elements are concatenated with the \code{::} operator; \code{Nil} represents
the end of the list. An \code{Enum} instance is \emph{assigned} to the list of states.
The register holding the state is defined with the \emph{green} state as the reset value:

\noindent 单独的状态变量被描述为一个序列，这里单独的元素通过\code{::}进行合并；\code{Nil}代表序列的结尾。
\code{Enum}实例是被\emph{assigned}赋值到一列状态。
含有状态的寄存器通过\emph{green}状态被定义到重置值。


\shortlist{code/simple_fsm_register.txt}

\noindent The meat of the FSM is in the next state logic. We use a Chisel switch on the
state register to cover all states. Within each \code{is} branch we code the next state
logic, which depends on the inputs, by assigning a new value for our state register:

\noindent FSM的核心在下一个状态逻辑的定义。我们使用Chisel的switch声明，在状态寄存器，去抵消所有状态。
通过每个\code{is}分支，我们编写了下个状态逻辑，依赖于输入，通过给我们的状态寄存器赋新的数值。

\shortlist{code/simple_fsm_next.txt}

\noindent Last, but not least, we code our \emph{ringing bell} output to be true when
the state is \emph{red}.

\noindent 最后重要的，我们编写了\emph{ringing bell}的输出为真，当状态是\emph{red}。

\shortlist{code/simple_fsm_output.txt}

Note that we did \emph{not} introduce a \code{next\_state} signal for the register input,
as it is common practice in Verilog or VHDL.
Registers in Verilog and VHDL are described in a special syntax and cannot
be assigned (and reassigned) within a combinational block.
Therefore, the additional signal, computed in a combinational block, is
introduced and connected to the register input.
In Chisel a register is a base type and can be freely used within a combinational block.

记着我们没有引入\code{next\_state}作为寄存器输入，
尽管这个在verilog或是vhdl是常见的。
verilog和VHDL的寄存器被表述为一个特定的形式，并且不能赋值或是重复赋值，在一个组合框架。
于是，额外的信号，在组合框架被计算出来，并连接给寄存器的输入。
在Chisel，寄存器是一个基础类型，可以通过组合框架免费使用。

\section{Faster Output with a Mealy FSM}

On a Moore FSM, the output depends only on the current state.
That means that a change of an input can be seen as a change of the
output \emph{earliest} in the next clock cycle.
If we want to observe an immediate change, we need a combinational
path from the input to the output.
Let us consider a minimal example, an edge detection circuit.
We have seen this Chisel one-liner before:

在一个Moore FSM，输出值只取决于当前状态。
那意味着输入改变可以被看成导致\emph{最早的}下个周期的输出改变。
如果我们想要观察一个间接的改变，我们需要一个组合路径，从输入到输出。
让我们想一个最小的例子，在边沿检测电路。
我们可能以前看过这一行Chisel代码：

\shortlist{code/sequ_reg_rising.txt}

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/fsm-rising}
  \caption{A rising edge detector (Mealy type FSM).}
  \label{fig:fsm-rising}
\end{figure}

Figure~\ref{fig:fsm-rising} shows the schematic of the rising edge detector.
The output becomes 1 for one clock cycle when the current input is 1
and the input in the last clock cycle was 0.
The state register is just a single D flip-flop where the next state
is just the input. We can also consider this as a delay element of one
clock cycle. The output logic \emph{compares} the current
input with the current state.

~\ref{fig:fsm-rising}表明了上升边沿检测器的草图。
当这个周期输入为1的时候，经过一个周期，输出变为1，并且上个周期的输入是0.
这个状态寄存器只是一个简单的D触发器，下个状态只是输入值。我们也可以把这个看成一个时钟延迟的元素。
输出逻辑\emph{比较}当前输入和当前状态。

When the output depends also on the input, i.e., there is a combinational path between
the input of the FSM and the output, this is called a
\myref{https://en.wikipedia.org/wiki/Mealy_machine}{Mealy machine}.

当输出也取决于输入，例如，有一个组合逻辑的路径在FSM的输入和输出之间，这被称为
\myref{https://en.wikipedia.org/wiki/Mealy_machine}{Mealy machine}。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/mealy}
  \caption{A Mealy type finite state machine.}
  \label{fig:mealy}
\end{figure}

Figure~\ref{fig:mealy} shows the schematic of a Mealy type FSM.
Similar to the Moore FSM, the register contains the current \code{state}, and
the next state logic computes the next state value (\code{next\_state})
from the current \code{state} and the input (\code{in}).
On the next clock tick, \code{state} becomes \code{next\_state}.
The output logic computes the output (\code{out}) from the current state
\emph{and} the input to the FSM.

Figure~\ref{fig:mealy} 表明了Mealy类型的FSM的草图。
类似于Moore FSM，寄存器包含了当前\code{state}，
和来自当前\code{state}和输入(\code{in})的用于计算(\code{next\_state})的状态逻辑。
在下一个时钟，\code{state}变为\code{next\_state}。
输出逻辑从当前状态的(\code{out})计算输出。


\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/state-diag-mealy}
  \caption{The state diagram of the rising edge detector as Mealy FSM.}
  \label{fig:diag:mealy}
\end{figure}

Figure~\ref{fig:diag:mealy} shows the state diagram of the Mealy FSM for the
edge detector. As the state register consists just of a single D flip-flop,
only two states are possible, which we name \code{zero} and \code{one} in this
example.

图片~\ref{fig:diag:mealy}表明Mealy FSM的状态图，用于边沿检测。作为状态寄存器，包含了只是一个D触发器，
只有两个状态是可能的，在这个例子中，是\code{zero}和\code{one}。

As the output of a Mealy FSM does not only depend on the state, but also
on the input, we cannot describe the output as part of the state circle.
Instead, the transitions between the states are labeled with the input
value (condition) \emph{and} the output (after the slash).
Note also that we draw self transitions, e.g., in state \code{zero} when
the input is \code{0} the FSM stays in state \code{zero}, and the output is {0}.
The rising edge FSM generates the \code{1} output only on the transition
from state \code{zero} to state \code{one}. In state \code{one}, which represents
that the input is now \code{1}, the output is \code{0}. We only want a single (cycle)
puls for each rising edge of the input.

作为Mealy FSM的输出，并不只是依赖于状态，也依赖于输入，我们不能描述输出作为状态圆的一部分。
相反，状态间的转移函数和输入值和输出值是一起被标出的。
注意到我们画本身的状态转移，例如，在状态\code{0}当输入是\code{0}，FSM停留在\code{0}，
输出是{0}。
FSM的上升沿产生\code{1}作为输出，只有当从状态\code{0}转移到\code{1}。在状态\code{1}，
代表输入现在是\code{1}，输出是\code{0}。我们现在想要一个对于每个输入的上升沿，
产生单一周期的跳变。

\longlist{code/rising_fsm.txt}{Rising edge detection with a Mealy FSM.}{lst:fsm:rising}

Listing~\ref{lst:fsm:rising} shows the Chisel code for the rising edge detection
with a Mealy machine.
As in the previous example, we use the Chisel type \code{Bool} for the
single-bit input and output.
The output logic is now part of the next state logic; on the transition from
\code{zero} to \code{one}, the output is set to \code{true.B}. Otherwise,
the default assignment to the output (\code{false.B}) counts.

Listing~\ref{lst:fsm:rising}表明了使用Mealy机器用于上升沿检测的chisel代码。
像是前边的例子，我们使用chisel类型\code{Bool}用于单比特的输入和输出。
输出逻辑是下个逻辑的一部分，在从\code{zero}到\code{one}的转换过程，输出被设定为\code{true.B}。
否则的话，默认赋值是按照(\code{false.B})。

One can ask if a full-blown FSM is the best solution for the edge detection circuit,
especially, as we have seen a Chisel one-liner for the same functionality.
The hardware consumptions is similar. Both solutions need a single D flip-flop
for the state. The combinational logic for the FSM is probably a bit more complicated, as
the state change depends on the current state and the input value.
For this function, the one-liner is easier to write and easier to read,
which is more important. Therefore, the one-liner is the preferred solution.

如果问到如果一个成熟的FSM是不是一个最好的边沿检测电路的最好方法，
特别地，像我们看到过chisel单行代码解决了同样的问题。
硬件消耗是同样的。两个解决方案需要一个单D触发器用于表示状态。
FSM的组合逻辑可能有点复杂，随着状态改变，需要依赖于现有状态和输入值。
对于这个函数，单行代码是易写和易读的，这个更为重要。
于是，单行代码是更好的解决方式。

We have used this example to show one of the smallest possible Mealy FSMs.
FSMs shall be used for more complex circuits with three and more states.

我们已经使用了这个例子区表明了一个更为聪明的方式去编写Mealy FSM。
FSM应当在更为复杂的三个或是更多状态的电路被使用。

\section{Moore versus Mealy}

To show the difference between a Moore and Mealy FSM, we redo the edge
detection with a Moore FSM. 

为了表明Moore和Mealy FSM的区别，我们重做了一遍使用Moore FSM进行边沿检测。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/state-diag-rising-moore}
  \caption{The state diagram of the rising edge detector as Moore FSM.}
  \label{fig:diag:rising:moore}
\end{figure}

Figure~\ref{fig:diag:rising:moore} shows the state diagram for the rising
edge detection with a Moore FSM. The first thing to notice is that the Moore FSM
needs three states, compared to two states in the Mealy version.
The state \code{puls} is needed to produce the single-cycle puls.
The FSM stays in state \code{puls} just one clock cycle and then
proceeds either back to the start state \code{zero} or to the \code{one}
state, waiting for the input to become 0 again.
We show the input condition on the state transition arrows and the
FSM output within the state representing circles.

Figure~\ref{fig:diag:rising:moore} 表明了使用Moore FSM的状态图用于上升沿检测。
第一个事情是去注意到Moore FSM需要三个状态，相比较于Mealy版本需要两个状态。
\code{puls}状态需要去产生单一周期的脉冲。
FSM处于状态\code{puls}只是一个周期，然后返回到开始状态\code{zero}或是状态\code{one}，
等待输入再次变为0。
我们表明了在状态转移箭头下的输入条件，和在圆圈代表的状态下FSM的输出。

\longlist{code/rising_moore_fsm.txt}{Rising edge detection with a Moore FSM.}{lst:fsm:rising:moore}

Listing~\ref{lst:fsm:rising:moore} shows the Moore version of the rising edge detection
circuit. Is uses double the number of D flip-flops than the Mealy or direct
coded version. The resulting next state logic is therefore also larger
than the Mealy or direct coded version.

列表~\ref{lst:fsm:rising:moore}表明了Moore版本的上升沿检测电路。
它使用双倍的D触发器，比Mealy或是直接的版本。
转移逻辑于是比Mealy或直接版本的更大。

\begin{figure}
  \centering
  \includegraphics[scale=1]{figures/rising}
  \caption{Mealy and a  Moore FSM waveform for rising edge detection.}
  \label{fig:rising}
\end{figure}

Figure~\ref{fig:rising} shows the waveform of a Mealy and a  Moore version
of the rising edge detection FSM. We can see that the Mealy output closely
follows the input rising edge, while the Moore output rises after the clock tick.
We can also see that the Moore output is one clock cycle wide, where the Mealy
output is usually less than a clock cycle.

图片~\ref{fig:rising}表明了Mealy和Moore版本的上升沿检测FSM。你可以看到Mealy输出紧紧跟随上升边沿，
当Moore输出在时钟tick后上升。
我们也可以看到Moore输出是一个时钟周期的宽度，而Mealy输出一般小于一个时钟周期。

From the above example, one is tempted to find Mealy FSMs the \emph{better}
FSMs as they need less state (and therefore logic) and react faster than a Moore FSM.
However, the combinational path within a Mealy machine can cause trouble in
larger designs. First, with a chain of communicating FSM (see next chapter), this
combinational path can become lengthy. Second, if the communicating FSMs build
a circle, the result is a combinational loop, which is an error in synchronous design.
Due to a cut in the combinational path with the state register in a Moore FSM,
all the above issues do not exist for communicating Moore FSMs.

从以上的例子，你可以发现Mealy FSM是\emph{更好的}，
因为它需要更少的状态（和逻辑），并比Moore FSM反应更快。
但是，在一个Mealy机器种，组合电路可能在更大规模的决定上制造麻烦。
首先，具有一串通信FSM（看下一章），这个组合通路可以很长。
其次，如果FSM的通信形成一个圆圈，会造成组合回馈，在同步设计造成错误。
由于具有状态寄存器的组合通路的一个切割形成Moore FSM，
上述的问题在Moore FSM通信不存在。

In summary, Moore FSMs combine better for communicating state machines; they
are \emph{more robust} than Mealy FSMs. Use Mealy FSMs only when the reaction within the same
cycle is of utmost importance. Small circuits such as the rising edge detection,
which are practically Mealy machines, are fine as well.

总结来说，Moore FSM在状态机间通信的组合是更好的，他们比Mealy FSM\emph{更加稳定}。
使用Mealy FSM只是当关注在相同周期的反应下更为重要。
小的电路，像是上升沿检测，
像是实际上的Mealy机，也是可以的。

\section{Exercise}

% This is a boring example, maybe I can find something more interesting
In this chapter, you have seen many examples of very small FSMs.
Now it is time to write some \emph{real} FSM code.
Pick a little bit more complex example and implement the FSM and
write a test bench for it.

% 这是一个无聊的例子，或许我可以发现一个更有兴趣的。
在这一章节，你已经看到了很多小的FSM的例子。
现在是时候写一些\emph{real}的FSM代码。
选取一些更复杂的例子，并去补充FSM和一些测试台。

A classic example for a FSM is a traffic light controller (see~\cite[Section~14.3]{dally:vhdl:2016}).
A traffic light controller has to ensure that on a switch from red to green
there is a phase in between where both roads in the intersection
have a no-go light (red and orange).
To make this example a little bit more interesting, consider a priority road.
The minor road has two car detectors (on both entries into the intersection).
Switch to green for the minor road only when a car is detected and then switch
back to green for the priority road.

一个经典FSM的例子是交通灯控制器(看~\cite[Section~14.3]{dally:vhdl:2016})。
一个交通灯控制器需要去确定从红到绿的切换，有一个状态是两条路的中间没有信号灯（红色或是橘色）。
为了使这个例子变得更有趣一些，想象一个主干道。
副路需要有两个车辆检测器（在交叉的两个入口）。
当检查到车辆的时候，在副路切换到绿灯，然后切换回主干道切换回绿灯。

\todo{Luca: Greatest common divisor with Euclide algorithm can be also a nice exercise.
Martin: but this is shown at the Chisel homepage without an FSM.}

\chapter{Communicating State Machines}

A problem is often too complex to describe it with a single FSM.
In that case, the problem can be divided into two or more smaller and simpler FSMs.
Those FSMs then communicate with signals. One FSMs output is
another FSMs input, and the FSM watches the output of the other FSM.
When we split a large FSM into simpler ones, this is called factoring FSMs.
However, often communicating FSMs are directly designed from the specification,
as often a single FSM would be infeasible large.

一个问题是，经常很复杂，去使用单一FSM去描述一个电路。
在那种情况下，这个问题可以被分为两个或是更小更简单的FSM。
这些FSM然后使用信号去通信。
一个FSM的输出是另一个FSM的输入，然后这个FSM观察了另一个FSM的输出。
当我们把一个大型FSM为简单的FSM，这个被称为分解FSM。
但是，经常来说，直接根据要求在FSM之间进行通信，
作为一个简单的FSM会是非常大的。

\section{A Light Flasher Example}

To discuss communicating FSMs, we use an example
from~\cite[Chapter~17]{dally:vhdl:2016}, the light flasher.
The light flasher has one input \code{start} and one output
\code{light}. The specification of the light flasher is as follows:
\begin{itemize}
\item when \code{start} is high for one clock cycle, the flashing
sequence starts;
\item the sequence is to flash three times;
\item where the \code{light} goes \emph{on} for six clock cycles, and the \code{light} goes \emph{off} for four clock cycles between flashes;
\item after the sequence, the FSM switches the \code{light} \emph{off} and waits
for the next start.
\end{itemize}

为了讨论FSM的通信，我们使用一个例子~\cite[Chapter~17]{dally:vhdl:2016}，灯光闪烁器/
灯光闪烁器有一个输入\code{start}和一个输出\code{light}。
灯光闪烁器像是如下:
\begin{itemize}
\item 当\code{start} 在一个周期内, 闪烁序列开始
\item 一个序列闪烁三次。
\item 当\code{light}变为\emph{on}为6个周期，\code{light}变为\emph{off}四个周期，在一次闪烁中。
\item 在序列后，FSM变为\code{light} \emph{off}，等待下一个开始。
\end{itemize}


The FSM for a direct implementation\footnote{The state diagram is shown
in~\cite[p.~376]{dally:vhdl:2016}.} has 27 states:
one initial state that is waiting for the input, $3 \times 6$ states for the three
\emph{on} states and $2 \times 4$ states for the \emph{off} states.
We do not show the code for this simple-minded implementation of the light
flasher.

FSM用于直接补充\footnote{The state diagram is shown
in~\cite[p.~376]{dally:vhdl:2016}.}有27个状态:
一个开始值是等待输入，$3 \times 6$个状态，对于前三个\emph{on}的状态，并且$2 \times 4$个状态，对于\emph{off}状态。
我们不放出这个简单的灯光闪烁器的代码。

The problem can be solved more elegantly by factoring this large FSM into
two smaller FSMs: the master FSM implements the flashing logic, and the timer FSM
implements the waiting. Figure~\ref{fig:flasher} shows the composition of
the two FSMs.

这个问题可以通过更优雅地分解大型FSM到两个小的FSM: 主FSM补充了闪烁逻辑，和计时器FSM补充了等待。
图片~\ref{fig:flasher}表明了两个FSM的组成。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/flasher}
  \caption{The light flasher split into a Master FSM and a Timer FSM.}
  \label{fig:flasher}
\end{figure}

The timer FSM counts down for 6 or 4 clock cycles to produce the desired timing.
The timer specification is as follows:

计时器FSM从6或4向下数产生想要的延迟，
时序的定义如下：

\begin{itemize}
\item when \code{timerLoad} is asserted, the timer loads a value into the down counter,
independent of the state;
\item \code{timerSelect} selects between 5 or 3 for the load;
\item \code{timerDone} is asserted when the counter completed the countdown
and remains asserted;
\item otherwise, the timer counts down.
\end{itemize}

\begin{itemize}
\item 当code{timerLoad}被插入，计时器读入数值到向下计数器，
独立于状态。
\item \code{timerSelect} 选择5或3，用于读取。
\item \code{timerDone} 信号被插入，当计数器完成了向下计数，并保持插入。
\item 否则，计时器向下数。
\end{itemize}

\noindent Following code shows the timer FSM of the light flasher:

\noindent 以下的代码表明了FSM的时序用于亮灯的闪光：

\shortlist{code/flasher_timer.txt}

\noindent Listing~\ref{lst:flasher:master} shows the master FSM.

\noindent Listing~\ref{lst:flasher:master} 表明了主FSM.

\longlist{code/flasher_fsm.txt}{Master FSM of the light flasher.}{lst:flasher:master}

\longlist{code/flasher_fsm.txt}{用于灯光闪烁器的主FSM}{lst:flasher:master}

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/flasher2}
  \caption{The light flasher split into a Master FSM, a Timer FSM, and a Counter FSM.}
  \label{fig:flasher2}
\end{figure}

This solution with a master FSM and a timer has still redundancy in the code
of the master FSM. States \code{flash1}, \code{flash2}, and \code{flash3}
are performing the same function, states \code{space1} and \code{space2} as well.
We can factor out the number of remaining flashes into a second counter.
Then the master FSM is reduced to three states: \code{off}, \code{flash},
and \code{space}.

具有一个主FSM和一个计数器的解决方案始终在主FSM有代码的冗余。
状态\code{flash1}， \code{flash2}, 和\code{flash3}完成着同样的函数，
还有状态\code{space1}和code{space2}。
我们可以其它flash装进第二个计数器。
然后主FSM被缩减到三个状态：\code{off}, \code{flash},
和 \code{space}。


Figure~\ref{fig:flasher2} shows the design with a master FSM and two FSMs
that count: one FSM to count clock cycles for the interval length of \emph{on}
and \emph{off}; the second FSM to count the remaining flashes.

图片~\ref{fig:flasher2} 表明了主FSM的设计和两个计数的FSM。
一个FSM用于计数\emph{on}和\emph{off}之间的时钟周期长度；
第二个FSM去计数剩余的闪烁。

Following code shows the down counter FSM:

以下代码表明FSM的向下计数器：

\shortlist{code/flasher2_counter.txt}

\noindent Note, that the counter is loaded with 2 for 3 flashes, as it counts the
\emph{remaining} flashes and is decremented in state \code{space} when the timer
is done. Listing~\ref{lst:flasher2:master} shows the master FSM for the double refactored flasher.

\noindent 注意到，计数器读2的时候，是闪烁三次的，因为它计数剩下的闪烁，当计时器结束的时候减少状态量。
~\ref{lst:flasher2:master}表明主FSM用于双倍闪烁。

\longlist{code/flasher2_fsm.txt}{Master FSM of the double refactored light flasher.}{lst:flasher2:master}

Besides having a master FSM that is reduced to just three states, our current solution
is also better configurable. No FSM needs to be changed if we want to change
the length of the \emph{on} or \emph{off} intervals or the number of flashes.

除了有一个缩减到三个状态的主FSM，我们目前的解决方案也是一个更好的可配置方案。如果我们想要改变\emph{on}或是\emph{off}的闪烁数量间隔，
没有FSM需要被改变。

In this section, we have explored communicating circuits, especially FSM, that
only exchange control signals. However, circuits can also exchange data.
For the coordinated exchange of data, we use handshake signals.
The next section describes the ready-valid interface for flow control of
unidirectional data exchange.

在这个部分，我们已经探索了电路间通信，特别是FSM，那个只是交换控制信号。但是，电路也交换数据。
对于调度数据的交换，我们使用握手信号。下个部分描述了对于控制流数据交换的单向ready-valid界面。

\section{State Machine with Datapath}

One typical example of communicating state machines is a state machine
combined with a datapath. This combination is often called a finite state machine
with datapath (FSMD). The state machine controls the datapath, and the datapath
performs the computation. The FSM input is the input from the environment and the input
from the datapath. The data from the environment is fed into the datapath, and the
data output comes from the datapath. Figure~\ref{fig:popcnt-fsmd} shows an example
of the combination of the FSM with the datapath.

我们的一个状态机通信的例子是具有数据通路的状态机。这个组合被称为具有数据通路的有限状态机(FSMD)。
这个状态机控制着数据通路，数据通路完成计算。这个FSM数据是来自环境的输入和来自数据通路的输入。
来自于环境的数据输入到数据通路，输出来自数据通路。Figure~\ref{fig:popcnt-fsmd}表明一个具有
数据通路的FSM组合的例子。


\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/popcnt-fsmd}
  \caption{A state machine with a datapath.}
  \label{fig:popcnt-fsmd}
\end{figure}

\subsection{Popcount Example}

The FSMD shown in Figure~\ref{fig:popcnt-fsmd} serves as an example that computes the
popcount, also called the \myref{https://en.wikipedia.org/wiki/Hamming_weight}{Hamming weight}.
The Hamming weight is the number of symbols different from the zero symbol.
For a binary string, this is the number of `1's.

FSMD在图片~\ref{fig:popcnt-fsmd}作为一个例子，去计算位1计数，
也被称为\myref{https://en.wikipedia.org/wiki/Hamming_weight}{汉明重量}。
汉明重量是一串符号中非零符号的个数。
对于二进制字符，是1的数量。

The popcount unit contains the data input \code{din} and the result output \code{popCount},
both connected to the datapath. For the input and the output we use a ready-valid handshake.
When data is available, valid is asserted. When a receiver can accept data it asserts ready.
When both signals are asserted the transfer takes place. The handshake signals are connected
to the FSM. The FSM is connected with the datapath with control signals towards the datapath
and with status signals from the datapath.

位1计数单元包含数据输入\code{din}和结果输出\code{popCount}，连接到数据通路。
对于输入和输出，我们使用ready-valid握手信号。
当数据是可用的，出现valid。当接收器可以接受数据，出现ready。
当信号都出现，开始传输信号。握手信号传给FSM。
fsm使用控制信号传入数据通路，通过来自数据通路的状态信号和控制信号。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/popcnt-states}
  \caption{State diagram for the popcount FSM.}
  \label{fig:popcnt-states}
\end{figure}

As a next step, we can design the FSM, starting with a state diagram, shown in
Figure~\ref{fig:popcnt-states}. We start in state \code{Idle}, where the FSM waits
for input. When data arrives, signaled with a valid signal, the FSM advances to state \code{Load}
to load a shift register. The FSM proceeds to the next state \code{Count}, there the number
of `1's is counted sequentially. We use a shift register, an adder, an accumulator
register, and a down counter to perform the computation. When the down counter reaches
zero, we are finished and the FSM moves to state \code{Done}. There the FSM signals with a valid
signal that the popcount value is ready to be consumed. On a ready signal from the
receiver, the FSM moves back to the \code{Idle} state, ready to compute the next popcount.

作为下一步，我们可以设计FSM, 从状态图开始，像是Figure~\ref{fig:popcnt-states}的那样。
我们从\code{Idle}状态开始，这里FSM等待输入。当数据到来的时候，数据伴随着有效信号，FSM进入到\code{Load}状态，
开始读取移位寄存器。FSM进行到下一个状态\code{Count}，这里‘1’按照顺序读取。
我们使用一个移位寄存器，一个加法器，一个累加寄存器，和一个向下计数器去完成计算。
当向下计数器到达了0，我们完成了，FSM移动到状态\code{Done}。
这里具有valid的信号的FSM，它的位1计数开始被读取。
接收到接收器的ready信号以后，FSM返回到\code{Idle}状态，开始计算下一个位1计数。

The top level component, shown in Listing~\ref{lst:pop:top} instantiates the FSM and the datapath components and connects
them with bulk connections.

顶层部分，像是~\ref{lst:pop:top}初始化了FSM和数据通路的部分，并且使用整体连线的方式进行连线。

\longlist{code/popcnt_main.txt}{The top level of the popcount circuit.
\todo{Bulk connection should be used here (and tested).}}{lst:pop:top}

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/popcnt-data}
  \caption{Datapath for the popcount circuit.}
  \label{fig:popcnt-data}
\end{figure}

Figure~\ref{fig:popcnt-data} shows the datapath for the popcount circuit.
The data is loaded into the \code{shf} register. On the load also the \code{cnt}
register is reset to 0. To count the number of `1's, the \code{shf} register is shifted
right, and the least significant bit is added to \code{cnt} each clock cycle.
A counter, not shown in the figure, counts down until all bits have been shifted
through the least significant bit. When the counter reaches zero, the popcount
has finished. The FSM switches to state \code{Done} and signals the result
by asserting \code{popCntReady}. When the result is read, signaled by asserting
\code{popCntValid} the FSW switches back to \code{Idle}.

~\ref{fig:popcnt-data}表明了位1计数电路的数据通路。
数据读入\code{shf}寄存器。在读取端，\code{cnt}被置为0。
为了计算1的数量，\code{shf}是向右移动，每个周期最低位添加到\code{cnt}。
计数器没有出现在这个图片里，向下数，直到所有的二进制位移动到最低位。
当计数器到达零的时候，计数器结束了。
FSM切换到状态0，位1计数完成了。FSM切换到状态\code{Done}，并且通过\code{popCntReady}声明信号结果。
当开始读出结果的时候，通过查看\code{popCntValid}, FSM切换回\code{Idle}。


On a \code{load} signal, the \code{regData} register is loaded with the input,
the \code{regPopCount} register reset to 0, and the counter register \code{regCount}
set to the number of shifts to be performed.

收到\code{load}信号以后，\code{regData}寄存器通过输入读取，\code{regPopCount}重置为0，
计数寄存器\code{regCount}被设为需要移位的数量。

Otherwise, the \code{regData} register is shifted to the right, the least significant bit
of the \code{regData} register added to the \code{regPopCount} register, and the counter
decremented until it is 0. When the counter is 0, the output contains the popcount.
Listing~\ref{lst:pop:data} shows the Chisel code for the datapath of the popcount
circuit.

另一方面，\code{regData}向右移动，最低位的二进制位通过\code{regData}寄存器添加到\code{regPopCount}寄存器，
计数器向下计数直到为0。当计数器数到0，输出包含位1计数。
~\ref{lst:pop:data} 表明了用于位1计数的数据通路的chisel代码。

\longlist{code/popcnt_data.txt}{Datapath of the popcount circuit.}{lst:pop:data}

The FSM starts in state \code{idle}. On a valid signal for the input data (\code{dinValid}) it
switches to the \code{count} state and waits till the datapath has finished counting.
When the popcount is valid, the FSM switches to state \code{done} and waits till the
popcount is read (signaled by \code{popCntReady}).
Listing~\ref{lst:pop:fsm} shows the code of the FSM.

FSM从状态\code{idle}开始。一旦输入(\code{dinValid})有效，它切换到状态\code{count}，
等到数据通路完成了计数。
当位1计数的结果是有效的，FSM切换到状态\code{done}，等到位1计数开始读（通过\code{popCntReady}）。
~\ref{lst:pop:fsm}表明了FSM的代码。

\longlist{code/popcnt_fsm.txt}{The FSM of the popcount circuit.}{lst:pop:fsm}

\section{Ready-Valid Interface}

\todo{Luca: This comes very sudden after all this FSM reading.
Maybe give some more context and a timing diagram.}

Communication of subsystems can be generalized to the movement
of data and handshaking for flow control. In the popcount example,
we have seen a handshaking interface for the input and the output data
using valid and ready signals.

在子系统间通信可以通过数据移动和控制流的握手信号进行归纳。
在位1计数的例子，我们已经看到了使用到valid-ready信号的输入和输出数据的握手界面。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/readyvalid}
  \caption{The ready-valid flow control.}
  \label{fig:readyvalid}
\end{figure}

The ready-valid interface~\cite[p.~480]{dally:vhdl:2016} is a simple flow
control interface consisting of \code{data} and a \code{valid} signal at the
sender side and a \code{ready} signal at the receiver side (see
Figure~\ref{fig:readyvalid}). The sender asserts \code{valid} when \code{data} is available,
and the receiver asserts \code{ready} when it is ready to receive one word
of data. The transmission of the data happens when both signals, \code{valid}
and \code{ready}, are asserted. If either of the two signals is not asserted,
no transfer takes place.

ready-valid界面~\cite[p.~480]{dally:vhdl:2016}是一个简单的控制流界面，包含了\code{data}和\code{valid}，
在发送端，\code{ready}在接收端（参见~\ref{fig:readyvalid}）。发送端声明\code{valid}，当\code{data}是有效的。
当接收端开始接收一个字长的数据，它声明了\code{ready}。当两边信号\code{valid}和\code{ready}全部被声明的时候，
数据传输开始。如果两边的信号有一边没有被声明，没有传输发生。

To make this interface composable neither \code{ready} not \code{valid} is
allowed to depend combinational on the other signal.

为了让这个界面可以被拆解，\code{ready}和\code{valid}任意一方的逻辑组合，都不允许相互依赖。

\todo{Read and cite AXI}

\chapter{Hardware Generators}

The strength of Chisel is that it allows us to write so-called hardware generators.
With older hardware description languages, such as VHDL and Verilog,
we usually use another language, e.g., Java or Python, to generate hardware.
The author has often written small Java programs to generate VHDL tables.
In Chisel, the full power of Scala (and Java libraries) is available at hardware
construction. Therefore, we can write our hardware generators in the same
language and execute them as part of the Chisel circuit generation.

chisel有力的一点使它允许我们去写所谓的硬件生成器。
有了旧的硬件描述语言，类似VHDL或是Verilog，
我们一般使用其它语言，像是Java或是Python去生成硬件。
作者经常编写小型java程序去生成vhdl网表。
在chisel，scala（和java libraries）的完整力量在硬件构建上是可行的。
于是，我们可以使用相同语言编写硬件生成器，并去执行它们，作为chisel电路的生成。

\section{Configure with Parameters}

Chisel components and functions can be configured with parameters.
Parameters can be as simple as an integer constant, but can also be a Chisel
hardware type.

chisel组成部分和函数可以通过参数被设置。
参数可以像是整数常量一样简单，但是也可以称为chisel硬件类型。

\subsection{Simple Parameters}

The basic way to parameterize a circuit is to define a bit width as a parameter.
Parameters can be passed as arguments to
the constructor of the Chisel module. Following example is a toy example of
a module that implements an adder with a configurable bit width.
The bit width \code{n} is a parameter (of Scala type \code{Int}) of the component
passed into the constructor that can be used in the IO bundle.

最基本的参数化电路的方式是去定义一个单元宽度作为参数。参数可以被传入作为chisel的构建器。
以下例子是那个模块的玩具例子，去实现一个可以参数化单元宽度的加法器。
这个参数宽度\code{n}是作为组成部分的参数(scala类型的 \code{Int})传入构建器，
可以在IO捆束使用。

\shortlist{code/param_adder.txt}

\noindent Parameterized versions of the adder can be created as follows:

\noindent 加法器的参数化版本可以像如下被创造：

\shortlist{code/use_param_adder.txt}

\subsection{Functions with Type Parameters}

Having the bit width as a configuration parameter is just the starting point for
hardware generators. A very flexible configuration is the usage of types.
That feature allows for Chisel to provide a multiplexer (\code{Mux}) that
can accept any types for the multiplexing.
To show how to use types for the configuration, we build a multiplexer
that accepts arbitrary types. Following function defines the multiplexer:

有了位宽作为参数，这是硬件生成器的开始点。一个非常复杂的设置是使用类型。
这个功能允许你使用chisel使用任何类型的输入作为复用器(\code{Mux})。
为了表明如何使用参数的类型，我们搭建了一个可以接受任何类型的复用器。
以下函数定义了复用器：

\shortlist{code/param_func.txt}

Chisel allows parameterizing functions with types, in our case with Chisel
types. The expression in the square brackets \code{[T <: Data]} defines
a type parameter \code{T} set is \code{Data} or a subclass of \code{Data}.
\code{Data} is the root of the Chisel type system.

chisel允许使用类型参数化函数，在我们的例子里是去使用chisel的类型。在方括号的表达式\code{[T <: Data]}
定义了一个参数变量\code{T}集合是\code{Data}或是\code{Data}的一个子集。
\code{Data}是chisel类型系统的根。

Our multiplexer function has three parameters: the boolean condition,
one parameter for the true path, and one parameter for the false path.
Both path parameters are of type \code{T}, an information that is
provided at function call. The function itself is straight forward:
we define a wire with the default value of \code{fPath} and
change the value is the condition is true to the \code{tPath}.
This condition is a classic multiplexer function.
At the end of the function, we return the multiplexer hardware.

我们的复用器函数有三个参数，布尔条件，一个参数用于真的通路，和一个参数用于假的通路。
两个参数属于类型\code{T}，一个信息在函数呼叫的时候被提供。
函数本身是直接的：
我们定义一个wire，具有默认值是\code{fPath}，并去改变这个值。
这个条件是一个常见的复用器函数。
在函数的末尾，我们返回复用器硬件。

We can use our multiplexer function with simple types such as
\code{UInt}:

我们可以使用复用器函数，具有简单的类型类似于\code{UInt}:

\shortlist{code/param_func_simple.txt}

\noindent The types of the two multiplexer paths need to be the same.
Following wrong usage of the multiplexer results in a runtime error:

\noindent 两个复用器线路的类型需要一致。
以下复用器的错误使用会返回一个运行时间错误：

\shortlist{code/param_func_wrong.txt}

\noindent We define our type as a \code{Bundle} with two fields:
\noindent 我们定义了我们的\code{Bundle}类型，打包进两个域：

\shortlist{code/param_func_type.txt}

\noindent We can define \code{Bundle} constants by first creating
a \code{Wire} and then setting the subfields.
Then we can use our parameterized multiplexer with this complex type.

\noindent 我们可以定义\code{Bundle}常量，通过首先创造一个\code{Wire}，然后设置子域。
然后我们可以通过这个复杂类型，来使用我们定制的复用器。

\shortlist{code/param_func_complex.txt}

In our initial design of the function, we used \code{WireInit}
to create a wire with the type \code{T} with a default value.
If we need to create a wire just of the Chisel type without using a default
value, we can use \code{fPath.cloneType} to get the Chisel type.
Following function shows the alternative way to code the multiplexer.

在我们最开始的函数设计，我们使用\code{WireInit}用于创建一个具有\code{T}的默认类型的wire。
如果我们想要创建一个只有chisel类型的weire，没有告知默认值，我们可以使用\code{fPath.cloneType}
去访问chisel的类型。
以下的函数表明了另一个方式去编写复用器。

\shortlist{code/param_func_alt.txt}

\subsection{Modules with Type Parameters}

We can also parameterize modules with Chisel types.
Let us assume we want to design a network-on-chip to move data between
different processing cores. However, we do not want to hardcode the
data format in the router interface; we want to \emph{parametrize} it.
Similar to the type parameter for a function, we add a type parameter \code{T}
to the Module constructor. Furthermore, we need to have one constructor
parameter of that type. Additionally, in this example, we also make the number
of router ports configurable.

我们也可以参数化模块，使用chisel类型。
让我们假定，我们想要设计一个noc芯片，在处理核心和数据之间移动。
但是，我们不想要在路由界面上硬编码数据类型；我们想要对其进行\emph{parametrize}。
类似于函数的参数，我们对模块的构造器添加参数\code{T}。更多地，我们需要有那个类型的构造参数。
额外地，在这个例子，我们也使路由的端口数量变得可以设置。

\shortlist{code/param_mod.txt}

\noindent To use our router, we first need to define the data type we want to route, e.g.,
as a Chisel \code{Bundle}:

\noindent 为了使用我们的路由，我们首先需要去定义我们想要路由的数据类型，例如，
像是chisel的\code{Bundle}

\shortlist{code/param_mod_type.txt}

\noindent We create a router by passing an instance of the user-defined Bundle and
the number of ports to the constructor of the router:

\noindent 我们创造了一个路由，通过传入一个自定义的bundle的实例，
并且给路由的构建器传入端口数量：


\shortlist{code/param_mod_use.txt}

\subsection{Parametrize Bundles}

In the router example, we used two different vectors of fields for the input
of the router: one for the address and one for the data, which was parameterized.
A more elegant solution would be to have a \code{Bundle} that itself
is parametrized. Something like:

在路由的例子，我们使用两个不同的矢量域作为路由的输入，一个用于地址，另一个用于数据，这个是参数化的。
一个更加优雅的解法是使用自参数化的\code{Bundle}，类似于:

\shortlist{code/param_bundle_issue.txt}

The \code{Bundle} has a parameter of type \code{T}, which is a subtype
of Chisel's \code{Data} type.
Within the bundle, we define a field \code{data} by invoking \code{cloneType}
on the parameter.
However, when we use a constructor parameter, this parameter becomes a
public field of the class. When Chisel needs to clone the type of the \code{Bundle},
e.g., when it is used in a \code{Vec}, this public field is in the way.
A solution (workaround) to this issue is to make the parameter field private:

\code{Bundle}具有类型\code{T}，是chisel的\code{Data}的子类型。
在bundle，我们定义了一个\code{data}域，通过对其类型呼叫\code{cloneType}。
但是，当我们使用构建器参数，这个参数称为类的公共域。当chisel需要复制这个\code{Bundle}的类型，
例如，当在\code{Vec}内部使用的情况下，这个公共域行不通。
这个的解决方式是把参数变为私有域。

\shortlist{code/param_bundle.txt}

\noindent With that new \code{Bundle}, we can define our router ports
\noindent 通过新的\code{Bundle}，我们可以定义我们的路由端口

\shortlist{code/param_mod2.txt}

\noindent and instantiate that router with a \code{Port} that takes
a \code{Payload} as a parameter:

\noindent 使用\code{Port}去实例化我们的路由，采取\code{Payload}作为一个参数：

\shortlist{code/param_mod_use2.txt}


\section{Generate Combinational Logic}

In Chisel, we can easily generate logic by creating a logic table with
a Chisel \code{Vec} from a Scala \code{Array}.
We might have data in a file, that we can read in during hardware generation
time for the logic table.
Listing~\ref{lst:file:reader} shows how to use the Scala \code{Source}
class form the Scala standard library to read the file ``data.txt'', which
contains integer constants in a textual representation.

在Chisel，我们可以简单生成逻辑，通过使用来自继承自scala\code{Array}的chisel\code{Vec}创建的逻辑表。
我们可能会在文件内有数据，便于我们在硬件生成逻辑表的时候读数据。
~\ref{lst:file:reader}表明了如何使用scala的scala标准library的\code{Source}类，
读出文件``data.txt''。这个包含了用于文字表示的整型常量。

一些字段可能对表达式产生隐患。

\begin{chisel}
  val table = VecInit(array.map(_.U(8.W)))
\end{chisel}

\noindent A Scala \code{Array} can be implicitly converted to a sequence (\code{Seq}),
which supports the mapping function \code{map}.
\code{map} invokes a function on each element of the sequence and returns
a sequence of the return value of the function. Our function \code{\_.U(8.W)} represents
each \code{Int} value from the Scala array as a \code{\_} and performs the conversion
from a Scala \code{Int} value to a Chisel \code{UInt} literal, with a size of 8-bits.
The Chisel object \code{VecInit} creates a Chisel \code{Vec} from a sequence \code{Seq}
of Chisel types.

\noindent scala的\code{Array}可以隐式转换到序列(\code{Seq})，
这个支持map函数\code{map}。
\code{map} 产生了一个函数，序列的每一个元素返回了一序列的函数返回值。
在我们的函数\code{\_.U(8.W)}表示来自scala 序列的每一个\code{Int}，作为\code{\_}，完成了
从scala\code{Int}到chisel\code{UInt}的表达式，具有8位的大小。
chisel的对象\code{VecInit}创建了一个chisel\code{Vec}，来自序列\code{Seq}的chisel类型。


\longlist{code/file_reader.txt}{Reading a text file to generate a logic table.}{lst:file:reader}

We can use the full power of Scala to generate our logic (tables).
E.g., generate a table of fixpoint constants to represent a trigonometric function,
compute constants for digital filters, or writing a small assembler in Scala
to generate code for a microprocessor written in Chisel. All those functions
are in the same code base (same language) and can be executed during
hardware generation.

我们可以使用scala的全部能力，去生成我们的逻辑表。
例如，生成一个表格的定点类型常量，去表示一个三角函数，
计算数字滤波器的常量，或是编写一个小的scala汇编器用来生成chisel编写的微处理器。
所有的这些函数在同一个代码库（同一个语言）并且可以在硬件生成的过程中被执行。

A classic example is the conversion of a binary number
into a \myref{https://en.wikipedia.org/wiki/Binary-coded_decimal}{binary-coded decimal}
(BCD) representation. BCD is used to represent a number in a decimal
format using 4 bits fo each decimal digit. For example, decimal \code{13} is in binary
\code{1101} and BCD encoded as 1 and 3 in binary: \code{00010011}.
BCD allows displaying numbers in decimal, a more user-friendly number
representation than hexadecimal.

一个经典的例子是二进制数转换为\myref{https://en.wikipedia.org/wiki/Binary-coded_decimal}{十进制}
(BCD)表达方式。BCD用来生成十进制格式，每个十进制的数使用4二进制位。例如，十进制\code{13}在二进制\code{1101}
，在BCD里作为1和3的二进制\code{00010011}。
BCD允许显示十进制数，是更为用户友好的数字表达形式，相比较于十六进制。

We can write a Java program that computes the table to convert binary to BCD.
That Java program prints out VHDL code that can be included in a project.
The Java program is about 100 lines of code; most of the code generating
VHDL strings. The key part of the conversion is just two lines.

我们可以编写一个Java程序用来计算表格并转换二进制到BCD。
那个Java程序打印出的VHDL代码可以在一个项目中被引用。
Java程序大概是100行代码；大多数代码是生成VHDL字符串。
最核心的转换只是两行。

With Chisel, we can compute this table directly as part of the hardware generation.
Listing~\ref{lst:bcd} shows the table generation for the binary to BCD conversion.

有了chisel，我们可以直接计算这个表格作为硬件生成的一部分。
~\ref{lst:bcd}表明了这个表格的生成，作为二进制到BCD的转换。

\longlist{code/bcd_table.txt}{Binary to binary-coded decimal conversion.}{lst:bcd}

\section{Use Inheritance}
\label{sec:inheritance}

Chisel is an object-oriented language. A hardware component, the Chisel \code{Module}
is a Scala class. Therefore, we can use inheritance to factor a common behavior
out into a parent class. We explore how to use inheritance with an example.

Chisel是一个面对对象语言。一个硬件部分，chisel的\code{Module}是一个scala的类。
于是，我们可以使用继承，去把一个共有的行为归类为父类。我们用以下例子来探索如何使用继承。

In Section~\ref{sec:counter} we have explored different forms of counters,
which may be used for a low-frequency tick generation. Let us assume we want to
explore those different versions, e.g., to compare their resource requirement.
We start with an abstract class to define the ticking interface:

~\ref{sec:counter} 我们探索了不同类型的计数器，这个可以生成低频下的tick。
我们假设，我们想要探索不同版本，例如，去比较其它资源需求。
我们开始使用一个抽象类去定义tick的界面。

\shortlist{code/ticker.txt}

\noindent Listing~\ref{lst:ticker:up} shows a first implementation of that abstract class
with a counter, counting up, for the tick generation.

\noindent ~\ref{lst:ticker:up}表明那个抽象类型，具有一个计数器，向上计数，产生tick的第一个编写方式。

\longlist{code/up_ticker.txt}{Tick generation with a counter.}{lst:ticker:up}

We can test all different versions of our \emph{ticker} logic with a single test bench.
We \emph{just} need to define the test bench to accept subtypes of \code{Ticker}.
Listing~\ref{lst:ticker:test} shows the Chisel code for the tester.
The \code{TickerTester} has several parameters: (1) the type parameter
\code{[T <: Ticker]} to accept a \code{Ticker} or any class that inherits from \code{Ticker},
(2) the design under test, being of type \code{T} or a subtype thereof,
and (3) the number of clock cycles we expect for each tick.
The tester waits for the first occurrence of a tick (the start might be different for
different implementations) and then checks that \code{tick} repeats every $n$ clock cycles.

我们可以测试所有不同的\emph{ticker}逻辑，使用一个简单的测试平台。
我们emph{只是}需要去定义测试平台去接收\code{Ticker}的子类型。
~\ref{lst:ticker:test}表明了用于测试器的chisel代码。
\code{TickerTester}有一些参数：(1)类型参数\code{[T <: Ticker]}去接受一个\code{Ticker}
或是任何一个类型去继承\code{Ticker}。
(2) 接受测试的设计，作为类型\code{T}或是其子类型。
(3) 对于每个tick，我们期待的时钟周期。
测试器等待第一个tick发生的时间（开始的时间可能根据不同的做法有所不同），然后检查tick每$n$时钟周期重复。


\longlist{code/ticker_tester.txt}{A tester for different versions of the ticker.}{lst:ticker:test}

With a first, easy implementation of the ticker, we can test the tester
itself, probably with some \code{println} debugging. When we are confident that
the simple ticker and the tester are correct, we can proceed and explore
two more versions of the ticker. Listing~\ref{lst:ticker:down} shows the tick
generation with a counter counting down to 0.
Listing~\ref{lst:ticker:nerd} shows the nerd version of counting down to -1 to use
less hardware by avoiding the comparator.

第一个，简单的ticker的做法，我们可以测试测试器本身，可能是使用一些code{println}作为debug手段。
当我们对于这个简单的ticker感到有信心，并且测试器是正确的情况下，我们可以继续探索两个ticker的版本。
~\ref{lst:ticker:down}表明tick生成器，通过向下计数，数到0。
列表~\ref{lst:ticker:nerd}表明了傻瓜版本的向下数到-1，使用更少的硬件，通过规避比较器。

\longlist{code/down_ticker.txt}{Tick generation with a down counter.}{lst:ticker:down}

\longlist{code/nerd_ticker.txt}{Tick generation by counting down to -1.}{lst:ticker:nerd}

We can test all three versions of the ticker by using ScalaTest specifications,
creating instances of the different versions of the ticker and passing them
to the generic test bench. Listing~\ref{lst:ticker:spec} shows the specification.
We run only the ticker tests with:

我们可以测试所有的3个ticker的版本，通过使用ScalaTest的要求，
创建不同版本的ticker，并把它们传入testbench本身。
列表~\ref{lst:ticker:spec}表明要求。
我们使用ticker测试，通过:

\begin{chisel}
sbt "testOnly TickerSpec"
\end{chisel}

\longlist{code/ticker_spec.txt}{ScalaTest specifications for the ticker tests.}{lst:ticker:spec}

\chapter{Example Designs}

In this section, we explore some small size digital designs, such as
a FIFO buffer, which are used as building blocks for a larger design.
As another example, we design a serial interface (also called UART),
which itself may use the FIFO buffer.

在这个部分，我们探索一些中等大小的设计，例如FIFO缓冲，这个是用于大型设计中的部分。
作为一个例子，我们会设计一个串行接口（也称UART），它本身会使用FIFO缓冲器。

\section{FIFO Buffer}
\label{sec:fifo}

We can decouple a write (sender) and a reader (receiver) by a buffer
between the writer and reader.
A common buffer is a first-in, first-out
(\href{https://en.wikipedia.org/wiki/FIFO_%28computing_and_electronics%29}{FIFO})
buffer. Figure~\ref{fig:fifo} shows a writer, the FIFO, and a reader.
Data is put into the FIFO by the writer on \code{din} with an active
\code{write} signal. Data is read from the the FIFO by the reader on
\code{dout} with an active \code{read} signal.

为了分离一个写入（发送者）和一个读取（接收者），在写和读取之间插入一些形式的缓冲。
一个常见的缓冲是一个先进先出（FIFO）缓冲器。
图7.1表明了一个写入，一个FIFO，和一个读取。数据通过din写入，和一个激活write的信号。
信号从FIFO读取通过读取dout，和一个激活read的信号。

\begin{figure}
  \centering
  \includegraphics[scale=\scale]{figures/fifo}
  \caption{A writer, a FIFO buffer, and a reader.}
  \label{fig:fifo}
\end{figure}

A FIFO is initially empty, singled by the \code{empty} signal. Reading
from an empty FIFO is usually undefined. When data is written and never
read a FIFO will become \code{full}. Writing to a full FIFO is usually ignored
and the data lost. In other words, the signals \code{empty} and \code{full}
serve as handshake signals 

FIFO初始是空的，通过empty信号表明空着。
从一个空的FIFO读取一般是没有被定义的。
当数据写入，并从来没有从FIFO读取，会变得full。
写入一个full的FIFO经常被忽略，数据随之丢失。
换句话说，empty和full充当握手信号。

Several different implementations of a FIFO are possible: E.g., using on-chip
memory and read and write pointers or simply a chain of registers with a
tiny state machine. For small buffers (up to tens of elements) a FIFO organized
with individual registers connected into a chain of buffers is a simple
implementation with a low resource requirement.
The code of the bubble FIFO is available in the
\myref{https://github.com/schoeberl/chisel-examples}{chisel-examples}
repository.\footnote{For completeness, the Chisel book repository contains
a copy of the FIFO code as well.}

可能有一些不同形式对FIFO的补充：
例如，使用片上存储，读取和写入指针或只是一连串的寄存器伴随小的状态寄存器。
对于小的缓冲器（最多十多种元素）， FIFO通过一些小的寄存器连接到一串缓冲是一个简单高效的写法。
冒泡FIFO在\myref{https://github.com/schoeberl/chisel-examples}{chisel-examples}仓库下。
\footnote{为了整体性，本书的仓库也包含了一份FIFO代码}


We start by defining the IO signals for the writer and the reader side.
The size of the data is configurable with \code{size}.
The write data are \code{din} and a write is signaled by \code{write}.
The signal \code{full} performs the
\myref{https://en.wikipedia.org/wiki/Flow_control_(data)}{flow control}
at the writer side.

我们开始定义IO信号用于写入和读出端。
数据的大小通过\code{size}设置。
写入数据是\code{din}，写入信号是\code{write}。
\code{full}作为\myref{https://en.wikipedia.org/wiki/Flow_control_(data)}{flow control}
在写入端。

\shortlist{code/bubble_fifo_writer_io.txt}

The reader side provides data with \code{dout} and the read is initiated
with \code{read}. The \code{empty} signal is responsible for the flow control
at the reader side.

读出端提供了code{dout}作为数据，读出端使用\code{read}初始化。
\code{empty}信号负责控制读出端的信号控制。

\shortlist{code/bubble_fifo_reader_io.txt}

Listing~\ref{lst:fifo:stage} shows a single buffer. The buffer has a enqueueing port
\code{enq} of type \code{WriterIO} and a dequeueing port \code{deq} of type
\code{ReaderIO}. The state elements of the buffer is one register that holds the
data (\code{dataReg} and one state register for the simple FSM (\code{stateReg}).
The FSM has only two states: either the buffer is \code{empty} or \code{full}.
If the buffer is \code{empty}, a write will register the input data and change
to the \code{full} state.
If the buffer is \code{full}, a read will consume the data and change to the
\code{empty} state.
The IO ports \code{full} and \code{empty} represent the buffer state for
the writer and the reader.

~\ref{lst:fifo:stage}表明了一个单个缓存。缓存有一个进入端口\code{enq}，具有\code{WriterIO}的类型，
和一个输出端口\code{deq}，具有\code{ReaderIO}的类型。buffer的状态元素是一个寄存器，
含有数据（\code{dataReg}和一个状态寄存器用于一个简单的FSM(\code{stateReg})。
FSM只有两个状态：当状态是\code{empty}或是\code{full}。
如果缓存位于\code{empty}，写入会寄存输入数据，并且改变到\code{full}的状态。
如果缓存位于\code{full}，读出会倒出数据，并且改变为\code{empty}状态。
IO端口\code{full}和\code{empty}代表缓存的写入和读取的状态）

\longlist{code/bubble_fifo_register.txt}{A single stage of the bubble FIFO.}{lst:fifo:stage}

Listing~\ref{lst:fifo} shows the complete FIFO. The complete FIFO has
the same IO interface as the individual FIFO buffers.
\code{BubbleFifo} has as parameters the \code{size} of the data
word and \code{depth} for the number of buffer stages.
We can build an \code{depth} stages bubble FIFO out of \code{depth}
\code{FifoRegister}s. We crate the stages by filling them into a Scala \code{Array}.
The Scala array has no hardware meaning, it \emph{just} provides us with
a container to have references to the created buffers.
In a Scala \code{for} loop we connect the individual buffers.
The first buffers enqueueing side is connected to the enqueueing IO of
the complete FIFO and the last buffer's dequeueing side to the
dequeueing side of the complete FIFO.

~\ref{lst:fifo}表明了一个完整的FIFO。完整的FIFO具有一样的IO端口，像是单独的FIFO缓存。
\code{BubbleFifo}具有数据字长的\code{size}参数，和缓存的级数\code{depth}。
我们可以搭建一个\code{depth}的阶段用于缓冲FIFO，来自\code{FifoRegister}的深度\code{depth}。
我们通过把它们装填入scala的\code{Array}。
scala的array没有任何硬件意义，它\emph{只是}提供给我们一个容器，去有创造缓存的依据。
在scala的\code{for}循环，我们连接了单独的缓存。
在第一个buffer，读入端接入完整的FIFO端口，最后一个缓存的读出端连接到完整FIFO的读出端。


\longlist{code/bubble_fifo.txt}{A FIFO is composed of an array of FIFO bubble stages.}{lst:fifo}

The presented idea of connecting individual buffers to implement a FIFO
queue is called a bubble FIFO, as the data bubbles through the queue.
This is simple, and a good solution when the data rate is considerable slower
than the clock rate, e.g., as a decouple buffer for a serial port, which is presented
in the next section.

这个展示的想法是连接独立的缓冲, 去补充一个FIFO队列, 称为冒泡FIFO, 因为数据从队列冒泡。
这个简单的解法，在数据率比时钟慢的情况下是好的，例如，用于序列端口的去耦缓冲，
在下一部分展示。

However, when the data rate approaches the clock frequency, the bubble FIFO
has two limitations: (1) As each buffer's state has to toggle between \emph{empty} and
\emph{full}, which means the maximum throughput of the FIFO is 2 clock cycles
per word. (2) The data needs to bubble through the complete FIFO, therefore,
the latency from the input to the output is at least the number of buffers.
I will present other possible implementations of FIFOs in Section~\ref{sec:more:fifo}.

但是，当数据绿达到时钟频率，冒泡FIFO有两个限制：
(1)因为每个缓存需要在\emph{empty}和\emph{full}摆动，
这意味着最大吞吐量是每个字长两个时钟周期。
(2)数据需要通过整个FIFO进行冒泡，于是，
从输入到输出的延迟至少是buffer的数量。
我会展示另外的FIFO的可能做法Section~\ref{sec:more:fifo}。

\section{A Serial Port}

A serial port (also called
\myref{https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter}{UART}
or \myref{https://en.wikipedia.org/wiki/RS-232}{RS-232}) is one of the easiest options
to communicate between your laptop and an FPGA board.
As the name implies, data is transmitted serially. An 8-bit byte is transmitted as follows:
one start bit (0), the 8-bit data, least significant bit first, and then one or two stop
bits (1). When no data is transmitted, the output is 1.
Figure~\ref{fig:uart:wave} shows the timing diagram of one byte transmitted.

一个串口(经常被称为\myref{https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter}{UART}
或是\myref{https://en.wikipedia.org/wiki/RS-232}{RS-232})是其中一个最简单的方法去连接你的电脑和FPGA板子。
像名字暗示的那样，数据串行传输。一个8位的字节按照以下传输：
从开始的0位开始，8位的数据，从最低位开始，然后是每次1到2个比特。
当没有数据传输的时候，输出是1.
图片~\ref{fig:uart:wave}表明了一个字节传输的时序图。


\begin{figure}
  \centering
  \includegraphics[scale=1]{figures/uart_wave}
  \caption{One byte transmitted by a UART.}
  \label{fig:uart:wave}
\end{figure}

We design our UART in a modular way with minimal functionality
per module. We present a transmitter (TX), a receiver (RX),
a buffer, and then usage of those base components.

我们设计我们的UART以一个模块的方式，每个模块实现最小功能。
我们呈现一个发送器(TX), 接收端(RX),
一个缓存，然后是使用这些基本的单元。

First, we need an interface, a port definition.
For the UART design, we use a ready/valid handshake interface,
with the direction as seen from the transmitter.

首先，我们需要一个界面，一个端口定义。
从UART的定义，我们使用ready/valid握手界面，
从发送端观察。

\shortlist{code/uart_channel.txt}

The convention of a ready/valid interface is that the data is transferred
when both \code{ready} and \code{valid} are asserted.

ready/valid界面的常见做法是数据当\code{ready}和\code{valid}高位的时候进行传输。

\longlist{code/uart_tx.txt}{A transmitter for a serial port.}{lst:uart:tx}

Listing~\ref{lst:uart:tx} shows a bare-bone serial transmitter (\code{Tx}).
The IO ports are the \code{txd} port, where the serial data is sent and
a \code{Channel} where the transmitter can receive the characters to serialize
and send.
To generate the correct timing, we compute a constant for by computing
the time in clock cycles for one serial bit.

列表~\ref{lst:uart:tx}表明一个准系统串行发送器(\code{Tx})。
IO端口是\code{txd}端口，这里串行数据进行发送，\code{Channel}是发送器用来接受串行和发送的数据。
为了产生正确的时序，我们计算一个常量，通过计算一个串行二进制位的时钟周期。

We use three registers:
(1) register to shift the data (serialize them) (\code{shiftReg}),
(2) a counter to generate the correct baud rate (\code{cntReg}), and
(3) a counter for the number of bits that still need to be shifted out.
No additional state register of FSM is needed, all state is encoded in
those three registers.

我们使用三个寄存器：
(1) 移动数据的寄存器(串行化)(\code{shiftReg})。
(2) 一个计数器去生成正确的波特率(\code{cntReg})，和
(3) 一个计数器用于计算需要被移动走二进制位的数量。
不需要额外的FSM状态寄存器，所有的状态在这三个寄存器编码。

Counter \code{cntReg} is continuously running (counting down to 0
and reset to the start value when 0). All action is only done when
\code{cntReg} is 0. As we build a minimal transmitter, we have only
the shift register to store the data. Therefore, the channel is only ready
when \code{cntReg} is 0 and no bits are left to shift out.

计数器\code{cntReg}持续在运行(向下数到0，数到0以后重置到开始值)。
所有的行为只有当\code{cntReg}是0的时候结束。当我们搭建一个最小的发送器，
我们只有移位寄存器去保存数据。于是，这个通道只有当\code{cntReg}是ready的，
没有剩下的二进制位需要被移走。

The IO port \code{txd} is directly connected to the least significant bit
of the shift register.

IO端口\code{txd}直接连接到移位寄存器的最小位。

When there are more bits to shift out (\code{bitsReg =/= 0.U}),
we shift the bits to the right and fill with 1 from the top (the idle level
of a transmitter).
If no more bits need to be shifted out, we check if the channel contains
data (signaled with the \code{valid} port). If so, the bit string to
be shifted out is constructed with one start bit (0), the 8-bit data, and
two stop bits (1). Therefore, the bit count is set to 11.

当存在更多二进制位去移动(\code{bitsReg =/= 0.U})，
我们移动二进制位到右边，并把它从顶部填充1（发送器的闲置）。
如果没有更多的二进制位需要被移位，我们检查一下通道是否包含数据
(通过\code{valid}端口标志信号)。
如果是这样的，留做移动的二进制字符串通过首位(0), 8位数据，和两个停止位(1)。
于是，二进制位的总数被设为11。

This very minimal transmitter has no additional buffer and can
accept a new character only when the shift register is empty
and at the clock cycle when \code{cntReg} is 0.
Accepting new data only when \code{cntReg} is 0 also means
that the ready flag is also de-asserted when there would be
space in the shift register. However, we do not want to add this
``complexity'' to the transmitter but delegate it to a buffer.

这是一个非常小的发射器，没有额外的缓存，可以接受一个新的字符，当且仅当移位寄存器是空的，
并且时钟周期是\code{cntReg}为0的情况下。
当且仅当在\code{cntReg}为0的情况下接收新的数据也意味着
当移位寄存器没有空位的时候，ready符号也会被取消。
但是，我们不想把这个复杂性添加到发射器，而是把它作为缓冲器。

\longlist{code/uart_buffer.txt}{A single-byte buffer with a ready/valid interface.}{lst:uart:buffer}
Listing~\ref{lst:uart:buffer} shows a single byte buffer, similar to
the FIFO register for the bubble FIFO. The input port is a \code{Channel}
interface, and the output is the \code{Channel} interface with
flipped directions. The buffer contains the minimal state machine
to indicate \code{empty} or \code{full}. The buffer driven handshake
signals (\code{in.ready} and \code{out.valid} depend on the state
register.

\longlist{code/uart_buffer.txt}{一个具有ready/valid界面的单字节缓冲器}{lst:uart:buffer}
列表~\ref{lst:uart:buffer}表明了一个单字节的缓冲器，
类似于FIFO寄存器，用于冒泡FIFO。输入端口是\code{Channel}界面，
输出是翻转的\code{Channel}界面。
缓冲包含最小状态机，去表明是否\code{空}还是\code{满}。
缓冲器驱动握手信号(\code{in.ready} 和 \code{out.valid} 取决于状态寄存器)。

When the state is \code{empty}, and data on the input is \code{valid},
we register the data and switch to state \code{full}.
When the state is \code{full}, and the downstream receiver is
\code{ready}, the downstream data transfer happens, and we switch
back to state \code{empty}.

当状态为\code{empty}的时候，数据输入是\code{valid}，
当我们寄存数据，状态切换到状态\code{full}。
当状态切换到\code{full}，下方的接收器是\code{ready}，向下数据传输开始，
我们切换回状态\code{empty}。

\longlist{code/uart_buffered_tx.txt}{A transmitter with an additional buffer.}{lst:uart:buffered:tx}
With that buffer we can extend our bare-bone transmitter.
Listing~\ref{lst:uart:buffered:tx} shows the combination of the transmitter \code{Tx}
with a single-buffer in front. This buffer now relaxes the issue that \code{Tx}
was \code{ready} only for single clock cycles. We delegated the solution of
this issue to the buffer module.
An extension of the single word buffer to a real FIFO can easily be done
and needs no change in the transmitter or the single byte buffer.

\longlist{code/uart_buffered_tx.txt}{带有额外缓冲器的发射器}{lst:uart:buffered:tx}
有了缓冲器，我们可以拓展我们的发射器原型。
列表~\ref{lst:uart:buffered:tx}表明了发射器的组合\code{Tx}和一个单独的缓冲器在前边。
这个缓冲器现在变为这样一个问题，\code{Tx}只有在单时钟周期是\code{ready}的。
我们现在把这个问题变为缓冲器的问题。
单字长缓冲器的拓展，对于一个真实FIFO，可以简单被完成，
并且不需要在发射器或是单字节缓冲器做出改变。

\longlist{code/uart_rx.txt}{A receiver for a serial port.}{lst:uart:rx}
Listing~\ref{lst:uart:rx} shows the code for the receiver (\code{Rx}).
A receiver is a little bit tricky, as it needs to reconstruct the timing of
the serial data. The receiver waits for the falling edge of the start bit.
From that event, the receiver waits 1.5 bit times to position itself into the middle
of bit 0. Then it shifts in the bits every bit time. You can observe these
two waiting times as \code{START\_CNT} and \code{BIT\_CNT}.
For both times, the same counter (\code{cntReg}) is used.
After 8 bits are shifted in, \code{valReg} signals an available byte

\longlist{code/uart_rx.txt}{用于串行端口的接收器}{lst:uart:rx}
列表~\ref{lst:uart:rx}表明了接收器(\code{Rx})的代码。
接收器有点需要技巧，因为它需要去重新构建串行数据的时序。
接收端等待开始位的下降沿。
从那个时刻，接收端以每次1.5二进制位的速度等待，到它本身的位置0。
然后它每次移位一个二进制位。你可以观察这两个等待时间, 通过\code{START\_CNT}和\code{BIT\_CNT}。
对于这两个时间，使用相同的计数器(\code{cntReg})。
在8位全部移动进入，\code{valReg}标志着字节有效。

\longlist{code/uart_sender.txt}{Sending ``Hello World!" via the serial port.}{lst:uart:sender}
Listing~\ref{lst:uart:sender} shows the usage of the serial port transmitter
by sending a friendly message out. We define the message in a Scala
string (\code{msg}) and converting it to a Chisel \code{Vec} of \code{UInt}.
A Scala string is a sequence that supports the \code{map} method.
The \code{map} method takes as argument a function literal, applies this function to
each element, and builds a sequence of the functions return values.
If the function literal shall have only one argument, as it is in this case, the
argument can be represented by \code{\_}. Our function literal calls
the Chisel method \code{.U} to convert the Scala \code{Char} to a Chisel
\code{UInt}. The sequence is then passed to \code{VecInint} to construct
a Chisel \code{Vec}. We index into the vector \code{text} with the counter
\code{cntReg} to provide the individual characters to the buffered transmitter.
With each \code{ready} signal we increase the counter until the full string
is sent out. The sender keeps \code{valid} asserted until the last character
has been sent out.

\longlist{code/uart_sender.txt}{通过串行端口发送"Hello World!"}{lst:uart:sender}
列表~\ref{lst:uart:sender}表明了串行端口的使用，通过发送一个友善的信息。
我们在scala字符串定义消息(\code{msg})并把它转换为chisel的一个\code{Vec}的\code{UInt}。
scala字符串是一串序列，支持\code{map}方法。yu
\code{map}方法作用于函数字面量的参数，把这个函数应用于每个元素，并且搭建一串函数，返回数值。
如果函数字面量应该有一个参数，作为这个例子，
这个参数可以通过\code{\_}表示。我们的函数字面量呼叫chisel方法\code{.U}去传唤scala的\code{Char}
变为chisel\code{UInt}。
这个序列然后传递到\code{VecInint}去构建chisel的\code{Vec}。
我们使用计数器\code{cntReg}索引向量\code{text}，去提供单一的字符到具有缓存的发送器。
每收到\code{ready}信号，我们每增加计数器，直到完整的字符串被发送。
发送方保持\code{valid}为真，直到最后的字符被发送。


\longlist{code/uart_echo.txt}{Echoing data on the serial port.}{lst:uart:echo}
Listing~\ref{lst:uart:echo} shows the usage of the receiver and the transmitter
by connecting them together. This connection generates an \code{Echo} circuit where each
received character is sent back (echoed).

\longlist{code/uart_echo.txt}{在串口端口打印数据}{lst:uart:echo}
Listing~\ref{lst:uart:echo} 表明了接收端和发送端的使用，通过将它们相连。
这个连接产生了\code{Echo}电路，这里每个接受到的字符都被返回（回声echo）。

\section{FIFO Design Variations}
\label{sec:more:fifo}.

In this section we will implement different variations of a FIFO queue.
To make these implementations interchangeable we will use inheritance,
as introduced in Section~\ref{sec:inheritance}. We define an \code{abstract}
FIFO class:

在这个部分，我们会补充一个FIFO序列的不同变量。
为了补充这些可互换量，我们会使用继承，
像是在~\ref{sec:inheritance}介绍的那样。我们定义一个\code{abstract}的FIFO类型：

\shortlist{code/fifo_abstract.txt}

\noindent Note that we use a Chisel type as parameter to be able to buffer
any Chisel data type.
In Section~\ref{sec:fifo} we defined our own types for the interface with common
names for signals, such as \code{write}, \code{full}, \code{din}, \code{read},
\code{empty}, and \code{dout}. The input and the output of such a buffer consists
of data and two signals for handshaking (e.g., we \code{write} into the FIFO when
it is not \code{full}.
However, we can generalize this handshaking to the so called ready-valid interface.
E.g, we can enqueue an element (write into the FIFO) when the FIFO is \code{ready}.
We signal this at the writer side with \code{valid}.
As this ready-valid interface is so common, Chisel provides a definition
of this interface in \code{DecoupledIO} as follows:\footnote{This is a simplification,
as \codefoot{DecoupledIO} actually extends an abstract class.}

\noindent 注意到我们使用chisel类型作为变量去缓存任何chisel数据类型。
在~\ref{sec:fifo}我们定义了我们的具有常见名称的界面类型，
例如\code{write}, \code{full}, \code{din}, \code{read}, \code{empty}和\code{dout}。
这样的缓存输入和输出包含了数据和两套握手信号(例如，当不是\code{full}的时候， 我们\code{write}入FIFO。)
但是，我们可以产生这个握手信号，作为所谓的ready-valid界面。
例如，我们可以产生一个元素（写入FIFO），当FIFO是\code{ready}。
我们使用\code{valid}作为写入端的信号。
因为这个ready-valid界面是很常见的，chisel提供了一个\code{DecoupledIO}界面，定义如下：
\footnote{这是一个简化，因为\codefoot{DecoupledIO}实际上拓展了一个抽象类型。}

\shortlist{code/fifo_decoupled.txt}

\noindent The \code{DecoupledIO} interface is defined from the writer's (producer's) view point.
Therefore, enqueue port of the FIFO needs to flip the signal directions.

\noindent \code{DecoupledIO}界面通过写入端的角度（或是产生端）的角度。
于是，FIFO的输入端需要去翻转信号的方向。

\section{Exercises}

This exercise section is a little bit longer as it contains two exercises:
(1) exploring the bubble FIFO and implement a different FIFO design;
and (2) exploring the UART and extending it.
Source code for both exercises is included in the
\myref{https://github.com/schoeberl/chisel-examples}{chisel-examples} repository.

练习部分有点长，它包含两个练习：
(1)探索冒泡FIFO，并补充一个不同的FIFO设计；
(2)探索UART并去拓展它。
两个练习的源码在\myref{https://github.com/schoeberl/chisel-examples}{chisel-examples}仓库。

\subsection{Explore FIFO Variations}

The FIFO source also includes a tester that provokes different read and write behavior and generates a waveform in the 
\myref{https://en.wikipedia.org/wiki/Value_change_dump}{value change dump (VCD)} format.
The VCD file can be viewed with a waveform viewer, such as
\myref{http://gtkwave.sourceforge.net/}{GTKWave}.
Explore the
\myref{https://github.com/schoeberl/chisel-examples/blob/master/src/test/scala/simple/FifoTester.scala}{FifoTester} in the repository.
The repository contains a \code{Makefile} to run the examples, for the FIFO example
just type:
\begin{verbatim}
$ make fifo
\end{verbatim}
This make command will compile the FIFO, run the test, and starts GTKWave for waveform
viewing. Explore the tester and the generated waveform.

FIFO也包括一个测试器，测试器包括读写操作，并生成波形文件
\myref{https://en.wikipedia.org/wiki/Value_change_dump}{value change dump (VCD)} 格式。
VCD也可以在波形观察器上查看，例如
\myref{http://gtkwave.sourceforge.net/}{GTKWave}。
查看
\myref{https://github.com/schoeberl/chisel-examples/blob/master/src/test/scala/simple/FifoTester.scala}{FifoTester} 的文件夹.
这个代码库也包含了 \code{Makefile} 用来运行例子, 例如FIFO例子
只是输入:
\begin{verbatim}
$ make fifo
\end{verbatim}
这个命令会编译FIFO，运行测试，并且从GTKWave开始查看波形。
请查看测试器和生成的波形。

In the first cycles, the tester writes a single word. We can observe in
the waveform how that word bubbles through the FIFO, therefore the
name \emph{bubble FIFO}. This bubbling also means that the
latency of a data word through the FIFO is equal to the depth of the FIFO.

在第一个周期中，测试器会写一个单词。我们可以观察到
波形该字如何通过FIFO冒泡，因此
名称\emph{bubble FIFO}。这种冒泡也意味着
数据字通过FIFO的等待时间等于FIFO的深度。

The next test fills the FIFO until it is full. A single read follows.
Notice how the empty word bubbles from the reader side of the FIFO
to the writer side. When a bubble FIFO is full, it takes
a latency of the buffer depth for a read to affect the writer side. 

下一个，是测试填充FIFO直到满，随之是一个简单的读。注意到空word如何从读到写端冒泡。
当一个冒泡FIFO是满的，它需要一个buffer深度的延迟用来读，去影响写端。

The end of the test contains a loop that tries to write and read at maximum speed.
We can see the bubble FIFO running at maximum bandwidth, which is two
clock cycles per word. A buffer stage has always to toggle between empty
and full for a single word transfer.

测试的末尾包含一个循环，试图去写入和读取，在最大的速度。
我们可以看到冒泡FIFO在最高带宽下运行，这个是每周期两个word。
一个缓冲阶段任何时候都可以在空和满状态下转递单个word。

A bubble FIFO is simple and for small buffers has a low resource requirement.
The main drawbacks of an $n$ stage bubble FIFO are: (1) maximum throughput is
one word every two clock cycles, (2) a data word has to travel $n$ clock cycles
from the writer end to the reader end, and (3) a full FIFO needs $n$ clock cycles
for the restart.

一个冒泡FIFO是简单的，对于小的缓存的资源要求低。
主要的缺点是$n$级冒泡FIFO是：
(1)最大吞吐量是每周期两个时钟周期生成一个字，
(2)一个字长需要旅行$n$时钟周期从写入端到读出端，
(3)一个完整的FIFO需要$n$时钟周期重新开始

These drawbacks can be solved by a FIFO implementation with a
\myref{https://en.wikipedia.org/wiki/Circular_buffer}{circular buffer}.
The circular buffer can be implemented with a memory and
read and write pointers.

这些缺点可以通过\myref{https://en.wikipedia.org/wiki/Circular_buffer}{环形缓冲器}
来解决。
环形缓冲可以通过存储器，读取和写入指针来解决。

Implement a FIFO as a circular buffer with four elements, using the same
interface, and explore the different behavior with the tester.
For an initial implementation of the circular buffer use, as a shortcut,
a vector of registers (\code{Reg(Vec(4, UInt(size.W)))}).

补充一个FIFO作为一个环形缓冲使用四种元素，使用相同的界面，并探索测试器下不同的行文。
对于一个最初的环形缓冲器的做法，作为一个快捷方式，
是一个向量的寄存器(\code{Reg(Vec(4, UInt(size.W)))})。

\subsection{The UART}

For the UART example, you need an FPGA board with a serial port and
a serial port for your laptop (usually with a USB connection).
Connect the serial cable between the FPGA board and the serial port on
your laptop. Start a terminal program, e.g., Hyperterm on Windows
or \code{gtkterm} on Linux:
\begin{verbatim}
$ gtkterm &
\end{verbatim}
Configure your port to use the correct device, with a USB UART this
is often something like \code{/dev/ttyUSB0}. Set the baud rate to 115200
and no parity or flow control (handshake).
With the following command you can create the Verilog code for the UART:
\begin{verbatim}
$ make uart
\end{verbatim}
Then use your synthesize tool to synthesize the design.
The repository contains a Quartus project for the DE2-115 FPGA board.
With Quartus use the play button to synthesize the design and then configure
the FPGA.
After configuration, you should see a greeting message in the terminal.

对于UART的例子，你需要一个具有串口的FPGA板子和带有串口的电脑(经常是通过USB连接)。
在FPGA板和电脑连接串口线。开始一个terminal程序，例如，windows下的hyperterm，
或是linux下的\code{gtkterm}
\begin{verbatim}
$ gtkterm &
\end{verbatim}
设置你的端口去选择正确设备，使用一个USB UART，这个经常是类似\code{/dev/ttyUSB0}。
把波特率设为114200，没有奇偶校验位或是控制流(握手信号)。
通过以下的命令行，你可以创造verilog代码用于UART：
\begin{verbatim}
$ make uart
\end{verbatim}
然后使用你的综合工具去综合设计。
仓库包含了一个Quartus项目用于DE2-115的FPGA板子。
通过Quartus点击运行按钮去综合设计，然后设置FPGA。
经过设置，你应该在terminal看到一个欢迎的消息。

Extend the blinking LED example with a UART and write 0 and 1 to the serial
line when the LED is off and on. Use the \code{BufferedTx}, as in the \code{Sender}
example.

拓展闪光LED的例子，使用一个UART，并去给串口线写0和1，当LED是关闭或是开启的时候。
使用\code{BufferedTx}，作为\code{Sender}的例子。

With the slow output of characters (two per second), you can write the data
to the UART transmit register and can ignore the read/valid handshake.
Extend the example by writing repeated numbers 0-9 as fast as the baud rate allows.
In this case, you have to extend your state machine to poll the UART status
to check if the transmit buffer is free.

有了字符的缓慢输出（每秒钟2个），你可以给UART传输寄存器写入数据，并且可以忽略read/valid握手信号。
通过重复写入数字0-9，尽波特率的最大允许速率，拓展这个例子。
在这个情况下，你需要拓展状态机去轮询UART状态，用来查看传输缓存是否空闲。

The example code contains only a single buffer for the \code{Tx}. Feel free to
add the FIFO that you have implemented to add buffering to the transmitter
and receiver. 

这个例子代码包含了只有一个缓冲用于\code{Tx}。欢迎添加你写好的FIFO，用于发送和接收的缓冲。

\chapter{Design of a Processor}

As one of the last chapters in this book, we present a medium size project:
the design, simulation, and testing of a microprocessor.
To keep this project manageable, we design a simple accumulator machine.
The processor is called \myref{https://leros-dev.github.io/}{Leros}~\cite{leros:arcs2019}
and is available in open source at \url{https://github.com/leros-dev/leros}.

作为本书的一个最后一章，我们讲述了一个中等大小的项目：设计，仿真和测试一个微处理器。
为了使这个项目科管理，我们会设计一个简单的累加器机器。
这个处理器被称为Leros，在开源 https://github.com/leros-dev/leros 可以使用。

We would like to mention that this is an advanced example and some computer
architecture knowledge is needed to follow the presented code examples.

我们想要说这是一个高阶的例子，一些计算机架构需要遵守所示代码例子。

Leros is designed to be simple, but still a good target for a C compiler.
The description of the instructions fits on one page, see Table~\ref{tab:leros:isa}.
In that table \code{A} represents the accumulator, \code{PC} is the program counter,
\code{i} is an immediate value (0 to 255), \code{Rn} a register
\code{n} (0 to 255), \code{o} a branch offset relative to the \code{PC},
and \code{AR} an address register for memory access.

Leros被设计为一个简单的，但是仍配备一个C编译器。
该指令的描述占一页，见表格8.1。
在那个表格，A代表累加器，OC使程序技术其，i使一个立即数（0到255）， Rn是一个寄存器n（0到255），
o是一个相对于PC的分支偏置，并且AR是一个地址寄存器用于存储器访问。


\begin{table}
\centering
\begin{tabular}{lll}
\toprule
Opcode & Function & Description\\
\midrule
add & A = A + Rn & Add register Rn to A \\
addi & A = A + i & Add immediate value i to A \\
sub & A = A - Rn & Subtract register Rn from A \\
subi & A = A - i & Subtract immediate value i from A \\
shr & A = A $>>>$ 1 & Shift A logically right \\
load & A = Rn & Load register Rn into A \\
loadi & A = i & Load immediate value i into A \\
and & A = A and Rn & And register Rn with A \\
andi & A = A and i & And immediate value i with A \\
or & A = A or Rn & Or register Rn with A \\
ori & A = A or i & Or immediate value i with A \\
xor & A = A xor Rn & Xor register Rn with A \\
xori & A = A xor i & Xor immediate value i with A \\
loadhi & A$_{15-8}$ = i & Load immediate into second byte \\
loadh2i & A$_{23-16}$ = i  & Load immediate into third byte \\
loadh3i & A$_{31-24}$ = i & Load immediate into fourth byte \\
store & Rn = A & Store A into register Rn \\
jal & PC = A, Rn = PC + 2 & Jump to A and store return address in Rn \\
ldaddr & AR = A & Load address register AR with A \\
loadind & A = mem[AR+(i $<<$ 2)] & Load a word from memory into A \\
loadindbu & A = mem[AR+i]$_{7-0}$  &  Load a byte unsigned from memory into A\\
storeind & mem[AR+(i $<<$ 2)] = A & Store A into memory \\
storeindb & mem[AR+i]$_{7-0}$ = A & Store a byte into memory \\
br & PC = PC + o & Branch \\
brz & if A == 0 PC = PC + o & Branch if A is zero \\
brnz & if A != 0 PC = PC + o  & Branch if A is not zero \\
brp & if A $>=$ 0 PC = PC + o & Branch if A is positive \\
brn & if A $<$ 0 PC = PC + o & Branch if A is negative \\
scall & scall A & System call (simulation hook) \\
\bottomrule
\end{tabular}
\caption{Leros instruction set.}
\label{tab:leros:isa}
\end{table}

\section{Start with an ALU}

A central component of a processor is the
\myref{https://en.wikipedia.org/wiki/Arithmetic_logic_unit}{arithmetic logic unit}, or ALU for short.
Therefore, we start with the coding of the ALU and a test bench.
First, we define an \code{Enum} to represent the different operations of the ALU:

处理器的一个中心组成部分是逻辑运算单元，或者ALU。
于是，我们从ALU和testbench开始编写。
首先，我们定义一个Enum代表ALU的不同操作：

\shortlist{code/leros_types.txt}

\noindent An ALU usually has two operand inputs (call them \code{a} and \code{b}), an operation \code{op}
(or opcode) input to select the function and an output \code{y}.
Listing~\ref{lst:leros-alu} shows the ALU.

ALU一般有两个操作数输入（称为a和b），一个操作op（或是op码）作为输入用来选择函数，和一个输出y。
图8.1表明ALU。

\todo{draw a nice ALU, see Wikipedia}

We first define shorter names for the three inputs. The \code{switch} statement defines the
logic for the computation of \code{res}. Therefore, it gets a default assignment of 0.
The switch statement enumerates all operations and assigns the expression accordingly.
All operations map directly to a Chisel expression.

我们首先定义一个短的输入名字。res的逻辑通过switch声明得到。于是，它得到一个默认值为0.
switch声明列举了所有操作，并分别赋值。所有的操作直接对应到一个Chisel表达式。

In the end, we assign the result \code{res} to the ALU output \code{y}

结尾，我们给\code{res}结果赋值ALU输出\code{y}。

\longlist{code/leros_alu.txt}{The Leros ALU.}{lst:leros-alu}

For the testing, we write the ALU function in plain Scala, as shown in Listing~\ref{lst:leros-alu-scala}.

为了测试，我们使用普通Scala函数编写了ALU函数，如下所示~\ref{lst:leros-alu-scala}。

\longlist{code/leros_alu_ref.txt}{The Leros ALU function written in Scala.}{lst:leros-alu-scala}

\noindent While this duplication of hardware written in Chisel by a Scala implementation does not
detect errors in the specification; it is at least some sanity check.
We use some corner case values as the test vector:

\noindent 使用Scala把这个Chisel硬件重写一遍不会检测出spec的错误；它只是一些合理性检验。
我们使用一些边角情况作为测试向量。

\shortlist{code/leros_alu_testvec.txt}

\noindent We test all functions with those values on both inputs:
\noindent 我们把这些值赋予输入，测试了所有的函数：

\shortlist{code/leros_alu_test.txt}

\noindent Full, exhaustive testing for 32-bit arguments is not possible, which was the reason we
selected some corner cases as input values. Beside testing against corner cases, it is also useful
to test against random inputs:

\noindent 全部，尽可能地去列举32位的参数是不可能的，这是为什么我们选取一些边角情况作为输入值。
除了测试一些边角情况，测试一些随机值也是有用的：

\shortlist{code/leros_alu_rand.txt}

\noindent You can run the tests within the Leros project with

\noindent 你可以在Leros项目中运行测试

\begin{verbatim}
$ sbt "test:runMain leros.AluTester"
\end{verbatim}

and shall produce a success message similar to:

应该会生成一个成功的消息像是如下：

\begin{verbatim}
[info] [0.001] SEED 1544507337402
test Alu Success: 70567 tests passed in 70572 cycles taking
3.845715 seconds
[info] [3.825] RAN 70567 CYCLES PASSED
\end{verbatim}

\section{Decoding Instructions}

From the ALU, we work backward and implement the instruction decoder.
However, first, we define the instruction encoding in its own Scala class and
a \emph{shared} package. We want to share the encoding constants between
the hardware implementation of Leros, an assembler for Leros, and an instruction
set simulator of Leros.

从ALU，我们向后退一步，补充指令译码器。
但是，首先，我们在它本身的scala类定义指令和一个\emph{shared}的拓展包。
我们想要在

\shortlist{code/leros_constants.txt}

\todo{Update code when Leros is more complete, as stuff is missing.}

\noindent For the decode component, we define a \code{Bundle} for the output,
which is later fed partially into the ALU.

\noindent 对于译码单元，我们定义了一个\code{Bundle}用于输出，
这个以后用于传给ALU。

\shortlist{code/leros_decode_bundle.txt}

\noindent Decode takes as input an 8-bit opcode and delivers the decoded signals
as output. Those driving signals are assigned a default value with \code{WireInit}.

\noindent 译码单元采取8位操作码作为输入，并把译码后的信号作为输出。
这些驱动信号被赋予一个默认值，通过\code{WireInit}。

\shortlist{code/leros_decode_init.txt}

\noindent The decoding itself is just a large switch statement on the part of the
instruction that represents the opcode (in Leros for most instructions the upper
8 bits.)

\noindent 译码本身是一个大的跳转声明，根据指令对应的操作码（在Leros, 指令大多根据前8位）。

\shortlist{code/leros_decode.txt}

\section{Assembling Instructions}

To write programs for Leros we need an assembler. However, for the very first
test, we can hard code a few instructions, and put them into a Scala array,
which we use to initialize the instruction memory.

要为Leros编写程序，我们需要一个汇编程序。但是，首先
测试，我们可以对一些指令进行硬编码，然后将它们放入Scala数组中，
我们用来初始化指令存储器。

\shortlist{code/leros_asm_hard.txt}

\noindent However, this is a very inefficient approach to test a processor.
Writing an assembler with an expressive language like Scala is not a big project.
Therefore, we write a simple assembler for Leros, which is possible within about
100 lines of code. We define a function \code{getProgram} that calls the assembler.
For branch destinations, we need a symbol table, which we collect in a \code{Map}.
A classic assembler runs in two passes: (1) collect the values for the symbol table
and (2) assemble the program with the symbols collected in the first pass.
Therefore, we call \code{assemble} twice with a parameter to indicate which pass it is.

\noindent 但是，这个是一个很困难的方法去测试处理器。
使用一个表达性的语言，像是scala编写一个汇编器，不是一个大的项目。
于是，我们写一个简单的汇编器用于leros，使用了不到100行的代码。
我们定义一个函数\code{getProgram}，呼叫汇编器。
对于跳转的目的地，我们需要一个符号的表格，这个在\code{Map}中被收集。
一个经典的汇编器在两个步骤：
(1)收集元素表格的值
(2)使用从第一步收集来的符号汇编程序。
于是，我们呼叫\code{assemble}两次，并使用一个参数去表明是哪个步骤。

\shortlist{code/leros_asm_call.txt}

The \code{assemble} function starts with reading in the source
file\footnote{This function does not actually read the source file, but for this
discussion we can consider it as the reading function.}
and defining two helper functions to parse the two possible operands: (1) an
integer constant (allowing decimal or hexadecimal notation) and (2) to read
a register number.

代码\code{assemble} 函数从读取源文件开始\footnote{这个函数实际上不读取源文件，
但是本次讨论中我们可以认为它读取函数}，
并定义两个辅助函数去传入两个可能的操作数：（1）一个整型常量（允许十进制和十六进制表示）
（2）读入寄存器数。

\shortlist{code/leros_asm_start.txt}

Listing~\ref{lst:leros-asm-match} shows the core of the assembler for Leros.
A Scala \code{match} expression covers the core of the assembly function.
\todo{Some more words on the code.}

~\ref{lst:leros-asm-match} 表明了汇编器的主要部分。
scala的\code{match}表达式覆盖了函数核心部分。

\longlist{code/leros_asm_match.txt}{The main part of the Leros assembler.}{lst:leros-asm-match}

\section{Exercise}

This exercise assignment in one of the last Chapters is in a very free form. You are at the end
of your learning tour through Chisel and ready to tackle design problems that
you find interesting.

最后章节的练习作业是非常自由的。你在学习Chisel旅程的末尾，并且准备解决有趣的设计难题。

One option is to reread the chapter and read along with all the source code in the
\myref{https://github.com/leros-dev/leros}{Leros repository}, run the test cases,
fiddle with the code by breaking it and see that tests fail.

其中一个选择是再次读本章节，并且读Leros仓库的源代码，运行测试案例，破坏代码，观察测试失败。

Another option is to write your implementation of Leros.
The implementation in the repository is just one possible organization of a pipeline.
You could write a Chisel simulation version of Leros with just a single pipeline stage,
or go crazy and superpipeline Leros for the highest possible clocking frequency.

另一个选择是简单写一个你对Leros的个人补充。
这个仓库的版本只是一种流水线的可能形式。
你可以写一个Chisel仿真版本的Keros使用只是一个单流水线，或者走向疯狂，尝试深度流水线的Leros，以达到最高的时钟频率的可能性。


A third option is to design your processor from scratch. Maybe the demonstration of
how to build the Leros processor and the needed tools has convinced you that processor
design and implementation is no magic art, but the engineering that can be very joyful.

第三个选择是从零设计你的处理器。
可能这个关于如何搭建Leros处理器的演示和所需要的工具已经让你感到信服：
这个处理器设计和补充不再是魔法，而可以是好玩的工程。

\chapter{Contributing to Chisel}

Chisel is an open-source project under constant development and improvement.
Therefore, you can also contribute to the project. Here we describe how to
set up your environment for Chisel library development and how to contribute
to Chisel.

Chisel是一个开源项目，在不断地开发和改进。所以，你也可以对项目做贡献。这里我们描述了如何去设置你的Chisel library开发环境，
以及如何对Chisel做贡献。

\section{Setup the Development Environment}

Chisel consists of several different repositories; all hosted at
the \myref{https://github.com/freechipsproject}{freechips organization at GitHub}.

Chisel包括了多个不同的仓库；所有在的\myref{https://github.com/freechipsproject}{freechips organization at GitHub}这里。

Fork the repository, which you like to contribute, into your personal GitHub account.
You can fork the repository by pressing the \code{Fork} button in the GitHub web interface.
Then from that fork, clone your fork of the repository. In our example, we change
\code{chisel3}, and the clone command for my local fork is:

分支你想要做贡献的仓库，到你的个人Github账户上，
你可以分支这个仓库，使用\code{Fork}按钮，在GitHub网页界面上。
然后从那个分支，clone你的repo的fork。在我们的例子，我们切换到
\code{chisel3}，clone命令到我的本地分支是：

\begin{verbatim}
$ git clone git@github.com:schoeberl/chisel3.git
\end{verbatim}

To compile Chisel 3 and publish as a local library execute:

为了编译Chisel3，和发布作为本地library，执行：

\begin{verbatim}
$ cd chisel3
$ sbt compile
$ sbt publishLocal
\end{verbatim}

Watch out during the publish local command for the version string of the published
library, which contains the string \code{SNAPSHOT}.
If you use the tester and the published version is not compatible with the Chisel
SNAPSHOT, fork and clone the \myref{https://github.com/freechipsproject/chisel-testers}{chisel-tester}
repo as well and publish it locally.

注意到在本地发布library的版本的命令行，包含了\code{SNAPSHOT}。
如果你使用测试器，发布的版本和Chisel SNAPSHOT不兼容，
要把它\myref{https://github.com/freechipsproject/chisel-testers}{chisel-tester}
也克隆下来，并且本地发布。

To test your changes in Chisel, you probably also want to set up a Chisel project,
e.g., by forking/cloning an \myref{https://github.com/schoeberl/chisel-empty}{empty Chisel project},
renaming it, and removing the \code{.git} folder from it.

为了测试你对chisel做出的改变，你可能也想要建立一个chisel对象，
例如，通过分支或是克隆\myref{https://github.com/schoeberl/chisel-empty}{空chisel项目},
重命名，并且移除来自其中的\code{.git}。

Change the \code{build.sbt} to reference the locally published version of Chisel.
Furthermore, at the time of this writing, the head of Chisel source uses Scala 2.12, but Scala
2.12 has troubles with
\myref{https://github.com/freechipsproject/chisel-template/issues/35}{anonymous bundles}.
Therefore, you need to add the following Scala option: \code{"-Xsource:2.11"}.
The \code{build.sbt} should look similar to:

改变\code{build.sbt}去引用本地版本的chisel。
更多地，在我写作的时刻，chisel源的头部使用scala 2.12, 但是scala 2.12在使用
\myref{https://github.com/freechipsproject/chisel-template/issues/35}{匿名捆束}会出现问题。
于是，你需要添加以下在scala的设置：\code{"-Xsource:2.11"}。
\code{build.sbt}应该看起来像是如下：

\begin{verbatim}
scalaVersion := "2.12.6"

scalacOptions := Seq("-Xsource:2.11")

resolvers ++= Seq(
  Resolver.sonatypeRepo("snapshots"),
  Resolver.sonatypeRepo("releases")
)

libraryDependencies +=
  "edu.berkeley.cs" %% "chisel3" % "3.2-SNAPSHOT"
libraryDependencies +=
  "edu.berkeley.cs" %% "chisel-iotesters" % "1.3-SNAPSHOT"
\end{verbatim}

Compile your Chisel test application and take a close look if it picks up the local published
version of the Chisel library (there is also a SNAPSHOT version published, so if, e.g.,
the Scala version is different between your Chisel library and your application code,
it picks up the SNAPSHOT version from the server instead of your local published
library.)

编译你的chisel测试应用，并且仔细看一下，它是否采用本地发布的chisel library(也存在一个发布的SNAPSHOT版本，
所以如果，例如，scala版本在你的chisel library和你的应用代码是有所不同的，
它会从服务器采取SNAPSHOT版本，而不是你本地发布的library)。

See also \myref{https://github.com/freechipsproject/chisel3\#for-chisel-developers}{some notes
at the Chisel repo}.

也看一下\myref{https://github.com/freechipsproject/chisel3\#for-chisel-developers}{一些chisel笔记}.


\section{Testing}

When you change the Chisel library, you should run the Chisel tests.
In an \code{sbt} based project, this is usually run with:

更改Chisel库时，应运行Chisel测试。
在基于\code{sbt的项目中，通常使用以下命令运行：

\begin{verbatim}
$ sbt test
\end{verbatim}

Furthermore, if you add functionality to Chisel, you should also provide tests for the
new features.


此外，如果您向Chisel添加功能，还应该提供针对新功能的测试。

\section{Contribute with a Pull Request}

In the Chisel project, no developer commits directly to the main repository.
A contribution is organized via a
\myref{https://help.github.com/articles/creating-a-pull-request-from-a-fork/}{pull request}
from a branch in a forked version of the library.
For further information, see the documentation at GitHub on
\myref{https://help.github.com/categories/collaborating-with-issues-and-pull-requests/}{collaboration with
pull requests}.
The Chisel group started to document
\myref{https://github.com/freechipsproject/chisel-lang-governance/blob/master/reviewer_guidelines.md}{contribution
guidelines}.

在chisel项目中，没有开发者直接对主仓库进行更新。
一次更新，是通过\myref{https://help.github.com/articles/creating-a-pull-request-from-a-fork/}{pull request}
从library的分支发动更新请求的。
对于更多的信息，参考github的文档\myref{https://help.github.com/categories/collaborating-with-issues-and-pull-requests/}{collaboration with
pull requests}。
chisel小组开始在\myref{https://github.com/freechipsproject/chisel-lang-governance/blob/master/reviewer_guidelines.md}{contribution
guidelines}进行文档。

\section{Exercise}

Invent a new operator for the \code{UInt} type, implement it in the Chisel library,
and write some usage/test code to explore the operator. It does not need to be
a useful operator; just anything will be good, e.g., a ? operator that delivers the lefthand side
if it is different from 0 otherwise the righthand side. Sounds like a multiplexer, right?
How many lines of code did you need to add?\footnote{A quick and dirty implementation
needs just two lines of Scala code.}

创造一个用于\code{UInt}类型的新操作符，把它写入chisel library，
并写下一些使用和测试代码去探索新的操作符。它不一定是一个有用的操作符；
只是无论是否有用都很好，例如，?操作符表示操作数的左手侧是否为零，否则就返回右手侧。
听起来像是复用器，对吗？
你需要添加多少行代码？
\footnote{一个快速和直接的补充只需要两行scala代码}。


As simple as this was, please be not tempted to fork the Chisel project and
add your little extensions. Changes and extension shall be coordinated with the
main developers.
This exercise was just a simple exercise to get you started.


尽管简单，请不要试图分支Chisel项目，
并添加您的小扩展。变更和扩展应与
主要开发商。
这项练习只是使您入门的简单练习。

If you are getting bold, you could pick one of the
\myref{https://github.com/freechipsproject/chisel3/issues}{open issues} and try to solve it.
Then contribute with a pull request to Chisel.
However, probably first watch the style of development in Chisel by watching the GitHub
repositories.
See how changes and pull requests are handled in the Chisel open-source project.

如果你变得有经验，你可以选取其中一个\myref{https://github.com/freechipsproject/chisel3/issues}{open issues}并且试图去解决它。
然后通过更新请求做出贡献。
但是，可能你要先去关注chisel开发的样式，通过点击github的watch。
这样你就会观察和对


\chapter{Summary}
\label{sec:conclusion}

This book presented an introduction to digital design using the
hardware construction language Chisel.
We have seen several simple to medium-sized digital circuits
described in Chisel.
Chisel is embedded in Scala and therefore inherits the powerful
abstraction of Scala.
As this book is intended as an introduction, we have restricted
our examples to simple uses of Scala.
A next logical step is to learn a few basics of Scala and apply them
to your Chisel project.

本书介绍了使用
硬件构造语言Chisel。
我们已经看到了几种简单到中型的数字电路
在Chisel中描述。
Chisel嵌入在Scala中，因此继承了强大的功能
Scala的抽象。
由于本书旨在作为介绍，因此我们限制了
我们的示例简单介绍了Scala的用法。
下一步的逻辑步骤是学习Scala的一些基础知识并将其应用
到您的Chisel项目中。

I would be happy to receive feedback on the book, as I will further
improve it and will publish new editions. You can contact me at
\url{mailto:masca@dtu.dk}, or with an issue request on the GitHub
repository. I am also happily accepting pull requests
for the book repository for any fixes and improvements.

能收到反馈，我会非常高兴的，并且我会进一步加强，并推出新版本。
你可以通过\url{mailto:masca@dtu.dk}联系我，或是在github提出issue。
我会很高兴接受书目录的pull request，用于任何的更正和改进。

\section*{Source Access}

This book is available in open source.
The repository also contains slides for a Chisel course and
all Chisel examples: \url{https://github.com/schoeberl/chisel-book}

这本书是开源的。
这个目录也包含了其它的chisel课程的演示内容，以及所有的chisel例子：
\url{https://github.com/schoeberl/chisel-book}

A collection of medium-sized examples, which most are referenced
in the book, is also available in open source. This collection
also contains projects for various popular FPGA boards:
\url{https://github.com/schoeberl/chisel-examples}

在这本书受到最多的引用的一系列中等大小的例子，也是开源的。
这个系列也包含了用于各种不同的FPGA例子的项目：
\url{https://github.com/schoeberl/chisel-examples}

\appendix

\chapter{Chisel Projects}

Chisel is not (yet) used in many projects. Therefore, open-source Chisel code
to learn the language and the coding style is rare. Here we list several projects
we are aware of that use Chisel and are in open source.

尚未在许多项目中使用Chisel。因此，开源的Chisel代码
学习语言和编码风格的情况很少。这里我们列出了几个项目
我们知道使用Chisel是开源的。

\begin{description}

\item[\myref{https://github.com/chipsalliance/rocket-chip}{Rocket Chip}]
is a \myref{https://en.wikipedia.org/wiki/RISC-V}{RISC-V}~\cite{risc-v}
processor-complex generator that comprises the Rocket
microarchitecture and TileLink interconnect generators.  Originally developed
at UC Berkeley as the first chip-scale Chisel project~\cite{rocket:techrep}, Rocket Chip is now
commercially supported by \myref{https://www.sifive.com/}{SiFive}.
%The codebase at SiFive serves as a major test bench for Chisel and new Chisel features
%need to pass the tests at SiFive.

\item[\myref{https://github.com/chipsalliance/rocket-chip}{Rocket Chip}]
是\myref{https://en.wikipedia.org/wiki/RISC-V}{RISC-V}~\cite{risc-v}
复杂处理器生成器， 包括rocket微处理器和TileLink连接生成器。 
最早在UC Berkeley被开发出来，作为芯片大小的Chisel项目~\cite{rocket:techrep}，
Rocket芯片现在被\myref{https://www.sifive.com/}{SiFive}商业支持。
%该代码框架是作为Chisel的主要测试平台，新的Chisel特性必须通过Sifive的测试。


\item[\myref{https://github.com/ucb-bar/riscv-sodor}{Sodor}] is a collection of RISC-V
implementations intended for educational use. It contains 1, 2, 3, and 5 stages pipeline
implementations. All processors use a simple scratchpad memory shared by instruction
fetch, data access, and program loading via a debug port. Sodor is mainly intended to
be used in simulation.

\item[\myref{https://github.com/ucb-bar/riscv-sodor}{Sodor}]是一套RISC-V的搭建，教育专用。
它包含1，2，3和5级流水线的搭建。所有的处理器使用一个简单的暂存存储器，被指令读取，数据读取，和debug端口程序所共享。
Sodor主要是用来仿真。

\item[\myref{https://github.com/t-crest/patmos}{Patmos}] is an implementation of a
processor optimized for real-time systems~\cite{patmos:rts2018}. The Patmos repository
includes several multicore communication architectures, such as a time-predictable memory
arbiter~\cite{t-crest:memnoc}, a network-on-chip~\cite{s4nocni:arcs2019}
a shared scratchpad memory with an ownership~\cite{t-crest:ownspm}.
At the time of this writing, Patmos is still described in Chisel 2.

\item[\myref{https://github.com/t-crest/patmos}{Patmos}] 是一个为实时系统而补充的处理器~\cite{patmos:rts2018}.
Patmos仓库包括多核通信的架构，例如时间可预测的存储器arbiter~\cite{t-crest:memnoc}
, 一个片上网络~\cite{s4nocni:arcs2019}
一个有版权的共享网络的存储器~\cite{t-crest:ownspm}.
在我写这本书的时候，Patmos仍然使用Chisel2进行描述。

\item[\myref{https://github.com/pretis/flexpret}{FlexPRET}] is an implementation of a
precision timed architecture~\cite{Zimmer:EECS-2015-181}. FlexPRET implements
the RISC-V instruction set and has been updated to Chisel 3.1.

\item[\myref{https://github.com/pretis/flexpret}{FlexPRET}] 是一个实时系统架构的补充
~\cite{Zimmer:EECS-2015-181}. FlexPRET补充了RISC-V指令集架构，并且升级到了Chisel3.1。

\item[\myref{https://github.com/schoeberl/lipsi}{Lipsi}] is a tiny processor intended
for utility functions on a system-on-chip~\cite{lipsi:arcs2018}. As the code base of
Lipsi is very small, it can serve as an easy starting point for processor design in Chisel.
Lipsi also showcases the productivity of Chisel/Scala. It took me 14 hours to describe the
hardware in Chisel and run it on an FPGA, write an assembler in Scala, write a
Lipsi instruction set simulator in Scala for co-simulation, and write a few test cases
in Lipsi assembler.

\item[\myref{https://github.com/schoeberl/lipsi}{Lipsi}]是一个小型处理器，用于工具性函数，在system-on-chip~\cite{lipsi:arcs2018}。
作为Lipsi的代码库是很小的，它可以作为使用chisel设计处理器的起始点。Lipsi也可以作为chisel生产力的代表。它花费了我14个小时去使用chisel描述硬件，
在fpga上运行它，使用scala编写汇编，写了一个Lipsi指令集模拟器作为协仿真，并写了一些测试例子用于Lipsi汇编。

\item[\myref{http://www.opensocfabric.org/}{OpenSoC Fabric}] is an open-source NoC
generator written in Chisel~~\cite{OpenSoC:ispass2016}. It is intended to provide a
system-on-chip for large-scale design exploration. The NoC itself is a state-of-the-art design with wormhole routing, credits for flow control, and virtual channels.
OpenSoC Fabric is still using Chisel~2.

\item[\myref{http://www.opensocfabric.org/}{OpenSoC Fabric}] 是一个开源NoC生成器，通过chisel~~\cite{OpenSoC:ispass2016}进行编写。
它是用来提供一个片上系统的大型设计探索。NoC本身是使用虫孔路由的当代设计，为控制流，和虚拟通道创造贡献。
OpenSoC Fabric仍然使用chisel2。


\item[\myref{https://github.com/bu-icsg/xfiles-dana}{DANA}] is a neural network accelerator
that integrates with the RISC-V Rocket processor using the Rocket Custom Coprocessor (RoCC) interface~\cite{RoCC:2015}.
DANA supports inference and learning.

\item[\myref{https://github.com/bu-icsg/xfiles-dana}{DANA}] 是一个神经网络加速器，整合了RISCV Rocket处理器，
使用Rocket Custom Coprocessor(RoCC)接口~\cite{RoCC:2015}。DANA支持推理和学习。

\end{description}

If you know an open-source project that uses Chisel, please drop me a note
so I can include it in a future edition of the book.

如果您知道使用Chisel的开源项目，请给我留言
因此我可以将其包含在本书的未来版本中。

\chapter{Chisel 2}

This book covers version 3 of Chisel. Moreover, Chisel 3 is recommended for new designs.
However, there is still Chisel 2 code out in the wild, which has not yet been converted
to Chisel 3. There is documentation available on how to convert a Chisel 2 project to
Chisel 3:


本书涵盖了Chisel的第3版。此外，Chisel3建议用于新设计。
但是，仍然有大量的Chisel2代码，尚未转换
到Chisel3。有有关如何将Chisel2项目转换为Chisel2的文档。
Chisel3：

\begin{itemize}
\item \myref{https://github.com/freechipsproject/chisel3/wiki/Chisel3-vs-Chisel2}{Chisel2 vs. Chisel3} and
\item \myref{https://github.com/schoeberl/chisel-examples/blob/master/TowardsChisel3.md}{Towards Chisel 3}
\end{itemize}


However, you might get involved in a project that still uses Chisel 2,
e.g., the \myref{https://github.com/t-crest/patmos}{Patmos}~\cite{patmos:rts2018} processor.
Therefore, we provide here some information on Chisel 2 coding for those who
have started with Chisel 3.

但是，你可能加入一个仍旧使用chisel2的项目，
例如，\myref{https://github.com/t-crest/patmos}{Patmos}~\cite{patmos:rts2018}处理器。
于是，我们在这里提供一些chisel2的信息，为这些是以chisel3为起点的。

First, all documentation on Chisel 2 has been removed from the web sites
belonging to Chisel. We have rescued those PDF documents and put them
on GitHub at \url{https://github.com/schoeberl/chisel2-doc}.
You can use the Chisel 2 tutorial by switching to the Chisel 2 branch:

首先，所有chisel2的文档官网上被移除了。我们保留了这些文档，并把它放在github上，
在\url{https://github.com/schoeberl/chisel2-doc}。
你可以使用chisel2教程，通过切换到chisel2的分支：

\begin{chisel}
$ git clone https://github.com/ucb-bar/chisel-tutorial.git
$ cd chisel-tutorial
$ git checkout chisel2
\end{chisel}

The main visible difference between Chisel 3 and 2 are the definitions of
constants, bundles for IO, wires, memories, and probably older forms of register
definitions.

Chisel3和2之间的主要可见区别是
常量，用于IO的捆束，电线，存储器以及可能是较旧形式的寄存器
定义。

Chisel 2 constructs can be used, to some extent, in a Chisel 3 project by
using the compatibility layer using as package \code{Chisel} instead of \code{chisel3}.
However, using this compatibility layer should only be used in a transition phase.
Therefore, we do not cover it here.

chisel2构建出的模块，在某种程度上，在chisel3项目中使用兼容层使用像是\code{Chisel}拓展包，而不是\code{Chisel3}拓展包。
无论如何，使用兼容层应该只用来转换的过度。于是，我们在这里不讨论。

Here are two examples of basic components, the same that have been presented
for Chisel 3. A module containing combinational logic:

有两个基础构成的例子，在Chisel3的版本里同样被演示过。一个包含组合逻辑的模块：

\shortlist{chisel2/src/main/scala/Logic.scala}

Note that the \code{Bundle} for the IO definition is \emph{not} wrapped into
an \code{IO()} class.  Furthermore, the direction of the different IO ports is defined
as part of the type definition, in this example as \code{INPUT} and \code{OUTPUT}
as part of \code{UInt}. The width is given as the second parameter.

注意到这个\code{Bundle}用来定义IO是\emph{not}被包裹进\code{IO()}类。更多的， 不同的IO端口的方向作为类型的定义，
在这个例子里作为\code{INPUT}和\code{OUTPUT}，作为\code{UInt}的一部分。宽度作为第二参数提供。

\begin{minipage}{\linewidth}
The 8-bit register example in Chisel 2:

Chisel2的8位寄存器例子：

\shortlist{chisel2/src/main/scala/Register.scala}
\end{minipage}

Here you see a typical register definition with a reset value passed in as
a \code{UInt} to the named parameter \code{init}. This form is still valid in Chisel 3,
but the usage of \code{RegInit} and \code{RegNext} is recommended for new Chisel 3 designs.
Note also here the constant definition of an 8-bit wide 0 as \code{UInt(0, 8)}.

这里你看到一个伴随着复位值的典型寄存器定义，作为\code{UInt}在\code{init}下。这个形式在Chisel 3是仍旧有效的，
但是使用\code{RegInit}和\code{RegNext}是被推荐的，在新的Chisel3设计中。注意到这里，8位常量的0被定义为\code{UInt(0, 8)}。

Chisel based testing C++ code and Verilog code are generated by calling \code{chiselMainTest}
and \code{chiselMain}. Both ``main'' functions take a \code{String} array for further parameters.

以Chisel为基础的C++和Verilog的代码，是通过\code{chiselMainTest}和\code{chiselMain}生成的。 两个``main''函数采用\code{String}作为更多的参数。

\shortlist{chisel2/src/main/scala/LogicTester.scala}

\shortlist{chisel2/src/main/scala/LogicHardware.scala}

A memory with sequential registered read and write ports is defined in Chisel 2 as:

一个拥有时序寄存器的读写寄存器端口，在Chisel2被定义为：

\begin{chisel}
  val mem = Mem(UInt(width = 8), 256, seqRead = true)
  val rdData = mem(Reg(next = rdAddr))
  when(wrEna) {
    mem(wrAddr) := wrData
  }
\end{chisel}

\bibliographystyle{plain}
\bibliography{chisel}

\end{document}

\chapter{Headings}

\todo{Collect the headings here, but only elevate them to chapter level when some
writing is going on.}

\section{Introduction}

 * Why Chisel, what is cool about it
 * What this book is (and what not)
 * Overview of the following Chapters

\section{Basic Circuits}

 * Combinational expressions (basic gates with logic tables)
 * Combinational base circuits (chapter 8 in Culler)
 * Multiplexer (just the simple one for a start)
 * Registers

1. base functions: +, - , and or, register (with reset, with enable)


\section{Build Process and Testing}

 * A full example (blinking LED again)
 * Packages
 * Source organization (Scala)
 * Object to generate Verilog
 * Testing
 * sbt

\section{Components/Modules}

\section{Building Blocks}

 * building blocks (adder, mux, ALU, counter, memory)
 * maybe split into combinational and sequential

 * 搭建模块（加法器，复用器，ALU，计数器，存储器）
 * 可能会分为组合和时序逻辑

\section{Bundles and Vecs (better title needed)}

\section{Medium Complex Circuits (better title needed)}

3. small designs (better name): UART, FIFO, PWM, VGA, sigma delta


\section{State Machines and Data Path}

 * Covered in stuff for Dally book lecture spring 2019

 *

\section{Memory}

 * Vec based ROM with address register
 * Vec based read/write
 * All other variations
 * Escape code in VHDL and Verilog for unsupported memories


 *
 *
 *
 *

\section{Tips and Tricks (better title needed)}

Stuff that saves a little hardware, but might not worse the less readable code

 * Counter to -1
 * Shared adder and subtractor
 * Mux with one hot encoding of select
 * little tricks: count down, add/sub

 *
 *
 *
 *



\section{Scala for Hardware Developers}

 * Simple Scala (for, if else)
 * functions for hardware generation
 * Classes and constructor

 *
 *
 *
 
 \section{More Complex Testing}
 
  * As we know now sone Scala it is time to use the power of Scala for better testing

  *

\section{Hardware Generation}

 * More advanced stuff
 * Table generation (sinus, assembler)

  *
  *
 
 \section{Leros}
 
  * as a more complex design
  4. full design(s): processor

  *
  *

\section{Chisel 2}

 * Some notes for reading Chisel 2 code
 * Update Lipsi to Chisel 3 to work on the 2 to 3 documentation

  *
  *
 
 \section{Chisel Projects}
 
  * Projects written in Chisel, as paper reference, some words and a URL.
  * 使用Chisel编写的项目，作为纸质引用，一些words和一个URL

\section{Appendix}

 * Basic digital circuits, e.g., transistor based inverter, half and full adder
 * With lot of links to Wikipedia

 * 基本的数字电路，例如，晶体为基础的反相器，半加器和全加器 
 * 和很多Wiki的链接



\end{document}