From 1334f2ef71e09185963c687e236e57ea30bcb423 Mon Sep 17 00:00:00 2001 From: Kevin Petit Date: Fri, 25 Oct 2024 14:49:18 +0100 Subject: [PATCH] Add specification for cl_ext_immutable_memory_objects Fixes #1110 Change-Id: I120f66ad20f977c251b77cc42a32021cb407518e Signed-off-by: Kevin Petit --- api/cl_ext_immutable_memory_objects.asciidoc | 43 +++++ api/glossary.asciidoc | 10 ++ api/opencl_runtime_layer.asciidoc | 170 ++++++++++++++++++- xml/cl.xml | 7 +- 4 files changed, 225 insertions(+), 5 deletions(-) create mode 100644 api/cl_ext_immutable_memory_objects.asciidoc diff --git a/api/cl_ext_immutable_memory_objects.asciidoc b/api/cl_ext_immutable_memory_objects.asciidoc new file mode 100644 index 000000000..6e7f14175 --- /dev/null +++ b/api/cl_ext_immutable_memory_objects.asciidoc @@ -0,0 +1,43 @@ +// Copyright 2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}cl_ext_immutable_memory_objects.txt[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2024-11-06 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Kevin Petit, Arm Ltd. + - Ahmed Hesham, Arm Ltd. + - Michael Rizkalla, Arm Ltd. +*Interactions*:: + - This extension interacts with {cl_khr_egl_image_EXT}. + +=== Description + +{cl_ext_immutable_memory_objects_EXT} provides a mechanism to create memory +objects that cannot be modified by the implementation after creation. This, +for example, enables implementation to support image formats for which no write +operations can be supported. + +=== New Enums + + * {cl_mem_flags_TYPE} + ** {CL_MEM_IMMUTABLE_EXT} + +=== Issues + +1) Can {CL_MEM_READ_ONLY} be used instead of {CL_MEM_IMMUTABLE_EXT}? +-- +*RESOLVED*: No. Memory objects created with {CL_MEM_READ_ONLY} can be modified +by copy or fill commands and this behaviour cannot be changed without breaking +backwards compatibility. +-- + +=== Version History + + * Revision 1.0.0, 2024-11-06 + ** Initial version diff --git a/api/glossary.asciidoc b/api/glossary.asciidoc index 4794c760a..f8dc3778f 100644 --- a/api/glossary.asciidoc +++ b/api/glossary.asciidoc @@ -336,6 +336,16 @@ The elements of an image are selected from a list of predefined image formats. -- +ifdef::cl_ext_immutable_memory_objects[] +Immutable Memory Object :: + A _memory object_ whose contents cannot be altered by the implementation + after creation. +ifdef::cl_khr_external_memory[] + External entities may change the contents of + _immutable memory objects_ created from external handles. +endif::cl_khr_external_memory[] +endif::cl_ext_immutable_memory_objects[] + Implementation-Defined :: Behavior that is explicitly allowed to vary between conforming implementations of OpenCL. diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 019288efc..fb6fae1bd 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -612,6 +612,17 @@ include {CL_MEM_USE_HOST_PTR}, {CL_MEM_ALLOC_HOST_PTR}, or {CL_MEM_COPY_HOST_PTR}, and the _host_ptr_ argument must be `NULL`. endif::cl_khr_external_memory[] +ifdef::cl_ext_immutable_memory_objects[] +If {CL_MEM_IMMUTABLE_EXT} is set in _flags_, the buffer created is +an _immutable memory object_ that cannot be modified by the implementation +after creation, and one and only one of the following conditions must be met: + + * Either {CL_MEM_COPY_HOST_PTR} or {CL_MEM_USE_HOST_PTR} must be set in _flags_. +ifdef::cl_khr_external_memory[] + * An external memory handle must be included in _properties_. +endif::cl_khr_external_memory[] +endif::cl_ext_immutable_memory_objects[] + // refError {clCreateBuffer} and {clCreateBufferWithProperties} returns a valid non-zero @@ -662,6 +673,17 @@ ifdef::cl_khr_external_memory[] {CL_MEM_DEVICE_HANDLE_LIST_KHR} is specified as part of _properties_. ** if _properties_ includes more than one external memory handle. endif::cl_khr_external_memory[] +ifdef::cl_ext_immutable_memory_objects[] + * {CL_INVALID_VALUE} if {CL_MEM_IMMUTABLE_EXT} is set in _flags_ and + {CL_MEM_READ_WRITE}, {CL_MEM_WRITE_ONLY}, or {CL_MEM_HOST_WRITE_ONLY} + is set in _flags_. + * {CL_INVALID_VALUE} if {CL_MEM_IMMUTABLE_EXT} is set in _flags_ and none + of the following conditions are met + ** {CL_MEM_COPY_HOST_PTR} or {CL_MEM_USE_HOST_PTR} is set in _flags_. +ifdef::cl_khr_external_memory[] + ** _properties_ includes an external memory handle. +endif::cl_khr_external_memory[] +endif::cl_ext_immutable_memory_objects[] [[memory-flags-table]] .List of supported memory flag values @@ -771,6 +793,14 @@ include::{generated}/api/version-notes/CL_MEM_KERNEL_READ_AND_WRITE.asciidoc[] instance. To create a memory object that may be read from and written to use {CL_MEM_READ_WRITE}. + +ifdef::cl_ext_immutable_memory_objects[] +| {CL_MEM_IMMUTABLE_EXT_anchor} + +include::{generated}/api/version-notes/CL_MEM_IMMUTABLE_EXT.asciidoc[] + | This flag specifies that the contents of the memory object cannot be altered + by the implementation after creation. +endif::cl_ext_immutable_memory_objects[] |==== -- @@ -786,7 +816,11 @@ include::{generated}/api/version-notes/clCreateSubBuffer.asciidoc[] * _flags_ is a bit-field that is used to specify allocation and usage information about the sub-buffer memory object being created and is described in the <> table. - If the {CL_MEM_READ_WRITE}, {CL_MEM_READ_ONLY}, or {CL_MEM_WRITE_ONLY} values are + If the {CL_MEM_READ_WRITE}, {CL_MEM_READ_ONLY}, +ifdef::cl_ext_immutable_memory_objects[] + {CL_MEM_IMMUTABLE_EXT}, +endif::cl_ext_immutable_memory_objects[] + or {CL_MEM_WRITE_ONLY} values are not specified in _flags_, they are inherited from the corresponding memory access qualifiers associated with _buffer_. The {CL_MEM_USE_HOST_PTR}, {CL_MEM_ALLOC_HOST_PTR}, and {CL_MEM_COPY_HOST_PTR} @@ -864,6 +898,11 @@ Otherwise, it returns one of the following errors in _errcode_ret_: associated with _buffer_ for which the _origin_ field of the {cl_buffer_region_TYPE} structure passed in _buffer_create_info_ is aligned to the {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value. +ifdef::cl_ext_immutable_memory_objects[] + * {CL_INVALID_VALUE} if _buffer_ was created with {CL_MEM_IMMUTABLE_EXT} + and _flags_ specifies {CL_MEM_READ_WRITE}, {CL_MEM_WRITE_ONLY}, or + {CL_MEM_HOST_WRITE_ONLY}. +endif::cl_ext_immutable_memory_objects[] [NOTE] ==== @@ -1005,6 +1044,10 @@ Otherwise, they return one of the following errors: 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_ext_immutable_memory_objects[] + * {CL_INVALID_OPERATION} if {clEnqueueWriteBuffer} is called on _buffer_ + which has been created with {CL_MEM_IMMUTABLE_EXT}. +endif::cl_ext_immutable_memory_objects[] -- [open,refpage='clEnqueueReadBufferRect',desc='Enqueue command to read from a 2D or 3D rectangular region from a buffer object to host memory.',type='protos',alias='clEnqueueWriteBufferRect'] @@ -1162,6 +1205,10 @@ Otherwise, they return one of the following errors: 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_ext_immutable_memory_objects[] + * {CL_INVALID_OPERATION} if {clEnqueueWriteBufferRect} is called on _buffer_ + which has been created with {CL_MEM_IMMUTABLE_EXT}. +endif::cl_ext_immutable_memory_objects[] [NOTE] ==== @@ -1305,6 +1352,10 @@ Otherwise, it returns one of the following errors: 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_ext_immutable_memory_objects[] + * {CL_INVALID_OPERATION} if _dst_buffer_ was created with + {CL_MEM_IMMUTABLE_EXT}. +endif::cl_ext_immutable_memory_objects[] -- [open,refpage='clEnqueueCopyBufferRect',desc='Enqueues a command to copy a 2D or 3D rectangular region from a buffer object to another buffer object.',type='protos'] @@ -1452,6 +1503,10 @@ Otherwise, it returns one of the following errors: 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_ext_immutable_memory_objects[] + * {CL_INVALID_OPERATION} if _dst_buffer_ was created with + {CL_MEM_IMMUTABLE_EXT}. +endif::cl_ext_immutable_memory_objects[] -- @@ -1548,6 +1603,9 @@ Otherwise, it returns one of the following errors: 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_ext_immutable_memory_objects[] + * {CL_INVALID_OPERATION} if _buffer_ was created with {CL_MEM_IMMUTABLE_EXT}. +endif::cl_ext_immutable_memory_objects[] -- @@ -1656,6 +1714,11 @@ values returned in _errcode_ret_: required by the OpenCL implementation on the host. * {CL_INVALID_OPERATION} if mapping would lead to overlapping regions being mapped for writing. +ifdef::cl_ext_immutable_memory_objects[] + * {CL_INVALID_OPERATION} if _buffer_ was created with {CL_MEM_IMMUTABLE_EXT} + in _flags_ and {CL_MAP_WRITE} or {CL_MAP_WRITE_INVALIDATE_REGION} is set + in _map_flags_. +endif::cl_ext_immutable_memory_objects[] The pointer returned maps a region starting at _offset_ and is at least _size_ bytes in size. @@ -2055,6 +2118,21 @@ When such information is acquired at image creation time, it is used for the lifetime of the image object. endif::cl_khr_external_memory[] +ifdef::cl_ext_immutable_memory_objects[] +If {CL_MEM_IMMUTABLE_EXT} is set in _flags_, the image created is +an _immutable memory object_ that cannot be modified by the implementation +after creation, and one and only one of the following conditions must be met: + + * Either {CL_MEM_COPY_HOST_PTR} or {CL_MEM_USE_HOST_PTR} must be set in _flags_. +ifdef::cl_khr_external_memory[] + * An external memory handle must be included in _properties_. +endif::cl_khr_external_memory[] + +If the image being created is created from another memory object and that memory +object is an _immutable memory object_, then {CL_MEM_IMMUTABLE_EXT} must be set +in _flags_. +endif::cl_ext_immutable_memory_objects[] + // refError {clCreateImage} and {clCreateImageWithProperties} returns a valid non-zero @@ -2131,6 +2209,19 @@ ifdef::cl_khr_external_memory[] {CL_MEM_DEVICE_HANDLE_LIST_KHR} is specified as part of _properties_. ** if _properties_ includes more than one external memory handle. endif::cl_khr_external_memory[] +ifdef::cl_ext_immutable_memory_objects[] + * {CL_INVALID_VALUE} if {CL_MEM_IMMUTABLE_EXT} is set in _flags_ and + {CL_MEM_READ_WRITE}, {CL_MEM_WRITE_ONLY}, or {CL_MEM_HOST_WRITE_ONLY} + is set in _flags_. + * {CL_INVALID_VALUE} if {CL_MEM_IMMUTABLE_EXT} is not set in _flags_ and + _mem_object_ was created with {CL_MEM_IMMUTABLE_EXT}. + * {CL_INVALID_VALUE} if {CL_MEM_IMMUTABLE_EXT} is set in _flags_ and none + of the following conditions are met + ** {CL_MEM_COPY_HOST_PTR} or {CL_MEM_USE_HOST_PTR} is set in _flags_. +ifdef::cl_khr_external_memory[] + ** _properties_ includes an external memory handle. +endif::cl_khr_external_memory[] +endif::cl_ext_immutable_memory_objects[] [[host-ptr-buffer-size-table]] .Required _host_ptr_ buffer sizes for images @@ -2206,6 +2297,13 @@ include::{generated}/api/version-notes/clCreateImage2D.asciidoc[] * _errcode_ret_ will return an appropriate error code. If _errcode_ret_ is `NULL`, no error code is returned. +ifdef::cl_ext_immutable_memory_objects[] +If {CL_MEM_IMMUTABLE_EXT} is set in _flags_, the image created is +an _immutable memory object_ that cannot be modified by the implementation +after creation, and {CL_MEM_COPY_HOST_PTR} or {CL_MEM_USE_HOST_PTR} must be set +in _flags_. +endif::cl_ext_immutable_memory_objects[] + // refError {clCreateImage2D} returns a valid non-zero image object created and the @@ -2237,6 +2335,10 @@ returned in _errcode_ret_: 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_ext_immutable_memory_objects[] + * {CL_INVALID_VALUE} if {CL_MEM_IMMUTABLE_EXT} is set in _flags_ and neither + {CL_MEM_COPY_HOST_PTR} nor {CL_MEM_USE_HOST_PTR} is set in _flags_. +endif::cl_ext_immutable_memory_objects[] -- [open,refpage='clCreateImage3D',desc='Creates a 3D image.',type='protos'] @@ -2290,6 +2392,13 @@ include::{generated}/api/version-notes/clCreateImage3D.asciidoc[] * _errcode_ret_ will return an appropriate error code. If _errcode_ret_ is `NULL`, no error code is returned. +ifdef::cl_ext_immutable_memory_objects[] +If {CL_MEM_IMMUTABLE_EXT} is set in _flags_, the image created is +an _immutable memory object_ that cannot be modified by the implementation +after creation, and {CL_MEM_COPY_HOST_PTR} or {CL_MEM_USE_HOST_PTR} must be set +in _flags_. +endif::cl_ext_immutable_memory_objects[] + // refError {clCreateImage3D} returns a valid non-zero image object created and the @@ -2322,6 +2431,10 @@ returned in _errcode_ret_: 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_ext_immutable_memory_objects[] + * {CL_INVALID_VALUE} if {CL_MEM_IMMUTABLE_EXT} is set in _flags_ and neither + {CL_MEM_COPY_HOST_PTR} nor {CL_MEM_USE_HOST_PTR} is set in _flags_. +endif::cl_ext_immutable_memory_objects[] -- @@ -2809,6 +2922,10 @@ include::{generated}/api/version-notes/clGetSupportedImageFormats.asciidoc[] may be written to by a kernel, or {CL_MEM_KERNEL_READ_AND_WRITE} to query image formats that may be both read from and written to by the same kernel instance. +ifdef::cl_ext_immutable_memory_objects[] + _flags_ may also be {CL_MEM_IMMUTABLE_EXT} to query image formats that + may be used to create immutable images. +endif::cl_ext_immutable_memory_objects[] Please see <> for clarification. * _image_type_ describes the image type and must be either {CL_MEM_OBJECT_IMAGE1D}, {CL_MEM_OBJECT_IMAGE1D_BUFFER}, {CL_MEM_OBJECT_IMAGE2D}, @@ -3038,6 +3155,10 @@ parameter and any other image parameter. | {CL_MEM_READ_ONLY}, + {CL_MEM_READ_WRITE}, + {CL_MEM_KERNEL_READ_AND_WRITE} +ifdef::cl_ext_immutable_memory_objects[] + Additionally, if the {cl_ext_immutable_memory_objects_EXT} extension is supported: + {CL_MEM_IMMUTABLE_EXT} +endif::cl_ext_immutable_memory_objects[] | `write_only` | {CL_MEM_WRITE_ONLY}, + {CL_MEM_READ_WRITE}, + @@ -3441,6 +3562,10 @@ ifdef::cl_khr_mipmap_image[] supported, and the mip level specified in _origin_ is not a valid level for _image_, endif::cl_khr_mipmap_image[] +ifdef::cl_ext_immutable_memory_objects[] + * {CL_INVALID_OPERATION} if {clEnqueueWriteImage} is called on _image_ which + has been created with {CL_MEM_IMMUTABLE_EXT}. +endif::cl_ext_immutable_memory_objects[] [NOTE] ==== @@ -3619,6 +3744,9 @@ ifdef::cl_khr_mipmap_image[] supported, and the mip level specified in _src_origin_ or _dst_origin_ is not a valid level for the corresponding _src_image_ or _dst_image_, endif::cl_khr_mipmap_image[] +ifdef::cl_ext_immutable_memory_objects[] + * {CL_INVALID_OPERATION} if _dst_image_ was created with {CL_MEM_IMMUTABLE_EXT}. +endif::cl_ext_immutable_memory_objects[] -- @@ -3740,6 +3868,9 @@ ifdef::cl_khr_mipmap_image[] supported, and the mip level specified in _origin_ is not a valid level for _image_, endif::cl_khr_mipmap_image[] +ifdef::cl_ext_immutable_memory_objects[] + * {CL_INVALID_OPERATION} if _image_ was created with {CL_MEM_IMMUTABLE_EXT}. +endif::cl_ext_immutable_memory_objects[] -- @@ -3872,6 +4003,9 @@ ifdef::cl_khr_mipmap_image[] supported, and the mip level specified in _src_origin_ is not a valid level for _src_image_, endif::cl_khr_mipmap_image[] +ifdef::cl_ext_immutable_memory_objects[] + * {CL_INVALID_OPERATION} if _dst_buffer_ was created with {CL_MEM_IMMUTABLE_EXT}. +endif::cl_ext_immutable_memory_objects[] -- @@ -4004,6 +4138,9 @@ ifdef::cl_khr_mipmap_image[] supported, and the mip level specified in _dst_origin_ is not a valid level for _dst_image_, endif::cl_khr_mipmap_image[] +ifdef::cl_ext_immutable_memory_objects[] + * {CL_INVALID_OPERATION} if _dst_image_ was created with {CL_MEM_IMMUTABLE_EXT}. +endif::cl_ext_immutable_memory_objects[] -- @@ -4148,6 +4285,11 @@ values returned in _errcode_ret_: required by the OpenCL implementation on the host. * {CL_INVALID_OPERATION} if mapping would lead to overlapping regions being mapped for writing. +ifdef::cl_ext_immutable_memory_objects[] + * {CL_INVALID_OPERATION} if _image_ was created with {CL_MEM_IMMUTABLE_EXT} + in _flags_ and {CL_MAP_WRITE} or {CL_MAP_WRITE_INVALIDATE_REGION} is set + in _map_flags_. +endif::cl_ext_immutable_memory_objects[] The pointer returned maps a 1D, 2D or 3D region starting at _origin_ and is at least _region_[0] pixels in size for a 1D image, 1D image buffer or 1D @@ -4800,13 +4942,16 @@ include::{generated}/api/version-notes/clCreateFromEGLImageKHR.asciidoc[] * _errcode_ret_ will return an appropriate error code. If _errcode_ret_ is `NULL`, no error code is returned. -Accepted for _flags_ are {CL_MEM_READ_ONLY}, {CL_MEM_WRITE_ONLY} and -CL_MEM_READ_WRITE. +Accepted for _flags_ are {CL_MEM_READ_ONLY}, {CL_MEM_WRITE_ONLY}, +ifdef::cl_ext_immutable_memory_objects[] +{CL_MEM_IMMUTABLE_EXT}, +endif::cl_ext_immutable_memory_objects[] +and {CL_MEM_READ_WRITE}. If OpenCL 1.2 is supported, _flags_ also accepts {CL_MEM_HOST_WRITE_ONLY}, {CL_MEM_HOST_READ_ONLY}, and {CL_MEM_HOST_NO_ACCESS}. {cl_khr_egl_image_EXT} only requires support for {CL_MEM_READ_ONLY}, and for -CL_MEM_HOST_NO_ACCESS if OpenCL 1.2 or later is supported. +{CL_MEM_HOST_NO_ACCESS} if OpenCL 1.2 or later is supported. For OpenCL 1.1, a {CL_INVALID_OPERATION} will be returned for images which do not support host mapping. @@ -4814,6 +4959,12 @@ If the value passed in _flags_ is not supported by the OpenCL implementation, it will return {CL_INVALID_VALUE}. The accepted _flags_ may be dependent upon the texture format used. +ifdef::cl_ext_immutable_memory_objects[] +If {CL_MEM_IMMUTABLE_EXT} is set in _flags_, the image created is +an _immutable memory object_ that cannot be modified by the implementation +after creation. +endif::cl_ext_immutable_memory_objects[] + // refError {clCreateFromEGLImageKHR} returns a valid non-zero OpenCL image object and @@ -4839,6 +4990,11 @@ returned in _errcode_ret_: images (i.e. {CL_DEVICE_IMAGE_SUPPORT} specified in table 4.3 is {CL_FALSE}) or if the flags passed are not supported for that image type. +ifdef::cl_ext_immutable_memory_objects[] + * {CL_INVALID_VALUE} if {CL_MEM_IMMUTABLE_EXT} is set in _flags_ and + {CL_MEM_READ_WRITE}, {CL_MEM_WRITE_ONLY}, or {CL_MEM_HOST_WRITE_ONLY} + is set in _flags_. +endif::cl_ext_immutable_memory_objects[] -- endif::cl_khr_egl_image[] @@ -5182,6 +5338,9 @@ returned in _errcode_ret_: 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_ext_immutable_memory_objects[] + * {CL_INVALID_VALUE} if {CL_MEM_IMMUTABLE_EXT} is set in _flags_. +endif::cl_ext_immutable_memory_objects[] Pipes follow the same memory consistency model as defined for buffer and image objects. @@ -7513,6 +7672,9 @@ Otherwise, like *malloc*, it returns a `NULL` pointer value. * _context_ is not a valid context, or no devices in _context_ support SVM. * _flags_ does not contain {CL_MEM_SVM_FINE_GRAIN_BUFFER} but does contain {CL_MEM_SVM_ATOMICS}. +ifdef::cl_ext_immutable_memory_objects[] + * _flags_ contains {CL_MEM_IMMUTABLE_EXT}. +endif::cl_ext_immutable_memory_objects[] * Values specified in _flags_ do not follow rules described for supported values in the <> table. * {CL_MEM_SVM_FINE_GRAIN_BUFFER} or {CL_MEM_SVM_ATOMICS} is specified in diff --git a/xml/cl.xml b/xml/cl.xml index 33f45ce82..af2f8afce 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -882,7 +882,7 @@ server's OpenCL/api-docs repository. - + @@ -7497,5 +7497,10 @@ server's OpenCL/api-docs repository. + + + + +