clGetKernelWorkGroupInfo
提供: Tommy6
cl_int clGetKernelWorkGroupInfo (cl_kernel kernel, cl_device device, cl_kernel_work_group_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret)
カーネルオブジェクトについて、デバイス特有の情報を取得します。
パラメータ
- kernel
- カーネルオブジェクトを指定します。
- device
- kernel に関連付けられたOpenCLデバイスデバイスのリストの中からひとつを指定します。「デバイスのリスト」は、カーネルと関連付けられたOpenCLコンテキスト内のデバイスのリストです。カーネルと関連付けられたデバイスのリストにデバイスが1つしかない場合、このパラメータには NULL を設定できます。
- param_name
- 取得する情報を指定します。下記の表にある定数からひとつ選んで指定できます。
- param_value
- 下記の表にしたがって param_name に指定した情報についての値が返されるメモリ空間へのポインタです。NULL の場合は無視されます。
- param_value_size
- param_value が指すメモリのサイズをバイトで指定します。このサイズは、下記の表で示されている戻り値型のサイズ以上でなければなりません。
- param_value_size_ret
- param_value にコピーされるデータの実際のサイズをバイトで返します。NULL の場合は無視されます。
取得できる情報
param_name で指定できる情報およびこれに対応して param_value に返される情報を以下の表に示しています。
1.1 : OpenCL 1.1で追加
| cl_kernel_work_group_info | 戻り値型 | 解説 |
|---|---|---|
| CL_KERNEL_WORK_GROUP_SIZE | size_t | device で指定したデバイス上でカーネルを実行する際に利用できる最大ワークグループサイズを返します。OpenCL実装は、指定したカーネルが必要とするリソース（レジスタの使用量など）をもとに、ワークグループサイズを決定します。 |
| CL_KERNEL_COMPILE_WORK_GROUP_SIZE | size_t [3] | __attribute__((reqd_work_group_size(X, Y, Z))) 修飾子で指定されているワークグループサイズを返します。この修飾を用いた指定がなされていない場合、(0, 0, 0) が返されます。 |
| CL_KERNEL_LOCAL_MEM_SIZE | cl_ulong | カーネルによって使用されるローカルメモリの量をバイトで返します。これには、カーネルの実行、カーネル内部で __local アドレス修飾子を用いて宣言された変数、__local アドレス修飾子を用いてポインタとして宣言されたカーネルの引数について確保され clSetKernelArg で指定されたサイズのローカルメモリなどで必要となるであろうローカルメモリが含まれます。
__local アドレス修飾子を用いて宣言されたカーネル引数のローカルメモリサイズが指定されていないとき、サイズは0であるものとみなされます。 |
| CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE | size_t | ワークグループサイズの推奨倍数を返します。この値はパフォーマンスについてのヒントとなります。このクエリによって返された値の倍数でないワークグループサイズを clEnqueueNDRangeKernel へのローカルワークサイズ引数として指定しカーネルの実行をキューに挿入しても、指定したサイズがデバイスの最大値を超えていないかぎり、失敗することはありません。 |
| CL_KERNEL_PRIVATE_MEM_SIZE | cl_ulong | それぞれのワークアイテムによってカーネル内で使用されるプライベートメモリの最小量をバイトで返します。これには、組み込み機能やカーネル内部で __private アドレス修飾子を用いて宣言された変数を含めカーネルの実行に必要とされるであろうプライベートメモリが含まれます。 |
エラー
実行が成功した場合、clGetKernelWorkGroupInfo は CL_SUCCESS を返します。そうでない場合は以下のエラーのうちひとつを返します。
- CL_INVALID_DEVICE - device が kernel に関連付けられたリストの中にない、あるいは device に NULL が指定されてるのに kernel に複数の関連付けられているとき。
- CL_INVALID_VALUE - param_name がサポートされている値でない、あるいは、param_value_size で指定されたサイズが上記の表で指定されている戻り値型のサイズより小さくかつ param_value が NULL でないとき。
- CL_INVALID_KERNEL - kernel が有効なカーネルオブジェクトでないとき。
- CL_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。
- CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
- OpenCL 1.1
- param_name に指定できる値として CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE, CL_KERNEL_PRIVATE_MEM_SIZE が追加
脚注
