Chisel3.5.0のリリースノートを確認した - ハードウェアの気になるあれこれ

年末にもうすぐChisel3.5.0が出そう、、、、と書いていたのだが、新年始まってバタバタしてたらとっくにリリースが行われていた。。。。という事で、勝手に毎度おなじみにしているリリースノートの確認をやっていこうと思う。

Chisel v3.5.0がリリースされた
v3.4.0 -> v3.5.0へのアップグレード
Highlights
API Changes
API Deprecations
Miscellany

Chisel v3.5.0がリリースされた

改めて、Chisel v3.5.0が1/12にリリースされた。

ということで、初回はChisel3.5.0のときと同様にリリースノートについて見ていこうと思う。 v3.4.0が2020年の10/7リリースなので、今回は一年以上開いたことになる。それだけに今回も更新が結構盛り沢山になっているようだ。

気になったやつについては、別途調べて記事にできればと考えている。なおリリースノートに含まれる"Dependency Bumping"と"Bug Fix"は省いてある。また"Miscellany"については、これはと思った一部のもののみを紹介している。

ちなみにだがもうすぐv3.5.1が出る計画があるらしい。

v3.4.0 -> v3.5.0へのアップグレード

では早速、、、と思ったのだが、v3.5.0を使うに当たってbuild.sbtの変更が必要になっているので、まずはそこを抑えておく。ざっくりまとめると以下の変更が入った。

Scalaのバージョンが正式に2.13になった
- これに伴いこれまで指定していた-Xsource:2.11が不要になった
プラグインの設定が変更になった
- paradiseが不要になった
- "-P:chiselplugin:useBundlePlugin"がデフォルトで有効になったため、指定が不要になった

Chisel3.4.x系で動かしていたプロジェクトをアップグレードする際には、chisel-templateのmasterの最新版のbuild.sbtを持ってくるか、以下のコミットを参考に書き換えるのが良さそう。

https://github.com/freechipsproject/chisel-template/commit/9d9c1115a141b086215089f9b8bba6f1c2f01474

Highlights

まずはハイライトから。

(#2045) Definition/Instance

試験段階ではあるがDefinition, Instance, @instantiable, @publicといったAPIが追加された。これを使うことによってRTL生成の際に内部の論理は同一のモジュールになるのに、別名のモジュールが生成されていた問題を解決できるとのこと。（例えばQueueを使う場合に同じビット幅を持つQueueを異なる場所でインスタンスすると、Queue/Queue_1のように名前だけ異なる複数のモジュールが生成されていた）

(#1955) DataView

これもまだexperimental指定ではあるが、DataViewという機能が追加された。これは「Scalaのオブジェクトをchisel3.Data型のサブタイプとして"見る"（というか扱うの方がしっくりくる）機能」とのこと。asUIntやasTypeOfといったキャストに処理は似ているが、次のような違いがあるそうだ。

DataViewは接続可能（キャストの場合は同じ型同士にしないと接続できない）
DataViewはどの様にマッピング（接続するか）をカスタマイズ可能（キャストの場合は、全てのデータをBits型とみなして接続し、その後対象の型が再構築される）
DataViewは部分的に適用可能（PartialDataViewを使うことで、一部分のみに適用可能）

詳細については次の2つのドキュメントが整備されていた。

こちらについては上記ドキュメントの内容も踏まえて別に試してまとめたいと思う。ざっくりは以下の様な事が出来るみたい。

class MyBundleA {
  val a = UInt(1.W)
  val b = UInt(2.W)
}

class MyBundleB {
  val c = UInt(1.W)
  val d = UInt(2.W)
}

// DataViewの定義
object MyBundleA {
  implicit val bundleBView = DataView[MyBundleB, MyBundleA](
    vab => new MyBundleA,
    _.c => _.a // MyBundleB.c は MyBundleA.aとする
    _.d => _.b // MyBundleB.d は MyBundleA.bとする
  )
}

class MyModule extends RawModule {
  val in_bunlde_a = IO(Input(new MyBundleA)
  val out_bunlde_b = IO(Output(new MyBundleB)

  // viewAs[MyBundleA]でout_bundle_bをMyBundleAとして扱える
  // この際<>での接続関係は`implicit val bundleBView`の定義に従う
  out_bunlde_b.viewAs[MyBundleA] <> in_bunlde_a
}

(#661) viewAsSuperType

これはDataViewの一種で継承関係にあるBundleにおいて、サブクラスをスーパークラスとして扱える機能、、、らしい。以下はサンプルコードとして載っていたもの。How do I view a Bundle as a parent type (superclass)?

import chisel3._
import chisel3.experimental.dataview._

class Foo extends Bundle {
  val foo = UInt(8.W)
}
class Bar extends Foo {
  val bar = UInt(8.W)
}
class MyModule extends Module {
  val foo = IO(Input(new Foo))
  val bar = IO(Output(new Bar))
  // barを.viewAsSuperTypeでFooとして扱うことで、fooを接続する
  bar.viewAsSupertype(new Foo) := foo // bar.foo := foo.foo
  // Barにのみ存在する信号は別途接続
  bar.bar := 123.U           // all fields need to be connected
}

(#1834) Vec Literals

BunldeLiteralsのVec版であるVecLiteralsが追加された。

(#2277) Seq/Tuple

DataViewを使うことで、Seq/TupleをChiselのData型として扱えるようになった。この機能を使うことでMuxのようにData型のサブセットしか取れないような機能にSeq/Tupleを指定できるようになっている（以下の処理が出来るようになった）。

val cond = true.B
val a, b = Wire(Bool())
(a, b) = Mux(cond, (true.B, false.B), (false.B, true.B))

Feature

(#1154) ExtModule now supports built in support for providing Verilog source

ExtModule用のトレイトHasExtModuleResource/HasExtModuleInline/HasExtModulePathがサポートされた。これによりExtModuleでもaddResource/setInline/addPathが使用可能になった。

Naming improvements

(#1614) When prefixing with a data, eagerly get local name

#1606の修正で、prefix内部の変数名がわかりやすくなった。

(#1616) Use Data refs for name prefixing with aggregate elements

prefix使用時のスピードアップのためのPR。

(#1634) Added Force Name API

forceNameというAPIが追加されて、インスタンスの名前やアグリゲート型以外の信号をリネームできるようになった。

(#1819) add new APIs to BitPat

BitPatにY, N, select, slice, ## が追加された。またtoStringというAPIが追加された。

Verification

(#1891) Guard statements with module reset

assert/assume/coverにリセット時のガードが追加された。

(#1968) create and extend annotatable BaseSim class for verification nodes

BaseSimというクラスの追加により、Assert/Assume/Coverのアノテートできるようになった。

(#1992) Make printf return BaseSim subclass so it can be named/annotated

printfがアノテートできるようになった。

(#1964) Implement Espresso Decoder

Espresso Decoderを使ったデコーダーが実装された。

(#1694) Add when.cond for getting the current when condition

when.condというAPIが追加された。呼び出したブロック式中のブール値を返却してくれる模様。

(#1740) Parametrized Mem- & SyncReadMem-based implementation of the Queue class

QueueにuseSyncReadMemというフラグオプションが追加された。Trueにすると内部のメモリにSyncReadMemを使用してくれるようになる。

(#1805) Import memory files inline for Verilog generation

loadMemoryFromFileInlineというAPIが追加された。生成したVerilogのコード中に、このAPIで指定したファイルをreadmemhで読み込むようにしてくれるらしい。

(#1826) Make plugin autoclonetype always on

autoclonetypeのプラグインが常に有効化された。これにより、これまでBundleに自前で実装していたcloneTypeが実装不要になる（＆これがあるコードをChisel3.5.0でコンパイルするとエラーになる）

(#1921) Add getVerilog in Chisel3

emitVerilogとgetVerilogStringが追加された。ChiselStage使うの何となく面倒だったから、ちょっと嬉しい。

(#1933) Merge minimized table before return as a TruthTable

最初はリリースノートの文言と内容にズレがある気があるな、、と思ったトピック。コミットの中身をみるとMinimizerの中身としてQMCMinimizerというオブジェクトが追加されており、渡した真理値テーブルの最小化が行われるようになった、という事なので、まあ確かにそうだなという感じ。

(#1966) Add isOneOf method to ChiselEnum

ChiselEnumにisOneOfというメソッドが追加された。

(#2211) Add BitSet API

BitSetというBitPatの集合を扱う型が追加された？？bitsetというメソッドがDecoderに追加されており、これを使うと論理の最適化を行ったデコード回路が生成できる、、っぽい。これは少し試してみないとわからないな。

(#2197) Improve Data.toString

stringAccessorというメソッドが追加され、stringAccessorがdeprecatedになった。これによりData型のサブクラスのtoStringの出力が見やすくなった。

(#2077) implement trace API

Trace.traceName というAPIが追加された。詳細は要調査。Verilatorが新し目じゃないと動かない機能の模様。手元の環境は当初v4.106が入っていたが、この状態だとテストがFAILした。（その後v4.218ではPASSすることを確認済み）

(#1140) Circular-shift (rotate) operations for UInt

これはそのまま、循環シフトのためのAPIであるrotateLeft/rotateRightがUIntに追加された。

(#2030) Added flush capability to Queue

QueueクラスにhasFlushというオプションが追加された。hasFlush == trueにすると、インターフェイスにflushというポートが追加される。 flushを1b'1にすると、内部のenq_ptr/deq_ptrがリセットされる。

(#2059) Added VecInit factory methods (fill,iterate)

VecInitにfillとiterateというAPIが追加された。これによりたとえばfillだとこれまでVecInit(Seq.fill(N)(value))のように記述していたものがVecInit.fill(N)(value)のように記述できる。

class VecInitAPI extends Module {
  val out_fill = IO(Output(Vec(2, UInt(8.W))))
  val out_iterate = IO(Output(Vec(2, UInt(8.W))))

  out_fill := VecInit.fill(2)(1.U)
  out_iterate := VecInit.iterate(2.U, 2)(_ + 1.U)
}

(#2065) Add multiple dimensions to VecInit fill and iterate

VecInitで2D/3DのVecを作成できるようになった。なおリリースノートではfillとietarateになっているが、コミットを見る限り2D/3Dに対応しているのはfillとtabulateの2つのみ。

class VecInitAPI extends Module {
  val out_fill_2d = IO(Output(Vec(2, Vec(3, UInt(8.W)))))
  val out_fill_3d = IO(Output(Vec(2, Vec(3, Vec(4, UInt(8.W))))))
  val out_tabulate_2d = IO(Output(Vec(2, Vec(3, UInt(8.W)))))
  val out_tabulate_3d = IO(Output(Vec(2, Vec(3, Vec(4, UInt(8.W))))))

  out_fill_2d := VecInit.fill(2, 3)(1.U)
  out_fill_3d := VecInit.fill(2, 3, 4)(1.U)
  out_tabulate_2d := VecInit.tabulate(2, 3)((a, b) => (a + b).U)
  out_tabulate_3d := VecInit.tabulate(2, 3, 4)((a, b, c) => (a + b + c).U)
}

API Changes

Bundles can no longer be instantiated with bound hardware

Bundles no longer can be instantiated with bound types

Bundleはバインドされた型／ハードウェアでインスタンスすることができなくなった。

(#1954) Stop Emitting BlackBoxResourceAnno.

BlackBoxResourceAnnoが生成されなくなった。

(#2271) Require the chisel3 compiler plugin

Chisel3.5.0からはchisel3のcompilerプラグインが必要になった。詳細についてはREADMEに記載（以下のドキュメント）があるが、build.sbtに以下の設定が必要になっている。

addCompilerPlugin("edu.berkeley.cs" % "chisel3-plugin" % "3.5.0" cross CrossVersion.full)

Build Your Own Chisel Projects

(#2217) Refactor TruthTable to use Seq (#2217)

再現性を担保するために、TruthTableでMapではなくSeqを使うようになった。

(#2149) Remove v3.4.0 version of autoNameRecursively (#2149)

v3.4.0とのバイナリ互換性のために残していたプラグインのautoNameRecursivelyを削除。

(#2170) Remove .toBools (#2170)

toBoolsを削除。これはずいぶん前から消すよーと言われていたやつで、asBoolsを使いましょうというお話。なお互換性維持のためにtoBoolsはChiselパッケージの下に移動されているので、import Chisel._の状態でなら使用可能。

(#2267) Remove ChiselExecutionOptions and HasChiselExecutionOptions (#2267)

ChiselExecutionOptionsとHasChiselExecutionOptionsが削除された。depredated扱いにはなっていなかったが、長期に渡って使用されていなかったのが理由とのこと。

(#245) refactor Queue.hasFlush: Boolean to Queue.flush: Option[Bool]. (#2245) -- change from RC1

先ほど紹介したQueueのhasFlushがOption[Bool]に変更された。

(#2052) Remove all Bundle cloneTypes and chiselRuntimeDeprecate its use (#2052)

全てのBundleのcloneTypeが削除された。これはChisel3.5.0からは、先に紹介したコンパイラプラグインで自動的に生成されるようになったため。

API Deprecations

ここからはDepredatedになったもの一覧なので、影響大きいやつだけ取り上げる。

(#1945) deprecate getPorts with modulePorts. (#1945)

(#2284) deprecate getModulePorts (#2284)

(#2302) Deprecate chisel3.internal.firrtl.Port (#2302)

(#2257) Deprecate chisel3.BackendCompilationUtilities (#2257)

(#2192) Deprecate computeName (#2192)

(#2149) Add nullary .fire to Valid and deprecate dummy version (#2156)

(#2124) Deprecate auto-application of empty argument lists to parameterless functions (#2124)

(#1730) Remove Deprecated APIs (#1730)

このPRでこれまで@deprecatedでアノテートされていた、APIがごっそり削除されている。先にあったtoBoolsやDriverなどが該当する。

(#1744) remove 2.11 dedicated code. (#1744)

(8a73362) 8a73362 Remove val io

これは3.4.0の時に@deprecated指定されたもの。コミットメッセージを読むとScalaの-Xsource:2.11が不要になったことにより、消せるようになった模様。なのでv3.5.0からはモジュールの実装時にval io = IO(new Bundle{})が必須ではなくなっている。

(7e4d1ee) Update docs for the removal of val io and MultiIOModule

ドキュメントでMultioIOModuleを使用していた部分が全てModuleに置き換わった。

(6c6ec71) Fold Chisel.CompatibilityModule into chisel3.internal.LegacyModule

CompatibilityModuleがLegacyModuleに吸収された。

Miscellany

(#1618) Provide user source locators in Builder.error errors

Bit選択時のエラー発生時のエラーメッセージが改善された。

(#1623) Enable Cat of Zero Element Vec (#1623)

要素数0のVecをCatできるようになった。

(#1630) Make -e option work with ChiselStage methods (#1630)

ChiselStageで-eオプション（モジュールをファイルごとに出力する）が使用可能になった。

(#1854 add helper function to convert chirrtl to firrtl. (#1854)

FIRRTLからCHIRRTLを生成するAPIとしてChiselStage.convertが追加された。

(5ece5aa) Rename MultiIOModule to Module

MultiIOModuleがModuleにリネームされた。

ひとまず、概要編は以上。気になったやつはもう少し調べて、まとめてみようと思う。