ネットワークAPI - DigitalMediaProfessionals/dv-sdk GitHub Wiki

• ネットワーククラスインターフェース
• 層のデータ構造

CDMP_Network クラスはSDK のユーザ空間ドライバを抽象化し、変換されたネットワークアプリケーションを実行するためのインターフェースを提供します。

enum convert_policy {
  CP_DIV_255,
  CP_MINUS_128,
  CP_MINUS_128_DIV_128,
  CP_MINUS_127_5_DIV_128,
  CP_DIRECT_CVT,
  CP_USER_SPECIFY,
  CP_NOTHING,
};

class CDMP_Network {
  // Internal member definitions.
  // ...
 public:
  std::vector<fpga_layer*>& get_output_layers();
  fpga_layer& get_layer(int i);
  int get_total_layer_count() const;
  int get_output_layer_count() const;
  virtual bool Initialize() = 0;
  bool LoadWeights(const std::string& filename);
  bool SetConvertPolicy(convert_policy cvt_policy, bool to_bgr, uint16_t *cvt_table=NULL);
  bool Commit();

  bool RunNetwork();
  void *get_network_input_addr_cpu();
  void get_final_output(std::vector<float>& output, int i_output = 0);
  int get_conv_usec() const;
  int get_fc_usec() const;
  int get_cpu_usec() const;
  void Verbose(int level);
  uint8_t *get_io_ptr() const;
  const dmp_dv_info_v0& get_dv_info() const;
};

以降では各関数を説明します。

  std::vector<fpga_layer*>& get_output_layers()

出力層の定義への参照を返します。

  fpga_layer& get_layer(int i)

インデックスi の層の定義への参照を返します。

  int get_total_layer_count()

全層の数を返します。

  int get_output_layer_count()

出力層の数を返します。ほとんどの場合でネットワークの最後の層が唯一の出力層であり、この関数は1 を返します。 しかし複雑なネットワークのではネットワーク変換ツールが複数の出力層を生成することもあります。 その場合この関数は1 以上の値を返します。

  virtual bool Initialize()

ネットワークを初期化します。

  bool LoadWeights(const std::string& filename)

パックされた重みをファイルから読み込みます。 注: ネットワーク変換ツールから同時に生成されたファイルを使ってください。 現在メタ情報はパックされた重みファイルには含まれません。 そのため正しい重みファイルが読み込まれなくてはなりません。 もしそうしない場合、実行結果は定義されていません。

  bool SetConvertPolicy(convert_policy cvt_policy, bool to_bgr, uint16_t *cvt_table=NULL)

8bit RGB からFP16 への変換を有効にします。 cvt 引数の各値での動作は以下の通りです。

CP_USER_SPECIFY を指定することで、ユーザーは変換テーブルcvt_table を設定できます。 変換テーブルは、長さが768 で__fp16 型の配列です。配列のレイアウトはNC 形式です。 入力値の配列における第iチャネル（i = 0, 1 ,2） の値v の変換後の値をcvt_table[3 * v + i] に設定してください。

CP_USER_SPECIFY が渡され、cvt_table がNULL のとき、この関数は失敗します。

  bool Commit()

ネットワークの設定をコミットします。RunNetwork の前に呼ばれなくてはなりません。

  bool RunNetwork()

ネットワークを実行します。 ネットワーク内の全層が一度に実行されます。 この層にはソフトマックス層やflatten 層などのソフトウェア実装された層も含みます。

  void *get_network_input_addr_cpu()

最初の層の入力バッファのアドレスを返します。

  void get_final_output(std::vector<float>& output, int i_output = 0)

• output 出力データを保存するためのベクトルです。あらかじめそのベクトルに存在していたデータは消去され、出力層のサイズにリサイズされます。
• i_output 出力層のインデックスです。出力層が一つしかなければ省略できます。

出力データを指定されたバッファに、単精度浮動小数点数形式でコピーします。

  int get_conv_usec()

これまでで最後の畳み込み層の実行にかかった時間をマイクロ秒単位で返します。

  int get_fc_usec()

これまでで最後の全結合層の実行にかかった時間をマイクロ秒単位で返します。

  int get_cpu_usec()

これまでで最後のCPU 層の実行にかかった時間をマイクロ秒で返します。

  void Verbose(int level);

verbosity レベルを設定します。

  uint8_t *get_io_ptr()

入出力バッファのベースポインタを返します。

  const dmp_dv_info_v0& get_dv_info()

SDK のコンテキストに関する情報への参照を返します。

fpga_layer 構造体はapplication/common/include/dmp_network.h で次のように定義されています。

enum layer_type {
  LT_INPUT,
  LT_CONV,
  LT_FC,
  LT_FLATTEN,
  LT_CONCAT,
  LT_COPY_CONCAT,
  LT_SOFTMAX,
  LT_CUSTOM,
};

typedef void (*run_custom_callback_proc)(fpga_layer& layer, void *custom_param, uint8_t *io_ptr);

struct fpga_layer {
  layer_type type;
  std::string name;
  union {
    dmp_dv_cmdraw_conv_v0 conv_conf;
    dmp_dv_cmdraw_conv_v1 conv_conf_v1;
    dmp_dv_cmdraw_fc_v0 fc_conf;
    int softmax_axis;
    struct {
      int input_layer_num;
      fpga_layer **input_layers;
    };
    struct {
      run_custom_callback_proc custom_proc_ptr;
      void *custom_param;
    };
  };
  size_t input_offs;
  size_t output_offs;
  size_t output_size;
  int input_dim[3];
  int input_dim_size;
  int output_dim[3];
  int output_dim_size;

  bool is_output;
  bool is_f32_output;
  bool is_input_hw_layout;

  dmp_dv_cmdlist *cmdlist;
  int cmdlist_pos;
  int cmdlist_size;
};

レイヤ種類の列挙型です。現在はネットワーク変換ツールにより次のレイヤ種が生成されます。

• LT_INPUT 入力層です。
• LT_CONV 畳み込み層です。FPGA ではプーリング層とバッチ正則化が統合されています。
• LT_FC 全結合層です。
• LT_FLATEN flatten 層です。必要な時にのみ生成されます。
• LT_CONCAT Concatenate 層です。層の接続情報を保持するためだけに生成されます。
• LT_COPY_CONCAT copy concatenate 層です。FPGA バッファレイアウトの制約に対処するために、コピーされる必要がある層です。
• LT_SOFTMAX ソフトマックス層です。
• LT_CUSTOM カスタムレイヤです。カスタムレイヤの定義がネットワーク変換ツールに与えられたときにのみ生成されます。詳細についてはカスタムレイヤ定義スクリプト をご覧ください。

FPGA 用に変換された層の情報を含みます。各メンバの説明は次の通りです。

• layer_type type 層の種類です。
• std::string name 層の名前です。
• dmp_dv_cmdraw_conv_v0 conv_conf 畳み込み層における、FPGA 用の設定データを含みます。
• dmp_dv_cmdraw_conv_v1 conv_conf_v1 畳み込み層における、FPGA 用の設定データを含みます。
• dmp_dv_cmdraw_fc_v0 fc_conf 全結合層における、FPGA 用の設定データを含みます。
• int softmax_axis ソフトマックス層における、ソフトマックスが適用される軸です。
• int input_layer_num copy concatenate 層における、入力層の数です。
• fpga_layer **input_layers copy concatenate 層における、入力層のポインタ配列です。
• run_custom_callback_proc custom_proc_ptr カスタムレイヤにおける、ソフトウェア実装された関数へのポインタです。
• void *custom_param カスタムレイヤにおける、層の実行時にinput_layers に渡されるパラメータへのポインタです。
• size_t input_offs 入出力バッファのベースアドレスからの入力バッファまでのオフセットです。
• size_t output_offs 入出力バッファのベースアドレスからの出力バッファまでのオフセットです。
• size_t output_size 出力のサイズ（バイト単位）です。
• int input_dim[3] 入力次元です。
• int input_dim_size 入力次元ベクトルの長さです。
• int output_dim[3] 出力次元です。
• int output_dim_size 出力次元ベクトルの長さです。
• bool is_output 層が出力層であるかを示します。
• bool is_f32_output 出力が単精度浮動小数点数であるかを示します。
• bool is_input_hw_layout 入力がFPGA レイヤレイアウトであるかを示します。
• dmp_dv_cmdlist *cmdlist この層を含んでいるコマンドリストです。NULL であることがあります。詳細はドライバインターフェース をご覧ください。
• int cmdlist_pos コマンドリスト内のこの層の位置を示します。
• int cmdlist_size コマンドリストのサイズを示します。