3.5_object_oriented_programming.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"top\"></a><img src=\"images/chisel_1024.png\" alt=\"Chisel logo\" style=\"width:480px;\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Module 3.5: Object Oriented Programming | 面向对象编程\n",
    "**Prev:上一小节： [Functional Programming | 函数式编程](3.4_functional_programming.ipynb)**<br>\n",
    "**Next:下一小节： [Types | 类型](3.6_types.ipynb)**\n",
    "\n",
    "## Motivation | 动机\n",
    "Scala and Chisel are object-oriented programming languages, meaning code may be compartmentalized into objects.\n",
    "Scala, which is built on Java, inherits many of Java's object-oriented features.\n",
    "However, as we'll see below, there are some differences. \n",
    "Chisel's hardware modules are similar to Verilog's modules, in that they can be instantiated and wired up as single or multiple instances.\n",
    "\n",
    "Scala 以及 Chisel 都是面向对象编程语言，这意味着代码可以划分为对象。\n",
    "Scala 建立在 Java 之上，传承了很多 Java 的面向对象特性。\n",
    "然而，这也有一些区别。我们将在后面看到。\n",
    "Chisel的硬件模块在被声明、单个或多个连接方面，与 Verilog 的模块相似。\n",
    "\n",
    "## Setup | 设置"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "val path = System.getProperty(\"user.dir\") + \"/source/load-ivy.sc\"\n",
    "interp.load.module(ammonite.ops.Path(java.nio.file.FileSystems.getDefault().getPath(path)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import chisel3._\n",
    "import chisel3.util._\n",
    "import chisel3.iotesters.{ChiselFlatSpec, Driver, PeekPokeTester}\n",
    "import chisel3.experimental._"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "# Object Oriented Programming | 面向对象编程\n",
    "This section outlines how Scala implements the object-oriented programming paradigm. So far you have already seen classes, but Scala also has the following features: \n",
    "\n",
    "这个小节简单描述了 Scala 是怎样实现面向对象编程的范例。虽然到目前为止，你已经见到了不少类，但是 Scala 也有如下的特指：\n",
    "- [Abstract classes | 抽象类](#abstract)\n",
    "- [Traits | 特质](#traits)\n",
    "- [Objects | 对象](#objects)\n",
    "- [Companion Objects | 伴生对象](#compobj)\n",
    "- [Case Classes | 案例类](#caseclass)\n",
    "\n",
    "## Abstract Classes | 抽象类<a name=\"abstract\"></a>\n",
    "Abstract classes are just like other programming language implementations. They can define many unimplemented values that subclasses must implement. Any object can only directly inherit from one parent abstract class. \n",
    "\n",
    "抽象类与其他编程语言实现相同，他们可以定义很多还没有实现的值，但是它的子类需要实现。任何一个对象都只能直接地继承于一个父抽象类。\n",
    "\n",
    "<span style=\"color:blue\">**Example: Abstract Class | 举例：抽象类**</span><br>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "abstract class MyAbstractClass {\n",
    "  def myFunction(i: Int): Int\n",
    "  val myValue: String\n",
    "}\n",
    "class ConcreteClass extends MyAbstractClass {\n",
    "  def myFunction(i: Int): Int = i + 1\n",
    "  val myValue = \"Hello World!\"\n",
    "}\n",
    "// Uncomment below to test! \n",
    "// 取消下面的注释再试试看！\n",
    "// val abstractClass = new MyAbstractClass() // Illegal! Cannot instantiate an abstract class \n",
    "                                             // 非法！不能实例化一个抽象类\n",
    "val concreteClass = new ConcreteClass()      // Legal! 合法！\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Traits | 特质<a name=\"traits\"></a>\n",
    "Traits are very similar to abstract classes in that they can define unimplemented values. However, they differ in two ways: \n",
    "- a class can inherit from multiple traits \n",
    "- a trait cannot have constructor parameters \n",
    "\n",
    "特质在定义未实现的值方面与抽象类很像。但是，他们在两方面有区别：\n",
    "- 一个类可以继承多个特质\n",
    "- 一个特质不能有构造变量\n",
    "\n",
    "<span style=\"color:blue\">**Example: Traits and Multiple Inheritance | 举例：特质和多继承**</span><br>\n",
    "Traits are how Scala implements multiple inheritance, as shown in the example below. `MyClass` extends from both traits `HasFunction` and `HasValue`: \n",
    "\n",
    "特质是在 Scala 中实现多继承的方法，就像下面的例子一样，`MyClass` 继承了 `HasFunction` 和 `HasValue` 两个特质"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "trait HasFunction {\n",
    "  def myFunction(i: Int): Int\n",
    "}\n",
    "trait HasValue {\n",
    "  val myValue: String\n",
    "  val myOtherValue = 100\n",
    "}\n",
    "class MyClass extends HasFunction with HasValue {\n",
    "  override def myFunction(i: Int): Int = i + 1\n",
    "  val myValue = \"Hello World!\"\n",
    "}\n",
    "// Uncomment below to test! 取消下面的注释再试试看！\n",
    "// val myTraitFunction = new HasFunction() // Illegal! Cannot instantiate a trait \n",
    "                                           // 非法！不能实例化一个特质\n",
    "// val myTraitValue = new HasValue()       // Illegal! Cannot instantiate a trait \n",
    "                                           //非法！不能实例化一个特质\n",
    "val myClass = new MyClass()                // Legal! 合法！"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To inherit multiple traits, chain them like \n",
    "\n",
    "如果要继承多个类，像下面这样把它们串起来\n",
    "\n",
    "```scala\n",
    "class MyClass extends HasTrait1 with HasTrait2 with HasTrait3 ...\n",
    "```\n",
    "In general, always use traits over abstract classes, unless you are certain you want to enforce the single-inheritance restriction of abstract classes. \n",
    "\n",
    "总的来说，除非你确认你想要使用抽象类的单个继承约束，不然建议使用特质而不是抽象类。\n",
    "\n",
    "## Objects | 对象<a name=\"objects\"></a>\n",
    "Scala has a language feature for these singleton classes, called objects. You cannot instantiate an object **(no need to call `new`)**; you can simply directly reference it. That makes them similar to Java static classes. \n",
    "\n",
    "对于这些单独的类，Scala 有一个语言特性，叫做对象。你不能实例化一个对象 **不需要声明 `new` **；你可以简单地引用它。这就与 Java 的静态类很相似。\n",
    "\n",
    "<span style=\"color:blue\">**Example: Objects | 举例：对象**</span><br>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "object MyObject {\n",
    "  def hi: String = \"Hello World!\"\n",
    "  def apply(msg: String) = msg\n",
    "}\n",
    "println(MyObject.hi)\n",
    "println(MyObject(\"This message is important! 这个信息很重要！\")) // equivalent to MyObject.apply(msg) 等同于 MyObject.apply(msg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Companion Objects | 伴生对象<a name=\"compobj\"></a>\n",
    "\n",
    "When a class and an object share the same name and defined in the same file, the object is called a **companion object**. When you use `new` before the class/object name, it will instantiate the class. If you don't use `new`, it will reference the object: \n",
    "\n",
    "当一个类与一个对象名字相同并且在同一个文件里面定义时，对象被称作**伴生对象**。当你在这个类/对象的名字前使用 `new` 时，它将会实例化类。如果你不使用 `new`，那么这将会引用对象。\n",
    "\n",
    "<span style=\"color:blue\">**Example: Companion Object | 举例：伴生对象**</span><br>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "object Lion {\n",
    "    def roar(): Unit = println(\"I'M AN OBJECT!\")\n",
    "}\n",
    "class Lion {\n",
    "    def roar(): Unit = println(\"I'M A CLASS!\")\n",
    "}\n",
    "new Lion().roar()\n",
    "Lion.roar()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Companion objects are usually used for the following reasons: \n",
    "  1. to contain constants related to the class\n",
    "  2. to execute code before/after the class constructor\n",
    "  3. to create multiple constructors for a class\n",
    "  \n",
    "In the example below, we will instantiate a number of instances of Animal. We want each animal to have a name, and to know its order within all instantiations. Finally, if no name is given, it should get a default name. \n",
    "  \n",
    "伴生对象经常由于下列的原因使用：\n",
    "  1. 包含类相关的常数\n",
    "  2. 在类构造体之前/之后执行一些代码\n",
    "  3. 为一个类创造多个构造体\n",
    "\n",
    "在下面这个例子中，我们将会实例化一些动物的实例。我们想要让每一个动物都有一个名字，并且知道它在所有实例化中的顺序。最后，如果它没有名字的话，那么它应该得到一个默认名字。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "object Animal {\n",
    "    val defaultName = \"Bigfoot\"\n",
    "    private var numberOfAnimals = 0\n",
    "    def apply(name: String): Animal = {\n",
    "        numberOfAnimals += 1\n",
    "        new Animal(name, numberOfAnimals)\n",
    "    }\n",
    "    def apply(): Animal = apply(defaultName)\n",
    "}\n",
    "class Animal(name: String, order: Int) {\n",
    "  def info: String = s\"Hi my name is $name, and I'm $order in line!\"\n",
    "}\n",
    "\n",
    "val bunny = Animal.apply(\"Hopper\") // Calls the Animal factory method 调用 Animal 工厂方法\n",
    "println(bunny.info)\n",
    "val cat = Animal(\"Whiskers\")       // Calls the Animal factory method 调用 Animal 工厂方法\n",
    "println(cat.info)\n",
    "val yeti = Animal()                // Calls the Animal factory method 调用 Animal 工厂方法\n",
    "println(yeti.info)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*What's happening here? *\n",
    "\n",
    "- Our **Animal companion object** defines a constant relevant to ```class Animal```: \n",
    "```scala\n",
    "val defaultName = \"Bigfoot\"\n",
    "```\n",
    "- It also defines a private mutable integer to keep track of the order of Animal instances: \n",
    "```scala \n",
    "private var numberOfAnimals = 0\n",
    "```\n",
    "- It defines two **apply** methods, which are known as **factory methods** in that they return instances of the **class Animal**. \n",
    "\n",
    "    - The first creates an instance of Animal using only one argument, ```name```, and uses ```numberOfAnimals``` as well to call the Animal class constructor.\n",
    "\n",
    "    ```scala\n",
    "    def apply(name: String): Animal = {\n",
    "                numberOfAnimals += 1\n",
    "                new Animal(name, numberOfAnimals)\n",
    "    }\n",
    "    ```\n",
    "    - The second factory method requires no argument, and instead uses the default name to call the other apply method. \n",
    "    ```scala\n",
    "    def apply(): Animal = apply(defaultName)\n",
    "    ```\n",
    "- These factory methods can be called naively like this \n",
    "```scala\n",
    "val bunny = Animal.apply(\"Hopper\")\n",
    "```\n",
    "which eliminates the need to use the new keyword, but the real magic is that the compiler assumes the apply method any time it sees parentheses applied to an instance or object: \n",
    "```scala\n",
    "val cat = Animal(\"Whiskers\")\n",
    "```\n",
    "- Factory methods, usually provided via companion objects, allow alternative ways to express instance creations, provide additional tests for constructor parameters, conversions, and eliminate the need to use the keyword ```new```. Note that you must call the companion object's `apply` method for `numberOfAnimals` to be incremented. \n",
    "\n",
    "**Chisel uses many companion objects, like Module.** When you write the following: \n",
    "```scala\n",
    "val myModule = Module(new MyModule)\n",
    "```\n",
    "you are calling the **Module companion object**, so Chisel can run background code before and after instantiating \n",
    "```MyModule```.\n",
    "\n",
    "*这发生了什么呢? *\n",
    "\n",
    "- 我们的 **Animal 伴生对象**定义了一个与 ```class Animal``` 有关的常量：\n",
    "\n",
    "```scala\n",
    "val defaultName = \"Bigfoot\"\n",
    "```\n",
    "\n",
    "- 这也定义了一个私有的可变整数以得到实例化的顺序：\n",
    "```scala \n",
    "private var numberOfAnimals = 0\n",
    "```\n",
    "- 它定义了两个 **apply** 方法，也称为**工厂方法**因为他们返回 **class Animal** 的实例。\n",
    "    \n",
    "    - 第一个创建了一个使用了一个参数的立即声明，```name```，并且使用 ```numberOfAnimals``` 调用 Animal 类构造器。\n",
    "\n",
    "    ```scala\n",
    "    def apply(name: String): Animal = {\n",
    "                numberOfAnimals += 1\n",
    "                new Animal(name, numberOfAnimals)\n",
    "    }\n",
    "```\n",
    "    \n",
    "    - 第二个工厂方法不需要参数，而是使用默认的名字去调用另外一个`apply`方法。\n",
    "    ```scala\n",
    "    def apply(): Animal = apply(defaultName)\n",
    "    ```\n",
    "\n",
    "- 这些工厂方法可以被简单地调用：\n",
    "```scala\n",
    "val bunny = Animal.apply(\"Hopper\")\n",
    "```\n",
    "\n",
    "这会忽略使用 `new` 关键词的需要，但是真正的魔力是编译器每看到一个括号被用在实例或者对象的时候，就会去假定使用的是 `apply` 方法：\n",
    "```scala\n",
    "val cat = Animal(\"Whiskers\")\n",
    "```\n",
    "\n",
    "- 工厂方法，常常由伴生对象提供，允许多种方式表达实例声明，为构造变量、转变并且忽略使用```new``` 关键词的需要。注意你必须调用伴生对象的 `apply` 方法才能够使得 `numberOfAnimals` 增加。\n",
    "\n",
    "\n",
    "**Chisel 使用很多伴生对象，比如 Module。**当你写如下代码的时候：\n",
    "```scala\n",
    "val myModule = Module(new MyModule)\n",
    "```\n",
    "\n",
    "你就在调用 **Module 伴生对象**，所以 Chisel 可以在实例之前或者之后允许一些后台代码。\n",
    "```MyModule```."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Case Classes | 案例类<a name=\"caseclass\"/>\n",
    "Case classes are a special type of Scala class that provides some cool additional features. They are very common in Scala programming, so this section outlines some of their useful features: \n",
    "\n",
    "- Allows **external access** to the **class parameters** \n",
    "- **Eliminates** the need to use **`new`** when instantiating the class \n",
    "- Automatically creates an **unapply method** that supplies access to all of the class Parameters. \n",
    "- Cannot be subclassed from \n",
    "\n",
    "In the following example, we declare three different classes, `Nail`, `Screw`, and `Staple`. \n",
    "\n",
    "案列类是 Scala 类中一个特殊的类，它提供了一下很酷的附加特性。他们在 Scala 编程中使用很多，所以这个小节简单描述了一些他们很有用的特性。\n",
    "\n",
    "- 允许 **外部获取类变量**\n",
    "- 当实例化类的时候可以**忽略**使用关键词 **`new`**\n",
    "- 自动生成一个 **unapply method** 以支持获取所有的类参数\n",
    "- 不能成为父类\n",
    "\n",
    "在下面这个例子中，我们声明了三种不同的类，`Nail`， `Screw`， 以及 `Staple`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Nail(length: Int) // Regular class 普通类\n",
    "val nail = new Nail(10) // Requires the `new` keyword 需要关键词 `new`\n",
    "// println(nail.length) // Illegal! Class constructor parameters are not by default externally visible \n",
    "                        // 非法！类的构造变量默认是不可以被外面获取的。\n",
    "\n",
    "class Screw(val threadSpace: Int) // By using the `val` keyword, threadSpace is now externally visible \n",
    "                                  //通过使用关键词 `val`，threadSpace 现在就是对外可见的了\n",
    "val screw = new Screw(2)          // Requires the `new` keyword 需要关键词 `new`\n",
    "println(screw.threadSpace)\n",
    "\n",
    "case class Staple(isClosed: Boolean) // Case class constructor parameters are, by default, externally visible \n",
    "                                     // 案列类的构造参数就是默认对外可见的\n",
    "val staple = Staple(false)           // No `new` keyword required 不需要关键词 `new` \n",
    "println(staple.isClosed)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`Nail` is a regular class, and its parameters are not externally visible because we did not use the `val` keyword in the argument list. It also requires the `new` keyword when declaring an instance of `Nail`.   \n",
    "\n",
    "`Screw` is declared similarly to `Nail`, but includes `val` in the argument list. This allows its parameter, `threadSpace`, to be visible externally.  \n",
    "\n",
    "By using a case class, `Staple` gets the benefit of all its parameters being externally visible (without needing the `val` keyword). \n",
    "\n",
    "In addition, `Staple` does not require using `new` when declaring a case class. This is because the Scala compiler automatically creates a companion object for every case class in your code, which contains an apply method for the case class. \n",
    "\n",
    "Case classes are nice containers for generators with lots of parameters. \n",
    "The constructor gives you a good place to define derived parameters and validate input. \n",
    "\n",
    "`Nail`是一个普通的类，它的变量不能被外面获取，因为外面没有在参数列表中使用关键词 `val`。当声明实例 `Nail`的时候，它也需要关键词  `new` \n",
    "\n",
    "`Screw` 的声明与 `Nail` 类似，但是包括了一个关键词 `val`。这使得它的参数 `threadSpace` 是对外可见的。\n",
    "\n",
    "通过使用一个案例类，`Staple` 的所有参数都可以通过外部获取到 ( 而不需要使用关键词 `val` )\n",
    "\n",
    "除此以外，在你每个案例类中实例化伴生对象的时候，`Staple` 也不需要使用关键词 `new`，并且案例类也包含了一个 `apply` 方法。\n",
    "\n",
    "案例类对带有很多参数的生成器非常友好。\n",
    "你可以在构造体内定义衍生参数和有效的输入。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "case class SomeGeneratorParameters(\n",
    "    someWidth: Int,\n",
    "    someOtherWidth: Int = 10,\n",
    "    pipelineMe: Boolean = false\n",
    ") {\n",
    "    require(someWidth >= 0)\n",
    "    require(someOtherWidth >= 0)\n",
    "    val totalWidth = someWidth + someOtherWidth\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "# Inheritance with Chisel | 从 Chisel 继承<a name=\"super\"></a>\n",
    "You've seen `Module`s and `Bundle`s before, but it's important to realize what's really going on. \n",
    "Every Chisel module you make is a class extending the base type `Module`. \n",
    "Every Chisel IO you make is a class extending the base type `Bundle` (or, in some special cases, `Bundle`'s supertype [`Record`](https://github.com/freechipsproject/chisel3/blob/v3.0.0/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala#L415)). \n",
    "Chisel hardware types like `UInt` or `Bundle` all have `Data` as a supertype. \n",
    "We'll explore using object oriented programming to create hierarchical hardware blocks and explore object reuse. You'll learn more about types and `Data` in the next Module on type generic generators. \n",
    "\n",
    "你已经在之前看到过 `Module` 和 `Bundle` 了，但是意识到真正发生了什么是很重要的。\n",
    "你声明的每一个 Chisel 模块都是一个继承自基础类型 `Module` 的类。\n",
    "每一个你声明的 IO 都是一个继承自基础类型 `Bundle` 的类 (或者有时候是一个超级类型 [`Record`](https://github.com/freechipsproject/chisel3/blob/v3.0.0/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala#L415))\n",
    "硬件类型比如 `UInt` 或者 `Bundle` 都有一个 `Data` 的超级类型。\n",
    "我们将探索使用面向对象编程去创造一个分级的硬件模块并且探索对象重复使用。你将在下一个单元的类型通用生成器中学到更多类型和 `Data`。\n",
    "\n",
    "## Module | 模块名<a name=\"module\"></a>\n",
    "Whenever you want to create a hardware object in Chisel, it needs to have `Module` as a superclass. \n",
    "Inheritance might not always be the right tool for reuse ([composition over inheritance](https://en.wikipedia.org/wiki/Composition_over_inheritance) is a common principle), but inheritance is still a powerful tool. \n",
    "Below is an example of creating a `Module` and connecting multiple instantiations of them together hierarchically. \n",
    "\n",
    "不论什么时候你想在 Chisel 中创造一个硬件对象，这个对象都需要把 `Module` 当作超级类。\n",
    "继承可能并不总是正确复用的工具 ([超越继承的组成](https://en.wikipedia.org/wiki/Composition_over_inheritance) 但是它确实是很有效的一个工具。\n",
    "下面是一个创造 `Module` 并且分级地连接多个实例。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style=\"color:blue\">**Example: Gray Encoder and Decoder | 举例：格雷码编码、解码器**</span><br>\n",
    "We'll create a hardware Gray encoder/decoder. The encode or decode operation choice is hardware programmable. \n",
    "\n",
    "我们将创造一个硬件格雷码编码、解码器。编码或者解码操作是硬件可控的。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class NoGlitchCounterIO(bitwidth: Int) extends Bundle {\n",
    "    val en  = Input(Bool())\n",
    "    val out = Output(UInt(bitwidth.W))\n",
    "}\n",
    "\n",
    "abstract class NoGlitchCounter(val maxCount: Int) extends Module {\n",
    "    val bitwidth: Int\n",
    "    val io = IO(new NoGlitchCounterIO(bitwidth))\n",
    "}\n",
    "\n",
    "abstract class AsyncFIFO(depth: Int) extends Module {\n",
    "    val io = IO(new Bundle{\n",
    "         // write inputs 写输入\n",
    "         val write_clock = Input(Clock())\n",
    "         val write_enable = Input(Bool())\n",
    "         val write_data = Input(UInt(32.W))\n",
    "\n",
    "         // read inputs/outputs 读输入/输出\n",
    "         val read_clock = Input(Clock())\n",
    "         val read_enable = Input(Bool())\n",
    "         val read_data = Output(UInt(32.W))\n",
    "\n",
    "         // FIFO status      FIFO 的状态\n",
    "         val full = Output(Bool())\n",
    "         val empty = Output(Bool())\n",
    "    })\n",
    "    \n",
    "    def makeCounter(maxCount: Int): NoGlitchCounter\n",
    "\n",
    "    // add extra bit to counter to check for fully/empty status 为计数器添加一个额外的位来检查满/空状态\n",
    "    assert(isPow2(depth), \"AsyncFIFO needs a power-of-two depth!\")\n",
    "    val write_counter = withClock(io.write_clock) {\n",
    "        val count = makeCounter(depth * 2)\n",
    "        count.io.en := io.write_enable && !io.full\n",
    "        count.io.out\n",
    "    }\n",
    "    val read_counter = withClock(io.read_clock) {\n",
    "        val count = makeCounter(depth * 2)\n",
    "        count.io.en := io.read_enable && !io.empty\n",
    "        count.io.out\n",
    "    }\n",
    "\n",
    "    // synchronize 同步\n",
    "    val sync = withClock(io.read_clock) { ShiftRegister(write_counter, 2) }\n",
    "\n",
    "    // status logic goes here\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class GrayCounter(val bitwidth: Int) extends NoGlitchCounter(bitwidth) {\n",
    "    // todo\n",
    "}\n",
    "\n",
    "class RingCounter(maxCount: Int) extends NoGlitchCounter(maxCount) {\n",
    "    // todo\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import scala.math.pow\n",
    "\n",
    "// create a module 创造一个单元\n",
    "class GrayCoder(bitwidth: Int) extends Module {\n",
    "  val io = IO(new Bundle{\n",
    "    val in = Input(UInt(bitwidth.W))\n",
    "    val out = Output(UInt(bitwidth.W))\n",
    "    val encode = Input(Bool()) // decode on false 如果是 false 那就解码\n",
    "  })\n",
    "  \n",
    "  when (io.encode) { //encode 编码\n",
    "    io.out := io.in ^ (io.in >> 1.U)\n",
    "  } .otherwise { // decode, much more complicated 解码要稍微复杂一点\n",
    "    io.out := Seq.fill(log2Ceil(bitwidth))(Wire(UInt(bitwidth.W))).zipWithIndex.fold((io.in, 0)){\n",
    "      case ((w1: UInt, i1: Int), (w2: UInt, i2: Int)) => {\n",
    "        w2 := w1 ^ (w1 >> pow(2, log2Ceil(bitwidth)-i2-1).toInt.U)\n",
    "        (w2, i1)\n",
    "      }\n",
    "    }._1\n",
    "  }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Give it a whirl!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "// test our gray coder 测试我们的格雷码编码器\n",
    "val bitwidth = 4\n",
    "Driver(() => new GrayCoder(bitwidth)) {\n",
    "  c => new PeekPokeTester(c) {\n",
    "  \n",
    "    def toBinary(i: Int, digits: Int = 8) =\n",
    "      String.format(\"%\" + digits + \"s\", i.toBinaryString).replace(' ', '0')\n",
    "\n",
    "    println(\"Encoding:\")\n",
    "    for (i <- 0 until pow(2, bitwidth).toInt) {\n",
    "      poke(c.io.in, i)\n",
    "      poke(c.io.encode, true)\n",
    "      step(1)\n",
    "      println(s\"In = ${toBinary(i, bitwidth)}, Out = ${toBinary(peek(c.io.out).toInt, bitwidth)}\")\n",
    "    }\n",
    "    \n",
    "    println(\"Decoding:\")\n",
    "    for (i <- 0 until pow(2, bitwidth).toInt) {\n",
    "      poke(c.io.in, i)\n",
    "      poke(c.io.encode, false)\n",
    "      step(1)\n",
    "      println(s\"In = ${toBinary(i, bitwidth)}, Out = ${toBinary(peek(c.io.out).toInt, bitwidth)}\")\n",
    "    }\n",
    "  }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Gray codes are often used in asynchronous interfaces. Usually Gray counters are used rather than fully-featured encoders/decoders, but we'll the above module to simplify things. Below is an example AsyncFIFO, built using the above Gray coder. The control logic and tester is left as an exercise for later on. For now, look at how the Gray coder is instantiated multiple times and connected. \n",
    "\n",
    "格雷码通常被用于异步接口。通常会使用格雷码计数器而不是功能齐全的编码器、解码器，但是上面的单元是一个简化模型。下面是一个异步 FIFO 的例子，使用了上述的格雷码编码器。控制逻辑以及测试被留作后面的练习。现在，我们来看看格雷码编码器是怎么样被多次实例化和连接的。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class AsyncFIFO(depth: Int = 16) extends Module {\n",
    "  val io = IO(new Bundle{\n",
    "    // write inputs 写输入\n",
    "    val write_clock = Input(Clock())\n",
    "    val write_enable = Input(Bool())\n",
    "    val write_data = Input(UInt(32.W))\n",
    "    \n",
    "    // read inputs/outputs 读输入/输出\n",
    "    val read_clock = Input(Clock())\n",
    "    val read_enable = Input(Bool())\n",
    "    val read_data = Output(UInt(32.W))\n",
    "    \n",
    "    // FIFO status      FIFO 的状态\n",
    "    val full = Output(Bool())\n",
    "    val empty = Output(Bool())\n",
    "  })\n",
    "  \n",
    "  // add extra bit to counter to check for fully/empty status 为计数器添加一个额外的位来检查满/空状态\n",
    "  assert(isPow2(depth), \"AsyncFIFO needs a power-of-two depth!\")\n",
    "  val write_counter = withClock(io.write_clock) { Counter(io.write_enable && !io.full, depth*2)._1 }\n",
    "  val read_counter = withClock(io.read_clock) { Counter(io.read_enable && !io.empty, depth*2)._1 }\n",
    "  \n",
    "  // encode 编码\n",
    "  val encoder = new GrayCoder(write_counter.getWidth)\n",
    "  encoder.io.in := write_counter\n",
    "  encoder.io.encode := true.B\n",
    "  \n",
    "  // synchronize 同步\n",
    "  val sync = withClock(io.read_clock) { ShiftRegister(encoder.io.out, 2) }\n",
    "  \n",
    "  // decode 解码\n",
    "  val decoder = new GrayCoder(read_counter.getWidth)\n",
    "  decoder.io.in := sync\n",
    "  decoder.io.encode := false.B\n",
    "  \n",
    "  // status logic goes here 下面是状态逻辑\n",
    "  \n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "# You're done! | 恭喜你，完成了本节内容的学习！\n",
    "\n",
    "[Return to the top. | 回到顶层。](#top)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Scala",
   "language": "scala",
   "name": "scala"
  },
  "language_info": {
   "codemirror_mode": "text/x-scala",
   "file_extension": ".scala",
   "mimetype": "text/x-scala",
   "name": "scala211",
   "nbconvert_exporter": "script",
   "pygments_lexer": "scala",
   "version": "2.11.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}