From 75e4a0ef4366e0c447dbc92ac67b248f099a1b92 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 3 Sep 2024 23:42:27 -0700 Subject: [PATCH 1/2] fix descriptions of param_value_size for consistency Still need to check and update error conditions for consistency. --- api/opencl_platform_layer.asciidoc | 19 +-- api/opencl_runtime_layer.asciidoc | 207 ++++++++++++++++------------- 2 files changed, 124 insertions(+), 102 deletions(-) diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 2b1ae266..23140ca6 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -107,8 +107,9 @@ include::{generated}/api/version-notes/clGetPlatformInfo.asciidoc[] If _param_value_ is `NULL`, it is ignored. * _param_value_size_ specifies the size in bytes of memory pointed to by _param_value_. - This size in bytes must be {geq} size of return type specified in the - <> table. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -454,8 +455,9 @@ include::{generated}/api/version-notes/clGetDeviceInfo.asciidoc[] If _param_value_ is `NULL`, it is ignored. * _param_value_size_ specifies the size in bytes of memory pointed to by _param_value_. - This size in bytes must be {geq} size of return type specified in the - <> table. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -3502,15 +3504,16 @@ include::{generated}/api/version-notes/clGetContextInfo.asciidoc[] If _param_value_ is `NULL`, it is ignored. * _param_value_size_ specifies the size in bytes of memory pointed to by _param_value_. - This size must be greater than or equal to the size of return type as - described in the <> table. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. The list of supported _param_name_ values and the information returned in _param_value_ by {clGetContextInfo} is described in the -<> table. +<> table. [[context-info-table]] .List of supported param_names by {clGetContextInfo} @@ -3585,7 +3588,7 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_CONTEXT} if _context_ is not a valid context. * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values or if size in bytes specified by _param_value_size_ is < size of return - type as specified in the <> + type as specified in the <> table and _param_value_ is not a `NULL` value. * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required by the OpenCL implementation on the device. diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 7f6904dc..0b6ffde6 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -374,10 +374,10 @@ include::{generated}/api/version-notes/clGetCommandQueueInfo.asciidoc[] * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. @@ -385,9 +385,9 @@ include::{generated}/api/version-notes/clGetCommandQueueInfo.asciidoc[] The list of supported _param_name_ values and the information returned in _param_value_ by {clGetCommandQueueInfo} is described in the -<> table. +<> table. -[[command-queue-param-table]] +[[command-queue-info-table]] .List of supported param_names by {clGetCommandQueueInfo} [width="100%",cols="<33%,<17%,<50%",options="header"] |==== @@ -4192,10 +4192,11 @@ include::{generated}/api/version-notes/clGetImageInfo.asciidoc[] * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -5179,29 +5180,15 @@ include::{generated}/api/version-notes/clGetPipeInfo.asciidoc[] * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. -// refError - -{clGetPipeInfo} returns {CL_SUCCESS} if the function is executed successfully. -Otherwise, it returns one of the following errors: - - * {CL_INVALID_MEM_OBJECT} if _pipe_ is a not a valid pipe object. - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table and _param_value_ is - not `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. - [[pipe-info-table]] .List of supported param_names by {clGetPipeInfo} [width="100%",cols="<33%,<17%,<50%",options="header"] @@ -5236,6 +5223,21 @@ include::{generated}/api/version-notes/CL_PIPE_PROPERTIES.asciidoc[] _param_value_size_ret_ equal to 0, indicating that there are no properties to be returned. |==== + +// refError + +{clGetPipeInfo} returns {CL_SUCCESS} if the function is executed successfully. +Otherwise, it returns one of the following errors: + + * {CL_INVALID_MEM_OBJECT} if _pipe_ is a not a valid pipe object. + * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes + specified by _param_value_size_ is < size of return type as described in + the <> table and _param_value_ is + not `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. -- @@ -5966,14 +5968,15 @@ include::{generated}/api/version-notes/clGetMemObjectInfo.asciidoc[] * _param_name_ specifies the information to query. The list of supported _param_name_ types and the information returned in _param_value_ by {clGetMemObjectInfo} is described in the - <> table. + <> table. * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -6158,7 +6161,7 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_MEM_OBJECT} if _memobj_ is a not a valid memory object. * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes specified by _param_value_size_ is < size of return type as described in - the <> table and _param_value_ is not + the <> table and _param_value_ is not `NULL`. * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required by the OpenCL implementation on the device. @@ -6276,15 +6279,16 @@ include::{generated}/api/version-notes/clGetGLTextureInfo.asciidoc[] * _param_value_ is a pointer to memory where the result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory - pointed to by _param_value_. - This size must be >= size of return type as described in the table - below. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data copied to _param_value_. If _param_value_size_ret_ is `NULL`, it is ignored. -[[gl-texture-info-queries-table]] +[[gl-texture-info-table]] .OpenGL texture info that may be queried with {clGetGLTextureInfo} [cols=",,",options="header",] |==== @@ -8312,10 +8316,11 @@ include::{generated}/api/version-notes/clGetSamplerInfo.asciidoc[] * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -9696,10 +9701,11 @@ include::{generated}/api/version-notes/clGetProgramInfo.asciidoc[] * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -9912,10 +9918,11 @@ include::{generated}/api/version-notes/clGetProgramBuildInfo.asciidoc[] * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -10656,10 +10663,11 @@ include::{generated}/api/version-notes/clGetKernelInfo.asciidoc[] * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -10755,10 +10763,11 @@ include::{generated}/api/version-notes/clGetKernelWorkGroupInfo.asciidoc[] * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -10893,10 +10902,11 @@ Also see {cl_khr_subgroups_EXT}. * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -11040,10 +11050,11 @@ include::{generated}/api/version-notes/clGetKernelArgInfo.asciidoc[] * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be > size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -11849,10 +11860,11 @@ include::{generated}/api/version-notes/clGetEventInfo.asciidoc[] * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -12946,7 +12958,11 @@ include::{generated}/api/protos/clGetSemaphoreHandleForTypeKHR.txt[] * _handle_type_ specifies the type of semaphore handle that should be returned for this exportable _sema_object_, and must be one of the values specified when _sema_object_ was created. - * _handle_size_ specifies the size of memory pointed by _handle_ptr_. + * _handle_size_ specifies the size in bytes of memory pointed to by + _handle_ptr_. + This size must be greater than or equal to the size of the handle type + specified by _handle_type_. + If _handle_ptr_ is `NULL`, it is ignored. * _handle_ptr_ is a pointer to memory where the exported external handle is returned. If _handle_ptr_ is `NULL`, it is ignored. @@ -13486,11 +13502,11 @@ include::{generated}/api/version-notes/clGetSemaphoreInfoKHR.asciidoc[] returned as described in the <> table. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ specifies the size in bytes of memory pointed to + * _param_value_size_ specifies the size in bytes of memory pointed to by _param_value_. This size must be greater than or equal to the size of the return type - described in the <> - table. + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_value_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -13650,10 +13666,11 @@ include::{generated}/api/version-notes/clGetEventProfilingInfo.asciidoc[] * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. - * _param_value_size_ is used to specify the size in bytes of memory pointed to - by _param_value_. - This size must be {geq} size of return type as described in the - <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -16006,14 +16023,14 @@ include::{generated}/api/version-notes/clGetCommandBufferInfoKHR.asciidoc[] * _command_buffer_ specifies the command-buffer being queried. * _param_name_ specifies the information to query. - * _param_value_size_ specifies the size in bytes of memory pointed to by - _param_value_. - This size must be {geq} size of return type as described in the table - below. - If _param_value_ is `NULL`, it is ignored. * _param_value_ is a pointer to a memory location where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_value_. If _param_value_size_ret_ is `NULL`, it is ignored. @@ -16021,6 +16038,7 @@ include::{generated}/api/version-notes/clGetCommandBufferInfoKHR.asciidoc[] The list of supported _param_name_ values and the information returned in _param_value_ by {clGetCommandBufferInfoKHR} is described in the table below. +[[command-buffer-info-table]] .{clGetCommandBufferInfoKHR} values [cols=",,",options="header",] |==== @@ -16123,21 +16141,21 @@ include::{generated}/api/version-notes/clGetMutableCommandInfoKHR.asciidoc[] * _param_name_ specifies the information to query. The list of supported _param_name_ types and the information returned in _param_value_ by {clGetMutableCommandInfoKHR} is described in the - <> - table. - * _param_value_size_ is used to specify the size in bytes of memory - pointed to by _param_value_. - This size must be {geq} size of return type as described in the - <> + <> table. * _param_value_ is a pointer to memory where the appropriate result being queried is returned. If _param_value_ is `NULL`, it is ignored. + * _param_value_size_ is used to specify the size in bytes of memory + pointed to by _param_value_. + This size must be greater than or equal to the size of the return type + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_name_. If _param_value_size_ret_ is `NULL`, it is ignored. -[[mutable-command-object-queries]] +[[mutable-command-info-table]] ._Mutable Command Object Queries_ [width="100%",cols="<33%,<17%,<50%",options="header"] |==== @@ -16260,7 +16278,7 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes specified by _param_value_size_ is < size of return type as described in - the <> + the <> table and _param_value_ is not `NULL`. * {CL_INVALID_MUTABLE_COMMAND_KHR} if _command_ is not a valid mutable command object. @@ -16309,7 +16327,8 @@ include::{generated}/api/protos/clGetGLContextInfoKHR.txt[] * _param_value_size_ specifies the size in bytes of memory pointed to by _param_value_. This size must be greater than or equal to the size of the return type - described in the table below. + specified in the <> table. + If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_value_. If _param_value_size_ret_ is `NULL`, it is ignored. From 417afe03f67e17b669ce49701aed17ecdb68c183 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sun, 8 Sep 2024 17:31:12 -0700 Subject: [PATCH 2/2] improve consistency for error descriptions too --- api/opencl_platform_layer.asciidoc | 53 ++++--- api/opencl_runtime_layer.asciidoc | 226 +++++++++++++++-------------- 2 files changed, 143 insertions(+), 136 deletions(-) diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 23140ca6..7797e188 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -312,10 +312,11 @@ Otherwise, it returns one of the following errors footnote:[{fn-error-precedence}]. * {CL_INVALID_PLATFORM} if _platform_ is not a valid platform. - * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values or - if size in bytes specified by _param_value_size_ is < size of return - type as specified in the <> table, and _param_value_ is not a `NULL` value. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `NULL`. * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host. -- @@ -2161,12 +2162,11 @@ successfully. Otherwise, it returns one of the following errors: * {CL_INVALID_DEVICE} if _device_ is not a valid device. - * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values or - if size in bytes specified by _param_value_size_ is < size of return - type as specified in the <> table - and _param_value_ is not a `NULL` value or if _param_name_ is a value - that is available as an extension and the corresponding extension is not - supported by the device. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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 @@ -2458,17 +2458,15 @@ include::{generated}/api/version-notes/clGetDeviceIDsFromD3D10KHR.asciidoc[] * _platform_ refers to the platform ID returned by {clGetPlatformIDs}. * _d3d_device_source_ specifies the type of _d3d_object_, and must be one - of the values shown in the <> - table. + of the values shown in the + <> table. * _d3d_object_ specifies the object whose corresponding OpenCL devices are being queried. The type of _d3d_object_ must be as specified in the - <> table. + <> table. * _d3d_device_set_ specifies the set of devices to return, and must be one - of the values shown in the <> table. + of the values shown in the + <> table. * _num_entries_ is the number of {cl_device_id_TYPE} entries that can be added to _devices_. If _devices_ is not `NULL` then _num_entries_ must be greater than zero. @@ -2565,17 +2563,15 @@ include::{generated}/api/version-notes/clGetDeviceIDsFromD3D11KHR.asciidoc[] * _platform_ refers to the platform ID returned by {clGetPlatformIDs}. * _d3d_device_source_ specifies the type of _d3d_object_, and must be one - of the values shown in the <> - table. + of the values shown in the + <> table. * _d3d_object_ specifies the object whose corresponding OpenCL devices are being queried. The type of _d3d_object_ must be as specified in the - <> table. + <> table. * _d3d_device_set_ specifies the set of devices to return, and must be one - of the values shown in the <> table. + of the values shown in the + <> table. * _num_entries_ is the number of {cl_device_id_TYPE} entries that can be added to _devices_. If _devices_ is not `NULL` then _num_entries_ must be greater than zero. @@ -3586,10 +3582,11 @@ successfully. Otherwise, it returns one of the following errors: * {CL_INVALID_CONTEXT} if _context_ is not a valid context. - * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values or - if size in bytes specified by _param_value_size_ is < size of return - type as specified in the <> - table and _param_value_ is not a `NULL` value. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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 diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 0b6ffde6..695a7bf7 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -463,10 +463,11 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid command-queue, or if _command_queue_ is not a valid command-queue for _param_name_. - * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values or - if size in bytes specified by _param_value_size_ is < size of return - type as specified in the <> table, and _param_value_ is not a `NULL` value. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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 @@ -4321,11 +4322,12 @@ endif::cl_khr_d3d11_sharing[] successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table and _param_value_ is - not `NULL`. * {CL_INVALID_MEM_OBJECT} if _image_ is a not a valid image object. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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 @@ -5230,10 +5232,11 @@ include::{generated}/api/version-notes/CL_PIPE_PROPERTIES.asciidoc[] Otherwise, it returns one of the following errors: * {CL_INVALID_MEM_OBJECT} if _pipe_ is a not a valid pipe object. - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table and _param_value_ is - not `NULL`. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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 @@ -6159,10 +6162,11 @@ successfully. Otherwise, it returns one of the following errors: * {CL_INVALID_MEM_OBJECT} if _memobj_ is a not a valid memory object. - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table and _param_value_ is not - `NULL`. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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 @@ -6324,10 +6328,12 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_MEM_OBJECT} if _memobj_ is not a valid OpenCL memory object. * {CL_INVALID_GL_OBJECT} if there is no OpenGL texture object associated with _memobj_. - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is less than the size of the return type - as described in the table above and _param_value_ is not `NULL`, or if - _param_value_ and _param_value_size_ret_ are `NULL`. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `NULL`. + * {CL_INVALID_VALUE} if _param_value_ and _param_value_size_ret_ are `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 @@ -8386,11 +8392,12 @@ include::{generated}/api/version-notes/CL_SAMPLER_PROPERTIES.asciidoc[] successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table and - _param_value_ is not `NULL`. * {CL_INVALID_SAMPLER} if _sampler_ is a not a valid sampler object. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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 @@ -9883,11 +9890,12 @@ include::{generated}/api/version-notes/CL_PROGRAM_SCOPE_GLOBAL_DTORS_PRESENT.asc successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table and - _param_value_ is not `NULL`. * {CL_INVALID_PROGRAM} if _program_ is a not a valid program object. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `NULL`. * {CL_INVALID_PROGRAM_EXECUTABLE} if _param_name_ is {CL_PROGRAM_NUM_KERNELS}, {CL_PROGRAM_KERNEL_NAMES}, {CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT}, or @@ -10035,13 +10043,14 @@ include::{generated}/api/version-notes/CL_PROGRAM_BUILD_GLOBAL_VARIABLE_TOTAL_SI successfully. Otherwise, it returns one of the following errors: + * {CL_INVALID_PROGRAM} if _program_ is a not a valid program object. * {CL_INVALID_DEVICE} if _device_ is not in the list of devices associated with _program_. - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table and - _param_value_ is not `NULL`. - * {CL_INVALID_PROGRAM} if _program_ is a not a valid program object. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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 @@ -10730,11 +10739,12 @@ include::{generated}/api/version-notes/CL_KERNEL_ATTRIBUTES.asciidoc[] successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table and _param_value_ - is not `NULL`. * {CL_INVALID_KERNEL} if _kernel_ is a not a valid kernel object. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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 @@ -10782,12 +10792,12 @@ include::{generated}/api/version-notes/clGetKernelWorkGroupInfo.asciidoc[] include::{generated}/api/version-notes/CL_KERNEL_GLOBAL_WORK_SIZE.asciidoc[] | {size_t_TYPE}[3] | This provides a mechanism for the application to query the maximum - global size that can be used to execute a kernel (i.e. + global size that can be used to execute a kernel (i.e. the _global_work_size_ argument to {clEnqueueNDRangeKernel}) on a custom - device given by device or a built-in kernel on an OpenCL device - given by device. + device given by _device_ or a built-in kernel on an OpenCL device + given by _device_. - If device is not a custom device and kernel is not a built-in + If _device_ is not a custom device and _kernel_ is not a built-in kernel, {clGetKernelWorkGroupInfo} returns the error {CL_INVALID_VALUE}. | {CL_KERNEL_WORK_GROUP_SIZE_anchor} @@ -10857,16 +10867,17 @@ include::{generated}/api/version-notes/CL_KERNEL_PRIVATE_MEM_SIZE.asciidoc[] successfully. Otherwise, it returns one of the following errors: + * {CL_INVALID_KERNEL} if _kernel_ is a not a valid kernel object. * {CL_INVALID_DEVICE} if _device_ is not in the list of devices associated with _kernel_ or if _device_ is `NULL` but there is more than one device associated with _kernel_. - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table and _param_value_ is not `NULL`. * {CL_INVALID_VALUE} if _param_name_ is {CL_KERNEL_GLOBAL_WORK_SIZE} and _device_ is not a custom device and _kernel_ is not a built-in kernel. - * {CL_INVALID_KERNEL} if _kernel_ is a not a valid kernel object. * {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 @@ -11011,20 +11022,21 @@ Also see {cl_khr_subgroups_EXT}. successfully. Otherwise, it returns one of the following errors: + * {CL_INVALID_KERNEL} if _kernel_ is a not a valid kernel object. * {CL_INVALID_DEVICE} if _device_ is not in the list of devices associated with _kernel_ or if _device_ is `NULL` but there is more than one device associated with _kernel_. * {CL_INVALID_OPERATION} if _device_ does not support sub-groups. - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table and _param_value_ is not `NULL`. * {CL_INVALID_VALUE} if _param_name_ is {CL_KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGE}, {CL_KERNEL_SUB_GROUP_COUNT_FOR_NDRANGE} or {CL_KERNEL_LOCAL_SIZE_FOR_SUB_GROUP_COUNT} and the size in bytes specified by _input_value_size_ is not valid or if _input_value_ is `NULL`. - * {CL_INVALID_KERNEL} if _kernel_ is a not a valid kernel object. * {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 @@ -11169,14 +11181,19 @@ include::{generated}/api/version-notes/CL_KERNEL_ARG_NAME.asciidoc[] successfully. Otherwise, it returns one of the following errors: + * {CL_INVALID_KERNEL} if _kernel_ is a not a valid kernel object. * {CL_INVALID_ARG_INDEX} if _arg_index_ is not a valid argument index. - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_ size is < size of return type as described in - the <> table and - _param_value_ is not `NULL`. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `NULL`. * {CL_KERNEL_ARG_INFO_NOT_AVAILABLE} if the argument information is not available for kernel. - * {CL_INVALID_KERNEL} if _kernel_ is a not a valid kernel object. + * {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. -- ifdef::cl_khr_suggested_local_work_size[] @@ -12219,13 +12236,14 @@ associated with _event_ will be visible to other enqueued commands. successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table and - _param_value_ is not `NULL`. - * {CL_INVALID_VALUE} if information to query given in _param_name_ cannot be - queried for _event_. * {CL_INVALID_EVENT} if _event_ is a not a valid event object. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `NULL`. + * {CL_INVALID_VALUE} if the information to query given in _param_name_ cannot be + queried for _event_. * {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 @@ -12958,14 +12976,14 @@ include::{generated}/api/protos/clGetSemaphoreHandleForTypeKHR.txt[] * _handle_type_ specifies the type of semaphore handle that should be returned for this exportable _sema_object_, and must be one of the values specified when _sema_object_ was created. + * _handle_ptr_ is a pointer to memory where the exported external handle + is returned. + If _handle_ptr_ is `NULL`, it is ignored. * _handle_size_ specifies the size in bytes of memory pointed to by _handle_ptr_. This size must be greater than or equal to the size of the handle type specified by _handle_type_. If _handle_ptr_ is `NULL`, it is ignored. - * _handle_ptr_ is a pointer to memory where the exported external handle - is returned. - If _handle_ptr_ is `NULL`, it is ignored. * _handle_size_ret_ returns the actual size in bytes for the external handle. If _handle_size_ret_ is `NULL`, it is ignored. @@ -12976,10 +12994,7 @@ include::{generated}/api/protos/clGetSemaphoreHandleForTypeKHR.txt[] handle is queried successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_SEMAPHORE_KHR} - ** if _sema_object_ is not a valid semaphore -// This is redundant with the error below. - ** if _sema_object_ is not exportable + * {CL_INVALID_SEMAPHORE_KHR} if _sema_object_ is not a valid semaphore. * {CL_INVALID_DEVICE} ** if _device_ is not a valid device, or ** if _sema_object_ belongs to a context that is not associated with @@ -12987,14 +13002,8 @@ Otherwise, it returns one of the following errors: ** if _sema_object_ can not be shared with _device_. * {CL_INVALID_VALUE} if the requested external semaphore handle type was not specified when _sema_object_ was created. - * {CL_INVALID_VALUE} if _handle_size_ is less than the size needed to - store the returned handle. -// I don't think this can happen. This would have been checked when the semaphore was created. -// ** if CL_SEMAPHORE_HANDLE_*_KHR is specified as one of the _sema_props_ and -// the property CL_SEMAPHORE_HANDLE_*_KHR does not identify a valid external -// memory handle poperty reported by -// {CL_PLATFORM_SEMAPHORE_IMPORT_HANDLE_TYPES_KHR} or -// {CL_DEVICE_SEMAPHORE_IMPORT_HANDLE_TYPES_KHR} queries. + * {CL_INVALID_VALUE} if the size in bytes specified by _handle_size_ is + less than size of the requested handle and _handle_ptr_ is not `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 @@ -13497,21 +13506,21 @@ include::{generated}/api/version-notes/clGetSemaphoreInfoKHR.asciidoc[] * _sema_object_ specifies the semaphore object being queried. * _param_name_ is a constant that specifies the semaphore information to query, and must be one of the values shown in the - <> table. + <> table. * _param_value_ is a pointer to memory where the result of the query is - returned as described in the <> table. If _param_value_ is `NULL`, it is ignored. * _param_value_size_ specifies the size in bytes of memory pointed to by _param_value_. This size must be greater than or equal to the size of the return type - specified in the <> table. + specified in the <> table. If _param_value_ is `NULL`, it is ignored. * _param_value_size_ret_ returns the actual size in bytes of data being queried by _param_value_. If _param_value_size_ret_ is `NULL`, it is ignored. -[[cl_khr_semaphore_info-table]] +[[semaphore-info-table]] .List of parameter names supported by {clGetSemaphoreInfoKHR} [width="100%",cols="<33%,<17%,<50%",options="header"] |==== @@ -13563,14 +13572,12 @@ endif::cl_khr_external_semaphore[] successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_SEMAPHORE_KHR} - ** if _sema_object_ is not a valid semaphore - * {CL_INVALID_VALUE} - ** if _param_name_ is not one of the attribute defined in the - <> table or - ** if _param_value_size_ is less than the size of Return Type of the - corresponding _param_name_ attribute as defined in the - <> table. + * {CL_INVALID_SEMAPHORE_KHR} if _sema_object_ is not a valid semaphore. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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 @@ -13786,6 +13793,7 @@ endif::cl_khr_command_buffer_multi_device[] successfully and the profiling information has been recorded. Otherwise, it returns one of the following errors: + * {CL_INVALID_EVENT} if _event_ is a not a valid event object. * {CL_PROFILING_INFO_NOT_AVAILABLE} if the {CL_QUEUE_PROFILING_ENABLE} flag is not set for the command-queue, if the execution status of the command identified by _event_ is not {CL_COMPLETE} or if _event_ is a user event @@ -13800,11 +13808,11 @@ ifdef::cl_khr_command_buffer_multi_device[] {CL_PROFILING_INFO_NOT_AVAILABLE} is returned if all the queues passed do not have {CL_QUEUE_PROFILING_ENABLE} set. endif::cl_khr_command_buffer_multi_device[] - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table and - _param_value_ is not `NULL`. - * {CL_INVALID_EVENT} if _event_ is a not a valid event object. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table and _param_value_ is not + a `NULL` value. * {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 @@ -16120,9 +16128,11 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid command-buffer. - * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values or - if size in bytes specified by _param_value_size_ is less than size of - return type and _param_value_ is not a `NULL` value. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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 @@ -16276,12 +16286,13 @@ include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_LOCAL_WORK_SIZE_KHR.a executed successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> - table and _param_value_ is not `NULL`. * {CL_INVALID_MUTABLE_COMMAND_KHR} if _command_ is not a valid mutable command object. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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 @@ -16385,15 +16396,14 @@ Otherwise, it returns one of the following errors: to a non-default value. ** Both of the properties {CL_CGL_SHAREGROUP_KHR} and {CL_GL_CONTEXT_KHR} are set to non-default values. - ** Any of the devices specified in the argument cannot support - OpenCL objects which share the data store of an OpenGL object. - * {CL_INVALID_VALUE} if an property name other than those specified in - _table 4.5_ is specified in _properties_. - * {CL_INVALID_VALUE} if _param_name_ is not one of the values listed in - the <> table, or if the size in bytes - specified by _param_value_size_ is less than the size of the return type - shown in the table and _param_value_ is not a `NULL` value + * {CL_INVALID_VALUE} if an property name other than {CL_GL_CONTEXT_KHR}, + {CL_CGL_SHAREGROUP_KHR}, {CL_EGL_DISPLAY_KHR}, {CL_GLX_DISPLAY_KHR}, or + {CL_WGL_HDC_KHR}, or is specified in _properties_. + * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or + if the size in bytes specified by _param_value_size_ is less than size of + the return type specified in the + <> table + and _param_value_ is not `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