SDK API

概要

AXCL API は 2 つの部分に分かれています。1 つ目は Runtime API、2 つ目は Native API です。
Runtime API は独立した API 群で、現時点ではメモリ管理用の Memory と、愛芯通元(TM) NPU の動作を制御する Engine API のみを含みます。
AXCL API が計算カード形態で使用され、エンコード／デコード機能を使用しない場合は、Runtime API のみで全ての計算タスクを完了できます。
エンコード／デコード機能が必要な場合は、Native API および FFMPEG モジュールに関する知識が必要となります。

runtime

Runtime API を使用すると、ホストシステム上で NPU を呼び出して計算機能を実行できます。
Memory API は、ホストおよび計算カード上でそれぞれメモリ空間の確保と解放を行うことができ、
Engine API はモデル初期化や IO 設定から推論までの全ての NPU 機能を実行できます。

runtime

axclInit

axclError axclInit(const char *config);

使用説明：

システム初期化。同期インターフェース。

パラメータ：

• config [IN]：指定する JSON 設定ファイルのパス。
  • ユーザーは JSON 設定ファイルを通じてシステムパラメータを設定できます。現時点ではログレベルの設定をサポートします。形式は FAQを参照。
  • NULL または存在しない JSON ファイルを渡すと、システムはデフォルト設定を使用します。

制限：

• axclFinalize とペアで呼び出し、システムをクリーンアップします。
• いかなる AXCL インターフェースを呼び出す前にも、本インターフェースを最初に呼び出す必要があります。
• 1 つのプロセス内で本インターフェースは一度だけ呼び出します。

axclFinailze

axclError axclFinalize();

使用説明：

システムの終了処理を行い、プロセス内の AXCL リソースを解放する同期インターフェース。

制限：

• axclInit とペアで呼び出します。
• アプリケーションプロセス終了前には明示的に本インターフェースを呼び出して終了処理を行うべきです。
• C++ アプリケーションではデストラクタでの呼び出しは推奨しません。プロセス終了時にシングルトンのデストラクタ順が不確定なため、異常終了する可能性があります。

axclrtGetVersion

axclError axclrtGetVersion(int32_t *major, int32_t *minor, int32_t *patch);

使用説明：

システムバージョンを取得する同期インターフェース。

パラメータ：

• major [OUT]：メジャーバージョン番号。
• minor [OUT]：マイナーバージョン番号。
• patch [OUT]：パッチバージョン番号。

制限：

特に制限はありません。

axclrtGetSocName

const char *axclrtGetSocName();

使用説明：

現在使用中のチップ SOC 名文字列を取得する同期インターフェース。

制限：

特に制限はありません。

axclrtSetDevice

axclError axclrtSetDevice(int32_t deviceId);

使用説明：

現在のプロセスまたはスレッドで使用するデバイスを指定し、同時にデフォルト Context を暗黙的に作成する同期インターフェース。

パラメータ：

• deviceId [IN]：デバイス ID。

制限：

• 本インターフェース内でデフォルト Context を暗黙的に作成します。この Context は axclrtResetDevice により自動的に回収され、axclrtDestroyContext で明示的に破棄することはできません。
• 同一プロセス内の複数スレッドで同じ deviceId を指定して本インターフェースを呼び出す場合、暗黙的に作成される Context は同一です。
• axclrtResetDevice とペアで呼び出し、本プロセスが使用するデバイスリソースを解放します。内部は参照カウントで管理され、参照カウントが 0 になった時点で解放されます。
• 複数デバイス利用時は、本インターフェースまたは axclrtSetCurrentContext によりデバイスを切り替えることができます。

axclrtResetDevice

axclError axclrtResetDevice(int32_t deviceId);

使用説明：

デバイスをリセットし、デバイス上のリソース（暗黙または明示的に作成された Context を含む）を解放する同期インターフェース。

パラメータ：

• deviceId [IN]：デバイス ID。

制限：

• axclrtCreateContext で明示的に作成した Context は、本インターフェースでデバイスリソースを解放する前に axclrtDestroyContext で明示的に破棄することを推奨します。
• axclrtSetDevice とペアで使用し、デフォルト Context リソースはシステムにより回収されます。
• 内部は参照カウントによって複数回の呼び出しを許容し、カウントが 0 になったときに解放されます。
• アプリケーションプロセス終了時には必ず axclrtResetDevice を呼び出すようにしてください。特に例外シグナル捕捉処理後にこれを行わないと、C++ が terminated abort を投げ、異常終了する恐れがあります。

axclrtGetDevice

axclError axclrtGetDevice(int32_t *deviceId);

使用説明：

現在使用中のデバイス ID を取得する同期インターフェース。

パラメータ：

• deviceId [OUT]：デバイス ID。

制限：

• axclrtSetDevice または axclrtCreateContext でデバイスを指定していない場合、本インターフェースはエラーを返します。

axclrtGetDeviceCount

axclError axclrtGetDeviceCount(uint32_t *count);

使用説明：

接続されているデバイスの総数を取得する同期インターフェース。

パラメータ：

• count [OUT]：デバイス数。

制限：

特に制限はありません。

axclrtGetDeviceList

axclError axclrtGetDeviceList(axclrtDeviceList *deviceList);

使用説明：

接続されている全てのデバイス ID を取得する同期インターフェース。

パラメータ：

• deviceList[OUT]：接続されている全デバイス ID 情報。

制限：

特に制限はありません。

axclrtSynchronizeDevice

axclError axclrtSynchronizeDevice();

使用説明：

現在のデバイスのすべてのタスクを同期実行する同期インターフェース。

制限：

少なくとも 1 つのデバイスをアクティブ化する必要があります。

axclrtGetDeviceProperties

axclError axclrtGetDeviceProperties(int32_t deviceId, axclrtDeviceProperties *properties);

使用説明：

デバイスの UID、CPU 使用率、NPU 使用率、メモリなどの情報を取得する同期インターフェース。

制限：

axclrtCreateContext

axclError axclrtCreateContext(axclrtContext *context, int32_t deviceId);

使用説明：

現在のスレッドで明示的に Context を作成する同期インターフェース。

パラメータ：

• context [OUT]：作成された Context ハンドル。
• deviceId [IN]：デバイス ID。

制限：

• ユーザーが作成したサブスレッドで AXCL API を呼び出す場合は、本インターフェースで明示的に作成するか、または axclrtSetCurrentContext で Context をバインドする必要があります。
• 指定されたデバイスがアクティブ化されていない場合、本インターフェース内部で最初にデバイスをアクティブ化します。
• axclrtDestroyContext を呼び出して明示的に Context リソースを解放します。
• 複数スレッドで 1 つの Context を共有することは可能（axclrtSetCurrentContext でバインド）ですが、タスクの実行はシステムのスレッドスケジューリング順序に依存します。ユーザーはスレッド間のタスク実行の順序を自分で管理する必要があります。マルチスレッド環境では、各スレッドごとに専用の Context を作成することを推奨します。これはプログラムの保守性を高めます。

axclrtDestroyContext

axclError axclrtDestroyContext(axclrtContext context);

使用説明：

明示的に Context を破棄する同期インターフェース。

パラメータ：

• context [IN]：作成された Context ハンドル。

制限：

• axclrtCreateContext によって作成された Context リソースのみを破棄できます。

axclrtSetCurrentContext

axclError axclrtSetCurrentContext(axclrtContext context);

使用説明：

スレッドが実行する Context をバインドする同期インターフェース。

パラメータ：

• context [IN]：Context ハンドル。

制限：

• 本インターフェースを複数回呼び出した場合、最後に設定した Context が有効となります。
• バインドされた Context のデバイスが axclrtResetDevice によってリセットされている場合、その Context をスレッドに設定することはできません。そうすると異常が発生します。
• あるスレッドで作成した Context は、そのスレッドで使用することを推奨します。スレッド A で axclrtCreateContext によって作成した Context をスレッド B で使用する場合は、同じ Context 下でのタスク実行順序をユーザーが自ら保証する必要があります。

axclrtGetCurrentContext

axclError axclrtGetCurrentContext(axclrtContext *context);

使用説明：

スレッドにバインドされている Context ハンドルを取得する同期インターフェース。

パラメータ：

• context [OUT]：現在の Context ハンドル。

制限：

• 呼び出しスレッドは axclrtSetCurrentContext を実行してバインドするか、または axclrtCreateContext で Context を作成した後に取得できます。
• axclrtSetCurrentContext を複数回呼び出した場合、最後に設定した Context が取得されます。

memory

axclrtMalloc

axclError axclrtMalloc(void **devPtr, size_t size, axclrtMemMallocPolicy policy);

使用説明：

デバイス側に非 CACHED 物理メモリを割り当て、 devPtr を通じて割り当てられたメモリのポインタを返す同期インターフェース。

パラメータ：

• devPtr [OUT]：割り当てられたデバイス側物理メモリのポインタ。
• size [IN]：割り当てるメモリサイズ（バイト単位）。
• policy[IN]：メモリ割当ルールの指定、現時点では未使用。

制限：

• 本インターフェースはデバイス側 CMM メモリプールから連続した物理メモリを割り当てます。
• 本インターフェースは非 CACHED メモリを割り当てるため、一貫性処理を行う必要はありません。
• axclrtFree を呼び出してメモリを解放します。
• 頻繁なメモリの割り当てと解放は性能を低下させるため、事前割り当てや二次管理を行い、頻繁な割り当て・解放を避けることを推奨します。

axclrtMallocCached

axclError axclrtMallocCached(void **devPtr, size_t size, axclrtMemMallocPolicy policy);

使用説明：

デバイス側に CACHED 物理メモリを割り当て、 devPtr を通じて割り当てられたメモリポインタを返す同期インターフェース。

パラメータ：

• devPtr [OUT]：割り当てられたデバイス側物理メモリのポインタ。
• size [IN]：割り当てるメモリサイズ（バイト単位）。
• policy[IN]：メモリ割当ルールの指定、現時点では未使用。

制限：

• 本インターフェースはデバイス側 CMM メモリプールから連続した物理メモリを割り当てます。
• 本インターフェースで割り当てた CACHED メモリは、ユーザーが一貫性処理を行う必要があります。
• axclrtFree を呼び出してメモリを解放します。
• 頻繁なメモリの割り当てと解放は性能を低下させるため、事前割り当てや二次管理を行い、頻繁な割り当て・解放を避けることを推奨します。

axclrtFree

axclError axclrtFree(void *devPtr);

使用説明：

デバイス側で割り当てられたメモリを解放する同期インターフェース。

パラメータ：

• devPtr [IN]：解放するデバイスメモリ。

制限：

• axclrtMalloc または axclrtMallocCached によって割り当てられたデバイス側メモリのみ解放できます。

axclrtMemFlush

axclError axclrtMemFlush(void *devPtr, size_t size);

使用説明：

キャッシュ内のデータを DDR に書き戻し、キャッシュの内容を無効化する同期インターフェース。

パラメータ：

• devPtr [IN]：flush 対象となる DDR メモリの開始アドレスポインタ。
• size [IN]：flush 対象となる DDR メモリのサイズ（バイト単位）。

制限：

特に制限なし

axclrtMemInvalidate

axclError axclrtMemInvalidate(void *devPtr, size_t size);

使用説明：

キャッシュ内のデータを無効化する同期インターフェース。

パラメータ：

• devPtr [IN]：キャッシュデータを無効化する DDR メモリの開始アドレスポインタ。
• size [IN]：DDR メモリのサイズ（バイト単位）。

制限：

• 特に制限なし

axclrtMallocHost

axclError axclrtMallocHost(void **hostPtr, size_t size);

使用説明：

HOST 側で仮想メモリを割り当てる同期インターフェース。

パラメータ：

• hostPtr [OUT]：割り当てられたメモリの先頭アドレス。
• size [IN]：割り当てるメモリサイズ（バイト単位）。

制限：

• axclrtMallocHost インターフェースで割り当てたメモリは、axclrtFreeHost インターフェースで解放する必要があります。
• 頻繁なメモリ確保と解放は性能低下を招くため、事前割り当てや二次管理によって頻繁な割り当てと解放を避けることを推奨します。
• HOST でのメモリ確保は malloc 関数を直接呼び出すことも可能ですが、axclrtMallocHost の使用を推奨します。

axclrtFreeHost

axclError axclrtFreeHost(void *hostPtr);

使用説明：

axclrtMallocHost で割り当てたメモリを解放する同期インターフェース。

パラメータ：

• hostPtr [IN]：解放するメモリの先頭アドレス。

制限：

• axclrtMallocHost により割り当てた HOST メモリのみ解放できます。

axclrtMemset

axclError axclrtMemset(void *devPtr, uint8_t value, size_t count);

使用説明：

axclrtMalloc または axclrtMallocCached で割り当てられたデバイス側メモリのみを初期化できる同期インターフェース。

パラメータ：

• devPtr[IN]：初期化対象のデバイス側メモリ先頭アドレス。
• value [IN]：設定する値。
• count [IN]：初期化するメモリの長さ（バイト単位）。

制限：

• axclrtMalloc または axclrtMallocCached で割り当てられたデバイス側メモリのみ初期化が可能。
• axclrtMallocCached で割り当てられたデバイス側メモリは、初期化後に axclrtMemInvalidate を呼び出して一貫性を保つ必要があります。
• axclrtMallocHost で割り当てられた HOST メモリは memset 関数で初期化してください。

axclrtMemcpy

axclError axclrtMemcpy(void *dstPtr, const void *srcPtr, size_t count, axclrtMemcpyKind kind);

使用説明：

HOST 内、HOST と DEVICE 間、DEVICE 内での同期メモリコピーを実現する同期インターフェース。

パラメータ：

• devPtr [IN]：コピー先メモリアドレスポインタ。
• srcPtr [IN]：コピー元メモリアドレスポインタ。
• count [IN]：コピーするメモリ長（バイト単位）。
• kind [IN]：メモリコピーの種類。
  • [AXCL_MEMCPY_HOST_TO_HOST]：HOST 内メモリコピー。
  • [AXCL_MEMCPY_HOST_TO_DEVICE]：HOST 仮想メモリから DEVICE へのメモリコピー。
  • [AXCL_MEMCPY_DEVICE_TO_HOST]：DEVICE から HOST 仮想メモリへのメモリコピー。
  • [AXCL_MEMCPY_DEVICE_TO_DEVICE]：DEVICE 内のメモリコピー。
  • [AXCL_MEMCPY_HOST_PHY_TO_DEVICE]：HOST 連続物理メモリから DEVICE へのメモリコピー。
  • [AXCL_MEMCPY_DEVICE_TO_HOST_PHY]：DEVICE から HOST 連続物理メモリへのメモリコピー。

制限：

• コピー元とコピー先のメモリは kind の要件を満たす必要があります。

axclrtMemcmp

axclError axclrtMemcmp(const void *devPtr1, const void *devPtr2, size_t count);

使用説明：

DEVICE 内のメモリ比較を実現する同期インターフェース。

パラメータ：

• devPtr1 [IN]：デバイス側アドレス 1 のポインタ。
• devPtr2 [IN]：デバイス側アドレス 2 のポインタ。
• count [IN]：比較長（バイト単位）。

制限：

• デバイス側メモリ同士の比較のみをサポートし、メモリが一致する場合のみ AXCL_SUCC (0) を返します。

engine

axclrtEngineInit

axclError axclrtEngineInit(axclrtEngineVNpuKind npuKind);

使用説明：

Runtime Engine を初期化するための関数。ユーザーは Runtime Engine を使用する前に本関数を呼び出す必要があります。

パラメータ：

• npuKind [IN]：初期化する VNPU の種類を指定。

制限：

ユーザーは Runtime Engine 使用後、axclrtEngineFinalize を呼び出して Runtime Engine のクリーンアップを行う必要があります。

axclrtEngineGetVNpuKind

axclError axclrtEngineGetVNpuKind(axclrtEngineVNpuKind *npuKind);

使用説明：

初期化された Runtime Engine の VNPU 種類を取得します。

パラメータ：

• npuKind [OUT]：返される VNPU 種類。

制限：

本関数を呼び出す前に axclrtEngineInit で Runtime Engine を初期化する必要があります。

axclrtEngineFinalize

axclError axclrtEngineFinalize();

使用説明：

Runtime Engine のクリーンアップを行います。全操作完了後に本関数を呼び出す必要があります。

制限：

本関数を呼び出す前に axclrtEngineInit で Runtime Engine を初期化する必要があります。

axclrtEngineLoadFromFile

axclError axclrtEngineLoadFromFile(const char *modelPath, uint64_t *modelId);

使用説明：

ファイルからモデルデータをロードし、モデル ID を生成します。

パラメータ：

• modelPath [IN]：オフラインモデルファイルの保存パス。
• modelId [OUT]：ロード後に生成されたモデル ID（後続操作の識別に使用）。

制限：

本関数を呼び出す前に axclrtEngineInit で Runtime Engine を初期化する必要があります。

axclrtEngineLoadFromMem

axclError axclrtEngineLoadFromMem(const void *model, uint64_t modelSize, uint64_t *modelId);

使用説明：

メモリからオフラインモデルデータをロードします。モデルの実行に必要なメモリはシステム内部で管理されます。

パラメータ：

• model [IN]：メモリに格納されたモデルデータ。
• modelSize [IN]：モデルデータサイズ。
• modelId [OUT]：ロード後に生成されたモデル ID（後続操作の識別に使用）。

制限：

モデルメモリはデバイスメモリである必要があり、ユーザーが管理・解放を行う必要があります。

axclrtEngineUnload

axclError axclrtEngineUnload(uint64_t modelId);

使用説明：

指定したモデル ID のモデルをアンロードします。

パラメータ：

• modelId [IN]：アンロード対象のモデル ID。

制限：

特に制限なし。

axclrtEngineGetModelCompilerVersion

const char* axclrtEngineGetModelCompilerVersion(uint64_t modelId);

使用説明：

モデルを構築したツールチェーンのバージョンを取得します。

パラメータ：

• modelId [IN]：モデル ID。

制限：

特に制限なし。

axclrtEngineSetAffinity

axclError axclrtEngineSetAffinity(uint64_t modelId, axclrtEngineSet set);

使用説明：

モデルの NPU アフィニティを設定します。

パラメータ：

• modelId [IN]：モデル ID。
• set [OUT]：設定するアフィニティセット。

制限：

ゼロは不可。設定するマスクビットはアフィニティ範囲を超えないこと。

axclrtEngineGetAffinity

axclError axclrtEngineGetAffinity(uint64_t modelId, axclrtEngineSet *set);

使用説明：

モデルの NPU アフィニティを取得します。

パラメータ：

• modelId [IN]：モデル ID。
• set [OUT]：返されるアフィニティセット。

制限：

特に制限なし。

axclrtEngineGetUsage

axclError axclrtEngineGetUsage(const char *modelPath, int64_t *sysSize, int64_t *cmmSize);

使用説明：

モデルファイルに基づき、モデル実行に必要なシステムメモリサイズおよび CMM メモリサイズを取得します。

パラメータ：

• modelPath [IN]：メモリ情報取得に使用するモデルパス。
• sysSize [OUT]：実行に必要なシステムメモリサイズ。
• cmmSize [OUT]：実行に必要な CMM メモリサイズ。

制限：

特に制限なし。

axclrtEngineGetUsageFromMem

axclError axclrtEngineGetUsageFromMem(const void *model, uint64_t modelSize, int64_t *sysSize, int64_t *cmmSize);

使用説明：

メモリ内のモデルデータに基づき、モデル実行に必要なシステムメモリサイズおよび CMM メモリサイズを取得します。

パラメータ：

• model [IN]：ユーザー管理のモデルメモリ。
• modelSize [IN]：モデルデータサイズ。
• sysSize [OUT]：実行に必要なシステムメモリサイズ。
• cmmSize [OUT]：実行に必要な CMM メモリサイズ。

制限：

モデルメモリはデバイスメモリである必要があり、ユーザーが管理・解放を行う必要があります。

axclrtEngineGetUsageFromModelId

axclError axclrtEngineGetUsageFromModelId(uint64_t modelId, int64_t *sysSize, int64_t *cmmSize);

使用説明：

モデル ID に基づき、モデル実行に必要なシステムメモリサイズおよび CMM メモリサイズを取得します。

パラメータ：

• modelId [IN]：モデル ID。
• sysSize [OUT]：実行に必要なシステムメモリサイズ。
• cmmSize [OUT]：実行に必要な CMM メモリサイズ。

制限：

特に制限なし。

axclrtEngineGetModelType

axclError axclrtEngineGetModelType(const char *modelPath, axclrtEngineModelKind *modelType);

使用説明：

この関数はモデルファイルに基づいてモデルタイプを取得します。

パラメータ：

• modelPath [IN]：モデルタイプを取得するためのモデルパス。
• modelType [OUT]：返されるモデルタイプ。

制限：

特に制限なし。

axclrtEngineGetModelTypeFromMem

axclError axclrtEngineGetModelTypeFromMem(const void *model, uint64_t modelSize, axclrtEngineModelKind *modelType);

使用説明：

この関数はメモリ内のモデルデータに基づいてモデルタイプを取得します。

パラメータ：

• model [IN]：ユーザーが管理するモデルメモリ。
• modelSize [IN]：モデルデータサイズ。
• modelType [OUT]：返されるモデルタイプ。

制限：

モデルメモリはデバイスメモリである必要があり、ユーザー自身が管理および解放を行う必要があります。

axclrtEngineGetModelTypeFromModelId

axclError axclrtEngineGetModelTypeFromModelId(uint64_t modelId, axclrtEngineModelKind *modelType);

使用説明：

この関数はモデル ID に基づいてモデルタイプを取得します。

パラメータ：

• modelId [IN]：モデル ID。
• modelType [OUT]：返されるモデルタイプ。

制限：

特に制限なし。

axclrtEngineGetIOInfo

axclError axclrtEngineGetIOInfo(uint64_t modelId, axclrtEngineIOInfo *ioInfo);

使用説明：

この関数はモデル ID に基づいてモデルの IO 情報を取得します。

パラメータ：

• modelId [IN]：モデル ID。
• ioInfo [OUT]：返される axclrtEngineIOInfo ポインタ。

制限：

モデル ID を破棄する前に、axclrtEngineDestroyIOInfo を呼び出して axclrtEngineIOInfo を解放する必要があります。

axclrtEngineDestroyIOInfo

axclError axclrtEngineDestroyIOInfo(axclrtEngineIOInfo ioInfo);

使用説明：

この関数は axclrtEngineIOInfo 型のデータを破棄します。

パラメータ：

• ioInfo [IN]：axclrtEngineIOInfo ポインタ。

制限：

特に制限なし。

axclrtEngineGetShapeGroupsCount

axclError axclrtEngineGetShapeGroupsCount(axclrtEngineIOInfo ioInfo, int32_t *count);

使用説明：

この関数は IO シェイプグループの数を取得します。

パラメータ：

• ioInfo [IN]：axclrtEngineIOInfo ポインタ。
• count [OUT]：シェイプグループの数。

制限：

Pulsar2 ツールチェーンでは、モデル変換時に複数のシェイプを指定できます。通常のモデルは 1 つのシェイプしか持たないため、通常の変換モデルに対しては本関数を呼び出す必要はありません。

axclrtEngineGetNumInputs

uint32_t axclrtEngineGetNumInputs(axclrtEngineIOInfo ioInfo);

使用説明：

この関数は axclrtEngineIOInfo データに基づいてモデルの入力数を取得します。

パラメータ：

• ioInfo [IN]：axclrtEngineIOInfo ポインタ。

制限：

特に制限なし。

axclrtEngineGetNumOutputs

uint32_t axclrtEngineGetNumOutputs(axclrtEngineIOInfo ioInfo);

使用説明：

この関数は axclrtEngineIOInfo データに基づいてモデルの出力数を取得します。

パラメータ：

• ioInfo [IN]：axclrtEngineIOInfo ポインタ。

制限：

特に制限なし。

axclrtEngineGetInputSizeByIndex

uint64_t axclrtEngineGetInputSizeByIndex(axclrtEngineIOInfo ioInfo, uint32_t group, uint32_t index);

使用説明：

この関数は axclrtEngineIOInfo データに基づいて、指定された入力のサイズを取得します。

パラメータ：

• ioInfo [IN]：axclrtEngineIOInfo ポインタ。
• group [IN]：入力シェイプグループインデックス。
• index [IN]：取得する入力サイズのインデックス値（0 から開始）。

制限：

特に制限なし。

axclrtEngineGetOutputSizeByIndex

uint64_t axclrtEngineGetOutputSizeByIndex(axclrtEngineIOInfo ioInfo, uint32_t group, uint32_t index);

使用説明：

この関数は axclrtEngineIOInfo データに基づいて、指定された出力のサイズを取得します。

パラメータ：

• ioInfo [IN]：axclrtEngineIOInfo ポインタ。
• group [IN]：出力シェイプグループインデックス。
• index [IN]：取得する出力サイズのインデックス値（0 から開始）。

制限：

特に制限なし。

axclrtEngineGetInputNameByIndex

const char *axclrtEngineGetInputNameByIndex(axclrtEngineIOInfo ioInfo, uint32_t index);

使用説明：

指定された入力の名前を取得します。

パラメータ：

• ioInfo [IN]：axclrtEngineIOInfo ポインタ。
• index [IN]：入力 IO インデックス。

制限：

返される入力テンソル名の有効期間は ioInfo のライフサイクルと同じです。

axclrtEngineGetOutputNameByIndex

const char *axclrtEngineGetOutputNameByIndex(axclrtEngineIOInfo ioInfo, uint32_t index);

使用説明：

指定された出力の名前を取得します。

パラメータ：

• ioInfo [IN]：axclrtEngineIOInfo ポインタ。
• index [IN]：出力 IO インデックス。

制限：

返される出力テンソル名の有効期間は ioInfo のライフサイクルと同じです。

axclrtEngineGetInputIndexByName

int32_t axclrtEngineGetInputIndexByName(axclrtEngineIOInfo ioInfo, const char *name);

使用説明：

入力テンソル名に基づいて入力インデックスを取得します。

パラメータ：

• ioInfo [IN]：モデル記述。
• name [IN]：入力テンソル名。

制限：

特に制限なし。

axclrtEngineGetOutputIndexByName

int32_t axclrtEngineGetOutputIndexByName(axclrtEngineIOInfo ioInfo, const char *name);

使用説明：

出力テンソル名に基づいて出力インデックスを取得します。

パラメータ：

• ioInfo [IN]：モデル記述。
• name [IN]：出力テンソル名。

制限：

特に制限なし。

axclrtEngineGetInputDims

axclError axclrtEngineGetInputDims(axclrtEngineIOInfo ioInfo, uint32_t group, uint32_t index, axclrtEngineIODims *dims);

使用説明：

指定された入力の次元情報を取得します。

パラメータ：

• ioInfo [IN]：axclrtEngineIOInfo ポインタ。
• group [IN]：入力シェイプグループインデックス。
• index [IN]：入力テンソルインデックス。
• dims [OUT]：返される次元情報。

制限：

axclrtEngineIODims のメモリ領域はユーザーが確保し、モデルの axclrtEngineIOInfo 破棄前に解放する必要があります。

axclrtEngineGetOutputDims

axclError axclrtEngineGetOutputDims(axclrtEngineIOInfo ioInfo, uint32_t group, uint32_t index, axclrtEngineIODims *dims);

使用説明：

指定された出力の次元情報を取得します。

パラメータ：

• ioInfo [IN]：axclrtEngineIOInfo ポインタ。
• group [IN]：出力シェイプグループインデックス。
• index [IN]：出力テンソルインデックス。
• dims [OUT]：返される次元情報。

制限：

axclrtEngineIODims のメモリ領域はユーザーが確保し、モデルの axclrtEngineIOInfo 破棄前に解放する必要があります。

axclrtEngineCreateIO

axclError axclrtEngineCreateIO(axclrtEngineIOInfo ioInfo, axclrtEngineIO *io);

使用説明：

axclrtEngineIO 型データを作成します。

パラメータ：

• ioInfo [IN]：axclrtEngineIOInfo ポインタ。
• io [OUT]：作成された axclrtEngineIO ポインタ。

制限：

モデル ID 破棄前に axclrtEngineDestroyIO を呼び出して axclrtEngineIO を解放する必要があります。

axclrtEngineDestroyIO

axclError axclrtEngineDestroyIO(axclrtEngineIO io);

使用説明：

axclrtEngineIO 型データを破棄します。

パラメータ：

• io [IN]：破棄する axclrtEngineIO ポインタ。

制限：

特に制限なし。

axclrtEngineSetInputBufferByIndex

axclError axclrtEngineSetInputBufferByIndex(axclrtEngineIO io, uint32_t index, const void *dataBuffer, uint64_t size);

使用説明：

IO インデックスで入力データバッファを設定します。

パラメータ：

• io [IN]：axclrtEngineIO データバッファのアドレス。
• index [IN]：入力テンソルインデックス。
• dataBuffer [IN]：追加するデータバッファのアドレス。
• size [IN]：データバッファのサイズ。

制限：

データバッファはデバイスメモリである必要があり、ユーザーが管理および解放を行う必要があります。

axclrtEngineSetOutputBufferByIndex

axclError axclrtEngineSetOutputBufferByIndex(axclrtEngineIO io, uint32_t index, const void *dataBuffer, uint64_t size);

使用説明：

IO インデックスで出力データバッファを設定します。

パラメータ：

• io [IN]：axclrtEngineIO データバッファのアドレス。
• index [IN]：出力テンソルインデックス。
• dataBuffer [IN]：追加するデータバッファのアドレス。
• size [IN]：データバッファのサイズ。

制限：

データバッファはデバイスメモリである必要があり、ユーザーが管理および解放を行う必要があります。

axclrtEngineSetInputBufferByName

axclError axclrtEngineSetInputBufferByName(axclrtEngineIO io, const char *name, const void *dataBuffer, uint64_t size);

使用説明：

IO 名で入力データバッファを設定します。

パラメータ：

• io [IN]：axclrtEngineIO データバッファのアドレス。
• name [IN]：入力テンソル名。
• dataBuffer [IN]：追加するデータバッファのアドレス。
• size [IN]：データバッファのサイズ。

制限：

データバッファはデバイスメモリである必要があり、ユーザーが管理および解放を行う必要があります。

axclrtEngineSetOutputBufferByName

axclError axclrtEngineSetOutputBufferByName(axclrtEngineIO io, const char *name, const void *dataBuffer, uint64_t size);

使用説明：

IO 名で出力データバッファを設定します。

パラメータ：

• io [IN]：axclrtEngineIO データバッファのアドレス。
• name [IN]：出力テンソル名。
• dataBuffer [IN]：追加するデータバッファのアドレス。
• size [IN]：データバッファのサイズ。

制限：

データバッファはデバイスメモリである必要があり、ユーザーが管理および解放を行う必要があります。

axclrtEngineGetInputBufferByIndex

axclError axclrtEngineGetInputBufferByIndex(axclrtEngineIO io, uint32_t index, void **dataBuffer, uint64_t *size);

使用説明：

IO インデックスで入力データバッファを取得します。

パラメータ：

• io [IN]：axclrtEngineIO データバッファのアドレス。
• index [IN]：入力テンソルインデックス。
• dataBuffer [OUT]：データバッファのアドレス。
• size [IN]：データバッファのサイズ。

制限：

データバッファはデバイスメモリである必要があり、ユーザーが管理および解放を行う必要があります。

axclrtEngineGetOutputBufferByIndex

axclError axclrtEngineGetOutputBufferByIndex(axclrtEngineIO io, uint32_t index, void **dataBuffer, uint64_t *size);

使用説明：

IO インデックスで出力データバッファを取得します。

パラメータ：

• io [IN]：axclrtEngineIO データバッファのアドレス。
• index [IN]：出力テンソルインデックス。
• dataBuffer [OUT]：データバッファのアドレス。
• size [IN]：データバッファのサイズ。

制限：

データバッファはデバイスメモリである必要があり、ユーザーが管理および解放を行う必要があります。

axclrtEngineGetInputBufferByName

axclError axclrtEngineGetInputBufferByName(axclrtEngineIO io, const char *name, void **dataBuffer, uint64_t *size);

使用説明：

IO 名で入力データバッファを取得します。

パラメータ：

• io [IN]：axclrtEngineIO データバッファのアドレス。
• name [IN]：入力テンソル名。
• dataBuffer [OUT]：データバッファのアドレス。

制限：

データバッファはデバイスメモリである必要があり、ユーザーが管理および解放を行う必要があります。

axclrtEngineGetOutputBufferByName

axclError axclrtEngineGetOutputBufferByName(axclrtEngineIO io, const char *name, void **dataBuffer, uint64_t *size);

使用説明：

IO 名で出力データバッファを取得します。

パラメータ：

• io [IN]：axclrtEngineIO データバッファのアドレス。
• name [IN]：出力テンソル名。
• dataBuffer [OUT]：データバッファのアドレス。

制限：

データバッファはデバイスメモリである必要があり、ユーザーが管理および解放を行う必要があります。

axclrtEngineSetDynamicBatchSize

axclError axclrtEngineSetDynamicBatchSize(axclrtEngineIO io, uint32_t batchSize);

使用説明：

動的バッチ処理シナリオで 1 回に処理する画像枚数を設定します。

パラメータ：

• io [IN]：モデル推論の IO。
• batchSize [IN]：1 回の処理で扱う画像枚数。

制限：

特に制限なし。

axclrtEngineCreateContext

axclError axclrtEngineCreateContext(uint64_t modelId, uint64_t *contextId);

使用説明：

この関数はモデル ID に対してモデル実行環境コンテキストを作成します。

パラメータ：

• modelId [IN]：モデル ID。
• contextId [OUT]：作成されたコンテキスト ID。

制限：

1 つのモデル ID から複数の実行コンテキストを作成できますが、各コンテキストはそれぞれ独立した設定とメモリ空間で動作します。

axclrtEngineExecute

axclError axclrtEngineExecute(uint64_t modelId, uint64_t contextId, uint32_t group, axclrtEngineIO io);

使用説明：

この関数はモデルの同期推論を実行し、推論結果が返るまで待機します。

パラメータ：

• modelId [IN]：モデル ID。
• contextId [IN]：モデル推論コンテキスト。
• group [IN]：モデルシェイプグループインデックス。
• io [IN]：モデル推論用の IO。

制限：

特に制限なし。

axclrtEngineExecuteAsync

axclError axclrtEngineExecuteAsync(uint64_t modelId, uint64_t contextId, uint32_t group, axclrtEngineIO io, axclrtStream stream);

使用説明：

この関数はモデルの非同期推論を実行し、推論結果が返るまでに処理を続行します。

パラメータ：

• modelId [IN]：モデル ID。
• contextId [IN]：モデル推論コンテキスト。
• group [IN]：モデルシェイプグループインデックス。
• io [IN]：モデル推論用の IO。
• stream [IN]：ストリーム。

制限：

特に制限なし。

native

• AXCL NATIVE モジュールは SYS、VDEC、VENC、IVPS、DMADIM、ENGINE、IVE モジュールをサポートします。

• AXCL NATIVE API と AX SDK API はパラメータが完全に一致しますが、関数名の接頭辞が従来の AX から AXCL に変更されている点が異なります。例：

  AX_S32 AXCL_SYS_Init(AX_VOID);
  AX_S32 AXCL_SYS_Deinit(AX_VOID);
  
  /* CMM API */
  AX_S32 AXCL_SYS_MemAlloc(AX_U64 *phyaddr, AX_VOID **pviraddr, AX_U32 size, AX_U32 align, const AX_S8 *token);
  AX_S32 AXCL_SYS_MemAllocCached(AX_U64 *phyaddr, AX_VOID **pviraddr, AX_U32 size, AX_U32 align, const AX_S8 *token);
  AX_S32 AXCL_SYS_MemFree(AX_U64 phyaddr, AX_VOID *pviraddr);
  
  ...
  
  AX_S32 AXCL_VDEC_Init(const AX_VDEC_MOD_ATTR_T *pstModAttr);
  AX_S32 AXCL_VDEC_Deinit(AX_VOID);
  
  AX_S32 AXCL_VDEC_ExtractStreamHeaderInfo(const AX_VDEC_STREAM_T *pstStreamBuf, AX_PAYLOAD_TYPE_E enVideoType,
                                           AX_VDEC_BITSTREAM_INFO_T *pstBitStreamInfo);
  
  AX_S32 AXCL_VDEC_CreateGrp(AX_VDEC_GRP VdGrp, const AX_VDEC_GRP_ATTR_T *pstGrpAttr);
  AX_S32 AXCL_VDEC_CreateGrpEx(AX_VDEC_GRP *VdGrp, const AX_VDEC_GRP_ATTR_T *pstGrpAttr);
  AX_S32 AXCL_VDEC_DestroyGrp(AX_VDEC_GRP VdGrp);
  
  ...

  AX_S32 AXCL_SYS_Init(AX_VOID); AX_S32 AXCL_SYS_Deinit(AX_VOID); /* CMM API */ AX_S32 AXCL_SYS_MemAlloc(AX_U64 *phyaddr, AX_VOID **pviraddr, AX_U32 size, AX_U32 align, const AX_S8 *token); AX_S32 AXCL_SYS_MemAllocCached(AX_U64 *phyaddr, AX_VOID **pviraddr, AX_U32 size, AX_U32 align, const AX_S8 *token); AX_S32 AXCL_SYS_MemFree(AX_U64 phyaddr, AX_VOID *pviraddr); ... AX_S32 AXCL_VDEC_Init(const AX_VDEC_MOD_ATTR_T *pstModAttr); AX_S32 AXCL_VDEC_Deinit(AX_VOID); AX_S32 AXCL_VDEC_ExtractStreamHeaderInfo(const AX_VDEC_STREAM_T *pstStreamBuf, AX_PAYLOAD_TYPE_E enVideoType, AX_VDEC_BITSTREAM_INFO_T *pstBitStreamInfo); AX_S32 AXCL_VDEC_CreateGrp(AX_VDEC_GRP VdGrp, const AX_VDEC_GRP_ATTR_T *pstGrpAttr); AX_S32 AXCL_VDEC_CreateGrpEx(AX_VDEC_GRP *VdGrp, const AX_VDEC_GRP_ATTR_T *pstGrpAttr); AX_S32 AXCL_VDEC_DestroyGrp(AX_VDEC_GRP VdGrp); ...

• 詳細は AX SDK API のドキュメント（例：「AX SYS API ドキュメント.docx」、「AX VDEC API ドキュメント.docx」など）をご参照ください。

• 動的ライブラリ (.so) の名称は従来の libax_xxx.so から libaxcl_xxx.so に変更されています。対応表は以下のとおりです。

• 一部の AX SDK API は AXCL NATIVE ではサポートされていません。具体的な一覧は以下のとおりです。

PPL

architecture

libaxcl_ppl.so は、典型的なパイプライン（PPL）を実装した高集積モジュールです。アーキテクチャ図は以下の通りです。

| ----------------------------- |
| application                   |
| ----------------------------- |
| libaxcl_ppl.so                |
| ----------------------------- |
| libaxcl_lite.so               |
| ----------------------------- |
| axcl sdk                      |
| ----------------------------- |
| pcie driver                   |
| ----------------------------- |

transcode

axcl_transcode_sample のソースコードは、パス axcl/sample/ppl/transode にあります。

API

axcl_ppl_init

axcl ランタイムシステムおよび PPL の初期化。

prototype

axclError axcl_ppl_init(const axcl_ppl_init_param* param);

parameter

typedef enum {
    AXCL_LITE_NONE = 0,
    AXCL_LITE_VDEC = (1 << 0),
    AXCL_LITE_VENC = (1 << 1),
    AXCL_LITE_IVPS = (1 << 2),
    AXCL_LITE_JDEC = (1 << 3),
    AXCL_LITE_JENC = (1 << 4),
    AXCL_LITE_DEFAULT = (AXCL_LITE_VDEC | AXCL_LITE_VENC | AXCL_LITE_IVPS),
    AXCL_LITE_MODULE_BUTT
} AXCLITE_MODULE_E;

typedef struct {
    const char *json; /* axcl.json path */
    AX_S32 device;
    AX_U32 modules;
    AX_U32 max_vdec_grp;
    AX_U32 max_venc_thd;
} axcl_ppl_init_param;

return

成功時は 0 (AXCL_SUCC)、それ以外の場合は失敗。

axcl_ppl_deinit

axcl ランタイムシステムおよび PPL の終了処理。

prototype

axclError axcl_ppl_deinit();

return

成功時は 0 (AXCL_SUCC)、それ以外の場合は失敗。

axcl_ppl_create

PPL を作成します。

prototype

axclError axcl_ppl_create(axcl_ppl* ppl, const axcl_ppl_param* param);

parameter

typedef enum {
    AXCL_PPL_TRANSCODE = 0, /* VDEC -> IVPS ->VENC */
    AXCL_PPL_BUTT
} axcl_ppl_type;

typedef struct {
    axcl_ppl_type ppl;
    void *param;
} axcl_ppl_param;

AXCL_PPL_TRANSCODE のパラメータは以下の通りです：

typedef AX_VENC_STREAM_T axcl_ppl_encoded_stream;
typedef void (*axcl_ppl_encoded_stream_callback_func)(axcl_ppl ppl, const axcl_ppl_encoded_stream *stream, AX_U64 userdata);

typedef struct {
    axcl_ppl_transcode_vdec_attr vdec;
    axcl_ppl_transcode_venc_attr venc;
    axcl_ppl_encoded_stream_callback_func cb;
    AX_U64 userdata;
} axcl_ppl_transcode_param;

typedef struct {
    AX_PAYLOAD_TYPE_E payload;
    AX_U32 width;
    AX_U32 height;
    AX_VDEC_OUTPUT_ORDER_E output_order;
    AX_VDEC_DISPLAY_MODE_E display_mode;
} axcl_ppl_transcode_vdec_attr;

注意：

• output_order:
  • デコード順が表示順と同じ（IP ストリームなど）の場合、メモリ節約のために AX_VDEC_OUTPUT_ORDER_DEC を推奨します。
  • デコード順が表示順と異なる（IPB ストリームなど）の場合、AX_VDEC_OUTPUT_ORDER_DISP を設定します。
• display_mode
  • AX_VDEC_DISPLAY_MODE_PREVIEW: プレビュー モード。RTSP ストリームなどで一般的にフレームのドロップが許可されます。
  • AX_VDEC_DISPLAY_MODE_PLAYBACK: 再生モード。ローカルストリームファイルなどでフレームのドロップは禁止されます。

typedef struct {
    AX_PAYLOAD_TYPE_E payload;
    AX_U32 width;
    AX_U32 height;
    AX_VENC_PROFILE_E profile;
    AX_VENC_LEVEL_E level;
    AX_VENC_TIER_E tile;
    AX_VENC_RC_ATTR_T rc;
    AX_VENC_GOP_ATTR_T gop;
} axcl_ppl_transcode_venc_attr;

return

成功時は 0 (AXCL_SUCC)、それ以外の場合は失敗。

axcl_ppl_destroy

PPL を破棄します。

prototype

axclError axcl_ppl_destroy(axcl_ppl ppl)

parameter

return

成功時は 0 (AXCL_SUCC)、それ以外の場合は失敗。

axcl_ppl_start

PPL を開始します。

prototype

axclError axcl_ppl_start(axcl_ppl ppl);

parameter

return

成功時は 0 (AXCL_SUCC)、それ以外の場合は失敗。

axcl_ppl_stop

PPL を停止します。

prototype

axclError axcl_ppl_stop(axcl_ppl ppl);

parameter

return

成功時は 0 (AXCL_SUCC)、それ以外の場合は失敗。

axcl_ppl_send_stream

NALU フレームを PPL に送信します。

prototype

axclError axcl_ppl_send_stream(axcl_ppl ppl, const axcl_ppl_input_stream* stream, AX_S32 timeout);

parameter

typedef struct {
    AX_U8 *nalu;
    AX_U32 nalu_len;
    AX_U64 pts;
    AX_U64 userdata;
} axcl_ppl_input_stream;

return

成功時は 0 (AXCL_SUCC)、それ以外の場合は失敗。

axcl_ppl_get_attr

PPL の属性を取得します。

prototype

axclError axcl_ppl_get_attr(axcl_ppl ppl, const char* name, void* attr);

parameter

/**
 *            name                                     attr type        default
 *  axcl.ppl.id                             [R  ]       int32_t                            increment +1 for each axcl_ppl_create
 *
 *  axcl.ppl.transcode.vdec.grp             [R  ]       int32_t                            allocated by ax_vdec.ko
 *  axcl.ppl.transcode.ivps.grp             [R  ]       int32_t                            allocated by ax_ivps.ko
 *  axcl.ppl.transcode.venc.chn             [R  ]       int32_t                            allocated by ax_venc.ko
 *
 *  the following attributes take effect BEFORE the axcl_ppl_create function is called:
 *  axcl.ppl.transcode.vdec.blk.cnt         [R/W]       uint32_t          8                depend on stream DPB size and decode mode
 *  axcl.ppl.transcode.vdec.out.depth       [R/W]       uint32_t          4                out fifo depth
 *  axcl.ppl.transcode.ivps.in.depth        [R/W]       uint32_t          4                in fifo depth
 *  axcl.ppl.transcode.ivps.out.depth       [R  ]       uint32_t          0                out fifo depth
 *  axcl.ppl.transcode.ivps.blk.cnt         [R/W]       uint32_t          4
 *  axcl.ppl.transcode.ivps.engine          [R/W]       uint32_t   AX_IVPS_ENGINE_VPP      AX_IVPS_ENGINE_VPP|AX_IVPS_ENGINE_VGP|AX_IVPS_ENGINE_TDP
 *  axcl.ppl.transcode.venc.in.depth        [R/W]       uint32_t          4                in fifo depth
 *  axcl.ppl.transcode.venc.out.depth       [R/W]       uint32_t          4                out fifo depth
 */

return

成功時は 0 (AXCL_SUCC)、それ以外の場合は失敗。

axcl_ppl_set_attr

PPL の属性を設定します。

prototype

axclError axcl_ppl_set_attr(axcl_ppl ppl, const char* name, const void* attr);

parameter

return

成功時は 0 (AXCL_SUCC)、それ以外の場合は失敗。

エラーコード

定義

typedef int32_t axclError;

typedef enum {
    AXCL_SUCC                   = 0x00,
    AXCL_FAIL                   = 0x01,
    AXCL_ERR_UNKNOWN            = AXCL_FAIL,
    AXCL_ERR_NULL_POINTER       = 0x02,
    AXCL_ERR_ILLEGAL_PARAM      = 0x03,
    AXCL_ERR_UNSUPPORT          = 0x04,
    AXCL_ERR_TIMEOUT            = 0x05,
    AXCL_ERR_BUSY               = 0x06,
    AXCL_ERR_NO_MEMORY          = 0x07,
    AXCL_ERR_ENCODE             = 0x08,
    AXCL_ERR_DECODE             = 0x09,
    AXCL_ERR_UNEXPECT_RESPONSE  = 0x0A,
    AXCL_ERR_OPEN               = 0x0B,
    AXCL_ERR_EXECUTE_FAIL       = 0x0C,

    AXCL_ERR_BUTT               = 0x7F
} AXCL_ERROR_E;

#define AX_ID_AXCL           (0x30)

/* module */
#define AXCL_RUNTIME         (0x00)
#define AXCL_NATIVE          (0x01)
#define AXCL_LITE            (0x02)

/* runtime sub module */
#define AXCL_RUNTIME_DEVICE  (0x01)
#define AXCL_RUNTIME_CONTEXT (0x02)
#define AXCL_RUNTIME_STREAM  (0x03)
#define AXCL_RUNTIME_TASK    (0x04)
#define AXCL_RUNTIME_MEMORY  (0x05)
#define AXCL_RUNTIME_CONFIG  (0x06)
#define AXCL_RUNTIME_ENGINE  (0x07)
#define AXCL_RUNTIME_SYSTEM  (0x08)

/**
 * |---------------------------------------------------------|
 * | |   MODULE    |  AX_ID_AXCL | SUB_MODULE  |    ERR_ID   |
 * |1|--- 7bits ---|--- 8bits ---|--- 8bits ---|--- 8bits ---|
 **/
#define AXCL_DEF_ERR(module, sub, errid) \
    ((axclError)((0x80000000L) | (((module) & 0x7F) << 24) | ((AX_ID_AXCL) << 16 ) | ((sub) << 8) | (errid)))

#define AXCL_DEF_RUNTIME_ERR(sub, errid)    AXCL_DEF_ERR(AXCL_RUNTIME, (sub), (errid))
#define AXCL_DEF_NATIVE_ERR(sub,  errid)    AXCL_DEF_ERR(AXCL_NATIVE,  (sub), (errid))
#define AXCL_DEF_LITE_ERR(sub,    errid)    AXCL_DEF_ERR(AXCL_LITE,    (sub), (errid))

:::{Note}

エラーコードは AXCL ランタイムライブラリ と AX NATIVE SDK の 2 種類に分かれ、axclError の第 3 バイトで区別されます。
第 3 バイトが AX_ID_AXCL (0x30) の場合は AXCL ランタイムライブラリ のエラーコードを示し、そうでない場合は Device の AX NATIVE SDK モジュールのエラーコードを透過したものです。

• AXCL ランタイムライブラリエラーコード：axcl_rt_xxx.h ヘッダファイルを参照してください。
• Device の NATIVE SDK エラーコード は HOST 側へ透過されます。『AX ソフトウェアエラーコードドキュメント』を参照してください。 :::

解析

AXCLエラーコード解析 にアクセスして、エラーコードをオンラインで解析できます。