Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions 5.6_pipeline.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,8 @@
"`riscv/src/main/scala/riscv/PipelineFlush.scala`, restart the kernel and run the notebook again\n",
"(until then, the cells that build the core stop with a `NotImplementedError`, as do those of 5.2-5.4\n",
"if their exercises are not done). Think about which instructions are younger than the one in EX,\n",
"and than the one in MEM, and where each of them is."
"and than the one in MEM, and where each of them is. The test runs short programs on the core and\n",
"compares them with the golden model."
]
},
{
Expand All @@ -119,14 +120,16 @@
"metadata": {},
"outputs": [],
"source": [
"simulate(new PipelineFlush) { c =>\n",
" for (redirect <- Seq(false, true); halt <- Seq(false, true)) {\n",
" c.io.redirect.poke(redirect.B)\n",
" c.io.halt.poke(halt.B)\n",
" c.io.flushIfId.expect((redirect || halt).B, s\"redirect $redirect, halt $halt\")\n",
" c.io.flushIdEx.expect((redirect || halt).B, s\"redirect $redirect, halt $halt\")\n",
" c.io.flushExMem.expect(halt.B, s\"redirect $redirect, halt $halt: the jump itself goes on\")\n",
" }\n",
"// what the flushes are for: no instruction younger than a jump (in EX) or a halt (in MEM) may take\n",
"// effect; the nops give auipc's result time to reach the stores\n",
"simulate(new PipelinedSystem) { c =>\n",
" for (\n",
" (name, source) <- Seq(\n",
" \"stores on the wrong path\" -> \"auipc t0, 0\\nnop\\nnop\\nj 1f\\nsw t0, 0(t0)\\nsw t0, 4(t0)\\n1: ecall\",\n",
" \"stores behind a halt\" -> \"auipc t0, 0\\nnop\\nnop\\nebreak\\nsw t0, 0(t0)\\nsw t0, 4(t0)\\nsw t0, 8(t0)\",\n",
" \"a jump behind a halt\" -> \"auipc t0, 0\\nnop\\nnop\\nebreak\\nj 1f\\nsw t0, 0(t0)\\n1: sw t0, 4(t0)\"\n",
" )\n",
" ) CoSim.compare(c, Asm(source)).foreach(d => sys.error(s\"$name: $d\"))\n",
"}\n",
"println(\"SUCCESS!!\")"
]
Expand Down
5 changes: 2 additions & 3 deletions 5.7_hazards.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,6 @@
" \"EX/MEM to EX\" -> \"li a0, 5\\naddi a1, a0, 1\\necall\",\n",
" \"MEM/WB to EX\" -> \"li a0, 5\\nnop\\naddi a1, a0, 1\\necall\",\n",
" \"the newest result wins\" -> \"li a0, 1\\nli a0, 2\\nadd a1, a0, a0\\necall\",\n",
" \"x0 is not forwarded\" -> \"addi zero, zero, 7\\nadd a0, zero, zero\\necall\",\n",
" \"load-use\" -> \"la t0, d\\nlw a0, 0(t0)\\naddi a1, a0, 1\\necall\\n.data\\nd: .word 41\",\n",
" \"load then store\" -> \"la t0, d\\nlw a0, 0(t0)\\nsw a0, 4(t0)\\nlw a1, 4(t0)\\necall\\n.data\\nd: .word 41, 0\",\n",
" \"branch on a loaded value\" -> \"la t0, d\\nlw a0, 0(t0)\\nbnez a0, 1f\\nebreak\\n1: ecall\\n.data\\nd: .word 1\",\n",
Expand Down Expand Up @@ -294,8 +293,8 @@
"The pipeline needs more cycles than the single-cycle core, but each of its cycles is shorter: one\n",
"stage instead of the whole path, so ideally up to five times shorter, and less in practice (the\n",
"stages are not equally long, the stage registers add delay, and forwarding lengthens EX). Whether\n",
"it runs a program in less time depends on those delays, which a synthesis tool reports (Module\n",
"5.10).\n",
"it runs a program in less time depends on those delays, which place and route computes: Module\n",
"5.10 synthesizes the cores, and nextpnr, outside the image, reports how fast their clock can run.\n",
"\n",
"---\n",
"# You're done!\n",
Expand Down
34 changes: 30 additions & 4 deletions 5.8_bus_and_mmio.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,8 @@
"each bit. Restart the kernel and run the notebook again (the cells that build the transmitter or\n",
"the system stop with a `NotImplementedError` until then, as do the exercises of 5.2-5.7).\n",
"\n",
"`UartReceiver` is a receiver in software: fed `txd` once per cycle, it returns each byte."
"`UartReceiver` is a receiver in software: fed `txd` once per cycle, it returns each byte. Once the\n",
"test passes, it also draws one frame of `txd` as a waveform (`riscv.Waves`), bit by bit."
]
},
{
Expand All @@ -132,25 +133,50 @@
"outputs": [],
"source": [
"simulate(new UartTx(divider = 4)) { c =>\n",
" val txdLog = scala.collection.mutable.ArrayBuffer[Boolean]() // txd and busy in every cycle\n",
" val busyLog = scala.collection.mutable.ArrayBuffer[Boolean]()\n",
" val receiver = new UartReceiver(4)\n",
" val text = \"Hi!\"\n",
" val out = new StringBuilder\n",
" var pending = text.toList\n",
" var line = new StringBuilder // txd, one character per bit\n",
" for (cycle <- 0 until 150) {\n",
" val busy = c.io.busy.peek().litToBoolean\n",
" c.io.send.valid.poke((!busy && pending.nonEmpty).B)\n",
" c.io.send.bits.poke(pending.headOption.getOrElse(' ').toInt.U)\n",
" if (!busy && pending.nonEmpty) pending = pending.tail\n",
" val txd = c.io.txd.peek().litToBoolean\n",
" if (cycle % 4 == 0 && cycle < 4 * 12) line += (if (txd) '1' else '0')\n",
" txdLog += txd\n",
" busyLog += busy\n",
" out ++= receiver.sample(txd)\n",
" c.clock.step()\n",
" }\n",
" println(s\"txd, one sample per bit: $line\")\n",
" def bit(log: collection.Seq[Boolean])(cycle: Long): BigInt = if (log(cycle.toInt)) 1 else 0\n",
" println(s\"txd, one sample per bit: ${(0L until 4 * 12 by 4).map(bit(txdLog)).mkString}\")\n",
" println(\"idle 1, then 'H' (0x48 = 01001000): start 0, data 00010010 (least significant first), stop 1,\")\n",
" println(\"then the start bit of 'i' (each sample of 'H' is taken in the last cycle of its bit)\")\n",
" assert(out.toString == text, out.toString)\n",
"\n",
" // the frame of 'H' as a waveform, from just before its start bit to the start bit of 'i'\n",
" val start = txdLog.indexWhere(!_) // the first cycle of the start bit of 'H'\n",
" val next = txdLog.indexWhere(!_, busyLog.indexWhere(!_, start)) // and of 'i'\n",
" val frame = Seq(\"start\") ++ (0 to 7).map(i => s\"D$i\") ++ Seq(\"stop\")\n",
" val window = (start - 4L).max(0L) until (next + 4L)\n",
" def bitName(cycle: Long) = // no name while idle\n",
" if (!busyLog(cycle.toInt)) \"\" else frame.lift(((cycle - start) / 4).toInt).getOrElse(\"start of 'i'\")\n",
" almond.display\n",
" .Html(\n",
" Waves.svg(\n",
" window,\n",
" window.map(_.toString),\n",
" Seq(\n",
" Waves.Bit(\"txd\", bit(txdLog)),\n",
" Waves.Bus(\"bit\", bitName),\n",
" Waves.Bit(\"busy\", bit(busyLog))\n",
" ),\n",
" note = \"'H' = 0x48: a start bit, the data bits from the lowest, a stop bit; each bit lasts 4 cycles\"\n",
" )\n",
" )\n",
" .display()\n",
"}\n",
"println(\"SUCCESS!!\")"
]
Expand Down
74 changes: 51 additions & 23 deletions 5.9_debug_and_verify.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,9 @@
"`simulate(..., waves = \"name\")` dumps every signal of the design in every cycle into a VCD file\n",
"(Module 2.6), which a waveform viewer (GTKWave, Surfer) shows. `riscv.Vcd` reads one in Scala, so\n",
"this notebook can print the signals that matter as a table: one row per cycle, read just before\n",
"the clock edge (what the registers take at that edge).\n",
"the clock edge (what the registers take at that edge). `riscv.Waves` then draws the same signals\n",
"as a viewer would: a lane per signal, one-bit signals high or low, wider ones as bands with their\n",
"values.\n",
"\n",
"The units' instances are `rs1Data_f` and `rs2Data_f` (one per source register), and the pipeline\n",
"registers keep their names (`idEx_bits_inst` is the instruction in EX). `vcd(name)` gives a\n",
Expand All @@ -220,36 +222,62 @@
" CoSim.load(c, Asm(twice))\n",
" CoSim.run(c)\n",
"}\n",
"val vcd = Vcd.read(wavesFile(\"oldest-first\").get)\n",
"locally { // the helpers stay inside: Almond would print every top-level value\n",
" val vcd = Vcd.read(wavesFile(\"oldest-first\").get)\n",
"\n",
"def signal(name: String) = vcd(s\"core.$name\")\n",
"def unit(port: String) = signal(s\"rs1Data_f.io_$port\") // the forwarding unit of rs1\n",
"def result(stage: String) = { // what the unit gets from a stage ahead: \"x10 = 2\", or dashes\n",
" val (valid, rd, value) = (unit(s\"${stage}_valid\"), unit(s\"${stage}_bits_rd\"), unit(s\"${stage}_bits_value\"))\n",
" (t: Long) => if (valid(t) == 1) f\"x${rd(t)}%-2s = ${value(t)}%-6s\" else \"-\" * 13\n",
"}\n",
"val (inEx, inst, pc) = (signal(\"idEx_valid\"), signal(\"idEx_bits_inst\"), signal(\"idEx_bits_pc\"))\n",
"val (rs, forwarded) = (unit(\"rs\"), unit(\"value\"))\n",
"val (exMem, memWb) = (result(\"exMem\"), result(\"memWb\"))\n",
"def isEcall(t: Long) = Rv32i.decode(inst(t).toLong).exists(_.name == \"ecall\")\n",
"val cycles = vcd.risingEdges(\"core.clock\").map(_ - 1).zipWithIndex.filter { case (t, _) => inEx(t) == 1 }\n",
"assert(cycles.exists(c => isEcall(c._1)), \"the ecall never reached EX\")\n",
"println(\"cycle in EX rs EX/MEM rd = value MEM/WB rd = value forwarded\")\n",
"for ((t, cycle) <- cycles.take(cycles.indexWhere(c => isEcall(c._1)) + 1)) {\n",
" val text = Rv32i.disassemble(inst(t).toLong, pc(t).toLong)\n",
" println(f\"$cycle%5d $text%-24s x${rs(t)}%-2s ${exMem(t)}%19s ${memWb(t)}%19s ${forwarded(t)}\")\n",
" def signal(name: String) = vcd(s\"core.$name\")\n",
" def unit(port: String) = signal(s\"rs1Data_f.io_$port\") // the forwarding unit of rs1\n",
" def result(stage: String, none: String) = { // what the unit gets from a stage ahead: \"x10 = 2\", or none\n",
" val (valid, rd, value) = (unit(s\"${stage}_valid\"), unit(s\"${stage}_bits_rd\"), unit(s\"${stage}_bits_value\"))\n",
" (t: Long) => if (valid(t) == 1) s\"x${rd(t)} = ${value(t)}\" else none\n",
" }\n",
" val (inEx, inst, pc) = (signal(\"idEx_valid\"), signal(\"idEx_bits_inst\"), signal(\"idEx_bits_pc\"))\n",
" val (rs, forwarded) = (unit(\"rs\"), unit(\"value\"))\n",
" def is(name: String)(t: Long) = Rv32i.decode(inst(t).toLong).exists(_.name == name)\n",
" def text(t: Long) = Rv32i.disassemble(inst(t).toLong, pc(t).toLong)\n",
" val cycles = vcd.risingEdges(\"core.clock\").map(_ - 1).zipWithIndex.filter { case (t, _) => inEx(t) == 1 }\n",
" assert(cycles.exists(c => is(\"ecall\")(c._1)), \"the ecall never reached EX\")\n",
" // up to the ecall; twice never stalls, so these cycles follow one another\n",
" val shown = cycles.take(cycles.indexWhere(c => is(\"ecall\")(c._1)) + 1)\n",
" val (exMem, memWb) = (result(\"exMem\", \"-\" * 17), result(\"memWb\", \"-\" * 17))\n",
" println(\"cycle in EX rs EX/MEM rd = value MEM/WB rd = value forwarded\")\n",
" for ((t, cycle) <- shown) {\n",
" println(\n",
" f\"$cycle%5d ${text(t)}%-24s x${rs(t)}%-2s ${exMem(t)}%-20s${memWb(t)}%-20s${forwarded(t)}\"\n",
" )\n",
" }\n",
"\n",
" // the same cycles as a waveform; the cycle in which add is in EX is highlighted\n",
" val add = shown.indexWhere(c => is(\"add\")(c._1))\n",
" almond.display\n",
" .Html(\n",
" Waves.svg(\n",
" shown.map(_._1),\n",
" shown.map(_._2.toString),\n",
" Seq(\n",
" Waves.Bus(\"in EX\", text),\n",
" Waves.Bus(\"rs\", t => s\"x${rs(t)}\"),\n",
" Waves.Bus(\"EX/MEM rd = value\", result(\"exMem\", \"\")),\n",
" Waves.Bus(\"MEM/WB rd = value\", result(\"memWb\", \"\")),\n",
" Waves.Bus(\"forwarded\", t => forwarded(t).toString)\n",
" ),\n",
" mark = Set(add),\n",
" note = \"the unit for rs1, sampled just before each rising clock edge; no value: not valid\"\n",
" )\n",
" )\n",
" .display()\n",
"}"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In the cycle in which `add a1, a0, a0` is in EX, both stages ahead hold a result for `x10` (`a0`):\n",
"2 from the second `li`, one stage ahead, and 1 from the first. The unit forwards 1. With a bug in\n",
"hand, a waveform is the place to confirm the cause; it is a poor place to search for one, as a\n",
"long program has thousands of cycles and hundreds of signals. The trace narrows the search to one\n",
"instruction, and so to a few cycles."
"In the cycle in which `add a1, a0, a0` is in EX (highlighted in the waveform), both stages ahead\n",
"hold a result for `x10` (`a0`): 2 from the second `li`, one stage ahead, and 1 from the first. The\n",
"unit forwards 1. With a bug in hand, a waveform is the place to confirm the cause; it is a poor\n",
"place to search for one, as a long program has thousands of cycles and hundreds of signals. The\n",
"trace narrows the search to one instruction, and so to a few cycles."
]
},
{
Expand Down
3 changes: 2 additions & 1 deletion riscv/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,8 @@ disassembled by `Rv32i.disassemble` (as `objdump -M no-aliases` does, near enoug
assembles back to the same word, tested on every instruction of the programs but `fence`, which it
shows without operands), so `CoSim.compare`'s messages name the instruction that differs and what it
did. `Vcd` reads the VCD file (binary search per signal, so long tables stay fast) of `simulate(...,
waves = ...)`, so a notebook can print signals per cycle without a waveform viewer. `Formal.prove`
waves = ...)`, so a notebook can print signals per cycle without a waveform viewer, and `Waves` draws
such per-cycle samples as an SVG timing diagram that a notebook displays inline. `Formal.prove`
emits a check module (`ForwardCheck.scala`: a unit next to its specification, written with
last-connect `when`s rather than a `MuxCase`, with an output `ok`) and runs Yosys's `sat -prove` on
it: a proof for every input of a combinational module, or a counterexample (a module with registers
Expand Down
Loading