rocket diplomacy学习

最新推荐文章于 2023-11-08 17:22:30 发布

XX_bai

最新推荐文章于 2023-11-08 17:22:30 发布

阅读量668

点赞数

文章标签：学习 fpga开发硬件工程

本文链接：https://blog.csdn.net/XX_bai/article/details/122988408

版权

Diplomacy

diplomacy是什么？

diplomacy是一个参数协商框架，用于可参数化配置拓扑结构的生成。

引用于Diplomatic Design Patterns: A TileLink Case Study。
该文档将讲解一个极简的基于diplomacy的拓扑。介绍如何构建一个可参数化配置的加法器以及配套的测试模块。

diplomatic加法器及testbench

首先描述一个电路，一个2-to-1加法器。测试结构，需要一个顶层的testbench，两个输入驱动，一个简单的模拟器。
在这里插入图片描述
该电路的可配置参数为数据的宽度。在参数的协商过程中，拓扑结构期望得到两个宽度相同的输入数据。如果宽度不同，从驱动器到模拟器都将使用较小的宽度进行运算。

import chipsalliance.rocketchip.config.{Config, Parameters}
import chisel3._
import chisel3.internal.sourceinfo.SourceInfo
import chisel3.stage.ChiselStage
import chisel3.util.random.FibonacciLFSR
import freechips.rocketchip.diplomacy.{SimpleNodeImp, RenderedEdge, ValName, SourceNode, NexusNode, SinkNode, LazyModule, LazyModuleImp}

参数协商及传输

在拓扑结构中，共享一个数据宽度参数。所有发送或者接受参数信息的模块必须配有一个或多个nodes。
在每对nodes之间，可能有一条或多条edges。参数协商的工作由edges完成，确保连接着的nodes间的参数同步。edges带有方向，以箭头表示其方向，由source指向sink。
在这里插入图片描述
diplomacy希望用户描述一个由nodes组成的有向无环图（directed acyclic multigraph），箭头的方向为downward，其反方向为upward。

参数

在该例子中，需要电路同步一个scala Int，作为数据宽度，也就是线宽。为表述的更加清晰，我们定义出明确的case class作为我们所需的参数。尽管内容有些重复，包含有相同类型的信息。

case class UpwardParam(width: Int)
case class DownwardParam(width: Int)
case class EdgeParam(width: Int)

node实现

在node implementation或者简称NodeImp中，对参数在图中如何传递以及参数如何在nodes间协商进行描述。
该例子中，我们使用SimpleNodeImp，能够完成相同参数的协商，在edge上传递相同的bundles。不考虑edge的方向。
edge参数（E）描述图中edges传递的参数的类型。在我们的例子中，仅需要跟踪一个Int，最终确定的宽度用于生成电路。该内容构造于EdgeParamclass。
我们还指定了一个bundle参数（B），描述确定参数后，模块间端口传递的数据的类型。该例子中就是chisel的UInt其宽度由edge参数指定。

// PARAMETER TYPES:                       D              U            E          B
object AdderNodeImp extends SimpleNodeImp[DownwardParam, UpwardParam, EdgeParam, UInt] {
  def edge(pd: DownwardParam, pu: UpwardParam, p: Parameters, sourceInfo: SourceInfo) = {
    if (pd.width < pu.width) EdgeParam(pd.width) else EdgeParam(pu.width)
}
  def bundle(e: EdgeParam) = UInt(e.width.W)
  def render(e: EdgeParam) = RenderedEdge("blue", s"width = ${e.width}")
}

edge函数完成了node间的协商过程，在我们的例子中，对upwards及downwards两个方向传递的参数进行比较，然后选择较小的数据宽度作为最终的结果然后交给各个node。
render函数在NodeImp中是必须的，生成元数据，以图形的格式体现协商后的信息。

Nodes

Nodes用于接受或者发送参数。一个模块能够通过diplomacy带上可配置的属性，需要配有一个或者多个node用于接受或者发送参数。在这里，我们将构建几个不同类型的nodes，用于我们想配置参数的模块。
在该节中，除了会讨论upward和downward方向，还会涉及到inward和outward方向。对于一个node，由一条边指向该节点的方向为inward，往外指的方向为outward。
在这里插入图片描述
首先创建一个驱动器的节点。将其作为一个SourceNode，node的实现之前介绍过。SourceNode仅生成沿着outward边downward方向传递的参数。
在AdderDriverNode中，Seq[DownwardParam]类型的widths表示实例化此节点（AdderDriver）的模块的输出连接所需的宽度。使用Seq是因为每个node可以驱动多个输出。在我们的例子中，每个node会连接至adder运算单元以及模拟器。

/** node for [[AdderDriver]] (source) */
class AdderDriverNode(widths: Seq[DownwardParam])(implicit valName: ValName)
extends SourceNode(AdderNodeImp)(widths)

模拟器用同样的方法，但使用的是SinkNode，该类型的Node仅生成沿inward边upward方向流动的参数。所使用的参数是UpwardParam类型的width。

/** node for [[AdderMonitor]] (sink) */
class AdderMonitorNode(width: UpwardParam)(implicit valName: ValName)
extends SinkNode(AdderNodeImp)(Seq(width))

加法器节点接收来自AdderDriverNode的两个输入（两个加数）以及传递一个输出（加法结果）到模拟器。因为输入输出的数量不同，将采用NexusNode。
dFn将沿inward edge传递的downward参数映射至沿outward edge传递的downward参数。uFn将沿outward edge传递的upward参数映射至inward edge传递的upward参数。

/** node for [[Adder]] (nexus) */
class AdderNode(dFn: Seq[DownwardParam] => DownwardParam, 
                uFn: Seq[UpwardParam] => UpwardParam)(implicit valName: ValName)
extends NexusNode(AdderNodeImp)(dFn, uFn)

rocket中还实现的其他的node类型，Nodes.scala。

创建LazyModule

Lazy计算表示推迟一个表达式的运算直到该结果被用到。
diplomacy中的参数协商过程是lazily完成的，需要等到diplomacy的图构建完成。因此，具体的可参数化配置电路也需要lazily生成。diplomacy提供LazyModule结构用于撰写延迟计算的硬件模块。
使用LazyModule来定义我们的Adder。用于定义diplomacy图的模块的创建并不是lazy的（node）。但其模块所需的硬件必须在LazyModuleImp中实现。
在这个例子中，需要一个驱动器能够驱动两个相同位宽的加数到加法器，也就是说我们希望所有的downward方向流动的参数是相等的。还需要模拟器，因此所有upward方向流动的参数是相等的。然后，在AdderNode中可以获取到这些参数，以及简单的将第一个DownwardParam往downward方向传递。同样的逻辑，将第一个UpwardParam往upward方向传递。

/** adder DUT (nexus) */
class Adder(implicit p: Parameters) extends LazyModule {
  val node = new AdderNode (
      { case dps: Seq[DownwardParam] =>
        require(dps.forall(dp => dp.width == dps.head.width), "inward, downward adder widths must be equivalent")
        dps.head
      },
      { case ups: Seq[UpwardParam] =>
        require(ups.forall(up => up.width == ups.head.width), "outward, upward adder widths must be equivalent")
        ups.head
      }
    )
    lazy val module = new LazyModuleImp(this) {
      require(node.in.size >= 2)
      node.out.head._1 := node.in.unzip._1.reduce(_ + _)
    }
    
    override lazy val desiredName = "Adder"
}

AdderDriver每拍随机的生成一个加数，其位宽由finalWidth决定，然后传递至numOutputs数量的源。

/** driver (source)
  * drives one random number on multiple outputs */
class AdderDriver(width: Int, numOutputs: Int)(implicit p: Parameters) extends LazyModule {
  val node = new AdderDriverNode(Seq.fill(numOutputs)(DownwardParam(width)))
    
  lazy val module = new LazyModuleImp(this) {
    // check that node parameters converge after negotiation
    val negotiatedWidths = node.edges.out.map(_.width)
    require(negotiatedWidths.forall(_ == negotiatedWidths.head), "outputs must all have agreed on same width")
    val finalWidth = negotiatedWidths.head
    
    // generate random addend (notice the use of the negotiated width)
    val randomAddend = FibonacciLFSR.maxPeriod(finalWidth)
    
    // drive signals
    node.out.foreach { case (addend, _) => addend := randomAddend }
  }
    
  override lazy val desiredName = "AdderDriver"
}

AdderMonitor每拍会打印出Adder的结果，以及在Adder返回一个错误的结果时输出错误信号。有两个AdderMonitorNode，一个用于接受来自AdderDriver的加数，一个用于接受来自Adder的结果。

/** monitor (sink) */
class AdderMonitor(width: Int, numOperands: Int)(implicit p: Parameters) extends LazyModule {
  val nodeSeq = Seq.fill(numOperands) { new AdderMonitorNode(UpwardParam(width)) }
  val nodeSum = new AdderMonitorNode(UpwardParam(width))
  
  lazy val module = new LazyModuleImp(this) {
    val io = IO(new Bundle {
      val error = Output(Bool())
    })
    
    // print operation
    printf(nodeSeq.map(node => p"${node.in.head._1}").reduce(_ + p" + " + _) + p" = ${nodeSum.in.head._1}")

    // basic correctness checking
    io.error := nodeSum.in.head._1 =/= nodeSeq.map(_.in.head._1).reduce(_ + _)
  }
  
  override lazy val desiredName = "AdderMonitor"
}

创建顶层

顶层模块为一个testbench，实例化Adder以及其外围设备。可以看到不同的位宽参数通过启动器（derivers）和模拟器（checker）传递到diplomacy。如之前描述的，我们期望使用更小的位宽。
在这个模块中，连接各个节点。Sinks在左侧，sources在右侧。

/** top-level connector */
class AdderTestHarness()(implicit p: Parameters) extends LazyModule {
  val numOperands = 2
  val adder = LazyModule(new Adder)
  // 8 will be the downward-traveling widths from our drivers
  val drivers = Seq.fill(numOperands) { LazyModule(new AdderDriver(width = 8, numOutputs = 2)) }
  // 4 will be the upward-traveling width from our monitor
  val monitor = LazyModule(new AdderMonitor(width = 4, numOperands = numOperands))

  // create edges via binding operators between nodes in order to define a complete graph
  drivers.foreach{ driver => adder.node := driver.node }

  drivers.zip(monitor.nodeSeq).foreach { case (driver, monitorNode) => monitorNode := driver.node }
  monitor.nodeSum := adder.node

  lazy val module = new LazyModuleImp(this) {
    when(monitor.module.io.error) {
    ┊ printf("something went wrong")
    }
  }

  override lazy val desiredName = "AdderTestHarness"
}

该模块中，我们使用了最典型的节点间连接符号（:=），rocket中还描述了其他类型的操作符。Nodes.scala。

生成verilog

val verilog = (new ChiselStage).emitVerilog(
  LazyModule(new AdderTestHarness()(Parameters.empty)).module
)

以下就是生成的verilog，可以看到在Adder，启动器以及模拟器中可配置的端口参数位宽都使用了更小的4。LFSR同样配置为了4bit的宽度。

println(s"```verilog\n$verilog```")

其他资料

Rocket Chip Diplomacy Library
A Crash Course in the Diplomacy Framework
TileLink and Diplomacy Reference