C Specification

To query a suggested local work size for a kernel object, call the function

// Provided by cl_khr_suggested_local_work_size
cl_int clGetKernelSuggestedLocalWorkSizeKHR(
    cl_command_queue command_queue,
    cl_kernel kernel,
    cl_uint work_dim,
    const size_t* global_work_offset,
    const size_t* global_work_size,
    size_t* suggested_local_work_size);
clGetKernelSuggestedLocalWorkSizeKHR is provided by the cl_khr_suggested_local_work_size extension.

Parameters

  • command_queue specifies the command-queue and device for the query.

  • kernel specifies the kernel object and kernel arguments for the query. The OpenCL context associated with kernel and command_queue must the same.

  • work_dim specifies the number of work dimensions in the input global work offset and global work size, and the output suggested local work size.

  • global_work_offset can be used to specify an array of at least work_dim global ID offset values for the query. This is optional and may be NULL to indicate there is no global ID offset.

  • global_work_size is an array of at least work_dim values describing the global work size for the query.

  • suggested_local_work_size is an output array of at least work_dim values that will contain the result of the query.

Description

The returned suggested local work size is expected to match the local work size that would be chosen if the specified kernel object, with the same kernel arguments, were enqueued into the specified command-queue with the specified global work size, specified global work offset, and with a NULL local work size.

clGetKernelSuggestedLocalWorkSizeKHR returns CL_SUCCESS if the query executed successfully. Otherwise, it returns one of the following errors:

  • CL_INVALID_COMMAND_QUEUE if command_queue is not a valid host command-queue.

  • CL_INVALID_KERNEL if kernel is not a valid kernel object.

  • CL_INVALID_CONTEXT if the context associated with kernel is not the same as the context associated with command_queue.

  • CL_INVALID_PROGRAM_EXECUTABLE if there is no successfully built program executable available for kernel for the device associated with command_queue.

  • CL_INVALID_KERNEL_ARGS if all argument values for kernel have not been set.

  • CL_MISALIGNED_SUB_BUFFER_OFFSET if a sub-buffer object is set as an argument to kernel and the offset specified when the sub-buffer object was created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN for the device associated with command_queue.

  • CL_INVALID_IMAGE_SIZE if an image object is set as an argument to kernel and the image dimensions are not supported by device associated with command_queue.

  • CL_IMAGE_FORMAT_NOT_SUPPORTED if an image object is set as an argument to kernel and the image format is not supported by the device associated with command_queue.

  • CL_INVALID_OPERATION if an SVM pointer is set as an argument to kernel and the device associated with command_queue does not support SVM or the required SVM capabilities for the SVM pointer.

  • CL_INVALID_WORK_DIMENSION if work_dim is not a valid value (i.e. a value between 1 and CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS).

  • CL_INVALID_GLOBAL_WORK_SIZE if global_work_size is NULL or if any of the values specified in global_work_size are 0.

  • CL_INVALID_GLOBAL_WORK_SIZE if any of the values specified in global_work_size exceed the maximum value representable by size_t on the device associated with command_queue.

  • CL_INVALID_GLOBAL_OFFSET if the value specified in global_work_size plus the corresponding value in global_work_offset for dimension exceeds the maximum value representable by size_t on the device associated with command_queue.

  • CL_INVALID_VALUE if suggested_local_work_size is NULL.

  • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

  • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

These error conditions are consistent with error conditions for clEnqueueNDRangeKernel.

See Also

cl_command_queue, cl_kernel, cl_khr_suggested_local_work_size, cl_uint

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0