ドライバインターフェースAPI - DigitalMediaProfessionals/dv-sdk GitHub Wiki

すべての関数や構造体はdmp_dv.h とdmp_dv_cmdraw_v*.h にて宣言されています。

コンテキスト

デバイスを利用するためには、はじめにコンテキストを作成しなくてはなりません。 dmp_dv_context はコンテキストを利用するためのデータ型です。

`dmp_dv_context_create`

dmp_dv_context dmp_dv_context_create();

AI プロセッサのためのコンテキストを作成します。この関数はスレッドセーフです。

成功時にはNULL 以外の値が、エラー時にはNULL が返されます。

`dmp_dv_context_release`

void dmp_dv_context_release(dmp_dv_context ctx);

AI プロセッサのためのコンテキストが解放されます（参照カウンタを減らします）。 ctx が不要になったときにこの関数を呼んでください。この関数はスレッドセーフです。

ctx AI プロセッサのためのコンテキストです。NULL のときには無視されます。

`dmp_dv_context_retain`

void dmp_dv_context_retain(dmp_dv_context ctx);

AI プロセッサのためのコンテキストをretain します（参照カウンタを増やします）。この関数はスレッドセーフです。

ctx AI プロセッサのためのコンテキストです。NULL のときには無視されます。

`dmp_dv_context_get_info_string`

const char *dmp_dv_context_get_info_string(dmp_dv_context ctx);

コンテキストの情報を表す、人が読める文字列を返します。この関数はスレッドセーフです。

`dmp_dv_context_get_info`

// Structure with information about the context.
typedef struct dmp_dv_info_impl {
  uint32_t size;            // size of this structure
  uint32_t version;         // version of this structure
} dmp_dv_info;


// Structure with information about the context (version 0).
typedef struct dmp_dv_info_v0_impl {
  uint32_t size;               // size of this structure
  uint32_t version;            // version of this structure (set to 0)
  int32_t ub_size;             // unified buffer size
  int32_t max_kernel_size;     // maximum supported convolutional kernel size
  int32_t conv_freq;           // convolutional block frequency in MHz
  int32_t fc_freq;             // fully connected block frequency in MHz
  int32_t max_fc_vector_size;  // fully connected block maximum input vector size in elements
  int32_t rsvd;                // padding to 64-bits
} dmp_dv_info_v0;

int dmp_dv_context_get_info(dmp_dv_context ctx, dmp_dv_info *info);

この関数はそれぞれの構造体をコンテキストの情報で埋めます。関数から返るとき、バージョンフィールドが要求されたバージョンフィールド以下で最新のサーポートバージョンに設定されます。また、構造体の各フィールドは、サイズが十分にあるときにのみ設定されます。この関数はスレッドセーフです。

ctx AI プロセッサのためのコンテキストです。NULL ならば無視されます。
info 情報が格納される構造体です。フィールドsize とversion を設定しなくてはなりません。

成功時には0 が、そうでなければ0 以外の値が返されます。

メモリ管理

この節ではデバイスにアクセスできるメモリの確保などの関数を説明します。 dmp_dv_mem はメモリ確保のためのデータ型です。

`dmp_dv_mem_alloc`

dmp_dv_mem dmp_dv_mem_alloc(dmp_dv_context ctx, size_t size);

デバイスにアクセス可能な物理的に連続なメモリチャンクを確保します。メモリはCMA とION を使って確保されます。この関数が呼ばれた時点ではまだユーザーアドレス空間にもカーネルアドレス空間にもマップされていません。この関数はスレッドセーフです。

ctx AI プロセッサのためのコンテキストです。 NULL のときエラーが返ります。
size メモリサイズ（バイト単位）です

成功時には確保されたメモリのハンドルが、エラー時にはNULL が返されます。

`dmp_dv_mem_release`

void dmp_dv_mem_release(dmp_dv_mem mem);

確保されたメモリを解放します（参照カウンタを減らします）。mem が不要になった時にはこの関数を呼ばなくてはなりません。そのメモリがシステムに返される前にdmp_dv_mem_unmap() が自動的に呼ばれます。この関数はスレッドセーフです。

mem 確保されたメモリのハンドルです。NULLのときは無視されます。

`dmp_dv_mem_retain`

void dmp_dv_mem_retain(dmp_dv_mem mem);

確保されたをメモリをretain します（参照カウンタを増やします）。この関数はスレッドセーフです。

mem 確保されたメモリのハンドルです。NULLのときは無視されます。

`dmp_dv_mem_map`

uint8_t *dmp_dv_mem_map(dmp_dv_mem mem);

以前に確保されたメモリをユーザーアドレス空間にマップします。返されたメモリには書き込みフラグも読み込みフラグも実行フラグも設定されていません。もし与えられたメモリがすでにマップされていた場合、同じポインタが返されます。この関数は異なるメモリハンドルに対してのみスレッドセーフです。

mem 確保されたメモリのハンドル。NULL のときエラーが返されます。

成功時にはユーザーアドレス空間におけるメモリを指すポインタが、エラー時にはNULL が返されます。

`dmp_dv_mem_unmap`

void dmp_dv_mem_unmap(dmp_dv_mem mem);

以前確保され、ユーザーアドレス空間にマップされたメモリをアンマップします。プログラムはこの関数を繰り返し呼ぶことができます。メモリがアンマップされる前に、dmp_dv_mem_sync_end() が自動的に呼ばれます。この関数は異なるメモリハンドルに対してのみスレッドセーフです。

mem 確保されたメモリのハンドルです。NULL のときエラーが返されます。

`dmp_dv_mem_sync_start`

int dmp_dv_mem_sync_start(dmp_dv_mem mem, int rd, int wr);

デバイスとCPU の間でのメモリバッファの同期を開始します。この関数が同じ引数かより少ないフラグ(rd, wr) で何度も呼ばれたとき、何も起こりません。この関数は異なるメモリハンドルに対してのみスレッドセーフです。

mem 確保されたメモリのハンドルです。NULL のときエラーが返されます。
rd もし0 でないなら、デバイスからCPU への同期が、この関数が返る前に発生します。
wr もし0 でないなら、CPU からデバイスへの同期が dmp_dv_mem_sync_end() で発生します。

成功時には0 が、そうでなければ0 以外の値が返されます。

`dmp_dv_mem_sync_end`

int dmp_dv_mem_sync_end(dmp_dv_mem mem);

最後に始めたデバイスとCPU の間での同期を終了します。次のdmp_dv_mem_sync_start() の前にこの関数が再度呼ばれたとき、この関数は何もしないです。この関数は異なるメモリハンドルに対してのみスレッドセーフです。

mem 確保されたメモリのハンドルです。NULL のときエラーが返されます。

成功時には0 を、そうでなければ非ゼロ値が返されます。

`dmp_dv_mem_get_size`

size_t dmp_dv_mem_get_size(dmp_dv_mem mem);

与えられたメモリハンドルのために確保されたメモリサイズ（バイト単位）を返します。この関数はスレッドセーフです。

mem 確保されたメモリのハンドルです。NULL のとき0 が返され、エラーメッセージが設定されます。

メモリサイズをバイト単位で返します。この値はdmp_dv_mem_alloc() で要求されたサイズより大きいことがあります。mem がNULL の時は0 が返されます。

コマンドリスト

コマンドリストは、複数の実行コマンド（例えば、連続した畳み込み操作）を含みます。コマンドリストはそれらのコマンドを、複数の操作を一度に低遅延で実行できるハードウェア特有の実行形式へとパックします。 dmp_dv_cmdlist はコマンドリストのためのデータ型です。

`dmp_dv_cmdlist_create`

dmp_dv_cmdlist dmp_dv_cmdlist_create(dmp_dv_context ctx);

コマンドリストを作成します。この関数はスレッドセーフです。

ctx AI プロセッサのためのコンテキストです。NULL のときエラーが返されます。

成功時にはコマンドリストのハンドルが、エラー時にはNULL が返されます。

`dmp_dv_cmdlist_release`

void dmp_dv_cmdlist_release(dmp_dv_cmdlist cmdlist);

コマンドリストを解放します（参照カウンタを減らします）。cmdlist が不要になった時点でこの関数を呼ばなくてはなりません。この関数はスレッドセーフです。

cmdlist コマンドリストのハンドルです。NULL のときは無視されます。

`dmp_dv_cmdlist_retain`

void dmp_dv_cmdlist_retain(dmp_dv_cmdlist cmdlist);

コマンドリストをretain します（参照カウンタを増やします）。この関数はスレッドセーフです。

cmdlist コマンドリストのハンドルです。NULL のときは無視されます。

`dmp_dv_cmdlist_commit`

int dmp_dv_cmdlist_commit(dmp_dv_cmdlist cmdlist);

コマンドリストをコミットし、さらなる実行に対しデバイス特有の構造を準備します。この関数は異なるコマンドリストに対してのみスレッドセーフです。

cmdlist コマンドリストのハンドルです。NULL のときエラーが返されます。

成功時には0 が、そうでなければ0 以外の値が返されます。

`dmp_dv_cmdlist_exec`

int64_t dmp_dv_cmdlist_exec(dmp_dv_cmdlist cmdlist);

コマンドリストの実行をスケジュールします。各コンテキストには一つの実行キューが結び付けられます。この関数はスレッドセーフです。

cmdlist コマンドリストのハンドルです。NULL のときエラーが返されます。

コマンドリストの実行の成功時には0 以上の実行ID が、エラー時には負の値が返されます。

`dmp_dv_cmdlist_wait`

int dmp_dv_cmdlist_wait(dmp_dv_cmdlist cmdlist, int64_t exec_id);

特定のスケジュールされたコマンドが完了するまで待ちます。この関数はスレッドセーフです。

cmdlist コマンドリストのハンドルです。NULL のときエラーが返されます。
exec_id 完了を待つスケジュール済みのコマンドの実行 IDです。

成功時には0 が、そうでなければ0 以外の値が返されます。

`dmp_dv_cmdlist_add_raw`

// Memory buffer specification.
typedef struct dmp_dv_buf_impl {
  union {
    dmp_dv_mem *mem;  // memory handle
    uint64_t rsvd;    // padding to 64-bit size
  };
  uint64_t offs;      // offset from the start of the buffer, must be 16-bit aligned
} dmp_dv_buf;

// Convolutional device type id.
#define DMP_DV_DEV_CONV 1

/// Fully connected device type id.
#define DMP_DV_DEV_FC 2

/// Upper bound of different device type ids.
#define DMP_DV_DEV_COUNT 3

/// Raw command for execution.
struct dmp_dv_cmdraw {
  uint32_t size;        // size of this structure
  uint8_t device_type;  // device type
  uint8_t version;      // version of this structure
  uint8_t rsvd[2];      // padding to 64-bit size
} ;

// Convolution layer runs.
struct dmp_dv_cmdraw_conv_v0_run {
  dmp_dv_buf weight_buf;    // Buffer with packed weights
  uint32_t conv_pad;        // Bits [7:0] = left padding, bits [15:8] = right padding, bits [23:16] = top padding, bits [31:24] = bottom padding
  uint32_t pool_pad;        // Bits [7:0] = left padding, bits [15:8] = right padding, bits [23:16] = top padding, bits [31:24] = bottom padding
  uint16_t m;               // Number of Output Channels
  uint16_t conv_enable;     // 1 = Enabled, 0 = Disabled, 3 = Depthwise
  uint16_t p;               // Filter Size (bits[7:0] = width, bits[15:8] = height)
  uint16_t pz;              // Filter Depth (1 in case of 2D convolution)
  uint16_t conv_stride;     // Bits [7:0] = X stride, bits [15:8] = Y stride
  uint16_t conv_dilation;   // Bits [7:0] = X dilation, bits [15:8] = Y dilation
  uint16_t weight_fmt;      // Weights format (0 = random access blocks, 1 = compact stream, 3 = 8-bit quantized stream)
  uint16_t pool_enable;     // 0 = disabled, 1 = max pooling, 2 = average pooling, 4 - upsampling
  uint16_t pool_avg_param;  // Usually be set to 1/pool_size^2 in FP16 when using average pooling (average pooling assumes square size)
  uint16_t pool_size;       // Bits [7:0] = width, bits [15:8] = height
  uint16_t pool_stride;     // Bits [7:0] = X stride, bits [15:8] = Y stride
  uint16_t actfunc;         // Activation Function: 0 = None, 1 = Tanh, 2 = Leaky ReLU, 3 = Sigmoid, 4 = PReLU, 5 = ELU, 6 = ReLU6
  uint16_t actfunc_param;   // Leaky ReLU parameter in FP16
  uint16_t rectifi_en;      // Rectification, i.e. max(0, x) (NOTE: Can be applied after non-ReLU activation function)
  uint16_t lrn;             // Bits [0]: 1 = LRN enable, 0 = LRN disable, [1]: 1 = incl. power func, 0 = excl., [8:11]: x^2 scale factor log2
  uint16_t rsvd;            // padding to 64-bit size
};

// Raw command for convolutional block version 0.
struct dmp_dv_cmdraw_conv_v0 {
  dmp_dv_cmdraw header;               // General structure information

  dmp_dv_buf input_buf;               // Input buffer
  dmp_dv_buf output_buf;              // Output buffer
  dmp_dv_buf eltwise_buf;             // Buffer for elementwise add (0 = UBUF Input Buffer)
  uint32_t topo;                      // [31:0] Output Destination of each run, 0 = UBUF, 1 = EXTMEM
  uint16_t w;                         // Input Width
  uint16_t h;                         // Input Height
  uint16_t z;                         // Input Depth
  uint16_t c;                         // Input Channels
  uint16_t input_circular_offset;     // Input Depth circular offset
  uint16_t output_mode;               // 0 = concat, 1 = elementwise add

  struct dmp_dv_cmdraw_conv_v0_run run[32];  // description of each run
} dmp_dv_cmdraw_conv_v0;

// Raw command for fully connected block version 0.
struct dmp_dv_cmdraw_fc_v0 {
  dmp_dv_cmdraw header;    // General structure information

  dmp_dv_buf weight_buf;   // Buffer with packed weights
  dmp_dv_buf input_buf;    // Input buffer
  dmp_dv_buf output_buf;   // Output buffer

  uint16_t input_size;     // Size of the input in elements
  uint16_t output_size;    // Size of the output in elements

  uint16_t weight_fmt;     // Weights format: 0 = half-float unquantized, 1 = 8-bit quantized

  uint16_t actfunc;        // Activation Function: 0 = None, 1 = ReLU, 2 = Tanh, 3 = Leaky ReLU, 4 = Sigmoid, 5 = PReLU (PReLU must be used with POST-OP=1)
  uint16_t actfunc_param;  // Leaky ReLU parameter (in FP16 format), 0 = non-leaky
  uint16_t rsvd[3];        // padding to 64-bit size
};

// Raw command for convolutional block version 1.
struct dmp_dv_cmdraw_conv_v1 {
  struct dmp_dv_cmdraw header;  // General structure information

  struct dmp_dv_buf u8tofp16_table;  // u8tofp16 conversion table
  uint16_t to_bgr;                   // flag to convert input to BGR format
  uint16_t rsvd[3];                  // padding

  struct dmp_dv_cmdraw_conv_v0 conv_cmd;  // Includes version 0 command
};

int dmp_dv_cmdlist_add_raw(dmp_dv_cmdlist cmdlist, struct dmp_dv_cmdraw *cmd);

コマンドリストにコマンドを追加します。この関数は異なるコマンドリストに対してのみスレッドセーフです。

cmdlist コマンドリストのハンドルです。NULL のときエラーが返されます。
cmd 実行するコマンドです。コマンドバージョン0 についてはdmp_dv_cmdraw_v0.h をご覧ください。コマンドバージョン1 についてはdmp_dv_cmdraw_v1.h をご覧ください。

成功時には0 が、そうでなければ0 以外の値が返されます。エラーコードは以下の通りです。

EINVAL 無効な引数が渡されました。
ENOTSUP 与えられたコマンドバージョンはサポートされていません。

重みのパッキング

この節では層の重みをハードウェア特有の配置にパックするための関数を説明します。

`dmp_dv_pack_conv_weights`

int dmp_dv_pack_conv_weights(
    int n_channels, int kx, int ky, int n_kernels,
    const uint16_t quant_map[256],
    const void *weights, const uint16_t *bias,
    uint8_t *packed_weights, size_t *packed_weights_size);

畳み込み層の重みとバイアスを出力配列にパックします。この関数はスレッドセーフです。

n_channels 入力のチャネル数
kx カーネルの幅
ky カーネルの高さ
n_kernels 出力のチャネル数
quant_map 重みのための量子化テーブル。256 要素あり、NULL にできます。
weights quant_map がNULL ならば、NCDW フォーマットの半精度浮動小数点数であらわされる重みの配列、そうでなければ1バイトインデックスの配列
bias 半精度浮動小数点数のバイアスの、サイズがn_kernels の配列
packed_weights パックされた重み情報のための出力バッファ。もし`packed_weights_size が0 ならばNULL を指定できます。
packed_weights_size 入力としてはpacked_weights バッファの大きさ（バイト単位）です。0 を指定することもできます。出力としては、必要なバッファサイズが与えられます。

成功時には0 が、そうでなければ0 以外の値が返されます。

`dmp_dv_pack_fc_weights`

int dmp_dv_pack_fc_weights(
    int c_input, int h_input, int w_input,
    int c_output, int h_output, int w_output,
    const uint16_t quant_map[256],
    const void *weights, const uint16_t *bias,
    uint8_t *packed_weights, size_t *packed_weights_size);

全結合層の重みとバイアスを、入力と出力の形に合わせるように並び替えながら、出力配列にパックします。この関数はNCHW フォーマットの重みをAI プロセッサの入力フォーマットであるWHC8 フォーマットに、配列を並び替えてパックします。この関数はスレッドセーフです。

c_input 入力のチャネル数
h_input 入力の高さ。入力が一次元の際は1 を指定してください。
w_input 入力の幅。入力が一次元の際は1 を指定してください。
c_output 出力のチャネル数
h_output 出力の高さ。入力が一次元の際は1 を指定してください。
w_output 出力の幅。入力が一次元の際は1 を指定してください。
quant_map 重みのための量子化テーブル。256 要素あり、NULL にできます。
weights quant_map がNULL ならば、NCDW フォーマットの半精度浮動小数点数であらわされる重みの配列、そうでなければ1バイトインデックスの配列
bias半精度浮動小数点数のバイアスの、サイズがoutput_size=c_output*h_output*w_output の配列
packed_weights パックされた重み情報のための出力バッファ。もし`packed_weights_size が0 ならばNULL を指定できます。
packed_weights_size 入力としてはpacked_weights バッファの大きさ（バイト単位）です。0 を指定することもできます。出力としては、必要なバッファサイズが与えられます。

成功時には0 が、そうでなければ0 以外の値が返されます。

一般情報関数

この節では一般情報関数を説明します。

`dmp_dv_get_version_string`

const char* dmp_dv_get_version_string();

ドライバインターフェースのバージョン文字列を返します。この関数はスレッドセーフです。

返される文字列は HW_MAJOR.HW_MINOR.YYYYMMDD で始まります。例えば "7.0.20181214" です。

`dmp_dv_get_last_error_message`

const char* dmp_dv_get_last_error_message();

最後のエラーメッセージが返されます。この関数の呼び出し中に、複数の関数がいくつかあるスレッドにより失敗したとき、この関数は有効な値を返さないことがあります。

`dmp_dv_fpga_device_exists`

int dmp_dv_fpga_device_exists(dmp_dv_context ctx, int dev_type_id);

指定されたFPGAブロックが存在するか確認します。

ctx AI プロセッサのためのコンテキストです。NULL のときには-1 が返されます。
dev_type_id ブロックタイプのID です。DMP_DV_DEV_* マクロを指定できます。

不正な引数が渡しされたときは-1 が、FPGA ブロックが存在するときは1 が、そうでもないときは0 が返されます。