clCreateProgramWithBinary/1.0
cl_program clCreateProgramWithBinary (cl_context context, cl_uint num_devices, const cl_device_id *device_list, const size_t lengths, const unsgined char **binaries, cl_int *binary_status, cl_int *errcode_ret)
指定したOpenCLコンテキストについてプログラムオブジェクトを作成し、binaries で指定したバイナリビット列をそのプログラムオブジェクト内に読み込みます。
パラメータ
- context
- 有効なOpenCLコンテキストを指定します。
- num_devices
- device_list で指定したデバイスの数を指定します。
- device_list
- contxt 内から選んだ対象デバイスの一覧へのポインタを指定します。device_list に NULL を指定することはできません。バイナリは、この一覧内のデバイス用に読み込まれます。
- device_list で指定したデバイスがプログラムオブジェクト関連付けられます。device_list で指定するデバイスは、context と関連付けられたものでなければなりません。
- lengths
- device_list で指定したデバイスのために読み込まれるプログラムバイナリのバイトサイズの配列を指定します。
- binaries
- device_list で指定したデバイスのために読み込まれるプログラムバイナリへのポインタの配列を指定します。各デバイス device_list[i] に対応するプログラムバイナリへのポインタおよびバイナリ長さは、device_list[i] および lengths[i] です。lengths[i] に0を指定することはできずまた、binaries[i] に NULL ポインタを指定することはできません。
- binaries で指定するプログラムバイナリには、context と関連付けられたデバイス上で実行される実行可能プログラムを表すビット列が含まれます。プログラムバイナリには、以下のいずれかもしくはどちらも含めることができます:
- デバイス固有の実行可能プログラムもしくは/および
- デバイス固有の実行可能プログラムに変換される実装固有の中間表現 (IR)
- binary_status
- device_list 内の各デバイスに対するプログラムバイナリの読み込みが成功した否かを返します。エントリ数 num_devices の配列で、device_list[i] で指定したデバイスへのバイナリの読み込みが成功すると binary_status[i] に CL_SUCCESS が返されます。lengths[i] が0もしくは binaries[i] が NULL のとき、CL_INVALID_VALUE が返されます。プログラムバイナリがデバイスに対して有効なものでないとき、CL_INVALID_BINARY が返されます。binary_status に NULL を指定すると無視されます。
- errcode_ret
- 適切なエラーコードを返します。errcode_ret が NULL のとき、エラーコードは返されません。
解説
OpenCLはアプリケーションに対し、プログラムソースもしくはバイナリのいずれかからプログラムオブジェクトを作成し、適切な実行可能プログラムをビルドすることを認めています。アプリケーションは、事前ビルド済みオフラインバイナリを使用するか、プログラムソースを読み込んでコンパイル・リンクした実行可能プログラムを使用するかを選べます。これにより、システム内のあるデバイスに対してプログラムを最初に実行させるときは読み込みとビルドをオンラインで行い、次回以降の実行ではアプリケーションが保存していたバイナリを使用することで、アプリケーションが初期化に使用する時間を削減できます。
エラー
プログラムオブジェクトの作成が成功すると、clCreateProgramWithBinary は有効な非ゼロのプログラムオブジェクトを返し errcode_ret に CL_SUCCESS を設定します。そうでない場合は NULL を返して errcode_ret に以下のエラーのうちのひとつを設定します。
- CL_INVALID_CONTEXT - context が有効なOpenCLコンテキストでないとき。
- CL_INVALID_VALUE - device_list が NULL のとき。あるいは、num_devices が0であるとき。
- CL_INVALID_DEVICE - device_list で指定されているOpenCLデバイスが context と関連付けられたデバイスでないとき。
- CL_INVALID_VALUE - lengths もしくは binaries が NULL のとき。あるいは、lengths[i] のいずれかが0もしくは binaries[i] のいずれかが NULL のとき。
- CL_INVALID_BINARY - いずれかのデバイスでプログラムバイナリが有効なものでなかったたとき。binary_status にそれぞれのデバイスでの状況が返されます。
- CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
脚注