English | 日本語
Elixir HLS は、Elixir で書いた関数から FPGA の回路を作る、高位合成(HLS: High-Level Synthesis)のツールです。
高位合成とは
FPGA の回路は、ふつう Verilog や VHDL などのハードウェア記述言語で書きます。そこでは、 どのクロックで、どのレジスタに、どの値を入れるかを、ひとつずつ書いていきます。この書き方を RTL(Register Transfer Level)と呼びます。高位合成は、ソフトウェアの言語で書いた処理から、 この RTL を自動で作る技術です。書く人は「何を計算するか」に集中でき、クロックやレジスタの 割り当ては、ツールが決めます。
Elixir HLS では、元になる言語が Elixir です。defhls で定義した関数は、ふだんの Elixir の
関数として CPU で動き、同時に FPGA の回路にもなります。作った回路は、元の Elixir の関数と
シミュレーションで比べ、結果が一致することを確かめてから使います。そのため、Elixir の関数が
そのまま回路の仕様になります。なぜこの形にしたのかは、構想に書いて
います。
現状
Elixir HLS 0.1.0 は最初のリリースで、まだ初期の段階です。整数の関数(状態、表、メモリ、回数の決まったループを含む)と、それらをストリーム、 レベル、イベントでつなぐインスタンスを合成し、FPGA でも CPU でも動かせます。最初のターゲットは Sipeed Tang Primer 25K と AtomVM で、動く例は FM ラジオ(atomvm-fm-radio)です。復調のすべてが FPGA で動きます。まだないものは、割り算、浮動小数点数、再帰、Elixir のストリームのうち全体がそろう必要があるもの、などです。
例
defmodule KernelDemo do
use EHLS
defhls stream_kernel(x :: u32) :: u32 do
a = signed(x &&& 0xFFFF, 16)
b = signed(x >>> 16, 16)
if a > b, do: a * 3 + b, else: a + b * 2
end
end
KernelDemo.stream_kernel(123) # => 369(CPU で計算する)stream_kernel は、32 ビットの値を受け取り、下位の 16 ビットと上位の 16 ビットを符号付きの
数として比べて、その結果で計算を変える関数です。整数を渡すと、CPU で、Elixir の関数として
計算します。同じ関数を FPGA の回路として動かす方法は、ボードで動かすで
説明します。
u32(符号なし 32 ビット)のような型は、回路のビット幅になります。回路はビット幅の分だけ
配線と論理を使うので、幅を必要なだけに絞ると、回路が小さく速くなります。CPU で計算する
ときも、値をこの型の幅に合わせて切り詰めるので、CPU と回路は同じ結果になります。
mix ehls.compile --out build lib/kernel_demo.ex
mix ehls.compile は、ファイルの中の defhls の関数を、それぞれ SystemVerilog の回路にします。
そのあと、どの回路も、元の関数とシミュレーションで照合します。一致しない回路があれば、
そこで止まります。
Elixir と Elixir HLS
書けるもの
defhls(CPU でも回路としても動く関数)と definstance(インスタンスの定義。関数を回路として置く)で書けるものを、
Elixir の書き方と並べます。✗ は書けないものです。詳しくは Elixir HLS の考え方、EHLS.defhls/2、
EHLS.Pipeline、EHLS.Stream にあります。
値と型(defhls)
| 項目 | Elixir | Elixir HLS |
|---|---|---|
| 整数 | integer()(大きさは任意) | u8、s16 など(u は符号なし、s は符号あり、数字はビット数 1〜64)。幅を超えた分は折り返す |
| 型の書き方 | @spec f(integer()) :: integer()(なくてもよい) | defhls f(x :: u8) :: u16(必ず書く) |
| タプル | {integer(), integer()} | {u8, s16}。同じ型が並ぶものは tuple(s16, 32) とも書ける |
| 浮動小数点数 | float() | ✗ |
| アトム、文字列、マップ | atom()、String.t()、map() | ✗ |
| リスト | [integer()] | ✗(CPU からは、リストでインスタンスを呼べる) |
| 定数の表 | Enum.at(@t, i) | 同じ(回路の中の表になる) |
関数の定義(defhls)
| 項目 | Elixir | Elixir HLS |
|---|---|---|
| 定義 | def f(x) do ... end | defhls f(x :: u8) :: u8 do ... end(Elixir の関数でもある) |
| 演算 | + - *、Bitwise、== <、and or not | 同じ |
| 割り算 | div、rem、/ | ✗ |
| 分岐 | if、case、cond、複数の節とガード | 同じ(最後の節はすべてに一致すること) |
| 呼び出し | g(x) | 同じモジュールの defhls だけ(呼んだ場所ごとに回路ができる) |
| for ループ | for k <- 0..15, reduce: acc do ... end | 同じ(範囲は定数。1 つの回路を繰り返し使う) |
| reduce | Enum.reduce(0..15, acc, fn k, acc -> ... end) | 同じ(範囲は定数。回路を回数だけ並べる) |
| 状態の中のタプル | elem(t, i)、put_elem(t, i, v) | 同じ(回路ではレジスタ。transform の memory: で FPGA のメモリに) |
| 再帰 | def f(n), do: f(n - 1) | ✗ |
| 無名関数 | fn x -> x + 1 end | ✗ |
| 例外、メッセージ、入出力 | raise、receive、IO.puts | ✗ |
ストリームを扱う関数
| 項目 | Elixir | Elixir HLS |
|---|---|---|
| map | Stream.map(&f/1) | EHLS.Stream.map(&f/1)(モジュール名は省ける: map(&f/1)) |
| filter | Stream.filter(&f/1) | EHLS.Stream.filter(&f/1) |
| transform | Stream.transform(0, &f/2) | EHLS.Stream.transform(0, &f/2)(f は defhls の関数) |
| zip_with | Stream.zip_with(a, b, &f/2) | EHLS.Stream.zip_with(a, b, &f/2) |
| chunk_every | Stream.chunk_every(32, 4, :discard) | EHLS.Stream.chunk_every(32, 4, :discard)(長さ 32 のタプルを返す。Elixir はリストで返すので、型が違う) |
| run | Stream.run() | EHLS.Stream.run() |
| 一定の間隔 | Stream.interval(1) | ticks(1000)(1 秒あたりの回数) |
| 要素を増やす | Stream.flat_map(fn x -> [x, x] end) | ✗ |
| 全体が要るもの | Enum.sort()、Enum.take(n) | ✗ |
| 2 本をつなげる | Stream.concat(a, b) | ✗ |
状態の共有とイベント(definstance)
| 項目 | Elixir | Elixir HLS |
|---|---|---|
| 状態の共有 | Agent | EHLS.Agent(違いは EHLS.Agent を参照) |
| イベント | Phoenix.PubSub | EHLS.PubSub(違いは EHLS.PubSub を参照) |
| プロセスを作る | spawn、Task | ✗ |
Elixir に加わるもの
definstance は関数を回路として配置し(FPGA がなければ CPU のプロセスとして)、アプリケーションが呼べる新しいものを加えます。
- インスタンスの呼び出しは、関数の呼び出しと同じです。
my_inst(x)は配置した関数の結果を返し、my_inst(list)(または binary)は結果のリストを返します。呼んだプロセスはreceiveで待ち、ほかのプロセスは動き続けます。メッセージで受け取る 呼び方もあります(my_inst(:send, :x, data)、my_inst(:request, :out, n))。要素 1 つなら DMA を使わずにmy_inst(:send, :x, 5)で入れられます。状態はmy_inst(:state, n)で読みます。 - CPU で設定した値を回路で使う: 値のインスタンス(
definstance gain_hw(g :: u9))に CPU が値を設定し(gain_hw(12))、 回路の関数はそれを引数として使います(map(&volume(&1, gain_hw(:value))))。値が変わるたびに要素が 1 つ来る ストリームにもできます(changes(gain_hw(:value)))。 動く場所: FPGA があれば FPGA、なければ CPU で、呼び方は同じです。
on: :cpu | :fpgaで指定でき、インスタンスの関数 1 つ だけを CPU に置くこともできます。- ピンとデバイスを回路の中で: ボタンやセンサーのピン、音、USB を、CPU を通さずに回路の関数とつなげます。
changes(:button0, :rising) |> transform(0, &count/2) |> pin_out(:led0)は、ボタンを押すたびに数え、その最下位 ビットを LED に出す回路(押すたびに点いたり消えたりする)になります。音や USB はパッケージのブロックとして置きます(x |> i2s_out()、usb_bulk_in())。CPU からはEHLS.GPIO.read(:pin)、EHLS.GPIO.write(:pin, v)でピンを読み書きできます。 - テスト:
defhlsの関数は Elixir の関数で、mix testではインスタンスも CPU で動きます。mix ehls.compileとmix ehls.simは、各回路を元の関数と照合します。 - GenServer としてのインスタンス:
EHLS.Serverで包むと、インスタンスを GenServer と同じに扱えます(監視ツリーに入り、 アプリケーションと一緒に起動し、呼び出しは順番を待つ)。GenServerとの違いはEHLS.Serverを参照。
必要なもの
- Elixir 1.18 以降
- CIRCT 1.160.0 の配布バイナリ(
hlstoolとmlir-opt)。CIRCT は、LLVM のプロジェクトの 一つで、回路を作るためのコンパイラの基盤です。展開したディレクトリを、環境変数CIRCT_BINに設定します(例: シェルの設定にexport CIRCT_BIN=$HOME/tools/circt-1.160.0/bin)。 - python3
- Icarus Verilog(iverilog。12.0 で確かめています)。回路のシミュレーションに使います。
Ubuntu / Debian では
sudo apt install iverilog、macOS ではbrew install icarus-verilogで入ります。
プログラムの例
defhls は、合成できる関数の定義で、CPU でも動きます。
definstance は、回路を 1 つ FPGA に置きます。いちばん簡単なインスタンスは値を受け取って値を返し、CPU から関数のように
呼べます。次々に来る値(ストリーム)を受け取るインスタンスもあり、リセット直後から動き続けて、デバイスからカーネルへと
CPU を通らずにデータを流すこともできます。
defmodule InstanceDemo do
use EHLS
defhls stream_kernel(x :: u32) :: u32 do
a = signed(x &&& 0xFFFF, 16)
b = signed(x >>> 16, 16)
if a > b, do: a * 3 + b, else: a + b * 2
end
# 値を受け取って値を返す。CPU が書き込み、回路が計算し、結果が保たれる
definstance kernel_hw(x :: u32) do
stream_kernel(x)
end
# ストリーム: CPU の値を次々にカーネルに通して、CPU に返す
definstance accel(words) do
words |> map(&stream_kernel/1)
end
# ticks が 1 秒に 1,000 回カウンタの値を出し、それをカーネルに通して、CPU に返す
definstance demo do
ticks(1000) |> map(&stream_kernel/1)
end
end
InstanceDemo.stream_kernel(0x0002_0001) # 5。CPU で計算する
InstanceDemo.kernel_hw(0x0002_0001) # 5。FPGA で計算する
InstanceDemo.accel([0x0002_0001]) # [5]。ストリーム。リストを渡すとリストが返る
InstanceDemo.accel(<<1, 0, 2, 0>>) # binary を渡すと binary が返る
InstanceDemo.demo(:out, 4) # 4 つの値を受け取るこの先(ボードがなくてもできること、ボードで動かす手順)は、はじめにを見てください。
資料
- はじめに: 関数を書いてから、ボードの回路で動かすまで
- リファレンス(英語。HexDocs のモジュールの説明):
EHLS.defhls/2(型と式、状態、メモリ、レベル、ループ、 ストリーム関数)、EHLS.Pipeline(インスタンス、レベル・イベント・ストリーム、CPU からの呼び出し)、EHLS.Stream(インスタンスがつなぐ関数。Streamと同じ名前)、EHLS.Agent(複数の行で 1 つの状態)、EHLS.PubSub(トピック: イベント)、EHLS.GPIO(ピン)、EHLS.Server(GenServer としてのインスタンス)、EHLS.Backend(バックエンドの選び方、ターゲットに渡すファイル) - Elixir HLS の考え方:
defhlsとdefinstance、値、ハードウェアにできる書き方、ストリーム(合流、分岐、 インスタンスの中のインスタンス)、CPU とのやり取り、読むまでの動作 - 用語集
- このリポジトリのテスト:
mix test(MLIR と回路の説明の生成、CPU での計算)、EHLS_TEST_CIRCT=1 mix test(すべての例を CIRCT と iverilog にも通す。数分かかります) - 構想: なぜ作るのか、層の構成、予定
- 設計: Elixir の関数が回路になるまでの内部の流れ
mix docs で、これらの資料とモジュールのドキュメント(上のモジュール、バックエンド、mix タスク)を
HexDocs と同じ HTML として doc/ に作ります。
ライセンス
Apache-2.0(LICENSE を参照)。