3.2_collections.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.2: Generators: Collections | 生成器：集合\n",
    "**Prev:上一个小节： [Generators: Parameters | 生成器：变量](3.1_parameters.ipynb)**<br>\n",
    "**Next:下一个小节： [Interlude: Chisel Standard Library | 间歇：Chisel 标准库](3.2_interlude.ipynb)**\n",
    "\n",
    "\n",
    "## Motivation | 动机\n",
    "Generators will frequently have to deal with variable numbers of objects, whether they are IOs, modules, or test vectors. \n",
    "Collections are important building blocks for dealing with situations like this. \n",
    "This module will introduce Scala collections and how to use them with Chisel generators.\n",
    "\n",
    "生成器会经常处理很多对象，不论是 IO，模块或者是测试向量。\n",
    "集合可以生成专为很好地处理这些情况的代码块。\n",
    " 这个单元将会介绍 Scala 集合并且它在 Chisel 生成器中的使用方法。\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": "markdown",
   "metadata": {},
   "source": [
    "Note we add a new import here because `mutable.ArrayBuffer` lives in `scala.collections`. 注意我们添加了一个新的引用，因为 `mutable.ArrayBuffer` 包含在 `scala.collections` 中。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import chisel3._\n",
    "import chisel3.util._\n",
    "import chisel3.iotesters.{ChiselFlatSpec, Driver, PeekPokeTester}\n",
    "import scala.collection._"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "# Generators and Collections | 生成器与集合<a name=\"generators-and-collections\"></a> \n",
    "In this section, we will focus on the concept of *generators* and the use of Scala collections as a tool to implement them. \n",
    "Instead of looking at Chisel code as an *instance* of a circuit, i.e. a description of a particular circuit, \n",
    "we will instead consider it to be a generator of a circuit. \n",
    "\n",
    "We will start by considering the FIR filter from previous exercises.  \n",
    "\n",
    "在这个小节中，我们将会专注于*生成器*的概念，并且学习怎样把 Scala 集合作为实现它的工具。\n",
    "我们通常不把 Chisel 代码看作一个电路的实例，比如说描述一个特定的电路，\n",
    "而将它看作是某个电路的生成器。\n",
    "我们将从之前练习中的 FIR 滤波器开始讲解。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class My4ElementFir(b0: Int, b1: Int, b2: Int, b3: Int) extends Module {\n",
    "  val io = IO(new Bundle {\n",
    "    val in = Input(UInt(8.W))\n",
    "    val out = Output(UInt(8.W))\n",
    "  })\n",
    "\n",
    "  val x_n1 = RegNext(io.in, 0.U)\n",
    "  val x_n2 = RegNext(x_n1, 0.U)\n",
    "  val x_n3 = RegNext(x_n2, 0.U)\n",
    "  io.out := io.in * b0.U(8.W) + x_n1 * b1.U(8.W) +\n",
    "    x_n2 * b2.U(8.W) + x_n3 * b3.U(8.W)\n",
    "}\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This circuit is a simple case of a generator because it can generate versions of this 4-tap filter with different coefficients.  \n",
    "But what if we want the circuit to have more taps?  We are going to do this in several steps.\n",
    "- Build a software *Golden Model* of a tap configurable FIR. \n",
    "- Redesign our test to use this model, and confirm that it works. \n",
    "- Refactor our My4ElementFir to allow an configurable number of taps. \n",
    "- Test the new circuit using our new test harness. \n",
    "\n",
    "这个电路是一个生成器的简单例子，因为它可以生成带有不同系数的多版本 4 抽头滤波器。\n",
    "但是如果我们想要这个电路有更多的抽头呢？我们需要完成接下来的步骤。\n",
    "- 建立一个可配置抽头数量 FIR 滤波器的软件*黄金模型*。\n",
    "- 重新运用这个模型设计测试文件，以确保这个模型是无误的。\n",
    "- 重构 MyManyElementFir 以可配置抽头数。\n",
    "- 用新的测试包测试新生成的电路。\n",
    "\n",
    "<span style=\"color:blue\">**Example: FIR Golden Model | 举例： FIR 黄金模型**</span><br><a name=\"fir-golden-model\"></a> \n",
    "Below is a Scala software implementation of a FIR circuit.  \n",
    "\n",
    "下面是一个使用 Scala 语言实现的 FIR 电路。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "/**\n",
    "  * A naive implementation of an FIR filter with an arbitrary number of taps. \n",
    "  * 一个简单的实现带有任意数抽头的 FIR 滤波器的方法。\n",
    "  */\n",
    "class ScalaFirFilter(taps: Seq[Int]) {\n",
    "  var pseudoRegisters = List.fill(taps.length)(0)\n",
    "\n",
    "  def poke(value: Int): Int = {\n",
    "    pseudoRegisters = value :: pseudoRegisters.take(taps.length - 1)\n",
    "    var accumulator = 0\n",
    "    for(i <- taps.indices) {\n",
    "      accumulator += taps(i) * pseudoRegisters(i)\n",
    "    }\n",
    "    accumulator\n",
    "  }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Seq | 系列\n",
    "Note that `taps` has become a `Seq[Int]` which means that the user of the class can pass an arbitrarily-long sequence of `Int`s when constructing the class. \n",
    "\n",
    "注意，`taps` 已经变成了 `Seq[Int]`，这表明类的使用者在构造类的时候可以传递任意长度 `Int` 序列。\n",
    "### Registers | 寄存器\n",
    "With `  var pseudoRegisters = List.fill(taps.length)(0)` we create a `List` that will hold values from previous cycles.  `List` was chosen because its syntax of adding an element to the head and removing the last element is very simple. Just about any member of the scala collections family could be used.  We are also initializing this list to contain all zeros. \n",
    "\n",
    "通过`  var pseudoRegisters = List.fill(taps.length)(0)`我们创建了一个将保留前一个循环的值的 `List`。因为 `List` 从头增加一个元素、从尾删去一个元素的语法很简单，所以选择使用它。任何 Scala 集合类型都可以使用。我们也初始化这个列表至全零。\n",
    "### Poke \n",
    "Our class adds a poke function/method that emulates putting a new input into the filter and cycling the clock. \n",
    "\n",
    "我们的类加入了一个 poke 函数/方法，它可以实现在滤波器中添加一个新的输入并且驱动时钟。\n",
    "### Updating the registers | 更新寄存器\n",
    "The line `pseudoRegisters = value :: pseudoRegisters.take(taps.length - 1)` first uses the `take` method of list to keep the all but the last element of the list, then uses the `::` list concatentation operator to add `value` to the head of the reduced version of the list. \n",
    "\n",
    "这一行 `pseudoRegisters = value :: pseudoRegisters.take(taps.length - 1)` 第一次使用了列表的 `take` 方法来保留除了最后一个元素之外的所有值，然后使用列表的级联操作符 `::` ，以在删去最后一位的列表头的位置，添加 `value`。\n",
    "### Computing the output | 计算输出\n",
    "A simple for loop with an accumulator sums each element of the list times its corresponding tap coefficient. The line with just `accumulator` returns that value as the function result. \n",
    "\n",
    "循环使用累加器对每一个列表中的元素乘上对应的抽头系数的积求和。一行只有 `accumulator` 的返回这个函数的结果。\n",
    "## Adapting our previous test for testing our golden model | 改变我们早期的测试代码以测试我们的黄金模型\n",
    "We will now use our previous work to confirm that our golden model works.  A bit of editing magic takes our previous tests harness and morphs it into... \n",
    "\n",
    "我们现在使用我们早先的设计确保我们的黄金模型正确。有一些编辑的魔力发生在了早期的测试包中，然后将它改变成了……"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "val filter = new ScalaFirFilter(Seq(1, 1, 1, 1))\n",
    "\n",
    "var out = 0\n",
    "\n",
    "out = filter.poke(1)\n",
    "println(s\"out = $out\")\n",
    "assert(out == 1)  // 1, 0, 0, 0\n",
    "\n",
    "out = filter.poke(4)\n",
    "assert(out == 5)  // 4, 1, 0, 0\n",
    "println(s\"out = $out\")\n",
    "\n",
    "out = filter.poke(3)\n",
    "assert(out == 8)  // 3, 4, 1, 0\n",
    "println(s\"out = $out\")\n",
    "\n",
    "out = filter.poke(2)\n",
    "assert(out == 10)  // 2, 3, 4, 1\n",
    "println(s\"out = $out\")\n",
    "\n",
    "out = filter.poke(7)\n",
    "assert(out == 16)  // 7, 2, 3, 4\n",
    "println(s\"out = $out\")\n",
    "\n",
    "out = filter.poke(0)\n",
    "assert(out == 12)  // 0, 7, 2, 3\n",
    "println(s\"out = $out\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Executing the previous block demonstrates that our software model returns the same results as My4ElementFir did. \n",
    "\n",
    "执行上一个代码块显示了我们的软件模型返回了和 My4ElementFir 一样的结果。\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Test circuit using the golden model. | 使用黄金模型测试电路<a name=\"use-golden-model-as-test\"></a> \n",
    "Now that we are reasonably confident about our golden model, we re-write our test to compare the circuit outputs with the output of the golden model, instead of using laboriously hand-crafted examples. \n",
    "What follows is a quick first pass to do it.\n",
    "\n",
    "既然我们已经有理由对我们的黄金模型很自信，那么我们重写我们的测试文件来对比这个电路的输出和黄金模型的输出。\n",
    "下面是一个无误、快速实现它的方式。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "val goldenModel = new ScalaFirFilter(Seq(1, 1, 1, 1))\n",
    "\n",
    "Driver(() => new My4ElementFir(1, 1, 1, 1)) {\n",
    "  c => new PeekPokeTester(c) {\n",
    "    for(i <- 0 until 100) {\n",
    "      val input = scala.util.Random.nextInt(8)\n",
    "\n",
    "      val goldenModelResult = goldenModel.poke(input)\n",
    "\n",
    "      poke(c.io.in, input)\n",
    "\n",
    "      expect(c.io.out, goldenModelResult, s\"i $i, input $input, gm $goldenModelResult, ${peek(c.io.out)}\")\n",
    "\n",
    "      step(1)\n",
    "    }\n",
    "  }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Our test runs for 100 cycles, and checks that the two different methods, hardware and software, are in sync at each step. \n",
    "\n",
    "我们硬件和软件测试，两个不同的检查方法，同步运行100个循环。\n",
    "\n",
    "### Things to watch out for | 需要注意的事情\n",
    "(i.e., mistakes we actually committed while writing this.)\n",
    "\n",
    "1. Getting the step in the right place. Software and hardware execute differently; it's easy to get this wrong. \n",
    "1. This test is weak because it is very sensitive to how the IOs and registers are sized. Implementing a software golden model that observes wrapping behavior at arbitrary data bit widths can be complicated.  Here we just make sure that we only pass in values that fit. \n",
    "\n",
    "(也即是我们在编程的时候实际犯过的错误。)\n",
    "1. 在软件、硬件部分执行对应的步骤。软件和硬件执行方式不同，这很容易弄错。\n",
    "1. 这个测试是比较脆弱的，因为它对 IO 和寄存器定义大小的方式是敏感的。我们编写的这个 Chisel 代码相当于一个任意位宽的 wrapper，而如果要实现一个检测这样任意位宽 wrapper 的黄金模型程序，这将是非常复杂的。在这里我们就确保只传递合适的值。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style=\"color:blue\">**Example: Parameterized FIR Generator | 举例：参数化的 FIR 生成器**</span><br><a name=\"fir-golden-model\"></a> \n",
    "Below we have created a new Filter class, `MyManyElementsFilter` that takes a `Seq` of constants to use for taps.  This list can be any number of elements.\n",
    "For good measure a `bitWidth` has been added that allows us to control the sizes of numbers that can be handled by our circuit.  \n",
    "In response the variable length we have had to refactor the creation of registers and how they are connected. \n",
    "The methodology used below uses a simple subset of the available library of collection functions. \n",
    "Later sections show how to more succinctly express the behavior in a way that also makes what is happening clearer. \n",
    "\n",
    "下面我们创建了一个新的滤波器的类，`MyManyElementsFilter` 。它使用了一个常数的 `Seq` 来定义抽头的位数。\n",
    "新添加的 `bitWidth` 参数使得电路处理的位宽可以被我们控制。\n",
    "对应的，我们已经加入了可变化的长度，以重构寄存器的声明和连接。\n",
    "下面的这个方法使用了集合函数的库中一个简单的子集\n",
    "后续的小节会展示怎样更加简洁地、清晰地表述电路的行为。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class MyManyElementFir(consts: Seq[Int], 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",
    "  })\n",
    "\n",
    "  val regs = mutable.ArrayBuffer[UInt]()\n",
    "  for(i <- 0 until consts.length) {\n",
    "      if(i == 0) regs += io.in\n",
    "      else       regs += RegNext(regs(i - 1), 0.U)\n",
    "  }\n",
    "  \n",
    "  val muls = mutable.ArrayBuffer[UInt]()\n",
    "  for(i <- 0 until consts.length) {\n",
    "      muls += regs(i) * consts(i).U\n",
    "  }\n",
    "\n",
    "  val scan = mutable.ArrayBuffer[UInt]()\n",
    "  for(i <- 0 until consts.length) {\n",
    "      if(i == 0) scan += muls(i)\n",
    "      else scan += muls(i) + scan(i - 1)\n",
    "  }\n",
    "\n",
    "  io.out := scan.last\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### How we did it | 我们如何实现的\n",
    "There are three parallel sections starting at lines 7, 13, and 18. \n",
    "We are using a Scala collection type called `ArrayBuffer`. \n",
    "`ArrayBuffer` allows you to append elements using the `+=` operator (also insert and delete, but we don't need this).\n",
    "First, we create an ArrayBuffer `regs` whose elements will be `UInt`s. \n",
    "Then iterate over the taps, adding the input as the first element followed by creating registers using RegNext which connect the input of the register to the previous element (`regs(i-1)`) and initializes it to unsigned zero (`0.U`).  \n",
    "These registers will hold the previous values of inputs as they are needed.\n",
    "\n",
    "Next, we create another ArrayBuffer `muls` of `UInt`s. \n",
    "Each element of muls will be a node whose i-th element is the product of the `regs(i)` and `const(i)`. \n",
    "\n",
    "Note the use of the `scan.last` method. \n",
    "It takes the last element of a collection, and is a more elegant alternative to `regs(i - 1)` used during the `regs` construction. \n",
    "\n",
    "从7、13、18行开始，有三个平行的小节。\n",
    "我们使用了一个 Scala 集合类型——`ArrayBuffer`。\n",
    "`ArrayBuffer` 允许你使用 `+=` 操作符附加元素（也可以插入和删除，但是我们不需要）。\n",
    "首先，我们声明一个 ArrayBuffer `regs`，它的元素将会是 `UInt` 类型。\n",
    "然后反复添加抽头，首先输入作为第一个元素，然后是使用 RegNext 声明寄存器，并且也将该寄存器的输入和上一个元素连接起来 (`regs(i-1)`)，最后将其初值设置为无符号零 (`0.U`)。\n",
    "这些寄存器将会暂存它们需要的输入的先前值。\n",
    "\n",
    "然后，我们声明了另外一个 `UInt` 类型的 ArrayBuffer `muls`。\n",
    "`muls` 的每一个元素都是一个结点，它的第 i 个元素是 `regs(i)` 与 `const(i)`的积。\n",
    "\n",
    "注意 `scan.last` 方法的使用。\n",
    "它获取了一个集合的最后一个元素，是比在构建 `regs` 使用的 `regs(i - 1)` 更加优雅的替换方法。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Does it behave the same as `My4ElementFir`? | 它与 `My4ElementFir` 功能一样吗？\n",
    "A good first test of our new version is to see if it can pass the test we just applied to the\n",
    "`My4ElementFir`. \n",
    "We create an instance of `MyManyElementFir` and run even more data through it. \n",
    "\n",
    "我们新版本的初步测试主要是为了检查它是否可以通过测试 `My4ElementFir` 的测试程序。\n",
    "我们编写了一个 `My4ElementFir` 的实例，并且通过更多数据测试它。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "val goldenModel = new ScalaFirFilter(Seq(1, 1, 1, 1))\n",
    "\n",
    "Driver(() => new MyManyElementFir(Seq(1, 1, 1, 1), 8)) {\n",
    "  c => new PeekPokeTester(c) {\n",
    "    for(i <- 0 until 100) {\n",
    "      val input = scala.util.Random.nextInt(8)\n",
    "\n",
    "      val goldenModelResult = goldenModel.poke(input)\n",
    "\n",
    "      poke(c.io.in, input)\n",
    "\n",
    "      expect(c.io.out, goldenModelResult, s\"i $i, input $input, gm $goldenModelResult, ${peek(c.io.out)}\")\n",
    "\n",
    "      step(1)\n",
    "    }\n",
    "  }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Now let's test a bunch of different sized FIR filters | 现在，我们测试一串不同大小的 FIR 滤波器。\n",
    "We create some helper functions: `r` which gets a random number; `runOneTest` which creates a golden model and a hardware simulation of a filter for a particular set of taps, and then runs at least twice the number of taps worth of data through the filter. \n",
    "\n",
    "我们新加入了一些更加有帮助的函数：通过 `r` 获得一个随机数；通过 `runOneTest` 创建一个黄金模型和针对特定数量抽头的滤波器硬件激励，运行的时候至少使两倍于抽头数量的测试数据通过滤波器。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "/** a convenience method to get a random integer 一个可以获得随机整数的方便方法\n",
    "  */\n",
    "def r(): Int = {\n",
    "  scala.util.Random.nextInt(1024)\n",
    "}\n",
    "\n",
    "/**\n",
    "  * run a test comparing software and hardware filters 运行一个对比软件和硬件滤波器的测试\n",
    "  * run for at least twice as many samples as taps 至少运行两倍于抽头数量的测试样本\n",
    "  */\n",
    "def runOneTest(taps: Seq[Int]) {\n",
    "  val goldenModel = new ScalaFirFilter(taps)\n",
    "\n",
    "  Driver(() => new MyManyElementFir(taps, 32)) {\n",
    "    c => new PeekPokeTester(c) {\n",
    "      for(i <- 0 until 2 * taps.length) {\n",
    "        val input = r()\n",
    "\n",
    "        val goldenModelResult = goldenModel.poke(input)\n",
    "\n",
    "        poke(c.io.in, input)\n",
    "\n",
    "        expect(c.io.out, goldenModelResult, s\"i $i, input $input, gm $goldenModelResult, ${peek(c.io.out)}\")\n",
    "\n",
    "        step(1)\n",
    "      }\n",
    "    }\n",
    "  }\n",
    "}\n",
    "\n",
    "for(tapSize <- 2 until 100 by 10) {\n",
    "  val taps = Seq.fill(tapSize)(r())  // create a sequence of random coefficients 声明一个随机系数序列\n",
    "\n",
    "  runOneTest(taps)\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Just for fun, let's make a bigger one | 让我们玩一个更大的\n",
    "The following will run a single test on a 500 tap FIR filter.\n",
    "It can take a minute or so to run. \n",
    "(Hint: Watch for the Scala ● to change to Scala ○ on the Toolbar when the execution completes.)\n",
    "\n",
    "下面我们将运行一个拥有 500 抽头 FIR 滤波器的单个测试。\n",
    "运行将会花费一分钟左右的时间。\n",
    "（提示：注意在工具栏的 `Scala ●` 将在运行完成的时候变成 `Scala ○`）"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "runOneTest(Seq.fill(500)(r()))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "val taps = Seq.fill(500)(r())\n",
    "\n",
    "val goldenModel = new ScalaFirFilter(taps)\n",
    "\n",
    "Driver(() => new MyManyElementFir(taps, 32)) {\n",
    "  c => new PeekPokeTester(c) {\n",
    "    for(i <- 0 until 100) {\n",
    "      val input = r()\n",
    "\n",
    "      val goldenModelResult = goldenModel.poke(input)\n",
    "\n",
    "      poke(c.io.in, input)\n",
    "\n",
    "      expect(c.io.out, goldenModelResult, s\"i $i, input $input, gm $goldenModelResult, ${peek(c.io.out)}\")\n",
    "\n",
    "      step(1)\n",
    "    }\n",
    "  }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "# Hardware Collections | 硬件集合\n",
    "\n",
    "<span style=\"color:blue\">**Example: Add run-time configurable taps to our FIR | 举例：为 FIR 添加运行时可配置的抽头**</span><br>\n",
    "The following code adds an additional `consts` vector to the IO of our FIR generator which allows the coefficients to be changed externally after circuit generation. \n",
    "This is done with the Chisel collection type `Vec`. \n",
    "`Vec` supports many of the scala collection methods but it can only contain Chisel hardware elements. \n",
    "`Vec` should only be used in situations where ordinary Scala collections won't work. \n",
    "Basically this is in one of two situations. \n",
    "1. You need a collection of elements in a Bundle, typically a Bundle that will be used as IO. \n",
    "1. You need to access the collection via an index that is part of the hardware (think Register File). \n",
    "\n",
    "\n",
    "下面的代码给 FIR 生成器的 IO 添加了一个附加的 `consts` 向量，这允许系数在电路生成后从外部是可变的。\n",
    "这使用 Chisel 集合类型—— `Vec` 实现的。\n",
    "`Vec` 支持很多的 Scala 集合的方法但是它只能包含 Chisel 硬件元素。\n",
    "`Vec` 只应该在普通的 Scala 集合不能起效的时候才使用。 \n",
    "基本上是以下两种情况之一。\n",
    "1. 你需要在 Bundle 中使用集合，特别是将作为 IO 使用的 Bundle。 \n",
    "1. 你需要通过硬件查找表获取集合（比如说寄存器蒲） "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class MyManyDynamicElementVecFir(length: Int) extends Module {\n",
    "  val io = IO(new Bundle {\n",
    "    val in = Input(UInt(8.W))\n",
    "    val out = Output(UInt(8.W))\n",
    "    val consts = Input(Vec(length, UInt(8.W)))\n",
    "  })\n",
    "\n",
    "  // Reference solution\n",
    "  val regs = RegInit(VecInit(Seq.fill(length - 1)(0.U(8.W))))\n",
    "  for(i <- 0 until length - 1) {\n",
    "      if(i == 0) regs(i) := io.in\n",
    "      else       regs(i) := regs(i - 1)\n",
    "  }\n",
    "  \n",
    "  val muls = Wire(Vec(length, UInt(8.W)))\n",
    "  for(i <- 0 until length) {\n",
    "      if(i == 0) muls(i) := io.in * io.consts(i)\n",
    "      else       muls(i) := regs(i - 1) * io.consts(i)\n",
    "  }\n",
    "\n",
    "  val scan = Wire(Vec(length, UInt(8.W)))\n",
    "  for(i <- 0 until length) {\n",
    "      if(i == 0) scan(i) := muls(i)\n",
    "      else scan(i) := muls(i) + scan(i - 1)\n",
    "  }\n",
    "\n",
    "  io.out := scan(length - 1)\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "val goldenModel = new ScalaFirFilter(Seq(1, 1, 1, 1))\n",
    "\n",
    "Driver(() => new MyManyDynamicElementVecFir(4)) {\n",
    "  c => new PeekPokeTester(c) {\n",
    "    poke(c.io.consts(0), 1)\n",
    "    poke(c.io.consts(1), 1)\n",
    "    poke(c.io.consts(2), 1)\n",
    "    poke(c.io.consts(3), 1)\n",
    "    for(i <- 0 until 100) {\n",
    "      val input = scala.util.Random.nextInt(8)\n",
    "\n",
    "      val goldenModelResult = goldenModel.poke(input)\n",
    "\n",
    "      poke(c.io.in, input)\n",
    "\n",
    "      expect(c.io.out, goldenModelResult, s\"i $i, input $input, gm $goldenModelResult, ${peek(c.io.out)}\")\n",
    "\n",
    "      step(1)\n",
    "    }\n",
    "  }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style=\"color:red\">**Exercise: 32-bit RISC-V Processor | 练习：32 位 RISC-V 处理器**</span><br><a name=\"fir-golden-model\"></a>\n",
    "\n",
    "A [register file](https://en.wikipedia.org/wiki/Register_file) is an important building block for making a processor. \n",
    "A register file is an array of registers that can be read from or written to via a number of read or write ports. \n",
    "Each port consists of an address and data field. 每一个端口都包含了地址和数据部分。\n",
    "\n",
    "The [RISC-V instruction set architecture](https://riscv.org/specifications/) defines several variants, the simplest of which is called RV32I. \n",
    "RV32I has a size-32 array of 32-bit registers. \n",
    "**The register at index 0 (the first register) is always zero when you read from it, regardless of what you write to it** (it's often useful to have 0 handy).\n",
    "\n",
    "Implement a register file for RV32I with a single write port and a paramterized number of read ports. \n",
    "Writes will only be performed when `wen` (write enable) is asserted.\n",
    "\n",
    "[寄存器蒲](https://zh.wikipedia.org/wiki/%E5%AF%84%E5%AD%98%E5%99%A8%E5%A0%86)是组成处理器的一个很重要部件。\n",
    "寄存器蒲是一个寄存器阵列，这些寄存器可以通过读写端口被读取或者写入。\n",
    "\n",
    "[RISC-V 指令集架构](https://riscv.org/specifications/) 定义了一些变体，其中最简单的叫 RV32I。\n",
    "RV32I 有一个由 32 个 32 位寄存器组成的阵列。\n",
    "**在索引 0 的寄存器（第一个寄存器）在你读的时候永远是零值，不管你给它写入的什么**（要方便地获得 0 时它就很有帮助了。）\n",
    "\n",
    "实现一个带有一个写端口和可配置数量的读端口的 RV32I 寄存器蒲。\n",
    " 在 `wen` （写使能）有效时才可以写入。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class RegisterFile(readPorts: Int) extends Module {\n",
    "    require(readPorts >= 0)\n",
    "    val io = IO(new Bundle {\n",
    "        val wen   = Input(Bool())\n",
    "        val waddr = Input(UInt(5.W))\n",
    "        val wdata = Input(UInt(32.W))\n",
    "        val raddr = Input(Vec(readPorts, UInt(5.W)))\n",
    "        val rdata = Output(Vec(readPorts, UInt(32.W)))\n",
    "    })\n",
    "    \n",
    "    // A Register of a vector of UInts 一个无符号整数向量寄存器\n",
    "    val reg = RegInit(VecInit(Seq.fill(32)(0.U(32.W))))\n",
    "\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "chisel3.iotesters.Driver(() => new RegisterFile(2) ) { c => new PeekPokeTester(c) {\n",
    "    def readExpect(addr: Int, value: Int, port: Int = 0): Unit = {\n",
    "        poke(c.io.raddr(port), addr)\n",
    "        expect(c.io.rdata(port), value)\n",
    "    }\n",
    "    def write(addr: Int, value: Int): Unit = {\n",
    "        poke(c.io.wen, 1)\n",
    "        poke(c.io.wdata, value)\n",
    "        poke(c.io.waddr, addr)\n",
    "        step(1)\n",
    "        poke(c.io.wen, 0)\n",
    "    }\n",
    "    // everything should be 0 on init 在开始时所有值都应该是零\n",
    "    for (i <- 0 until 32) {\n",
    "        readExpect(i, 0, port = 0)\n",
    "        readExpect(i, 0, port = 1)\n",
    "    }\n",
    "\n",
    "    // write 5 * addr + 3 \n",
    "    for (i <- 0 until 32) {\n",
    "        write(i, 5 * i + 3)\n",
    "    }\n",
    "\n",
    "    // check that the writes worked 检查写是否有效\n",
    "    for (i <- 0 until 32) {\n",
    "        readExpect(i, if (i == 0) 0 else 5 * i + 3, port = i % 2)\n",
    "    }\n",
    "\n",
    "}}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div id=\"container\"><section id=\"accordion\"><div>\n",
    "<input type=\"checkbox\" id=\"check-1\" />\n",
    "<label for=\"check-1\"><strong>Solution | 解答</strong></label>\n",
    "<article>\n",
    "<pre style=\"background-color:#f7f7f7\">\n",
    "    when (io.wen) {\n",
    "        reg(io.waddr) := io.wdata\n",
    "    }\n",
    "    for (i &lt;- 0 until readPorts) {\n",
    "        when (io.raddr(i) === 0.U) {\n",
    "            io.rdata(i) := 0.U\n",
    "        } .otherwise {\n",
    "            io.rdata(i) := reg(io.raddr(i))\n",
    "        }\n",
    "    }\n",
    "\n",
    "</pre></article></div></section></div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "# You're done! | 恭喜你，完成了本节内容的学习！\n",
    "\n",
    "[Return to the top. | 回到顶层。](#top)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Scala",
   "language": "scala",
   "name": "scala"
  },
  "language_info": {
   "codemirror_mode": "text/x-scala",
   "file_extension": ".scala",
   "mimetype": "text/x-scala",
   "name": "scala",
   "nbconvert_exporter": "script",
   "version": "2.12.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}