Elixir HLS の考え方

Copy Markdown View Source

English | 日本語

Elixir HLS で書いたものが、FPGA の上でどう動くかの考え方を説明します。Elixir を知っていて、FPGA の経験は問わない人を 想定しています。手順ははじめにに、書けるものの一覧は HexDocs のモジュールの説明 (EHLS.defhls/2、EHLS.Pipeline、EHLS.Stream、EHLS.Agent、EHLS.PubSub、EHLS.Server)にあります。

1. defhls と definstance

Elixir HLS には、2 つの定義があります。処理は defhls で関数として書き、definstance でその関数を実体として FPGA に 配置します。

defhls larger(x :: u32) :: u32 do              # 関数の定義。CPU でも動く
  a = x &&& 0xFFFF
  b = x >>> 16
  if a > b, do: a * 3, else: b * 3
end

defhls plus_one(x :: u32) :: u32 do
  x + 1
end

defhls larger_plus_one(x :: u32) :: u32 do
  plus_one(larger(x))                          # defhls からほかの defhls を呼べる
end

definstance larger_plus_one_hw(x :: u32) do    # 実体として FPGA に配置する。CPU から呼べる
  larger_plus_one(x)
end
defhlsdefinstance
意味回路にでき、CPU でも動く関数の定義関数を実体として FPGA に配置したもの
回路作られない作られる
書くもの計算実体にする部分(どの関数を FPGA に置くか)
I/O を含む部品使えない(CPU で動かせないので)使える
CPU から呼ぶとElixir の関数として CPU で処理する回路に入力を与え、回路から結果を受け取る

I/O を含む部品には、i2s_out() や usb_bulk_in() などがあります。

FPGA がないところ(PC や mix test)では、インスタンスは代わりに CPU で動きます。呼び方も結果も同じです(10 節)。

HDL を知っている人には、モジュールの定義とインスタンスの関係だと思うと分かりやすいでしょう。

インスタンスは関数の形をしていますが、呼び出しのたびに作られるわけではありません。動き続けている 1 つの回路なので、 回路が持っているものは呼び出しをまたいで続きます。動き方は、登録された名前で呼ぶ 1 つの GenServer に近く、数が合成の ときに決まる点が違います。

2. 値

引数に型を付けたインスタンスは、値を受け取って値を返します。いちばん簡単に配置できるもので、ほかのものの土台にも なります。

larger_plus_one_hw(0x0002_0005)     # 16: 引数を書き込み、回路が計算し、その結果が返る
larger_plus_one_hw(:value)          # 16: いま保たれている結果をもう一度読む
  • 何が起きるか: CPU が引数を回路のレジスタに書き込み、回路が 1 回計算し、結果は次の呼び出しまでレジスタに保たれます。 呼んだ側は、自分の書き込みの結果を待ちます(回路の中では長くても数十マイクロ秒、AtomVM での呼び出し全体では数ミリ秒)。

  • 最新の値だけが意味を持つ: 値は、最新のものだけが意味を持つもの(音量、設定など)です。回路が計算している間に呼ぶと、 計算が終わるのを待ちます。いくつも来たら、計算するのは最新のものだけです。f(v, wait: false) は、書き込むだけですぐに 戻ります。

  • 最初の呼び出しの前: 結果は initial: の値です(書かなければ 0)。definstance gain_hw(v :: u9), initial: 96。

  • 配線: definstance の中では、CPU で値を読むのと同じ式が、その値への配線になります。別のインスタンスに置いた関数は、 それを引数として受け取り、値を 1 つ受け取るたびに読みます(5 章)。

    definstance k_hw(k :: u8), initial: 1 do       # CPU が書く値。そのまま返す
      k
    end
    
    definstance many_hw(words) do
      words |> map(&scale(&1, k_hw(:value)))       # scale の k は k_hw の値
    end

    ほかのモジュールのインスタンスは Other.k_hw(:value)、ピンのレベルは EHLS.GPIO.read(:switch0) と書きます。

3. ハードウェアにできる書き方

回路は大きさが決まっていなければならず、値は決まった幅のビットです。そのため、Elixir の一部だけが回路にできます。 回路にできない書き方は、コンパイルの時に、ファイルと行を示して止まります。

defhls の中に書けるもの:

種類書けるもの
型u1..u64(符号なし)、s1..s64(符号付き)と、そのタプル。引数と結果は 64 ビットまで
式+ - *、&&& ||| ^^^、シフト、比較、and or not、タプル、signed(x, n) / unsigned(x, n)
分岐if、case、cond、パターンとガードを使った複数の節(最後はすべてに当てはまること)
呼び出し同じモジュールの defhls(呼んだ場所に展開される)
ループ回数の決まった for k <- a..b, reduce:(回路を使い回す)と Enum.reduce(a..b, ...)(並べて展開する)
表Enum.at(@t, i)(モジュール属性の整数のリスト)
状態2 つ目の引数。f(x :: t, s :: u16) :: {t, u16} で {出力, 次の状態} を返す(Stream.transform/3 が受け取る関数の形)
出力のない入力出力を要素 1 つまでのリストにする。{[y], s} / {[], s}、型は {[t], u16}
状態の中のタプル{pos, hist} :: {u8, tuple(s16, 256)}。elem(hist, i) で読み、次の状態は put_elem(hist, i, v) で作る。回路ではレジスタ。置く場所で memory: [:hist] と書くと FPGA のメモリ
レベルストリーム以外の普通の引数。関数を配置する場所で与える: レベルのインスタンス k_hw(:value)、ピン、整数

書けないもの: 割り算(div、rem、/)、浮動小数点数、リスト(出力のない入力を除く)、マップ、文字列、アトム、ほかのモジュールの関数 (Enum.reduce で範囲を回すのは除く)、自分自身を呼ぶこと、プロセスやメッセージ。状態、メモリ、レベルは 32 ビット までです。

definstance の中に置けるもの:

書き方意味
頭に f(x :: t, ...)値のインスタンス。本体は引数の 1 つ、そのタプル、または defhls の呼び出し
f(x) または x |> f()defhls の関数をそのまま置く。ストリーム関数なら、中のパイプごと置かれる
map(&f/1)、map(&f(&1, k_hw(:value)))パイプの中で関数を置く。ほかの引数はレベルか整数
transform(初期値, &f/2)パイプの中で、2 つ目の引数を状態として関数を置く。name: n を付けると CPU から状態を読める
{:ok, n} = EHLS.Agent.start_link(初期値)、x |> EHLS.Agent.get_and_update(n, &f/2)、x |> EHLS.Agent.update(n, &f/2)複数の行で 1 つの状態を使う。Agent と同じ(8 章)
chunk_every(n, k, :discard) |> map(&f/1)n 個の塊を k 個ごとに作り、関数に渡す。Stream.chunk_every と同じ(FIR フィルタなど)。f(w :: tuple(t, n)) は elem(w, i) で読む
run()パイプを終える。状態やイベントのためだけのパイプに。Stream.run と同じ
zip_with(a, b, &f/2)、両方がストリームの f(a, b)2 つのストリームを 1 つの関数に。それぞれから 1 つずつ(5 章)
y = ... とし、y を 2 回使うストリームに名前を付ける。2 回使うと分岐(5 章)
x |> other_hw()ほかのインスタンスを呼ぶ。そこへの配線になる(5 章)
組み込みのブロックticks(rate)(一定の間隔で値を出す)、hold(name)(最新の値をレベルにする)、run()(受け取って捨てる)。SoC のバックエンドが持つもので、手元で試すときは EHLS_SOC=litex を指定する
デバイスボードの部品。i2s_out()、usb_bulk_in()、changes(pin, edge)、sample(pin)、pin_out(pin) など

パイプでつないだ関数の出力と次の関数の入力は、型が合っている必要があります。値が変わる狭め方は、コンパイルで止まります。 オプションは initial:(値のインスタンス)、buffer:(CPU に返す前にためる量)、overflow:(埋まったときの動作)です。

細かい規則は、EHLS.defhls/2(defhls に書けるもの)と EHLS.Pipeline(definstance に置けるもの、CPU からの呼び方) にあります。

4. ストリーム

値が次々に来るとき(音のサンプル、一定の間隔で読むセンサー、USB からのデータ)は、回路はそれをストリームとして 受け取ります。値は 1 つずつ順に関数を通り、前の値を計算している間に次の値が入ってきます。インスタンスの型のない引数が ストリームで、map(&f/1) は 1 つ 1 つの値を f に通します。

definstance many_hw(words) do
  words |> map(&larger_plus_one/1)
end

many_hw([0x0002_0005, 1, 0x0001_0000])     # [16, 4, 4]: リストを入れるとリストが返る

配置した関数はストリームを受け取ってストリームを返すので、関数をパイプでつなぐと、その間もストリームになります。

ストリームの 1 要素は、1 つの値か、いくつかの値のタプルです。いくつかの値を 1 要素として一緒に運びたいとき(ステレオの 左右など)は、タプルにします。タプルの値は同じクロックで一緒に動き、受け取る関数は 1 回の呼び出しでそれを全部受け取ります。

入力と入力の間で値を覚えておくには、要素と状態を受け取って {出力, 次の状態} を返す関数を、map の代わりに transform(初期値, &f/2) で置きます(Stream.transform/3 と同じ形)。状態は回路のレジスタに置かれます。関数そのものは 何も持たず、CPU では普通の関数です。

組み込みのブロックの ticks(1000) は、1 秒に 1,000 回、0, 1, 2, … と数え上げた値(u32)を出します。ストリームは、CPU からではなく、これやボードのデバイスから始めることもできます。

definstance counter do
  ticks(1000) |> map(&larger_plus_one/1)
end

関数をつないだパイプに名前を付けることもできます。ストリームを受け取る defhls(ストリーム関数)です。CPU ではリストを 受け取ってリストを返すので、回路を作らずに普通のテストで処理を確かめられます。

defhls larger_plus_ones(x :: stream(u32)) :: stream(u32) do
  x |> map(&larger/1) |> map(&plus_one/1)
end

test "larger_plus_ones" do
  assert larger_plus_ones([0x0002_0005, 1]) == [16, 4]
end

5. 合流、分岐、インスタンスの中のインスタンス

2 つのストリームを 1 つの関数に: zip_with(a, b, &f/2) は、Elixir の Enum.zip_with と同じく、それぞれから 1 つずつ 取って一緒に渡します。両方の引数がストリームの f(a, b) も、a |> f(b) も同じ意味です。

defhls mix(a :: s16, b :: s16) :: s17 do
  a + b
end

definstance mixer(left, right) do
  zip_with(left, right, &mix/2) |> map(&half/1)
end

mixer([1, 2, 3], [10, 20, 30])             # 2 つのリストを入れると 1 つ返る

合流は本体のどこにでも置けます。合流するストリームは、引数からでも、ソースからでも、ほかの合流からでもかまいません。

1 つのストリームを 2 か所で使う: y = ... でストリームに名前を付け、それを 2 回使うと分岐になります。要素はそれぞれの 枝に渡ります。CPU に返るのは最後の式だけで、それより前の式は、ストリームを受け取って終わるもの(シンク)で終えます。

definstance tapped(x) do
  y = x |> map(&smooth/1)
  y |> map(&low16/1) |> hold(:last)        # 一方の枝はシンクへ
  y |> map(&scale(&1, 3))                  # もう一方がインスタンスの出力
end

インスタンスの中でインスタンスを呼ぶ: インスタンスは 1 つしかないので、ほかのインスタンスの中で呼ぶと、そこへの配線に なります。手前のストリームがその入力に入り、出力がそこから出てきます。どちらも CPU との端にはなりません。ほかの モジュールのインスタンスは Other.fir_hw() と書きます。

definstance player(samples) do
  samples |> map(&gain/1) |> fir_hw() |> map(&clip/1)
end

6. ストリームの流れ方

1 クロックに 1 要素まで動けます。リンクは要素の型の幅で、受け渡しには、送る側の「ある」(valid)と受ける側の「受け取れる」 (ready)の 2 本の信号を使い、両方がそろったクロックでだけ値が動きます。

Erlang のプロセスとの一番の違いは、ためておける量に上限があることです。メールボックスは送り先が遅ければ伸びて いきますが、パイプでつないだ関数の間には数要素分のレジスタしかありません。そこが埋まると、パイプの手前の関数の 「受け取れる」が落ちて、そのまた手前も止まり、ソースまで順に止まっていきます。これをバックプレッシャーと呼びます。

ここから、いくつかのことが決まります。

  • いちばん遅いものが全体の速さを決めます。 1 要素に 100 クロックかかる関数があれば、その手前は 100 クロックに 1 要素ずつしか進みません。
  • 合流は両方を待ち、分岐はすべての枝を待ちます。 合流は、それぞれのストリームに要素がそろうと進みます。分岐は、 すべての枝が要素を受け取ると進むので、遅い枝がほかの枝を待たせます。
  • 待てるソースと待てないソースがあります。 ticks は、次の値を受け取ってもらえるまで待ちます。 usb_bulk_in() や changes(...) は、外から来るものなので待てません。止まっている間に来たものは失われます。

7. CPU とのやり取り

CPU とやり取りするものは 3 種類あります。判断の基準は、上書きされても困らないかです。

種類例書き方
値(レベル。最新の値だけ意味がある)音量、カーネルの状態、スイッチの位置gain_hw(16)、gain_hw(:value)、radio(:state, :level)、EHLS.GPIO.read(:button0)
イベント(まれだが、1 回ずつ大事)ボタンが押されたインスタンスの中の EHLS.PubSub.broadcast(:presses)、EHLS.PubSub.subscribe(:presses) で届くメッセージ(8 節)
ストリーム(全部の値を順番どおりに)音声、IQインスタンスの型のない引数と戻り値

FPGA の中でも、この区別は回路そのものです。値はレジスタで、変わっても、それを読む側では何も動きません。ストリームには valid と ready があり、値が届くと、それを受け取る関数が動きます。イベントは、FPGA の中ではストリームと同じ回路です。 違いは CPU への届き方で、イベントは 1 回ごとにメッセージで届きます。

ストリームは、インスタンスの型のない引数と戻り値でやり取りします。どちらにも DMA エンジンが 1 つ付きます。

out = many_hw([0x0002_0005, 1])           # 入れて、結果を受け取る

CPU からストリームを渡すときは、要素のリストを渡します。要素が 1 つの値ならその値のリスト、タプルならタプルのリストです。 値を左から順に詰めて並べた binary を渡すこともできます。結果は、渡したのと同じ形で返ります。受け取る形は、as: :list か as: :binary で選べます。リストは、CPU が DMA の前に binary に詰め、受け取ったあとでリストに戻します。binary ならこの 変換がないので、そのぶん速く処理できます。2 つのストリームを受け取るインスタンスには、2 つのリストを渡します(mixer(l, r))。

呼び出している間、止まるのは呼んだプロセスだけです。中は receive なので、他のプロセスは動き続けます。待たずに進めたい ときは、メッセージの形で呼べます(ソケットの active: :once と同じ考え方です)。入れるだけ、受け取るだけの呼び方もあります。 呼び方の一覧は EHLS.Pipeline にあります。

キーが押されたとき、測った値が 1 つ出たときのように、要素を 1 つずつ来たときに入れたい場合は、DMA を使わずに入れられます。

many_hw(:send, :words, 0x0002_0005)       # :ok。入りきらないと {:error, :full}(入力は 8 要素まで持てる)

入れた要素は、DMA が運ぶ要素と順番に、1 要素ずつ丸ごとストリームに入ります。結果は many_hw(:out, n) で読みます。入れて 結果を受け取る呼び出しは、自分が入れた要素の分しか数えないためです。

8. イベント

イベントは、まれにしか起きないが 1 回ずつが大事なものです。インスタンスは、トピック(アトム)を付けてイベントを出します。 考え方は Phoenix.PubSub と同じで、EHLS.PubSub.broadcast(topic) に入った値の 1 つ 1 つがイベントになります。プロセスは EHLS.PubSub.subscribe(topic) で購読し、{topic, value} のメッセージで受け取ります。

definstance presses do
  changes(:button0, :rising) |> transform(0, &count/2) |> EHLS.PubSub.broadcast(:presses)
end

EHLS.PubSub.subscribe(:presses)                   # GenServer の init/1 などで

def handle_info({:presses, n}, st), do: ...
  • ストリームとの違い: 出す側は誰が受け取るかを知らず、待つこともありません。出す側は小さな置き場を持ち、入りきらない イベントは数えて捨てます。1 つのトピックを何個のプロセスでも購読でき(今は同時に 4 個まで)、それぞれが購読した時点から すべてのイベントを受け取ります。

  • 別のインスタンスでも受け取れます: インスタンスの中の EHLS.PubSub.subscribe(topic) は、そのトピックのイベントを出す入力元です。 CPU を通さずに回路がイベントに応じられます(EHLS.PubSub.subscribe(:presses) |> map(&dbl/1) |> EHLS.PubSub.broadcast(:doubled))。

  • 値の変化をイベントに: changes(k_hw(:value)) は、値のインスタンスが変わるたびに新しい値を出します。filter(&f/1) は、 Enum.filter と同じく、f が 0 以外を返したものだけを残します。

    definstance watcher do
      y = changes(k_hw(:value))
      y |> EHLS.PubSub.broadcast(:k)                     # 変化のたびに
      y |> filter(&big?/1) |> EHLS.PubSub.broadcast(:big)  # 大きいものだけ
    end

1 つのトピックのイベントは、1 つが 32 ビットまでの値です。FPGA の中の 1 本の待ち行列を来た順に通り、1 回の割り込みで CPU に 渡されて、メッセージになります。イベントを作るのは FPGA で、CPU で動くインスタンス(10 節)はまだイベントを出せません。 EHLS.PubSub.unsubscribe(topic) でプロセスへのメッセージを止めます。EHLS.PubSub.subscribe/2 は、ソケットと同じく active: :once(または n)と timestamps: true も受け取ります。

複数の行で 1 つの状態: エージェント。 transform で置いた関数は、それぞれ自分の状態を持ちます。何種類かの要素で 1 つの状態を変えたいとき(ある所で値を設定し、別の所で数え上げる、2 つのトピックのイベントを 1 つに数えるなど)は、 状態をエージェントにします。書き方は Elixir の Agent と同じです。

definstance panel do
  {:ok, n} = EHLS.Agent.start_link(0, name: MyApp.Count)
  changes(k_hw(:value)) |> EHLS.Agent.update(n, &set_n/2)                   # 状態だけ
  ticks(200) |> EHLS.Agent.get_and_update(n, &inc_n/2) |> EHLS.PubSub.broadcast(:count)
end

EHLS.Agent.get(MyApp.Count, & &1)                  # CPU から状態を読む(名前を付けたエージェント)

関数は 1 要素ずつ順番に状態を受け取り、それぞれ前の関数が残した状態を見ます。関数として CPU で呼ぶと、本物の Agent の上で動きます。

GenServer としてのインスタンス。 EHLS.Server は、インスタンスを監視ツリーの中で持ちます。アプリケーションと一緒に 始め、呼び出しを順番に受け、トピックのイベントをいくつのプロセスにでも渡します ({EHLS.Server, instance: {MyApp, :panel}, name: Panel, topics: [:count]}、そして EHLS.Server.call(Panel, [:get, :n]))。

9. 回路はリセット直後から動いている

回路は常に動いているので、CPU が読む前にも、データは流れています。

definstance logger, buffer: 1024 do
  ticks(1000) |> map(&larger_plus_one/1)
end

ここで大事なのは、logger(:out, n) が返すのは呼んだあとのデータではなく、たまっている分から順だということです。 たまる量は buffer:(要素の数)で決めます。埋まったあとは、既定(overflow: :wait)ではストリームが止まり、値は失われ ません。overflow: :drop にすると、ストリームは動き続け、新しい値が捨てられます。待てないソースから CPU に返すときは、 :drop を書く必要があります。

今からのデータがほしいときや、初期状態からやり直したいときは、止めて動かします。

logger(:stop)      # 転送を取り消し、リンクとバッファの中身を捨てる
logger(:start)     # 初期状態から動く

値のインスタンスは、止めている間も最後の結果を保ちます。:start で initial: に戻ります。FPGA をリセットせずに アプリケーションだけを入れ替えたときは、回路は動き続けています。前の状態や値が残るので、気になるならアプリケーションの 起動時にこの 2 つを呼びます。

10. FPGA か CPU か

definstance は、関数をいちばん合うところに置きます。FPGA があれば FPGA に、なければ CPU にです。そのため、同じ アプリケーションがボードで動き、テストのときは PC で動きます。

  • FPGA があるとき(ボードのスクリプトや、回路を作る mix ehls.compile / mix ehls.sim)、インスタンスは回路です。
  • ないとき(PC での mix test や iex -S mix)、インスタンスはプロセスです。回路が持つはずのものを持ち、最初の 呼び出しで始まります。呼び方(f(list)、f(binary)、:start、:stop、:value、:state、:out、:request)も結果も 同じです。defhls の関数が同じだからです。
  • 明示もできます: インスタンスの on:(definstance radio(iq), on: :fpga do)や、アプリケーション全体の config :elixir_hls, placement: :cpu | :fpga(または EHLS_PLACEMENT)です。明示したものが優先します。

FPGA に置いたインスタンスの関数を 1 つだけ、CPU で動かすこともできます。CPU では C として動き、その C は mix ehls.compile --target cpu が defhls から作ります。

definstance radio, overflow: :drop, buffer: 512 do
  usb_bulk_in() |> map(&demod/1) |> transform(0, &level/2, on: :cpu) |> i2s_out()
end

radio(:cpu_start, batch: 8192)             # ストリームを CPU に通すプロセスを始める

インスタンスはそこで radio__pre と radio__post の 2 つの回路に分かれ、CPU へのストリームと CPU からのストリームで つながります。間のプロセスが、まとまった要素(バッチ)ごとに関数を通します。FPGA に入りきらない大きな関数には向きますが、 決まったペースを守らなければならない関数には向きません。AtomVM は一度に 1 つのプロセスしか動かさないので、バッチが数十 ミリ秒遅れることがあり、前後の回路はその分を持ちこたえる必要があるからです(buffer: や、待てる出力先)。CPU が 追いついているかは radio(:cpu_stats, pid) で分かります。詳しくは EHLS.Pipeline の "Placement" にあります。

11. 間違えやすいこと

  • 終点の書き忘れ: パイプがストリームのまま終わると、CPU に返すストリームとして受け付けられます。関数の最後の式が 戻り値になるのと同じです。読む人がいなければ、すぐに止まります。mix ehls.compile が CPU との端の一覧を表示するので、 そこで気づけます。状態だけを読むなら run() で終えます。
  • :ok の意味: 入れるだけの呼び出しが返す :ok は、メモリから読み終えたという意味です。音なら、鳴るのはこれからです。
  • 順に呼んで止まる: 大きな入力を入れるだけの呼び出しのあとに、受け取るだけの呼び出しをすると、誰も出力を読まないので 入力が止まり、時間切れになります。入れて受け取る呼び方か、メッセージを使います。
  • wait: false のすぐ後の :value: 回路がまだ計算を終えていなければ、:value は前の結果のことがあります。待つ呼び方なら、 自分の書き込みの結果が返ります。
  • ストリームの途中で値が変わる: 値につないだ関数は、要素を 1 つ受け取るたびにその値を読むので、変わると次の要素から 効きます。CPU のストリーム関数は、リスト全体に 1 つの値を使います。両者は、値が変わらない間は一致します。