B.33. カーネルの実行

Prev		Next

B.33.1. clEnqueueNDRangeKernel

Table B.88. 表：clEnqueueNDRangeKernel

関数
cl_int	clEnqueueNDRangeKernel ( cl_command_queue command_queue, cl_kernel kernel, cl_uint work_dim, const size_t global_work_offset, const size_t global_work_size, const size_t local_work_size, cl_uint num_events_in_wait_list, const cl_event event_wait_list, cl_event *event )
OpenCLデバイス上でカーネルを実行するコマンドを挿入。
引数
command_queue	有効なコマンドキューを指定。カーネルは command_queueに関連付けられたOpenCLデバイス上での実行待ちに追加される。
kernel	有効なカーネルオブジェクトを指定。kernel と関連付けられた OpenCLコンテキストと command_queueと関連付けられたOpenCLコンテキストは同じとなる必要がある。
work_dim	グローバルワークアイテム数とワークグループ内のワークアイテム数を決定する際の次元数を指定。work_dim は0より大きく CL_DEVICE_MAX_WORK_ ITEM_DIMENSIONS以下の値となる必要がある。
global_ work_offset	要素数work_dimの配列でワークアイテムのグローバルIDを決定する際のオフセット値を指定。global_work_ offsetがNULLの場合、グローバルIDはオフセット値 `(0,0,...0)` で始まる値となる。
global_ work_size	要素数work_dim の配列で、カーネル関数を実行するwork_dim次元のグローバルワークアイテムの個数を指定。グローバルワークアイテムの総数は、 `global_work_size[0] ` `* global_work_size[1] ` `* ... ` `* global_work_size` `[work_dim - 1]` です。
local_ work_size	要素数work_dimの配列で、カーネル関数を実行する各ワークグループを構成するワークアイテムの数（ワークグループのサイズとも呼ぶ）を指定。ワークグループ内のワークアイテムの総数は、 `local_work_size[0]` `* local_work_size[1]` `* ... * local_work_` `size[work_dim - 1]` となる。ワークグループ内のワークアイテムの総数は、 CL_DEVICE_MAX_WORK_ GROUP_SIZEの値以下となる必要がある。 `local_work_size[0], ` `... local_work_size` `[work_dim - 1]`で指定するワークアイテム数は、対応する`CL_DEVICE_MAX_WORK_` `ITEM_SIZES[0], ...` `CL_DEVICE_MAX_WORK_` `ITEM_SIZES[work_dim - 1]` の値以下となる必要がある。 local_work_sizeは、 global_work_sizeで指定したグローバルワークアイテムをどのようにしてワークグループに分割するのかを決定するために使用できる。 local_work_sizeを指定した場合、 `global_work_size[0], ` `... global_work_size` `[work_dim - 1]`で指定した値は対応する `local_work_size[0], ` `... local_work_size` `[work_dim - 1]`の値で整除できる必要がある。 kernel を実行するワークグループのサイズは、 `__attribute__((reqd_` `work_group_size(X, Y, Z)))` 修飾子を利用してプログラムのソース中で指定できる。この場合、local_work_ size で指定したワークグループサイズは、reqd_work_ group_size 属性修飾子で指定した値と一致している必要がある。 local_work_size には NULLを指定することもでき、この場合はグローバルワークアイテムをどのようにワークグループに分割するか OpenCL実装が決定。これらのワークグループのインスタンスは複数の計算ユニットで並列または、同じ計算ユニットで並行に実行される。各ワークアイテムは、グローバル識別子を利用して一意に識別できる。カーネル内で利用できる「グローバルID」は、 global_work_size と global_work_offset の値から決定できる。ワークグループ内で一意のローカルIDを利用してワークアイテムを識別することもできる。カーネル内で利用できるローカルIDは、 local_work_sizeの値を使って決定でき、ローカル IDはいつも `(0,0, ... , 0)` から始まります。
num_events_ in_wait_list	event_wait_listで指定したイベントオブジェクトの数を指定します。
event_wait_ list	このコマンドが実行される前に完了されているイベントを指定。 event_wait_listが NULLの場合、このコマンドはどのイベントの完了待機もしない。 event_wait_listが NULLの場合、 num_events_in_wait_ listは0となる必要がある。 event_wait_listが NULLではない場合、 event_wait_listが指す各イベントは有効となり、またnum_events_in_ wait_listは0より大きな値となる必要がある。 event_wait_listに指定したイベントは同期点としてふるまう。 event_wait_list内のイベントと関連付けられたOpenCLコンテキストと command_queueと関連付けられたOpenCLコンテキストは同じとなる必要がある。 event_wait_listと関連付けられたメモリ領域は関数が戻った後に、再利用か解放できる。
event	カーネルコマンドを識別するイベントオブジェクトが戻され、コマンド完了の確認やコマンド完了の待機に使える。 eventがNULLの場合、アプリケーションはコマンドの状況確認やコマンド完了待ちができなくなる。 event_wait_list とeventがNULLでない場合、eventは event_wait_list 配列の要素を参照すべきでない。 clEnqueueBarrier WithWaitListを代わりに使うことができる。 event_wait_listと event引数NULLでない場合、event引数はevent_ wait_list内の要素を参照すべきでない。
成功した場合の戻り値
CL_SUCCESS
失敗した場合の戻り値
CL_INVALID_ PROGRAM_ EXECUTABLE		command_queueと関連付けられたデバイス上で実行可能な、正常にビルドされたプログラムが一つもない場合。
CL_INVALID_ COMMAND_QUEUE		command_queueが有効なコマンドキューでない場合。
CL_INVALID_ KERNEL		kernelが有効なカーネルオブジェクトでない場合。
CL_INVALID_ CONTEXT		command_queueと関連付けられたコンテキストとkernelと関連付けられたコンテキストが同じでない場合。 command_queueと関連付けられたコンテキストとevent_wait_list 内のイベントと関連付けられたコンテキストが同じでない場合。
CL_INVALID_ KERNEL_ARGS		カーネル引数が指定されていない場合。
CL_INVALID_ WORK_DIMENSION		work_dimが有効な値（1から3）でない場合。
CL_INVALID_ GLOBAL_WORK_ SIZE		global_work_size がNULLの場合。 `global_work_size[0],` `... global_work_size` `[work_dim - 1]`で指定した値のいずれかが0の場合。カーネルを実行するデバイス上での sizeof(size_t)で与えられる範囲をこえている場合。
CL_INVALID_ GLOBAL_OFFSET		いずれかの次元での (global_work_size で指定した値 + 対応する global_work_offset の値) がカーネルを実行するデバイス上での sizeof(size_t) をこえている場合。
CL_INVALID_ WORK_GROUP_SIZE		local_work_sizeを指定していて、global_ work_sizeで指定したワークアイテム数がlocal_work_ sizeで指定したワークグループサイズの値で整除できない場合。プログラムソース内で `__attribute__((reqd_` `work_group_size(X, Y, Z)))` 修飾子を利用して指定したワークグループサイズと local_work_sizeで指定した値が一致しない場合。
CL_INVALID_ WORK_GROUP_SIZE		local_work_sizeを指定し、 `local_work_size[0] ` `... local_work_size` `[work_dim - 1]`で求められるワークグループ内のワークアイテムの総数が CL_DEVICE_MAX_WORK_ GROUP_SIZEの値をこえている場合。
CL_INVALID_ WORK_GROUP_SIZE		local_work_sizeが NULLで、プログラムソース内で `((reqd_work_group_` `size(X, Y, Z)))` 修飾子を利用してワークグループサイズを宣言している場合。
CL_INVALID_ WORK_ITEM_SIZE		`local_work_size[0],` `... local_work_size` `[work_dim – 1]`で求められるワークアイテムの総数が、対応する`CL_DEVICE_MAX_` `WORK_ITEM_SIZES[0], ....` `CL_DEVICE_MAX_WORK_` `ITEM_SIZES[work_dim – 1]` で指定した値が大きい場合。
CL_MISALIGNED_ SUB_BUFFER_OFFSET		このサブバッファオブジェクトを生成する際に指定した、バッファオブジェクトの引数と、オフセットがcommand_queue と関連付けられたデバイスの CL_DEVICE_MEM_ BASE_ADDR_ALIGNにアラインされていない場合。
CL_INVALID_ IMAGE_SIZE		カーネルの引数にイメージオブジェクトが指定されていて、イメージの次元（幅、高さ、行/カラムの長さ）が command_queueと関連付けられたデバイスでサポートされていない場合。
CL_IMAGE_ FORMAT_NOT_ SUPPORTED		イメージオブジェクトが引数として指定され、そのイメージ型式（image channel orderやデータ型）が queueに関連付けられたデバイスにサポートされていない場合。
CL_OUT_OF_ RESOURCES		カーネルを実行するのに必要なリソースが不足しているためにカーネル実行を挿入できないとき。例：local_work_ sizeを指定すると、レジスタやローカルメモリのようなリソースの不足によりカーネルを実行できない。例：kernelの引数に指定した読み取り専用イメージオブジェクトの数がデバイスの CL_DEVICE_MAX_ READ_IMAGE_ARGS をこえている場合例：kernelの引数に指定した書き込み専用イメージオブジェクトの数がデバイスのCL_ DEVICE_MAX_WRITE_ IMAGE_ARGS をこえている場合例：kernelの引数に指定したサンプラーの数がデバイスの CL_DEVICE_MAX_ SAMPLERSをこえている場合。
CL_MEM_ OBJECT_ ALLOCATION_ FAILURE		カーネルに指定したイメージまたはバッファオブジェクトと関連付けられたデータ格納領域のメモリの確保に失敗した場合。
CL_INVALID_ EVENT_WAIT_LIST		event_wait_listが NULLで、num_events_ in_wait_list > 0の場合。 event_wait_listが NULLでなくnum_ events_in_wait_list が0の場合。 event_wait_list内のイベントオブジェクトが有効なイベントでない場合。
CL_OUT_ OF_RESOURCES		デバイス上のOpenCL 実装が必要とするリソース確保に失敗した場合。
CL_OUT_ OF_HOST_MEMORY		ホスト上のOpenCL 実装が必要とするリソース確保に失敗した場合。

B.33.2. clEnqueueTask

Table B.89. 表：clEnqueueTask

関数
cl_int	clEnqueueTask ( cl_command_queue command_queue, cl_kernel kernel, cl_uint num_events_in_wait_list, const cl_event event_wait_list, cl_event event )
デバイス上でカーネルを実行するコマンドを挿入。一つのワークアイテムを使いカーネルを実行。
引数
command_queue		有効なコマンドキューを指定。カーネルはコマンドキューと関連付けられたデバイス上で実行のためにキューに入れられる。
kernel		有効なカーネルオブジェクト。
num_events_ in_wait_list		event_wait_list で指定したイベントオブジェクトの数を指定します。
event_wait_ list		このコマンドが実行される前に完了されているイベントを指定。 event_wait_listが NULLの場合、このコマンドはどのイベントの完了待機もしない。 event_wait_listが NULLの場合、 num_events_in_ wait_listは0となる必要がある。 event_wait_listが NULLではない場合、 event_wait_listが指す各イベントは有効となり、またnum_events_ in_wait_listは0より大きな値となる必要がある。 event_wait_listに指定したイベントは同期点としてふるまう。 event_wait_list内のイベントと関連付けられた OpenCLコンテキストと command_queueと関連付けられたOpenCLコンテキストは同じとなる必要がある。 event_wait_listと関連付けられたメモリ領域は関数が戻った後に、再利用か解放できる。
event		カーネルコマンドを識別するイベントオブジェクトが戻され、コマンド完了の確認やコマンド完了の待機に使える。 eventがNULLの場合、アプリケーションはコマンドの状況確認やコマンド完了待ちができなくなる。 event_wait_list とeventがNULLでない場合、eventは event_wait_list 配列の要素を参照すべきでない。 clEnqueueBarrier WithWaitListを代わりに使うことができる。event_wait_ listとevent引数 NULLでない場合、 event引数はevent_ wait_list内の要素を参照すべきでない。
成功した場合の戻り値
CL_SUCCESS
失敗した場合の戻り値
CL_INVALID_ PROGRAM_ EXECUTABLE		command_queue に関連付けられたデバイスのためにビルドに成功した実行可能プログラムがない場合。
CL_INVALID_ COMMAND_QUEUE		command_queueが有効なコマンドキューでない場合。
CL_INVALID_ KERNEL		kernelが有効なカーネルオブジェクトでない場合。
CL_INVALID_ CONTEXT		command_queueと kernelに関連付けられたコンテキストが同じでない場合。 command_queueと、 event_wait_list 内のイベントに関連付けられたコンテキストが同じでない場合。
CL_INVALID_ KERNEL_ARGS		カーネル引数の値が指定されてない場合。
CL_INVALID_ WORK_GROUP_SIZE		プログラムソース内で `__attribute__((reqd_` `work_group_size(X,` `Y, Z)))`修飾子を使ってカーネルのワークグループサイズを指定したが、 (1,1,1)でない場合。
CL_MISALIGNED_ SUB_BUFFER_OFFSET		サブバッファオブジェクトが、バッファオブジェクトを引数の値として指定され、サブバッファオブジェクトが生成された際のオフセットがqueue に関連付けられたデバイスに対してCL_DEVICE_ MEM_BASE_ADDR_ ALIGNとアラインされて場合。
CL_INVALID_ IMAGE_SIZE		カーネルの引数にイメージオブジェクトが指定されていて、イメージの次元（幅、高さ、行/ カラムの長さ）が command_queueと関連付けられたデバイスでサポートされていない場合。
CL_IMAGE_ FORMAT_NOT_ SUPPORTED		イメージオブジェクトが引数として指定され、そのイメージ型式（image channel orderやデータ型）が queueに関連付けられたデバイスにサポートされていない場合。
CL_OUT_ OF_RESOURCES		コマンドキュー上のカーネルの実行インスタンスをキューに入れるのに、リソースが不足して失敗した場合。
CL_MEM_ OBJECT_ ALLOCATION_ FAILURE		カーネルに指定したイメージまたはバッファオブジェクトと関連付けられたデータ格納領域のメモリの確保に失敗した場合。
CL_INVALID_ EVENT_WAIT_LIST		event_wait_listが NULLで、 num_events_in_ wait_list > 0の場合。 event_wait_listが NULLでなくnum_ events_in_wait_ listが0の場合。 event_wait_list 内のイベントオブジェクトが有効なイベントでない場合。
CL_OUT_ OF_RESOURCES		デバイス上のOpenCL 実装が必要とするリソース確保に失敗した場合。
CL_OUT_ OF_HOST_MEMORY		ホスト上のOpenCL 実装が必要とするリソース確保に失敗した場合。

B.33.3. clEnqueueNativeKernel

Table B.90. 表：clEnqueueNativeKernel

関数
cl_int	clEnqueueNativeKernel ( cl_command_queue command_queue, void (CL_CALLBACK user_func)(void ) void args, size_t cb_args, cl_uint num_mem_objects, const cl_mem mem_list, const void *args_mem_loc, cl_uint num_events_in_wait_list, const cl_event event_wait_list, cl_event *event )
OpenCLコンパイラを使い、コンパイルされてないネイティブC/C++関数を実行するコマンドを挿入。
引数
command_queue	有効なコマンドキューを指定。ネイティブユーザ関数は、 CL_DEVICE_EXECUTION_ CAPABILITIESを CL_EXEC_NATIVE_ KERNEL機能に設定したデバイスで生成される command-queue上で実行される。
user_func	ホストが呼び出せる関数を指すポインタを指定。
args	user_funcを呼び出す際の引数リストを指すポインタを指定。
cb_args	引数リストのバイトサイズを指定。args とcb_argsバイトサイズが指すデータは複数されて、複製した領域はuser_funcに渡される。複製をする理由は、 argsが保持するメモリオブジェクト（cl_mem の値）が変更したり、グローバルメモリを指すポインタと交換するため。 clEnqueueNative Kernelが戻る場合、 argsが指すメモリ領域はアプリケーションで再利用できる。
num_mem_ objects	argsに渡されるバッファオブジェクトの個数を指定。
mem_list	num_mem_objects > 0の場合、有効なバッファオブジェクトのリストを指定。mem_listで指定されたバッファオブジェクトの値は、 clCreateBufferが戻すメモリオブジェクトのハンドルか、NULLとなる。
args_mem_ loc	argsが指すメモリオブジェクトのハンドルが格納される領域を指すポインタ。ユーザ関数が実行される前に、メモリオブジェクトのハンドルはグローバルメモリへのポインタと交換される。
成功した場合の戻り値
CL_SUCCESS
失敗した場合の戻り値
CL_INVALID_ COMMAND_QUEUE		command_queueが有効なコマンドキューでない場合。
CL_INVALID_ CONTEXT		command_queueと event_wait_list内のイベントと関連付けられるコンテキストが同じでない場合。
CL_INVALID_ VALUE		user_funcが NULLの場合。
CL_INVALID_ VALUE		argsはNULL値で、 cb_args > 0の場合。 argsはNULL値で、 num_mem_objects > 0の場合。
CL_INVALID_ VALUE		argsがNULLでない場合で、cb_args が0の場合。
CL_INVALID_ VALUE		num_mem_objects > 0で、mem_list またはargs_mem_ locがNULLの場合。
CL_INVALID_ VALUE		num_mem_objects = 0で、mem_listまたはargs_mem_loc がNULLでない場合。
CL_INVALID_ OPERATION		コマンドキューが関連付けられたデバイスがネイティブカーネルを実行できない場合。
CL_INVALID_ MEM_OBJECT		mem_listに指定した一つ以上のメモリオブジェクトが有効でない、またはバッファオブジェクトでない場合。
CL_OUT_OF_ RESOURCES		コマンドキュー上のカーネルの実行インスタンスをキューに入れるのに、リソースが不足して失敗した場合。
CL_MEM_ OBJECT_ ALLOCATION_ FAILURE		カーネルに指定したイメージまたはバッファオブジェクトと関連付けられたデータ格納領域のメモリの確保に失敗した場合。
CL_INVALID_ EVENT_WAIT_LIST		event_wait_listが NULLで、 num_events_in_ wait_list > 0の場合。 event_wait_list がNULLでなく num_events_in_ wait_listが0の場合。 event_wait_list内のイベントオブジェクトが有効なイベントでない場合。
CL_OUT_OF_ RESOURCES		デバイス上のOpenCL 実装が必要とするリソース確保に失敗した場合。
CL_OUT_OF_ HOST_MEMORY		ホスト上のOpenCL 実装が必要とするリソース確保に失敗した場合。