コンテンツにスキップ
日昇 Docs

RKNNモデル展開API説明

1. 基本データ構造定義

本章では、RKNN Runtime C APIで使用する主要なデータ構造を説明します。これらの構造体は、モデル情報、入出力テンソル、性能情報、メモリ管理、推論実行、カスタム情報などを扱うために使用します。

1.1 rknn_sdk_version

構造体rknn_sdk_versionを表しますRKNN SDK的バージョン情報，構造体的定義は次のとおりです：

メンバー変数データ型意味
api_versionchar[]SDK的バージョン情報。
drv_versionchar[]SDK所基于的驱动バージョン情報。

1.2 rknn_input_output_num

構造体rknn_input_output_numは入力テンソルと出力テンソルの数を表し、そのメンバ変数は以下の表に示されています。

メンバー変数データ型意味
n_inputuint32_t输入tensor数。
n_outputuint32_t输入tensor数。

1.3 rknn_input_range

構造体rknn_input_rangeは、入力に対してサポートされる形状のリストを表します。この構造体には、入力インデックス、サポートされる形状の数、データレイアウト形式、名前、および形状リストが含まれます。具体的な構造体定義は、以下の表に示されています。

メンバー変数データ型意味
indexuint32_t入力形状に対応するインデックス位置を示します。
shape_numberuint32_tRKNNモデルがサポートする入力形状の数を示しています。
fmtrknn_tensor_format形状に対応するデータレイアウト形式。
namechar[]入力された名前を示しています。
dyn_rangeuint32_t[][]これは入力シェイプリストを表しており、複数のシェイプ配列を含む2次元配列で、シェイプは優先順位に従って格納されています。
n_dimsuint32_t各形状配列の有効な次元数を示します。

1.4 rknn_tensor_attr

テンソルの属性を表す重要な構造体です。index、n_dims、dims、name、n_elems、size、fmt、type、qnt_type、scale、zero_point、strideなどを含みます。

メンバー変数データ型意味
indexuint32_t入力または出力テンソルのインデックス。
n_dimsuint32_tテンソルの次元数
dimsuint32_t[]テンソル形状
namechar[]テンソル名前
n_elemsuint32_tテンソルデータ要素の数
sizeuint32_tテンソルデータのメモリサイズ
fmtrknn_tensor_formatテンソル次元のフォーマットは以下のとおりです。
RKNN_TENSOR_NCHW、RKNN_TENSOR_NHWC、
RKNN_TENSOR_NC1HWC2、
RKNN_TENSOR_UNDEFINED
typerknn_tensor_typeテンソルデータ型には、RKNN_TENSOR_FLOAT32、RKNN_TENSOR_FLOAT16、RKNN_TENSOR_INT8、RKNN_TENSOR_UINT8、RKNN_TENSOR_INT16、RKNN_TENSOR_UINT16、RKNN_TENSOR_INT32、RKNN_TENSOR_INT64、およびRKNN_TENSOR_BOOLが含まれます。
qnt_typerknn_tensor_qnt_typeテンソル量子化の種類は以下のとおりです。
RKNN_TENSOR_QNT_NONE：量子化なし
RKNN_TENSOR_QNT_DFP：動的固定小数点量子化
RKNN_TENSOR_QNT_AFFINE_ASYMMETRIC：非対称量子化
flint8_tRKNN_TENSOR_QNT_DFP量子化タイプのパラメータ。
scalefloatRKNN_TENSOR_QNT_AFFINE_ASYMMETRIC 量子化タイプのパラメータ。
w_strideuint32_t画像データの1行を格納する実際のピクセル数は、その行の有効なデータピクセル数に、ハードウェアが次の行へ素早くジャンプできるようにパディングされた無効なピクセル数を加えた数（ピクセル単位）に等しくなります。
size_with_strideuint32_t保存された画像データが実際に占める記憶容量（パディングされた無効ピクセルの記憶容量を含む）。
pass_throughuint8_t0は未変換データ、1は変換済みデータを表します。変換には正規化と量子化が含まれます。
h_strideuint32_tこの設定は、複数バッチ入力シナリオでのみ有効で、ユーザー定義です。目的は、NPUが各データバッチの開始アドレスを正しく読み取ることです。このアドレスは、元のモデルの入力高さに、次の列にパディングされた無効なピクセル数を加えた値に等しくなります。この値を0に設定すると、元のモデルの入力高さと同じピクセル数になります。

1.5 rknn_perf_detail

構造体rknn_perf_detailを示しますモデル的性能詳細，構造体的定义次の表のとおりです。

メンバー変数データ型意味
perf_datachar*パフォーマンスの詳細には、ネットワークの各層の実行時間が含まれており、印刷して確認することができます。
data_lenuint64_tパフォーマンスの詳細を格納する文字列配列の長さ。

1.6 rknn_perf_run

構造体rknn_perf_runは、モデルの全体的なパフォーマンスを表します。構造体の定義は以下の表に示されています。

（RV1106/RV1106B/RV1103/RV1103B/RK2118は現在サポートされていません）

メンバー変数データ型意味
run_durationint64_tネットワークの総稼働時間（セットアップ時の入出力を除く）はマイクロ秒単位で測定されます。

1.7 rknn_mem_size

rknn_mem_size構造体は、モデル初期化時のメモリ割り当てを表します。構造体の定義は以下の表に示されています。

メンバー変数データ型意味
total_weight_sizeuint32_tモデルの重みが占めるメモリ量。
total_internal_sizeuint32_tモデル内の中間テンソルのメモリサイズ
total_dma_allocated_sizeuint64_tモデルによって割り当てられたすべてのDMAメモリの合計。
total_sram_sizeuint32_tこれはRK3588にのみ有効で、NPU用に予約されたシステムSRAMのサイズです。
free_sram_sizeuint32_tこれはRK3588にのみ適用され、現在利用可能な空きSRAMサイズを示します。
reserved[12]uint32_t予備領域

1.8 rknn_tensor_mem

構造体rknn_tensor_memを示しますtensor的メモリ情報。構造体的定义次の表のとおりです：

メンバー変数データ型意味
virt_addrvoid*テンソルの仮想アドレス
phys_addruint64_tテンソルの物理アドレス。
fdint32_tこのテンソルのファイルディスクリプタ。
offsetint32_tファイルディスクリプタや仮想アドレスオからのフセット
sizeint32_tこのテンソルが占めるメモリサイズ。
flagsint32_trknn_tensor_mem のフラグには、次のものがあります。RKNN_TENSOR_MEMORY_FALGS_ALLOC_INSIDE: rknn_tensor_mem 構造体が実行時に作成されることを示します。RKNN_TENSOR_MEMORY_FLAGS_FROM_FD: rknn_tensor_mem 構造体がファイルディスクリプタ (fd) から構築されることを示します。RKNN_TENSOR_MEMORY_FLAGS_FROM_PHYS: rknn_tensor_mem 構造体が物理アドレスから構築されることを示します。ユーザーはこれらのフラグに注意を払う必要はありません。
priv_datavoid*メモリ内のプライベートデータ

1.9 rknn_input

構造体 rknn_input は、モデルの1つの入力データを表し、rknn_inputs_set 関数へ渡すパラメータとして使用します。構造体の定義は次のとおりです。

メンバー変数データ型説明
indexuint32_tこの入力のインデックス位置。
bufvoid*入力データへのポインタ。
sizeuint32_t入力データが占有するメモリサイズ。
pass_throughuint8_t1に設定すると、bufに格納された入力データをモデルの入力ノードへ直接設定し、前処理は行いません。
typerknn_tensor_type入力データの型。
fmtrknn_tensor_format入力データの形式。

1.10 rknn_output

構造体 rknn_output は、モデルの1つの出力データを表し、rknn_outputs_get 関数へ渡すパラメータとして使用します。関数実行後、この構造体オブジェクトに値が設定されます。構造体の定義は次のとおりです。

メンバー変数データ型説明
want_floatuint8_t出力データをfloat型へ変換して出力する必要があるかを示します。このフィールドはユーザーが設定します。
is_preallocuint8_t出力データを格納するバッファが事前割り当てかどうかを示します。このフィールドはユーザーが設定します。
indexuint32_tこの出力のインデックス位置。このフィールドはユーザーが設定します。
bufvoid*出力データへのポインタ。このフィールドはインターフェースから返されます。
sizeuint32_t出力データが占有するメモリサイズ。このフィールドはインターフェースから返されます。

1.11 rknn_init_extend

構造体 rknn_init_extend は、モデル初期化時の拡張情報を表します。構造体の定義は次のとおりです（RV1106/RV1106B/RV1103/RV1103B/RK2118 は現在未対応）。

メンバー変数データ型説明
ctxrknn_context初期化済みの rknn_context オブジェクト。
real_model_offsetint32_t実際のRKNNモデルがファイル内に存在するオフセット。ファイルパスをパラメータとして使用する場合、またはゼロコピーのモデルメモリ初期化時のみ有効です。
real_model_sizeint32_t実際のRKNNモデルのファイル内サイズ。ファイルパスをパラメータとして使用する場合、またはゼロコピーのモデルメモリ初期化時のみ有効です。
model_buffer_fdint32_tRKNN_FLAG_MODEL_BUFFER_ZERO_COPY フラグで初期化した後、NPUが割り当てたモデルメモリを表すfd。
model_buffer_flagsint32_tRKNN_FLAG_MODEL_BUFFER_ZERO_COPY フラグで初期化した後、NPUが割り当てたモデルメモリを表すメモリフラグ。
reserveduint8_t[]予約データ領域。

1.12 rknn_run_extend

構造体 rknn_run_extend は、モデル推論時の拡張情報を表します。現在は使用未対応です。構造体の定義は次のとおりです。

メンバー変数データ型説明
frame_iduint64_t現在の推論フレーム番号を示します。
non_blockint32_t0はブロッキングモード、1はノンブロッキングモードを示します。ノンブロッキングでは rknn_run 呼び出しが直接返ります。
timeout_msint32_t推論タイムアウト上限。単位はミリ秒です。
fence_fdint32_tノンブロッキング推論実行用。現在は未対応です。

1.13 rknn_output_extend

構造体 rknn_output_extend は、出力取得時の拡張情報を表します。現在は使用未対応です。構造体の定義は次のとおりです。

メンバー変数データ型説明
frame_idint32_t出力結果のフレーム番号。

1.14 rknn_custom_string

構造体 rknn_custom_string は、RKNNモデル変換時にユーザーが設定するカスタム文字列を表します。構造体の定義は次のとおりです。

メンバー変数データ型説明
stringchar[]ユーザー定義文字列。

2. 基本API説明

2.1 rknn_init

rknn_init 初期化関数は、rknn_context オブジェクトの作成、RKNNモデルの読み込み、および flag と rknn_init_extend 構造体に基づく特定の初期化動作を実行します。

項目内容
APIrknn_init
機能rknnコンテキストを初期化します。
パラメータrknn_context *context：rknn_contextポインタ。
void *model：RKNNモデルのバイナリデータ、またはRKNNモデルのパス。sizeが0より大きい場合、modelはバイナリデータを表します。sizeが0の場合、modelはRKNNモデルパスを表します。
uint32_t size：modelがバイナリデータの場合はモデルサイズを表し、modelがパスの場合は0に設定します。
uint32_t flag：初期化フラグ。デフォルトの初期化動作では0を設定します。
rknn_init_extend：特定の初期化時の拡張情報。使用しない場合はNULLを渡します。モデルweightメモリを共有する場合は、別のモデルのrknn_contextポインタを渡す必要があります。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_context ctx;
int ret = rknn_init(&ctx, model_data, model_data_size, 0, NULL);

各初期化フラグの説明は次のとおりです。

RKNN_FLAG_COLLECT_PERF_MASK：ランタイム時にネットワーク各レイヤーの時間を問い合わせるために使用します。

RKNN_FLAG_MEM_ALLOC_OUTSIDE：モデルの入力、出力、weight、中間テンソルのメモリをすべてユーザーが割り当てることを示します。主な用途は、

1.システム全体のメモリをユーザーが一元的に管理しやすくすること

2.メモリを再利用することです。特にRV1103/RV1106/RV1103B/RV1106B/RK2118のようにメモリが非常に限られる場合に有効です。

モデルAとモデルBが設計上シリアルに実行される場合、2つのモデルの中間テンソルメモリを再利用できます。

例：

rknn_context ctx_a, ctx_b;


rknn_init(&ctx_a, model_path_a, 0, RKNN_FLAG_MEM_ALLOC_OUTSIDE, NULL);
rknn_query(ctx_a, RKNN_QUERY_MEM_SIZE, &mem_size_a, sizeof(mem_size_a));


rknn_init(&ctx_b, model_path_b, 0, RKNN_FLAG_MEM_ALLOC_OUTSIDE, NULL);
rknn_query(ctx_b, RKNN_QUERY_MEM_SIZE, &mem_size_b, sizeof(mem_size_b));


max_internal_size = MAX(mem_size_a.total_internal_size, mem_size_b.total_internal_size);
internal_mem_max = rknn_create_mem(ctx_a, max_internal_size);


internal_mem_a = rknn_create_mem_from_fd(ctx_a, internal_mem_max->fd,
     internal_mem_max->virt_addr, mem_size_a.total_internal_size, 0);
rknn_set_internal_mem(ctx_a, internal_mem_a);


internal_mem_b = rknn_create_mem_from_fd(ctx_b, internal_mem_max->fd,
     internal_mem_max->virt_addr, mem_size_b.total_internal_size, 0);
rknn_set_internal_mem(ctx_b, internal_mem_b);

RKNN_FLAG_SHARE_WEIGHT_MEM：別モデルのweightを共有するために使用します。主に可変長入力を疑似的に扱うために使用されます（RKNPUランタイムライブラリ1.5.0以降では、この機能は動的shape機能に置き換えられます）。

例えば、一部の音声モデルでは入力長が可変ですが、NPUは可変長入力をサポートしていないため、異なる解像度のRKNNモデルを複数生成する必要があります。1つのRKNNモデルのみが完全な重みを保持し、他のモデルは重みが保持されません。重みが保持されないRKNNモデルを初期化する際にこのフラグを使用すると、現在のコンテキストで完全なRKNNモデルの重みを共有できます。解像度AとBの2つのモデルが必要な場合、手順は以下のとおりです。

  1. RKNN-Toolkit2を使用して、解像度Aのモデルを生成します。

  2. RKNN-Toolkit2を使用して、解像度Bの重みが保持されないモデルを生成します。rknn.config()では、主にモデルBのサイズを小さくするために、remove_weightをTrueに設定する必要があります。

  3. モデルAをボード上で通常どおり初期化します。

  4. RKNN_FLAG_SHARE_WEIGHT_MEMフラグを使用して、モデルBを初期化します。 5. 残りは通常どおり使用してください。基板側の参照コードは以下のとおりです。

例：

rknn_context ctx_a, ctx_b;
rknn_init(&ctx_a, model_path_a, 0, 0, NULL);


rknn_init_extend extend;
extend.ctx = ctx_a;
rknn_init(&ctx_b, model_path_b, 0, RKNN_FLAG_SHARE_WEIGHT_MEM, &extend);

RKNN_FLAG_COLLECT_MODEL_INFO_ONLY：空のコンテキストを初期化し、rknn_queryでモデルweightメモリ総量および中間テンソル総量のみを問い合わせます。推論はできません。

RKNN_FLAG_INTERNAL_ALLOC_OUTSIDE：モデル中間テンソルをユーザーが割り当てることを示し、複数モデル間の中間テンソルメモリをユーザーが管理・再利用する場合によく使用します。

RKNN_FLAG_EXECUTE_FALLBACK_PRIOR_DEVICE_GPU：NPUがサポートしないすべてのレイヤーについて、優先的にGPUで実行することを示します。ただしGPU上での実行は保証されず、実際の実行バックエンドはランタイムがその演算子をサポートする状況に依存します。

RKNN_FLAG_ENABLE_SRAM：中間テンソルメモリを可能な限りSRAM上に割り当てます。

RKNN_FLAG_SHARE_SRAM：現在のコンテキストが別のコンテキストのSRAMアドレス空間を共有しようとすることを示します。現在のコンテキスト初期化時に RKNN_FLAG_ENABLE_SRAM を同時に有効にする必要があります。

RKNN_FLAG_DISABLE_PROC_HIGH_PRIORITY：現在のコンテキストにデフォルトのプロセス優先度を使用します。このフラグを設定しない場合、プロセスのnice値は -19 になります。

RKNN_FLAG_DISABLE_FLUSH_INPUT_MEM_CACHE：このフラグを設定すると、runtime内部で入力テンソルキャッシュを自動フラッシュしません。ユーザーは rknn_run 呼び出し前に入力テンソルのキャッシュがフラッシュ済みであることを保証する必要があります。入力データがCPUからアクセスされない場合、runtime内部のキャッシュフラッシュ時間を削減するために使用します。

RKNN_FLAG_DISABLE_FLUSH_OUTPUT_MEM_CACHE：このフラグを設定すると、runtimeは出力テンソルキャッシュを自動クリアしません。この場合、ユーザーは output_mem->virt_addr を直接アクセスできません。アクセスするとキャッシュ整合性の問題が発生します。output_mem->virt_addr を使用したい場合は、rknn_mem_sync(ctx, mem, RKNN_MEMORY_SYNC_FROM_DEVICE) でキャッシュを更新する必要があります。このフラグは通常、NPUの出力データをCPUがアクセスせず、GPUやRGAがアクセスする場合に、キャッシュ更新時間を削減するために使用します。

RKNN_FLAG_MODEL_BUFFER_ZERO_COPY：rknn_initに渡すモデルbufferが rknn_create_mem または rknn_create_mem2 で割り当てられたメモリであり、runtime内部でモデルbufferを再コピーしないことを示します。これにより実行時メモリ使用量を削減できます。ただし、コンテキスト破棄前にモデルメモリが有効であること、およびコンテキスト破棄後にそのメモリを解放することをユーザーが保証する必要があります。

RKNN_MEM_FLAG_ALLOC_NO_CONTEXT： rknn_create_mem2でメモリを割り当てる際にこのフラグを設定すると、ctxパラメータに0またはNULLを指定できます。これにより、どのコンテキストも初期化していない状態でNPUドライバが割り当てるメモリを取得できます。返されたメモリ構造体は rknn_destroy_mem で解放する必要があり、解放時のパラメータには任意のコンテキストを使用できます。

例：

rknn_tensor_mem* model_mem = rknn_create_mem2(ctx, model_size,
RKNN_MEM_FLAG_ALLOC_NO_CONTEXT);
memcpy(model_mem->virt_addr, model_data, model_size);
rknn_init_extend init_ext;
 memset(&init_ext, 0, sizeof(rknn_init_extend));
 init_ext.real_model_offset = 0;
 init_ext.real_model_size = model_size;
 init_ext.model_buffer_fd = model_mem->fd;
 init_ext.model_buffer_flags = model_mem->flags;
 int ret = rknn_init(&ctx, model_mem->virt_addr, model_size, RKNN_FLAG_MODEL_BUFFER_ZERO_COPY,
&init_ext);


// do rknn inference...


rknn_destroy_mem(ctx, model_mem);
rknn_destroy(ctx);

2.2 rknn_set_core_mask

rknn_set_core_mask 関数は、動作するNPUコアを指定します。この関数はRK3576/RK3588プラットフォームのみ対応し、単一コアNPUアーキテクチャのプラットフォームで設定するとエラーが返ります。

項目内容
APIrknn_set_core_mask
機能実行するNPUコアを設定します。
パラメータrknn_context context：rknn_contextオブジェクト。
rknn_core_mask core_mask：NPUコアの列挙型。設定方法は以下のとおりです。
RKNN_NPU_CORE_AUTO：モデルを自動スケジューリングし、現在空いているNPUコア上で自動実行します。
RKNN_NPU_CORE_0：NPU0コア上で実行します。
RKNN_NPU_CORE_1：NPU1コア上で実行します。
RKNN_NPU_CORE_2：NPU2コア上で実行します。
RKNN_NPU_CORE_0_1：NPU0およびNPU1コア上で同時に動作します。
RKNN_NPU_CORE_0_1_2：NPU0、NPU1、NPU2コア上で同時に動作します。
RKNN_NPU_CORE_ALL：すべてのNPUコア上で動作します。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_context ctx;
rknn_core_mask core_mask = RKNN_NPU_CORE_0;
int ret = rknn_set_core_mask(ctx, core_mask);

RKNN_NPU_CORE_0_1 および RKNN_NPU_CORE_0_1_2 モードでは、現在 Conv、DepthwiseConvolution、Add、Concat、Relu、Clip、Relu6、ThresholdedRelu、PRelu、LeakyRelu などのOPでより良い高速化が得られます。その他のOPは単一コアCore0へfallbackして実行されます。一部のOP（Pool系、ConvTransposeなど）は後続バージョンで対応予定です。

2.3 rknn_set_batch_core_num

rknn_set_batch_core_num 関数は、マルチバッチRKNNモデル（RKNN-Toolkit2変換時に rknn_batch_size を1より大きく設定してエクスポートしたモデル）のNPUコア数を指定します。この関数はRK3588/RK3576プラットフォームのみ対応します。

項目内容
APIrknn_set_batch_core_num
機能マルチバッチRKNNモデルを実行するNPUコア数を設定します。
パラメータrknn_context context：rknn_contextオブジェクト。
int core_num：実行するコア数を指定します。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_context ctx;
int ret = rknn_set_batch_core_num(ctx, 2);

2.4 rknn_dup_context

rknn_dup_context は同一モデルを指す新しい context を生成し、同一モデルをマルチスレッドで実行する際のweight再利用に使用できます。RV1106/RV1103/RV1106B/RV1103B/RK2118プラットフォームは現在未対応です。

項目内容
APIrknn_dup_context
機能同一モデルの2つのctxを生成し、モデルのweight情報を再利用します。
パラメータrknn_context *context_in：rknn_contextポインタ。初期化済みのrknn_contextオブジェクト。
rknn_context *context_out：rknn_contextポインタ。新しいrknn_contextオブジェクトを生成します。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_context ctx_in;
rknn_context ctx_out;
int ret = rknn_dup_context(&ctx_in, &ctx_out);

2.5 rknn_destroy

rknn_destroy 関数は、渡された rknn_context および関連リソースを解放します。

項目内容
APIrknn_destroy
機能rknn_contextオブジェクトおよび関連リソースを破棄します。
パラメータrknn_context context：破棄するrknn_contextオブジェクト。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_context ctx;
int ret = rknn_destroy(ctx);

2.6 rknn_query

rknn_query 関数は、モデルの入力/出力情報、各レイヤーの実行時間、モデル推論の総時間、SDKバージョン、メモリ使用量情報、ユーザー定義文字列などの情報を問い合わせて取得できます。

項目内容
APIrknn_query
機能モデルおよびSDK関連情報を問い合わせます。
パラメータrknn_context context：rknn_contextオブジェクト。
rknn_query_cmd：問い合わせコマンド。
void* info：戻り結果を格納する構造体変数。
uint32_t size：infoに対応する構造体変数のサイズ。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

SDKで現在サポートされているクエリコマンドを以下の表に示します。

クエリコマンド戻り結果構造体機能
RKNN_QUERY_IN_OUT_NUMrknn_input_output_num入力テンソルおよび出力テンソルの個数を問い合わせます。
RKNN_QUERY_INPUT_ATTRrknn_tensor_attr入力テンソル属性を問い合わせます。
RKNN_QUERY_OUTPUT_ATTRrknn_tensor_attr出力テンソル属性を問い合わせます。
RKNN_QUERY_PERF_DETAILrknn_perf_detailネットワーク各レイヤーの実行時間を問い合わせます。rknn_init呼び出し時に RKNN_FLAG_COLLECT_PERF_MASK フラグを設定した場合に有効です。
RKNN_QUERY_PERF_RUNrknn_perf_run推論モデルの処理時間（入力/出力設定を含まない）を問い合わせます。単位はマイクロ秒です。
RKNN_QUERY_SDK_VERSIONrknn_sdk_versionSDKバージョンを問い合わせます。
RKNN_QUERY_MEM_SIZErknn_mem_sizeweightおよびネットワーク中間テンソルに割り当てられるメモリサイズを問い合わせます。
RKNN_QUERY_CUSTOM_STRINGrknn_custom_stringRKNNモデル内のユーザー定義文字列情報を問い合わせます。
RKNN_QUERY_NATIVE_INPUT_ATTRrknn_tensor_attrゼロコピーAPI使用時に、NPUが直接読み取るモデル入力属性であるネイティブ入力テンソル属性を問い合わせます。
RKNN_QUERY_NATIVE_OUTPUT_ATTRrknn_tensor_attrゼロコピーAPI使用時に、NPUが直接出力するモデル出力属性であるネイティブ出力テンソル属性を問い合わせます。
RKNN_QUERY_NATIVE_NC1HWC2_INPUT_ATTRrknn_tensor_attrゼロコピーAPI使用時にネイティブ入力テンソル属性を問い合わせます。結果は RKNN_QUERY_NATIVE_INPUT_ATTR と一致します。
RKNN_QUERY_NATIVE_NC1HWC2_OUTPUT_ATTRrknn_tensor_attrゼロコピーAPI使用時にネイティブ出力テンソル属性を問い合わせます。結果は RKNN_QUERY_NATIVE_OUTPUT_ATTR と一致します。
RKNN_QUERY_NATIVE_NHWC_INPUT_ATTRrknn_tensor_attrゼロコピーAPI使用時にネイティブ入力テンソル属性を問い合わせます。結果は RKNN_QUERY_NATIVE_INPUT_ATTR と一致します。
RKNN_QUERY_NATIVE_NHWC_OUTPUT_ATTRrknn_tensor_attrゼロコピーAPI使用時にネイティブ出力NHWCテンソル属性を問い合わせます。
RKNN_QUERY_DEVICE_MEM_INFOrknn_tensor_memモデルbufferのメモリ属性を問い合わせます。
RKNN_QUERY_INPUT_DYNAMIC_RANGErknn_input_range動的形状に対応したRKNNモデル使用時に、モデルがサポートする入力形状数、リスト、形状に対応するデータレイアウトおよび名称などを問い合わせます。
RKNN_QUERY_CURRENT_INPUT_ATTRrknn_tensor_attr動的形状に対応したRKNNモデル使用時に、現在の推論で使用される入力属性を問い合わせます。
RKNN_QUERY_CURRENT_OUTPUT_ATTRrknn_tensor_attr動的形状に対応したRKNNモデル使用時に、現在の推論で使用される出力属性を問い合わせます。
RKNN_QUERY_CURRENT_NATIVE_INPUT_ATTRrknn_tensor_attr動的形状に対応したRKNNモデル使用時に、現在の推論で使用されるNPUネイティブ入力属性を問い合わせます。
RKNN_QUERY_CURRENT_NATIVE_OUTPUT_ATTRrknn_tensor_attr動的形状に対応したRKNNモデル使用時に、現在の推論で使用されるNPUネイティブ出力属性を問い合わせます。

各コマンドの使用方法

1. SDKバージョンの照会

RKNN_QUERY_SDK_VERSION コマンドを渡すことで、RKNN SDKのバージョン情報を問い合わせることができます。先に rknn_sdk_version 構造体オブジェクトを作成する必要があります。

例：

rknn_sdk_version version;
ret = rknn_query(ctx, RKNN_QUERY_SDK_VERSION, &version, sizeof(rknn_sdk_version));
printf("sdk api version: %s\n", version.api_version);
printf("driver version: %s\n", version.drv_version);

2. 入力テンソルおよび出力テンソルの個数の照会

rknn_init インターフェース呼び出し完了後、RKNN_QUERY_IN_OUT_NUM コマンドを渡すことで、モデルの入力テンソルおよび出力テンソルの個数を問い合わせることができます。先に rknn_input_output_num 構造体オブジェクトを作成する必要があります。

例：

rknn_input_output_num io_num;
ret = rknn_query(ctx, RKNN_QUERY_IN_OUT_NUM, &io_num, sizeof(io_num));
printf("model input num: %d, output num: %d\n", io_num.n_input, io_num.n_output);

3. 入力テンソル属性の照会（汎用API用）

rknn_init インターフェース呼び出し完了後、RKNN_QUERY_INPUT_ATTR コマンドを渡すことでモデル入力テンソル属性を問い合わせることができます。先に rknn_tensor_attr 構造体オブジェクトを作成する必要があります。注意：RV1106/RV1103/RV1106B/RV1103B/RK2118で問い合わせたテンソルは、元入力のネイティブテンソルです。

例：

rknn_tensor_attr input_attrs[io_num.n_input];
memset(input_attrs, 0, sizeof(input_attrs));
for (int i = 0; i < io_num.n_input; i++) {
    input_attrs[i].index = i;
    ret = rknn_query(ctx, RKNN_QUERY_INPUT_ATTR, &(input_attrs[i]), sizeof(rknn_tensor_attr));
}

4. 出力テンソル属性の照会（汎用API用）

rknn_init インターフェース呼び出し完了後、RKNN_QUERY_OUTPUT_ATTR コマンドを渡すことでモデル出力テンソル属性を問い合わせることができます。先に rknn_tensor_attr 構造体オブジェクトを作成する必要があります。

例：

rknn_tensor_attr output_attrs[io_num.n_output];
memset(output_attrs, 0, sizeof(output_attrs));
for (int i = 0; i < io_num.n_output; i++) {
    output_attrs[i].index = i;
    ret = rknn_query(ctx, RKNN_QUERY_OUTPUT_ATTR, &(output_attrs[i]), sizeof(rknn_tensor_attr));
}

5. モデル推論の各レイヤー処理時間の照会

rknn_run インターフェース呼び出し完了後、rknn_query に RKNN_QUERY_PERF_DETAIL を渡すことで、ネットワーク推論時の各レイヤー処理時間を問い合わせることができます。単位はマイクロ秒です。このコマンドを使用する前提として、rknn_init の flag パラメータに RKNN_FLAG_COLLECT_PERF_MASK フラグを含める必要があります。

例：

rknn_context ctx;
int ret = rknn_init(&ctx, model_data, model_data_size, RKNN_FLAG_COLLECT_PERF_MASK, NULL);
...
ret = rknn_run(ctx, NULL);
...
rknn_perf_detail perf_detail;
ret = rknn_query(ctx, RKNN_QUERY_PERF_DETAIL, &perf_detail, sizeof(perf_detail));

6. モデル推論の総処理時間の照会

rknn_run インターフェース呼び出し完了後、rknn_query に RKNN_QUERY_PERF_RUN を渡すことで、モデル推論（入力/出力設定を含まない）の処理時間を問い合わせることができます。単位はマイクロ秒です。

例：

rknn_context ctx;
int ret = rknn_init(&ctx, model_data, model_data_size, 0, NULL);
...
ret = rknn_run(ctx, NULL);
...
rknn_perf_run perf_run;
ret = rknn_query(ctx, RKNN_QUERY_PERF_RUN, &perf_run, sizeof(perf_run));

7. モデルのメモリ使用状況の照会

rknn_init インターフェース呼び出し完了後、ユーザーがネットワークメモリを自分で割り当てる必要がある場合、rknn_query に RKNN_QUERY_MEM_SIZE を渡すことで、モデルのweight、ネットワーク中間テンソルのメモリ（入力と出力を含まない）、推論モデルが使用するすべてのDMAメモリ、およびSRAMメモリ（SRAMが有効でない、またはこの機能がない場合は0）の使用状況を問い合わせることができます。このコマンドを使用する前提として、rknn_init の flag パラメータに RKNN_FLAG_MEM_ALLOC_OUTSIDE フラグを含める必要があります。

例：

rknn_context ctx;
int ret = rknn_init(&ctx, model_data, model_data_size, RKNN_FLAG_MEM_ALLOC_OUTSIDE, NULL);
rknn_mem_size mem_size;
ret = rknn_query(ctx, RKNN_QUERY_MEM_SIZE, &mem_size, sizeof(mem_size));

8. モデル内ユーザー定義文字列の照会

rknn_init インターフェース呼び出し完了後、RKNNモデル生成時に追加されたユーザー定義文字列を照会したい場合、rknn_query に RKNN_QUERY_CUSTOM_STRING を渡すことでこの文字列を取得できます。例えば、RKNNモデル変換時にユーザーが「RGB」というカスタム文字列を入力し、RKNNモデル入力がBGR形式の3チャンネル画像ではなくRGB形式の3チャンネル画像であることを識別できます。ランタイム時には、照会した「RGB」情報に基づいてデータをRGB画像へ変換できます。

例：

rknn_context ctx;
int ret = rknn_init(&ctx, model_data, model_data_size, 0, NULL);
rknn_custom_string custom_string;
ret = rknn_query(ctx, RKNN_QUERY_CUSTOM_STRING, &custom_string, sizeof(custom_string));

9. ネイティブ入力テンソル属性の照会（ゼロコピーAPI用）

rknn_initインターフェース呼び出しが完了した後、RKNN_QUERY_NATIVE_INPUT_ATTRコマンド（RKNN_QUERY_NATIVE_NC1HWC2_INPUT_ATTRと同じ）を渡すことで、モデルのネイティブ入力テンソルの属性を照会できます。これには、まずrknn_tensor_attr構造体オブジェクトを作成する必要があります。 例：

rknn_tensor_attr input_attrs[io_num.n_input];
memset(input_attrs, 0, sizeof(input_attrs));
for (int i = 0; i < io_num.n_input; i++) {
   input_attrs[i].index = i;
   ret = rknn_query(ctx, RKNN_QUERY_NATIVE_INPUT_ATTR, &(input_attrs[i]), sizeof(rknn_tensor_attr));
}

10. ネイティブ出力テンソル属性の照会（ゼロコピーAPI用）

rknn_initインターフェース呼び出しが完了した後、RKNN_QUERY_NATIVE_OUTPUT_ATTRコマンド（RKNN_QUERY_NATIVE_NC1HWC2_OUTPUT_ATTRと同じ）を渡すことで、モデルのネイティブ出力テンソルの属性を照会できます。これには、まずrknn_tensor_attr構造体オブジェクトを作成する必要があります。 例：

rknn_tensor_attr output_attrs[io_num.n_output];
memset(output_attrs, 0, sizeof(output_attrs));
for (int i = 0; i < io_num.n_output; i++) {
   output_attrs[i].index = i;
   ret = rknn_query(ctx, RKNN_QUERY_NATIVE_OUTPUT_ATTR, &(output_attrs[i]), sizeof(rknn_tensor_attr));
}

11. NHWC形式ネイティブ入力テンソル属性の照会（ゼロコピーAPI用）

rknn_initインターフェース呼び出しが完了した後、RKNN_QUERY_NATIVE_NHWC_INPUT_ATTRコマンドを渡して、モデルのNHWC形式の入力テンソルの属性を照会できます。これには、まずrknn_tensor_attr構造体オブジェクトを作成する必要があります。 例：

rknn_context ctx;
int ret = rknn_init(&ctx, model_data, model_data_size, RKNN_FLAG_COLLECT_PERF_MASK, NULL);
...
ret = rknn_run(ctx, NULL);
...
rknn_perf_detail perf_detail;
ret = rknn_query(ctx, RKNN_QUERY_PERF_DETAIL, &perf_detail, sizeof(perf_detail));

12. NHWC形式ネイティブ出力テンソル属性の照会（ゼロコピーAPI用）

rknn_initインターフェース呼び出しが完了した後、RKNN_QUERY_NATIVE_NHWC_OUTPUT_ATTRコマンドを渡して、モデルのNHWC形式出力テンソルの属性を照会できます。これには、まずrknn_tensor_attr構造体オブジェクトを作成する必要があります。 例：

rknn_tensor_attr output_attrs[io_num.n_output];
memset(output_attrs, 0, sizeof(output_attrs));
for (int i = 0; i < io_num.n_output; i++) {
   output_attrs[i].index = i;
   ret = rknn_query(ctx, RKNN_QUERY_NATIVE_NHWC_OUTPUT_ATTR,
             &(output_attrs[i]), sizeof(rknn_tensor_attr));
}

13. モデルbufferのメモリ属性の照会

(注: このクエリは RV1106/RV1103/RV1106B/RV1103B/RK2118 でのみサポートされています)

rknn_init インターフェイス呼び出しが完了した後、RKNN_QUERY_DEVICE_MEM_INFO コマンドを渡して、ランタイム内に割り当てられたモデル バッファの属性 (fd、物理アドレス、その他の属性を含む) を照会できます。 例：

rknn_tensor_mem mem_info;
memset(&mem_info, 0, sizeof(mem_info));
ret = rknn_query(ctx, RKNN_QUERY_DEVICE_MEM_INFO, &mem_info, sizeof(mem_info));

14. RKNNモデルがサポートする動的入力形状情報の照会

（注：このインターフェースはRV1106/RV1103/RV1106B/RV1103B/RK2118ではサポートされていません）

rknn_initインターフェース呼び出しが完了した後、RKNN_QUERY_INPUT_DYNAMIC_RANGEコマンドを実行することで、モデルがサポートする入力形状情報（入力形状の数、入力形状のリスト、対応する入力形状のレイアウトと名前など）を照会できます。これには、まずrknn_input_range構造体オブジェクトを作成する必要があります。 例：

rknn_input_range dyn_range[io_num.n_input];
memset(dyn_range, 0, io_num.n_input * sizeof(rknn_input_range));
for (uint32_t i = 0; i < io_num.n_input; i++) {
   dyn_range[i].index = i;
   ret = rknn_query(ctx, RKNN_QUERY_INPUT_DYNAMIC_RANGE,
             &dyn_range[i], sizeof(rknn_input_range));
}

15. RKNNモデルが現在使用する入力動的形状の照会

rknn_set_input_shapes インターフェース呼び出しが完了したら、RKNN_QUERY_CURRENT_INPUT_ATTR コマンドを渡して、モデルで現在使用されている入力属性情報を照会できます。最初に rknn_tensor_attr 構造体を作成する必要があります (注: このコマンドは RV1106/RV1103/RV1106B/RV1103B/RK2118 ではサポートされていません)。 例：

rknn_tensor_attr cur_input_attrs[io_num.n_input];
memset(cur_input_attrs, 0, io_num.n_input * sizeof(rknn_tensor_attr));
for (uint32_t i = 0; i < io_num.n_input; i++) {
   cur_input_attrs[i].index = i;
   ret = rknn_query(ctx, RKNN_QUERY_CURRENT_INPUT_ATTR,
             &(cur_input_attrs[i]), sizeof(rknn_tensor_attr));
}

16. RKNNモデルが現在使用する出力動的形状の照会

rknn_set_input_shapesインターフェース呼び出しが完了したら、RKNN_QUERY_CURRENT_OUTPUT_ATTRコマンドを渡して、モデルで現在使用されている出力属性情報を照会できます。最初にrknn_tensor_attr構造体を作成する必要があります（注：このコマンドはRV1106/RV1103/RV1106B/RV1103B/RK2118ではサポートされていません）。 例：

rknn_tensor_attr cur_output_attrs[io_num.n_output];
memset(cur_output_attrs, 0, io_num.n_output * sizeof(rknn_tensor_attr));
for (uint32_t i = 0; i < io_num.n_output; i++) {
   cur_output_attrs[i].index = i;
   ret = rknn_query(ctx, RKNN_QUERY_CURRENT_OUTPUT_ATTR,
             &(cur_output_attrs[i]), sizeof(rknn_tensor_attr));
}

17. RKNNモデルが現在使用するネイティブ入力動的形状の照会

rknn_set_input_shapes インターフェース呼び出しが完了したら、RKNN_QUERY_CURRENT_NATIVE_INPUT_ATTR コマンドを渡して、モデルが現在使用しているネイティブ入力属性情報を照会できます。これには、まず rknn_tensor_attr 構造体を作成する必要があります (注: このコマンドは RV1106/RV1103/RV1106B/RV1103B/RK2118 ではサポートされていません)。 例：

rknn_tensor_attr cur_input_attrs[io_num.n_input];
memset(cur_input_attrs, 0, io_num.n_input * sizeof(rknn_tensor_attr));
for (uint32_t i = 0; i < io_num.n_input; i++) {
   cur_input_attrs[i].index = i;
   ret = rknn_query(ctx, RKNN_QUERY_CURRENT_NATIVE_INPUT_ATTR,
             &(cur_input_attrs[i]), sizeof(rknn_tensor_attr));
}

18. RKNNモデルが現在使用するネイティブ出力動的形状の照会

rknn_set_input_shapes インターフェース呼び出しが完了したら、RKNN_QUERY_CURRENT_NATIVE_OUTPUT_ATTR コマンドを渡して、モデルが現在使用しているネイティブ出力属性情報を照会できます。これには、まず rknn_tensor_attr 構造体を作成する必要があります (注: このコマンドは RV1106/RV1103/RV1106B/RV1103B/RK2118 ではサポートされていません)。 例：

rknn_tensor_attr cur_output_attrs[io_num.n_output];
memset(cur_output_attrs, 0, io_num.n_output * sizeof(rknn_tensor_attr));
for (uint32_t i = 0; i < io_num.n_output; i++) {
   cur_output_attrs[i].index = i;
   ret = rknn_query(ctx, RKNN_QUERY_CURRENT_NATIVE_OUTPUT_ATTR,
             &(cur_output_attrs[i]), sizeof(rknn_tensor_attr));
}

2.6 rknn_inputs_set

rknn_inputs_set 関数によりモデルの入力データを設定できます。この関数は複数入力をサポートし、各入力は rknn_input 構造体オブジェクトです。渡す前にユーザーが各オブジェクトを設定する必要があります。注：RV1106/RV1103/RV1106B/RV1103B/RK2118 はこのインターフェース未対応です。

項目内容
APIrknn_inputs_set
機能モデル入力データを設定します。
パラメータrknn_context context：rknn_contextオブジェクト。
uint32_t n_inputs：入力データの個数。
rknn_input inputs[]：入力データ配列。配列の各要素は rknn_input 構造体オブジェクトです。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_input inputs[1];
memset(inputs, 0, sizeof(inputs));
inputs[0].index = 0;
inputs[0].type = RKNN_TENSOR_UINT8;
inputs[0].size = img_width * img_height * img_channels;
inputs[0].fmt = RKNN_TENSOR_NHWC;
inputs[0].buf = in_data;
inputs[0].pass_through = 0;
ret = rknn_inputs_set(ctx, 1, inputs);;

2.7 rknn_run

rknn_run 関数は1回のモデル推論を実行します。呼び出し前に rknn_inputs_set 関数、またはゼロコピーインターフェースにより入力データを設定しておく必要があります。

項目内容
APIrknn_run
機能1回のモデル推論を実行します。
パラメータrknn_context context：rknn_contextオブジェクト。
rknn_run_extend* extend：予約拡張。現在は使用しないためNULLを渡します。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

ret = rknn_run(ctx, NULL);

2.8 rknn_outputs_get

rknn_outputs_get 関数はモデル推論の出力データを取得します。この関数は複数の出力データを一度に取得できます。各出力は rknn_output 構造体オブジェクトであり、関数呼び出し前に各 rknn_output オブジェクトを順に作成・設定する必要があります。出力データのbuffer格納には2つの方式があります。1つはユーザーが自分で確保・解放する方式で、この場合 rknn_output オブジェクトの is_prealloc を1に設定し、bufポインタをユーザーが確保したbufferに向けます。もう1つは rknn が割り当てる方式で、この場合 is_prealloc を0に設定すればよく、関数実行後に buf が出力データを指します。注：RV1106/RV1103/RV1106B/RV1103B/RK2118 はこのインターフェース未対応です。

項目内容
APIrknn_outputs_get
機能モデル推論出力を取得します。
パラメータrknn_context context：rknn_contextオブジェクト。
uint32_t n_outputs：出力データの個数。
rknn_output outputs[]：出力データ配列。配列の各要素は rknn_output 構造体オブジェクトで、モデルの1つの出力を表します。
rknn_output_extend* extend：予約拡張。現在は使用しないためNULLを渡します。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_output outputs[io_num.n_output];
memset(outputs, 0, sizeof(outputs));
for (int i = 0; i < io_num.n_output; i++) {
    outputs[i].index = i;
    outputs[i].is_prealloc = 0;
    outputs[i].want_float = 1;
}
ret = rknn_outputs_get(ctx, io_num.n_output, outputs, NULL);

2.9 rknn_outputs_release

rknn_outputs_release 関数は、rknn_outputs_get 関数で取得した出力関連リソースを解放します。

項目内容
APIrknn_outputs_release
機能rknn_outputオブジェクトを解放します。
パラメータrknn_context context：rknn_contextオブジェクト。
uint32_t n_outputs：出力データの個数。
rknn_output outputs[]：破棄する rknn_output 配列。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

ret = rknn_outputs_release(ctx, io_num.n_output, outputs);

2.10 rknn_create_mem_from_phys

ユーザーがNPUで使用するメモリを自分で割り当てる必要がある場合、rknn_create_mem_from_phys 関数により rknn_tensor_mem 構造体を作成し、そのポインタを取得できます。この関数は物理アドレス、仮想アドレス、サイズを渡し、外部メモリ関連情報を rknn_tensor_mem 構造体へ設定します。

項目内容
APIrknn_create_mem_from_phys
機能物理アドレスから rknn_tensor_mem 構造体を作成し、メモリを割り当てます。
パラメータrknn_context context：rknn_contextオブジェクト。
uint64_t phys_addr：メモリの物理アドレス。
void *virt_addr：メモリの仮想アドレス。
uint32_t size：メモリサイズ。
戻り値rknn_tensor_mem*：テンソルメモリ情報構造体ポインタ。

例：

// suppose we have got buffer information as input_phys, input_virt and size
rknn_tensor_mem* input_mems[1];
input_mems[0] = rknn_create_mem_from_phys(ctx, input_phys, input_virt, size);

2.11 rknn_create_mem_from_fd

ユーザーがNPUで使用するメモリを自分で割り当てる必要がある場合、rknn_create_mem_from_fd 関数により rknn_tensor_mem 構造体を作成し、そのポインタを取得できます。この関数はファイルディスクリプタfd、オフセット、仮想アドレス、サイズを渡し、外部メモリ関連情報を rknn_tensor_mem 構造体へ設定します。

項目内容
APIrknn_create_mem_from_fd
機能ファイルディスクリプタから rknn_tensor_mem 構造体を作成します。
パラメータrknn_context context：rknn_contextオブジェクト。
int32_t fd：メモリのファイルディスクリプタ。
void *virt_addr：メモリの仮想アドレス。fdに対応するメモリの先頭アドレス。
uint32_t size：メモリサイズ。
int32_t offset：ファイルディスクリプタおよび仮想アドレスに対するメモリのオフセット。
戻り値rknn_tensor_mem*：テンソルメモリ情報構造体ポインタ。

2.12 rknn_create_mem

ユーザーがNPU内部でメモリを割り当てたい場合、rknn_create_mem 関数はユーザーが指定したメモリサイズを割り当て、rknn_tensor_mem 構造体を返します。

項目内容
APIrknn_create_mem
機能rknn_tensor_mem 構造体を作成し、メモリを割り当てます。
パラメータrknn_context context：rknn_contextオブジェクト。
uint32_t size：メモリサイズ。
戻り値rknn_tensor_mem*：テンソルメモリ情報構造体ポインタ。

例：

// suppose we have got buffer size
rknn_tensor_mem* input_mems[1];
input_mems[0] = rknn_create_mem(ctx, size);

2.13 rknn_create_mem2

ユーザーがNPU内部でメモリを割り当てたい場合、rknn_create_mem2 関数はユーザーが指定したメモリサイズおよびメモリタイプを割り当て、rknn_tensor_mem 構造体を返します。rknn_create_mem2 と rknn_create_mem の主な違いは、rknn_create_mem2 には alloc_flags があり、割り当てるメモリを cacheable にするか指定できる点です。rknn_create_mem は指定できず、デフォルトで cacheable です。

項目内容
APIrknn_create_mem2
機能rknn_tensor_mem 構造体を作成し、メモリを割り当てます。
パラメータrknn_context context：rknn_contextオブジェクト。
uint64_t size：メモリサイズ。
uint64_t alloc_flags：メモリをcacheableにするか制御します。
RKNN_FLAG_MEMORY_CACHEABLE：cacheableメモリを作成します。
RKNN_FLAG_MEMORY_NON_CACHEABLE：non-cacheableメモリを作成します。
RKNN_FLAG_MEMORY_FLAGS_DEFAULT：RKNN_FLAG_MEMORY_CACHEABLE と同じです。
戻り値rknn_tensor_mem*：テンソルメモリ情報構造体ポインタ。

2.14 rknn_destroy_mem

rknn_destroy_mem 関数は rknn_tensor_mem 構造体を破棄します。ユーザーが割り当てたメモリはユーザー自身が解放する必要があります。

項目内容
APIrknn_destroy_mem
機能rknn_tensor_mem 構造体を破棄します。
パラメータrknn_context context：rknn_contextオブジェクト。
rknn_tensor_mem*：テンソルメモリ情報構造体ポインタ。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_tensor_mem* input_mems[1];
int ret = rknn_destroy_mem(ctx, input_mems[0]);

2.15 rknn_set_weight_mem

ユーザーがネットワークweight用メモリを自分で割り当て、対応する rknn_tensor_mem 構造体を初期化した後、rknn_run を呼び出す前に rknn_set_weight_mem 関数を呼び出すことで、NPUにそのメモリを使用させることができます。

項目内容
APIrknn_set_weight_mem
機能weightメモリ情報を含む rknn_tensor_mem 構造体を設定します。
パラメータrknn_context context：rknn_contextオブジェクト。
rknn_tensor_mem*：weightテンソルメモリ情報構造体ポインタ。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_tensor_mem* weight_mems[1];
int ret = rknn_set_weight_mem(ctx, weight_mems[0]);

2.16 rknn_set_internal_mem

ユーザーがネットワーク中間テンソル用メモリを自分で割り当て、対応する rknn_tensor_mem 構造体を初期化した後、rknn_run を呼び出す前に rknn_set_internal_mem 関数を呼び出すことで、NPUにそのメモリを使用させることができます。

項目内容
APIrknn_set_internal_mem
機能中間テンソルメモリ情報を含む rknn_tensor_mem 構造体を設定します。
パラメータrknn_context context：rknn_contextオブジェクト。
rknn_tensor_mem*：モデル中間テンソルメモリ情報構造体ポインタ。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_tensor_mem* internal_tensor_mems[1];
int ret = rknn_set_internal_mem(ctx, internal_tensor_mems[0]);

2.17 rknn_set_io_mem

ユーザーがネットワークの入力テンソルまたは出力テンソル用メモリを自分で割り当て、対応する rknn_tensor_mem 構造体を初期化した後、rknn_run を呼び出す前に rknn_set_io_mem 関数を呼び出すことで、NPUにそのメモリを使用させることができます。

項目内容
APIrknn_set_io_mem
機能モデルの入力/出力メモリ情報を含む rknn_tensor_mem 構造体を設定します。
パラメータrknn_context context：rknn_contextオブジェクト。
rknn_tensor_mem*：入力/出力テンソルメモリ情報構造体ポインタ。
rknn_tensor_attr *：入力/出力テンソルの属性。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_tensor_attr output_attrs[1];
rknn_tensor_mem* output_mems[1];
ret = rknn_query(ctx, RKNN_QUERY_NATIVE_OUTPUT_ATTR, &(output_attrs[0]), sizeof(rknn_tensor_attr));
output_mems[0] = rknn_create_mem(ctx, output_attrs[0].size_with_stride);
rknn_set_io_mem(ctx, output_mems[0], &output_attrs[0]);

2.18 rknn_set_input_shape（deprecated）

このインターフェースは廃止されました。入力形状のバインドには rknn_set_input_shapes インターフェースを使用してください。現在のバージョンでは使用できません。このインターフェースを継続して使用する必要がある場合は、SDK 1.5.0 バージョンを使用し、1.5.0 バージョンの使用ガイド文書を参照してください。

項目内容
APIrknn_set_input_shape
機能廃止済み。現在使用不可。
パラメータなし。
戻り値なし。

2.19 rknn_set_input_shapes

動的形状入力のRKNNモデルでは、推論前に現在使用する入力形状を指定する必要があります。このインターフェースは入力数と rknn_tensor_attr 配列を渡し、各入力の形状と対応するデータレイアウト情報を含めます。各 rknn_tensor_attr 構造体オブジェクトの index、name、dims、fmt、n_dims メンバーを必ず設定し、その他のメンバーは設定不要です。このインターフェースを使用する前に、rknn_query 関数でRKNNモデルがサポートする入力形状数と動的形状リストを問い合わせることができます。入力データの形状は、モデルがサポートする入力形状リスト内に存在する必要があります。初回実行時、または新しい入力形状へ切り替えるたびに、このインターフェースを呼び出して新しい形状を設定する必要があります。そうでなければ、繰り返し呼び出す必要はありません。

項目内容
APIrknn_set_input_shapes
機能モデルが現在使用する入力形状を設定します。
パラメータrknn_context context：rknn_contextオブジェクト。
uint32_t n_inputs：入力テンソルの数量。
rknn_tensor_attr *：入力テンソル属性配列のポインタ。すべての入力形状情報を渡します。ユーザーは各入力属性構造体の index、name、dims、fmt、n_dims メンバーを設定する必要があり、その他のメンバーは設定不要です。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

for (int i = 0; i < io_num.n_input; i++) {
    for (int j = 0; j < input_attrs[i].n_dims; ++j) {
        // 最初の動的入力形状を使用
        input_attrs[i].dims[j] = dyn_range[i].dyn_range[0][j];
    }
}
ret = rknn_set_input_shapes(ctx, io_num.n_input, input_attrs);
if (ret < 0) {
    fprintf(stderr, "rknn_set_input_shapes error! ret=%d\n", ret);
    return -1;
}

2.20 rknn_mem_sync

rknn_create_mem 関数で作成されるメモリは、デフォルトで cacheable フラグを持ちます。cacheable フラグ付きで作成されたメモリをCPUとNPUが同時に使用する場合、cache動作によりデータ整合性の問題が発生する可能性があります。このインターフェースは、cacheable フラグ付きメモリを同期し、CPUとNPUがこのメモリへアクセスするデータの整合性を保証するために使用します。

項目内容
APIrknn_mem_sync
機能CPU cache と DDR データを同期します。
パラメータrknn_context context：rknn_contextオブジェクト。
rknn_tensor_mem* mem：テンソルメモリ情報構造体ポインタ。
rknn_mem_sync_mode mode：CPU cache と DDR データをフラッシュするモードを示します。
RKNN_MEMORY_SYNC_TO_DEVICE：CPU cacheデータをDDRへ同期します。通常、CPUがメモリを書き込んだ後、NPUが同一メモリへアクセスする前に、このモードでcache内データをDDRへ書き戻します。
RKNN_MEMORY_SYNC_FROM_DEVICE：DDRデータをCPU cacheへ同期します。通常、NPUがメモリへ書き込んだ後、次回CPUが同一メモリへアクセスする際にcacheデータを無効化し、CPUがDDRから再読み込みするために使用します。
RKNN_MEMORY_SYNC_BIDIRECTIONAL：CPU cacheデータをDDRへ同期すると同時に、CPUがDDRから再読み込みするようにします。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

ret = rknn_mem_sync(ctx, &outputs[0].mem, RKNN_MEMORY_SYNC_FROM_DEVICE);
if (ret < 0) {
    fprintf(stderr, " rknn_mem_sync error! ret=%d\n", ret);
    return -1;
}

3. 行列乗算データ構造定義

3.1 rknn_matmul_info

rknn_matmul_info は、行列乗算を実行するための仕様情報を表します。行列乗算の規模、入力/出力行列のデータ型、およびメモリレイアウトを含みます。構造体の定義は次のとおりです。

メンバー変数データ型説明
Mint32_t行列Aの行数。
Kint32_t行列Aの列数。
Nint32_t行列Bの列数。
typerknn_matmul_type入力および出力行列のデータ型：
RKNN_FLOAT16_MM_FLOAT16_TO_FLOAT32：行列AとBはfloat16、行列Cはfloat。
RKNN_INT8_MM_INT8_TO_INT32：行列AとBはint8、行列Cはint32。
RKNN_INT8_MM_INT8_TO_INT8：行列A、B、Cはint8。
RKNN_FLOAT16_MM_FLOAT16_TO_FLOAT16：行列A、B、Cはfloat16。
RKNN_FLOAT16_MM_INT8_TO_FLOAT32：行列Aはfloat16、行列Bはint8、行列Cはfloat。
RKNN_FLOAT16_MM_INT8_TO_FLOAT16：行列Aはfloat16、行列Bはint8、行列Cはfloat16。
RKNN_FLOAT16_MM_INT4_TO_FLOAT32：行列Aはfloat16、行列Bはint4、行列Cはfloat。
RKNN_FLOAT16_MM_INT4_TO_FLOAT16：行列Aはfloat16、行列Bはint4、行列Cはfloat16。
RKNN_INT8_MM_INT8_TO_FLOAT32：行列AとBはint8、行列Cはfloat。
RKNN_INT4_MM_INT4_TO_INT16：行列AとBはint4、行列Cはint16。
RKNN_INT8_MM_INT4_TO_INT32：行列Aはint8、Bはint4、行列Cはint32。
B_layoutint16_t行列Bのデータ配置方式。
RKNN_MM_LAYOUT_NORM：行列Bを元の形状、すなわちKxNで配置します。
RKNN_MM_LAYOUT_NATIVE：行列Bを高性能形状で配置します。
RKNN_MM_LAYOUT_TP_NORM：行列BをTranspose後の形状、すなわちNxKで配置します。
B_quant_typeint16_t行列Bの量子化方式タイプ。
RKNN_QUANT_TYPE_PER_LAYER_SYM：行列BをPer-Layer方式で対称量子化します。
RKNN_QUANT_TYPE_PER_LAYER_ASYM：行列BをPer-Layer方式で非対称量子化します。
RKNN_QUANT_TYPE_PER_CHANNEL_SYM：行列BをPer-Channel方式で対称量子化します。
RKNN_QUANT_TYPE_PER_CHANNEL_ASYM：行列BをPer-Channel方式で非対称量子化します。
RKNN_QUANT_TYPE_PER_GROUP_SYM：行列BをPer-Group方式で対称量子化します。
RKNN_QUANT_TYPE_PER_GROUP_ASYM：行列BをPer-Group方式で非対称量子化します。
AC_layoutint16_t行列AおよびCのデータ配置方式。
RKNN_MM_LAYOUT_NORM：行列AとCを元の形状で配置します。
RKNN_MM_LAYOUT_NATIVE：行列AとCを高性能形状で配置します。
AC_quant_typeint16_t行列AおよびCの量子化方式タイプ。
RKNN_QUANT_TYPE_PER_LAYER_SYM：行列AとCをPer-Layer方式で対称量子化します。
RKNN_QUANT_TYPE_PER_LAYER_ASYM：行列AとCをPer-Layer方式で非対称量子化します。
iommu_domain_idint32_t行列コンテキストが存在するIOMMUアドレス空間ドメインのインデックス。IOMMUアドレス空間はコンテキストと一対一に対応し、各IOMMUアドレス空間サイズは4GBです。このパラメータは主に、行列A、B、Cのパラメータ仕様が大きく、あるドメイン内でNPUが割り当てるメモリが4GBを超えた後、別のドメインへ切り替える必要がある場合に使用します。
group_sizeint16_t1グループの要素数。グループ量子化を有効にした場合のみ有効です。
reservedint8_t[]予約フィールド。

3.2 rknn_matmul_tensor_attr

rknn_matmul_tensor_attr は各行列テンソルの属性を表します。行列の名前、形状、サイズ、データ型を含みます。構造体の定義は次のとおりです。

メンバー変数データ型説明
namechar[]行列の名前。
n_dimsuint32_t行列の次元数。
dimsuint32_t[]行列の形状。
sizeuint32_t行列のサイズ。単位はバイトです。
typerknn_tensor_type行列のデータ型。

3.3 rknn_matmul_io_attr

rknn_matmul_io_attr は、行列のすべての入力および出力テンソル属性を表し、行列A、B、Cの属性を含みます。構造体の定義は次のとおりです。

メンバー変数データ型説明
Arknn_matmul_tensor_attr行列Aのテンソル属性。
Brknn_matmul_tensor_attr行列Bのテンソル属性。
Crknn_matmul_tensor_attr行列Cのテンソル属性。

3.4 rknn_quant_params

rknn_quant_params は行列の量子化パラメータを表します。name、scale配列およびzero_point配列へのポインタとその長さを含みます。nameは行列名を識別するために使用され、行列コンテキスト初期化時に得られる rknn_matmul_io_attr 構造体から取得できます。構造体の定義は次のとおりです。

メンバー変数データ型説明
namechar[]行列の名前。
scalefloat*行列のscale配列ポインタ。
scale_lenint32_t行列のscale配列長。
zpint32_t*行列のzero_point配列ポインタ。
zp_lenint32_t行列のzero_point配列長。

3.5 rknn_matmul_shape

rknn_matmul_shape は、特定shapeの行列乗算におけるM、K、Nを表します。動的shapeの行列乗算コンテキストを初期化する際、shapeの数量を指定し、rknn_matmul_shape 構造体配列ですべての入力shapeを表す必要があります。構造体の定義は次のとおりです。

メンバー変数データ型説明
Mint32_t行列Aの行数。
Kint32_t行列Aの列数。
Nint32_t行列Bの列数。

4. 行列乗算API説明

4.1 rknn_matmul_create

この関数は、渡された行列乗算仕様などの情報に基づき、行列乗算コンテキストを初期化し、入力および出力テンソルの形状、サイズ、データ型などの情報を返します。

項目内容
APIrknn_matmul_create
機能行列乗算コンテキストを初期化します。
パラメータrknn_matmul_ctx* ctx：行列乗算コンテキストポインタ。
rknn_matmul_info* info：行列乗算仕様情報構造体ポインタ。
rknn_matmul_io_attr* io_attr：行列乗算入力および出力テンソル属性構造体ポインタ。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_matmul_info info;
memset(&info, 0, sizeof(rknn_matmul_info));
info.M = 4;
info.K = 64;
info.N = 32;
info.type = RKNN_INT8_MM_INT8_TO_INT32;
info.B_layout = RKNN_MM_LAYOUT_NORM;
info.AC_layout = RKNN_MM_LAYOUT_NORM;
rknn_matmul_io_attr io_attr;
memset(&io_attr, 0, sizeof(rknn_matmul_io_attr));
int ret = rknn_matmul_create(&ctx, &info, &io_attr);
if (ret < 0) {
    printf("rknn_matmul_create fail! ret=%d\n", ret);
    return -1;
}

4.2 rknn_matmul_set_io_mem

この関数は行列乗算演算の入力/出力メモリを設定するために使用します。呼び出し前に rknn_create_mem で作成した rknn_tensor_mem 構造体ポインタを用意し、続いて rknn_matmul_create が返した行列A、BまたはCの rknn_matmul_tensor_attr 構造体ポインタとともにこの関数へ渡して、入力および出力メモリを行列乗算コンテキストへ設定します。呼び出し前に、rknn_matmul_infoで設定したメモリレイアウトに従って行列Aと行列Bのデータを準備する必要があります。

項目内容
APIrknn_matmul_set_io_mem
機能行列乗算の入力/出力メモリを設定します。
パラメータrknn_matmul_ctx ctx：行列乗算コンテキスト。
rknn_tensor_mem* mem：テンソルメモリ情報構造体ポインタ。
rknn_matmul_tensor_attr* attr：行列乗算入力および出力テンソル属性構造体ポインタ。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

// Create A
rknn_tensor_mem* A = rknn_create_mem(ctx, io_attr.A.size);
if (A == NULL) {
    printf("rknn_create_mem fail!\n");
    return -1;
}
memset(A->virt_addr, 1, A->size);
// Set A
ret = rknn_matmul_set_io_mem(ctx, A, &io_attr.A);
if (ret < 0) {
    printf("rknn_matmul_set_io_mem fail! ret=%d\n", ret);
    return -1;
}

4.3 rknn_matmul_set_core_mask

この関数は、行列乗算演算で使用可能なNPUコアを設定します（RK3588およびRK3576プラットフォームのみ対応）。呼び出し前に rknn_matmul_create 関数で行列乗算コンテキストを初期化する必要があります。この関数でマスク値を設定し、使用するコアを指定することで、行列乗算演算の性能と効率を向上できます。

項目内容
APIrknn_matmul_set_core_mask
機能行列乗算演算のNPUコアマスクを設定します。
パラメータrknn_matmul_ctx ctx：行列乗算コンテキスト。
rknn_core_mask core_mask：行列乗算演算のNPUコアマスク値。使用可能なNPUコアを指定します。マスクの各ビットが1つのコアを表し、対応ビットが1の場合はそのコアが使用可能であることを示します。0の場合は使用不可です（詳細なマスク説明は rknn_set_core_mask API パラメータを参照）。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_matmul_set_core_mask(ctx, RKNN_NPU_CORE_AUTO);

4.4 rknn_matmul_set_quant_params

rknn_matmul_set_quant_params は、各行列の量子化パラメータを設定するために使用します。Per-Channel量子化、Per-Layer量子化、Per-Group量子化方式の量子化パラメータ設定をサポートします。Per-Group量子化を使用する場合、rknn_quant_params の scale および zp 配列の長さは N*K/group_size です。Per-Channel量子化を使用する場合、scale および zp 配列の長さは N です。Per-Layer量子化を使用する場合、scale および zp 配列の長さは1です。rknn_matmul_run の前にこのインターフェースを呼び出して、すべての行列の量子化パラメータを設定します。このインターフェースを呼び出さない場合、デフォルト量子化方式はPer-Layer量子化で、scale=1.0、zero_point=0です。

項目内容
APIrknn_matmul_set_quant_params
機能行列の量子化パラメータを設定します。
パラメータrknn_matmul_ctx ctx：行列乗算コンテキスト。
rknn_quant_params* params：行列の量子化パラメータ情報。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

rknn_quant_params params_a;
memcpy(params_a.name, io_attr.A.name, RKNN_MAX_NAME_LEN);
params_a.scale_len = 1;
params_a.scale = (float *)malloc(params_a.scale_len * sizeof(float));
params_a.scale[0] = 0.2;
params_a.zp_len = 1;
params_a.zp = (int32_t *)malloc(params_a.zp_len * sizeof(int32_t));
params_a.zp[0] = 0;
rknn_matmul_set_quant_params(ctx, &params_a);

4.5 rknn_matmul_get_quant_params

rknn_matmul_get_quant_params は、rknn_matmul_type が RKNN_INT8_MM_INT8_TO_INT32 で、かつ Per-Channel 量子化方式の場合に、行列Bのすべてのチャネルのscale正規化後のscale値を取得するために使用します。取得したscale値にAの元scale値を掛けることで、Cのscale値を得ることができます。行列Cに実際のscaleがない場合、近似的にCのscaleを計算するために使用できます。

項目内容
APIrknn_matmul_get_quant_params
機能行列Bの量子化パラメータを取得します。
パラメータrknn_matmul_ctx ctx：行列乗算コンテキスト。
rknn_quant_params* params：行列Bの量子化パラメータ情報。
float* scale：行列Bのscaleポインタ。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

float b_scale;
rknn_matmul_get_quant_params(ctx, &params_b, &b_scale);

4.6 rknn_matmul_create_dyn_shape（deprecated）

このインターフェースは廃止されました。代わりに rknn_matmul_create_dynamic_shape インターフェースを使用してください。

項目内容
APIrknn_matmul_create_dyn_shape
機能廃止済み。
パラメータなし。
戻り値なし。

4.7 rknn_matmul_create_dynamic_shape

rknn_matmul_create_dynamic_shape は、動的shape行列乗算コンテキストを作成するために使用します。このインターフェースには rknn_matmul_info 構造体、shape数、対応するshape配列を渡す必要があります。shape配列には複数のM、K、N値が記録されます。初期化成功後、rknn_matmul_io_attr の配列が得られ、配列内にはすべての入力および出力行列のshape、サイズ、データ型などの情報が含まれます。現在、複数の異なるM、K、Nの設定をサポートします。

項目内容
APIrknn_matmul_create_dynamic_shape
機能動的shape行列乗算コンテキストを初期化します。
パラメータrknn_matmul_ctx ctx：行列乗算コンテキストポインタ。
rknn_matmul_info info：行列乗算仕様情報構造体ポインタ。この場合M、K、Nは設定不要です。
int shape_num：行列コンテキストがサポートするshape数。
rknn_matmul_shape dynamic_shapes[]：行列コンテキストがサポートするshape配列。
rknn_matmul_io_attr io_attrs[]：行列乗算入力および出力テンソル属性構造体配列。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

const int shape_num = 2;
rknn_matmul_shape shapes[shape_num];
for (int i = 0; i < shape_num; ++i) {
    shapes[i].M = i + 1;
    shapes[i].K = 64;
    shapes[i].N = 32;
}
rknn_matmul_io_attr io_attr[shape_num];
memset(io_attr, 0, sizeof(rknn_matmul_io_attr) * shape_num);
int ret = rknn_matmul_create_dynamic_shape(&ctx, &info, shape_num, shapes, io_attr);
if (ret < 0) {
    fprintf(stderr, " rknn_matmul_create_dynamic_shape fail! ret=%d\n", ret);
    return -1;
}

4.8 rknn_matmul_set_dynamic_shape

rknn_matmul_set_dynamic_shape は、行列乗算で使用する特定のshapeを指定するために使用します。動的shapeの行列乗算コンテキストを作成した後、rknn_matmul_shape 構造体の1つを入力パラメータとして選択し、このインターフェースを呼び出して演算で使用するshapeを設定します。

項目内容
APIrknn_matmul_set_dynamic_shape
機能行列乗算shapeを設定します。
パラメータrknn_matmul_ctx ctx：行列乗算コンテキスト。
rknn_matmul_shape* shape：行列乗算で使用するshapeを指定します。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

ret = rknn_matmul_set_dynamic_shape(ctx, &shapes[0]);
if (ret != 0) {
    fprintf(stderr, "rknn_matmul_set_dynamic_shapes fail!\n");
    return -1;
}

4.9 rknn_B_normal_layout_to_native_layout

rknn_B_normal_layout_to_native_layout は、行列Bの元形状配置データ（KxN）を高性能データ配置方式のデータへ変換するために使用します。

項目内容
APIrknn_B_normal_layout_to_native_layout
機能行列Bのデータ配置を元形状から高性能形状へ変換します。
パラメータvoid* B_input：元形状の行列Bデータポインタ。
void* B_output：高性能形状の行列Bデータポインタ。
int K：行列Bの行数。
int N：行列Bの列数。
int subN：rknn_matmul_io_attr構造体の B.dims[2] に等しい値。
int subK：rknn_matmul_io_attr構造体の B.dims[3] に等しい値。
rknn_matmul_info* info：行列乗算仕様情報構造体ポインタ。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

int32_t subN = io_attr.B.dims[2];
int32_t subK = io_attr.B.dims[3];
rknn_B_normal_layout_to_native_layout(B_Matrix, B->virt_addr, K, N, subN, subK, &info);

4.10 rknn_matmul_run

この関数は行列乗算演算を実行し、結果を出力行列Cに保存します。この関数を呼び出す前に、入力行列AとBのデータを準備し、rknn_matmul_set_io_mem 関数で入力バッファへ設定しておく必要があります。出力行列Cについても、rknn_matmul_set_io_mem 関数で出力バッファへ設定しておく必要があり、出力行列のテンソル属性は rknn_matmul_create 関数で取得します。

項目内容
APIrknn_matmul_run
機能行列乗算演算を実行します。
パラメータrknn_matmul_ctx ctx：行列乗算コンテキスト。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

int ret = rknn_matmul_run(ctx);

4.11 rknn_matmul_destroy

この関数は行列乗算演算コンテキストを破棄し、関連リソースを解放します。rknn_matmul_create 関数で作成した行列乗算コンテキストポインタを使用し終えた後、この関数を呼び出して破棄する必要があります。

項目内容
APIrknn_matmul_destroy
機能行列乗算演算コンテキストを破棄します。
パラメータrknn_matmul_ctx ctx：行列乗算コンテキスト。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

int ret = rknn_matmul_destroy(ctx);

5. カスタム演算子データ構造定義

5.1 rknn_gpu_op_context

rknn_gpu_op_context は、GPUで実行されるカスタム演算子のコンテキスト情報を表します。構造体の定義は次のとおりです。

メンバー変数データ型説明
cl_contextvoid*OpenCLの cl_context オブジェクト。使用時は cl_context へキャストしてください。
cl_command_queuevoid*OpenCLの cl_command_queue オブジェクト。使用時は cl_command_queue へキャストしてください。
cl_kernelvoid*OpenCLの cl_kernel オブジェクト。使用時は cl_kernel へキャストしてください。

5.2 rknn_custom_op_context

rknn_custom_op_context はカスタム演算子のコンテキスト情報を表します。構造体の定義は次のとおりです。

メンバー変数データ型説明
targetrknn_target_typeカスタム演算子を実行するバックエンドデバイス：
RKNN_TARGET_TYPE_CPU：CPU。
RKNN_TARGET_TYPE_GPU：GPU。
internal_ctxrknn_custom_op_interal_context演算子内部のプライベートコンテキスト。
gpu_ctxrknn_gpu_op_contextカスタム演算子のOpenCLコンテキスト情報を含みます。実行バックエンドデバイスがGPUの場合、コールバック関数内でこの構造体からOpenCLの cl_context などのオブジェクトを取得します。
priv_datavoid*開発者が管理するデータポインタ。

5.3 rknn_custom_op_tensor

rknn_custom_op_tensor はカスタム演算子の入力/出力テンソル情報を表します。構造体の定義は次のとおりです。

メンバー変数データ型説明
attrrknn_tensor_attrテンソルの名称、形状、サイズなどの情報を含みます。
memrknn_tensor_memテンソルのメモリアドレス、fd、有効データオフセットなどの情報を含みます。

5.4 rknn_custom_op_attr

rknn_custom_op_attr はカスタム演算子のパラメータまたは属性情報を表します。構造体の定義は次のとおりです。

メンバー変数データ型説明
namechar[]カスタム演算子のパラメータ名。
dtyperknn_tensor_type各要素のデータ型。
n_elemsuint32_t要素数。
datavoid*パラメータデータメモリ領域の仮想アドレス。

5.5 rknn_custom_op

rknn_custom_op はカスタム演算子の登録情報を表します。構造体の定義は次のとおりです。

メンバー変数データ型説明
versionuint32_tカスタム演算子バージョン番号。
targetrknn_target_typeカスタム演算子の実行バックエンドタイプ。
op_typechar[]カスタム演算子タイプ。
cl_kernel_namechar[]OpenCLのkernel関数名。
cl_kernel_sourcechar*OpenCLのソース名称。cl_source_size が0の場合はファイル絶対パスを表し、cl_source_size が0より大きい場合はkernel関数コードの文字列を表します。
cl_source_sizeuint64_tcl_kernel_sourceが文字列の場合は文字列長を表し、ファイルパスの場合は0に設定します。
cl_build_optionschar[]OpenCL kernelのコンパイルオプション。
initint ()(rknn_custom_op_context op_ctx, rknn_custom_op_tensor* inputs, uint32_t n_inputs, rknn_custom_op_tensor* outputs, uint32_t n_outputs);カスタム演算子初期化コールバック関数ポインタ。登録時に1回呼び出されます。不要な場合はNULLに設定できます。
prepareint ()(rknn_custom_op_context op_ctx, rknn_custom_op_tensor* inputs, uint32_t n_inputs, rknn_custom_op_tensor* outputs, uint32_t n_outputs);前処理コールバック関数ポインタ。rknn_run時に1回呼び出されます。不要な場合はNULLに設定できます。
computeint ()(rknn_custom_op_context op_ctx, rknn_custom_op_tensor* inputs, uint32_t n_inputs, rknn_custom_op_tensor* outputs, uint32_t n_outputs);カスタム演算子機能のコールバック関数ポインタ。rknn_run時に1回呼び出されます。NULLには設定できません。
compute_nativeint ()(rknn_custom_op_context op_ctx, rknn_custom_op_tensor* inputs, uint32_t n_inputs, rknn_custom_op_tensor* outputs, uint32_t n_outputs);高性能計算のコールバック関数ポインタ。computeコールバック関数との違いは、入力および出力テンソルの形式が異なる点です。現在は未対応で、NULLに設定します。
destroyint ()(rknn_custom_op_context op_ctx);リソース破棄コールバック関数ポインタ。rknn_destroy時に1回呼び出されます。

6. カスタム演算子API説明

6.1 rknn_register_custom_ops

コンテキスト初期化に成功した後、この関数はカスタム演算子タイプ、実行バックエンドタイプ、OpenCLカーネル情報、コールバック関数ポインタなど、複数のカスタム演算子情報をコンテキストへ登録するために使用します。登録に成功すると、推論段階で rknn_run インターフェースが開発者の実装したコールバック関数を呼び出します。

項目内容
APIrknn_register_custom_ops
機能複数のカスタム演算子をコンテキストへ登録します。
パラメータrknn_context context：rknn_contextポインタ。関数呼び出し前にcontextは初期化済みである必要があります。
rknn_custom_op op：カスタム演算子情報配列。配列の各要素は rknn_custom_op 構造体オブジェクトです。
uint32_t custom_op_num：カスタム演算子情報配列の長さ。
戻り値int エラーコード（RKNN戻り値エラーコードを参照）。

例：

// CPU operators
rknn_custom_op user_op[2];
memset(user_op, 0, 2 * sizeof(rknn_custom_op));
strncpy(user_op[0].op_type, "cstSoftmax", RKNN_MAX_NAME_LEN - 1);
user_op[0].version = 1;
user_op[0].target = RKNN_TARGET_TYPE_CPU;
user_op[0].init = custom_op_init_callback;
user_op[0].compute = compute_custom_softmax_float32;
user_op[0].destroy = custom_op_destroy_callback;
strncpy(user_op[1].op_type, "ArgMax", RKNN_MAX_NAME_LEN - 1);
user_op[1].version = 1;
user_op[1].target = RKNN_TARGET_TYPE_CPU;
user_op[1].init = custom_op_init_callback;
user_op[1].compute = compute_custom_argmax_float32;
user_op[1].destroy = custom_op_destroy_callback;
ret = rknn_register_custom_ops(ctx, user_op, 2);
if (ret < 0) {
    printf("rknn_register_custom_ops fail! ret = %d\n", ret);
    return -1;
}

6.2 rknn_custom_op_get_op_attr

この関数は、カスタム演算子のコールバック関数内でカスタム演算子のパラメータ情報を取得するために使用します。例えばSoftmax演算子のaxisパラメータなどです。カスタム演算子パラメータのフィールド名と rknn_custom_op_attr 構造体ポインタを渡します。このインターフェースを呼び出すと、パラメータ値は rknn_custom_op_attr 構造体内の data メンバーに格納されます。開発者は返された構造体内の dtype メンバーに基づき、そのポインタをC言語の特定データ型の配列先頭アドレスへキャストし、要素数に従って完全なパラメータ値を読み出します。

項目内容
APIrknn_custom_op_get_op_attr
機能カスタム演算子のパラメータまたは属性を取得します。
パラメータrknn_custom_op_context* op_ctx：カスタム演算子コンテキストポインタ。
const char* attr_name：カスタム演算子パラメータのフィールド名。
rknn_custom_op_attr* op_attr：カスタム演算子パラメータ値を表す構造体。
戻り値なし。

例：

rknn_custom_op_attr op_attr;
rknn_custom_op_get_op_attr(op_ctx, "axis", &op_attr);
if (op_attr.n_elems == 1 && op_attr.dtype == RKNN_TENSOR_INT64) {
   axis = ((int64_t*)op_attr.data)[0];
}
…

7. RKNN戻り値エラーコード

RKNN API関数の戻り値エラーコードの定義は次のとおりです。

エラーコードエラー詳細
RKNN_SUCC(0)実行成功。
RKNN_ERR_FAIL(-1)実行エラー。
RKNN_ERR_TIMEOUT(-2)実行タイムアウト。
RKNN_ERR_DEVICE_UNAVAILABLE(-3)NPUデバイスが使用不可。
RKNN_ERR_MALLOC_FAIL(-4)メモリ割り当て失敗。
RKNN_ERR_PARAM_INVALID(-5)渡されたパラメータが不正。
RKNN_ERR_MODEL_INVALID(-6)渡されたRKNNモデルが無効。
RKNN_ERR_CTX_INVALID(-7)渡されたrknn_contextが無効。
RKNN_ERR_INPUT_INVALID(-8)渡されたrknn_inputオブジェクトが無効。
RKNN_ERR_OUTPUT_INVALID(-9)渡されたrknn_outputオブジェクトが無効。
RKNN_ERR_DEVICE_UNMATCH(-10)バージョンが一致しません。
RKNN_ERR_INCOMPATILE_OPTIMIZATION_LEVEL_VERSION(-12)RKNNモデルに最適化レベルのオプションが設定されていますが、現在のドライバと互換性がありません。
RKNN_ERR_TARGET_PLATFORM_UNMATCH(-13)RKNNモデルが現在のプラットフォームと互換性がありません。