ランタイム グラフ制御 API

パラメーターの推論

カーネル関数の仮引数に整数スカラー値が表示される場合、パラメーターはランタイム パラメーターになります。次の例では、引数 select はランタイム パラメーターです。

#ifndef FUNCTION_KERNELS_H
#define FUNCTION_KERNELS_H
 
  void simple_param(input_window_cint16 * in, output_window_cint16 * out, int select);

#endif

#ifndef FUNCTION_KERNELS_H
#define FUNCTION_KERNELS_H

  void filter_with_array_param(input_window_cint16 * in, output_window_cint16 * out, const int32 (&coefficients)[32]);

#endif

関数引数 (配列パラメーターを含む) の各パラメーターにはポートが推論されます。次の表に、各関数引数に推論されるポートのタイプを示します。

この表から、AI エンジンで関数パラメーターに対して外部から見える変更を加えられない場合、入力ポートが推論されることがわかります。仮引数が値渡しの場合、コピーが作成されるため、そのコピーに対する変更は外部から見えません。パラメーターが const 修飾子付きで渡される場合、パラメーターに書き込めないため、これらも入力ポートとして扱われます。

AI エンジン カーネルにパラメーター参照が渡され、カーネルがそれを変更できる場合、入出力ポートが推論されるので、これを AI エンジン カーネル間でのパラメーター渡し、または制御プロセッサからの結果の読み出しに使用できます。

パラメーターの接続

入力および入出力ランタイム パラメーター ポートは、それらを含むグラフ内の対応する階層的ポートに接続できます。このメカニズムにより、パラメーターはランタイムに変更するためアクセスできるようになります。次のグラフでは、事前に定義された simple_param カーネルのインスタンスが作成されます。このカーネルには、2 つの入力ポートと 1 つの出力ポートがあります。引数リストに現れる最初の引数 in[0] は入力ウィンドウです。2 番目の引数は出力ウィンドウです。3 番目の引数はランタイム パラメーター (ウィンドウ型でもストリーム型でもない) であり、値渡しであるため、入力パラメーター in[1] として推論されます。

次のグラフ定義では、simple_param カーネルがインスタンシエートされ、ウィンドウは in[0] および out[0] (カーネルの入力ウィンドウと出力ウィンドウ) に接続されます。ランタイム パラメーターは、グラフの入力ポート select_value に接続されます。

class parameterGraph : public graph {
private:
  kernel first;
  
public:
  input_port select_value;
  input_port in;
  output_port out;
  parameterGraph() {
    first = kernel::create(simple_param);

    connect< window <32> >(in, first.in[0]);
    connect< window <32> >(first.out[0], out);
    connect<parameter>(select_value, first.in[1]);
  }
};

配列パラメーターも同じ方法で接続できます。配列データには、このカーネルがマップされるプロセッサからアクセスできるように、空間が自動的に割り当てられます。

class arrayParameterGraph : public graph {
private:
  kernel first;
  
public:
  input_port coeffs;
  input_port in;
  output_port out;
  arrayParameterGraph() {
    first = kernel::create(filter_with_array_param);

    connect< window <32> >(in, first.in[0]);
    connect< window <32> >(first.out[0], out);
    connect<parameter>(coeffs, first.in[1]);
  }
};

入力パラメーターの同期

入力ランタイム パラメーター ポートのデフォルト動作は、動作をトリガーすることです。つまり、このパラメーターは、カーネルがいつ起動するかを決定する規則の一部として使用されます。このグラフの例では、カーネルは次の 3 つの条件が満たされたときにのみ起動します。

• 32 バイトの入力データの有効なウィンドウが使用可能
• 出力データ用に 32 バイトの空のウィンドウが使用可能
• 入力パラメーターへの書き込みが発生

トリガー モードでは、入力パラメーターへの 1 回の書き込みでカーネルを 1 回起動でき、カーネルが呼び出されるたびに入力パラメーターの値が設定されます。

入力カーネル パラメーターを非同期で設定できるモードもあります。パラメーターを非同期でアップデートするよう指定するには、ポートの接続時に async 修飾子を使用します。

connect<parameter>(param_port, async(first.in[1]));

カーネル ポートが非同期と指定されている場合、カーネルの起動規則の一部としては使用されません。パラメーターに一度値が書き込まれると、それ以降のカーネル起動にその値が使用されます。PS は、いつでもランタイム パラメーターに新しい値を書き込むことができます。その値は、それ以降のカーネル起動に使用されます。

入出力パラメーターの同期

入出力ランタイム パラメーター ポートのデフォルト動作は、非同期動作です。つまり、パラメーターは制御プロセッサまたはほかのカーネルで読み出すことができますが、プロデューサー カーネルの実行には影響しません。入出力パラメーターからの同期動作で、カーネルの各呼び出しでパラメーター値が読み出されるまでカーネルがブロックされる場合は、次のように、それらを含むグラフで入出力ポートを接続する際に sync 修飾子を使用できます。

connect<parameter>(sync(first.out[1]), param_port);

デフォルトのコンパイル モードでは、main アプリケーションは個別の制御スレッドとしてコンパイルされます。この制御スレッドは、AI エンジン アレイ上で実行されるグラフと並行して PS 上で実行する必要があります。main アプリケーションは、アップデート API および読み出し API を使用して、グラフ内で宣言されたランタイム パラメーターに任意のレベルでアクセスできます。このセクションでは、これらの API を例を使用して説明します。

同期アップデート/読み出し

次のコードは、ランタイム データ パラメーターの指定 に説明されている simple_param グラフの main アプリケーションを示します。

#include "param.h"
parameterGraph mygraph;

int main(void) {
  mygraph.init();
  mygraph.run(2);
  
  mygraph.update(mygraph.select_value, 23);
  mygraph.update(mygraph.select_value, 45);

  mygraph.end();
  return 0;
}

この例では、グラフ mygraph が初期化された後に反復が 2 回実行されます。これにより、受信カーネルの実行ごとに新しい値で更新する必要がある入力パラメーター ポート select_value がトリガーされます。API の最初の引数 update はアップデートするポートを示し、2 番目の引数はその値を示します。ポートの方向、そのデータ型、およびスカラー パラメーターか配列パラメーターかに基づいて、ほかにもいくつかのアップデート API がサポートされています。適応型データフロー グラフ仕様の参考資料 を参照してください。

プログラムが固定された回数のテスト反復を使用してコンパイルされている場合、トリガーされたパラメーターに対して、main プログラム内のアップデート API 呼び出しの数がテスト反復回数と一致している必要があります。一致していない場合、シミュレーションが追加のアップデートを待機し続けることになる可能性があります。非同期パラメーターの場合、アップデートはグラフの実行とは非同期に実行されれ、アップデートされなかった場合はカーネルは以前の値を使用します。

さらに、前のグラフが同期入出力パラメーターを使用してコンパイルされている場合は、次の例に示すように、アップデート呼び出しと読み出し呼び出しを交互に実行する必要があります。

#include "param.h"
parameterGraph mygraph;

int main(void) {
  int result0, result1;
  mygraph.init();
  mygraph.run(2);

  mygraph.update(mygraph.select_value, 23);
  mygraph.read(mygraph.result_out, result0);
  mygraph.update(mygraph.select_value, 45);
  mygraph.read(mygraph.result_out, result1);

  mygraph.end();
  return 0;
}

この例では、グラフは反復ごとに入力ポート result_out を介してスカラー結果を生成すると想定されています。read API は、各反復後にこのポートの値を同期的に読み出すために使用されます。read API の最初の引数はリードバックするグラフの入出力ポートを示し、2 番目の引数はその値を保存する場所を示します (参照により渡す)。

同期プロトコルにより、グラフで値が生成されてから読み出し操作用に値がサンプリングされ、グラフの値が読み出されてから次の反復に進むようになります。このため、update と read を交互に実行することが重要です。

非同期アップデート/読み出し

入力パラメーターが非同期プロトコルで指定されている場合、最初のアップデートが実行されてパラメーターが初期化されてからカーネルが実行されます。ただし、次のアップデートの前に、カーネルが任意の回数実行される可能性があります。これは通常、アプリケーション運用時に非同期にアップデートされることを意図しています。デバッグでは、次の例に示すように、次のアップデートの前に、反復を決まった回数実行するために wait API を使用できます。

#include "param.h"
asyncGraph mygraph;

int main(void) {
  int result0, result1;
  mygraph.init();

  mygraph.update(mygraph.select_value, 23);
  mygraph.run(5);
  mygraph.wait();
  mygraph.update(mygraph.select_value, 45);
  mygraph.run(15);
  mygraph.end();
  return 0;
}

上記の例では、最初のアップデート後に反復が 5 回実行され、その後に別のアップデートが実行されてから、反復が 15 回実行されます。グラフに非同期入出力ポートがある場合は、待機 (または終了) の直後にデータをリードバックすることもできます。

非同期アップデートの別のテンプレートでは、次の例に示すように、wait API でタイムアウトを使用します。

#include "param.h"
asyncGraph mygraph;

int main(void) {
  int result0, result1;
  mygraph.init();
  mygraph.run();
  mygraph.update(mygraph.select_value, 23);
  mygraph.wait(10000);
  mygraph.update(mygraph.select_value, 45);
  mygraph.resume();
  mygraph.end(15000);
  return 0;
}

この例では、グラフは無限に実行されるよう設定されています。ただし、run API が呼び出された後、最初のアップデートでパラメーターが初期化されるまで実行がブロックされます。その後約 10,000 サイクル実行されてから、制御スレッドで別のアップデートが実行できるようになります。新しいアップデートは、次のカーネル呼び出し境界で有効になります。その後、グラフがさらに 15,000 サイクル実行されてから終了します。

上記のランタイム パラメーターの例は、制御プロセッサからランタイム パラメーターをアップデートする機能を示しています。パラメーターのアップデートを AI エンジン 間で伝搬することも可能です。カーネルの入出力ポートがほかのカーネルの入力ポートに接続されている場合、複数の AI エンジンを介してアップデートのチェーンをトリガーできます。次のコードで定義される 2 つのカーネルがあるとします。プロデューサー カーネルには、スカラー整数を読み出す入力ポートと、32 個の整数からなる配列の読み出しと書き込みを実行する入出力ポートがあります。コンシューマー カーネルには、係数の配列を読み出す入力ポートと、データのウィンドウを書き込む出力ポートがあります。

#ifndef FUNCTION_KERNELS_H
#define FUNCTION_KERNELS_H
 
  void producer(const int32 &, int32 (&)[32] );
  void consumer(const int32 (&)[32], output_window_cint16 *);

#endif

次のグラフに示すように、PS はプロデューサー カーネルのスカラー入力をアップデートします。プロデューサー カーネルが実行されると、コンシューマーの実行が自動的にトリガーされます (出力データ用にバッファーが使用可能な場合)。

#include <adf.h>
#include "kernels.h"

using namespace adf;

class chainedGraph : public graph {
private:
  kernel first;
  kernel second;
  
public:
  input_port select_value; 
  output_port out;

  chainedGraph() {
      first =  kernel::create(producer);
      second = kernel::create(consumer);

      connect< window <32> >(second.out[0], out);
      connect<parameter>(select_value, first.in[0]);
      connect<parameter>(first.inout[0], second.in[0]);
  }
};

ストリームの連続処理に使用される値を一度だけアップデートすることが目的である場合は、継続的に実行されることを確実にするため、コンシューマー カーネルのパラメーター入力ポートに async 修飾子を使用できます (パラメーターが指定されている場合)。