Merge pull request #40 from kpet/master
Deprecate cl_arm_shared_virtual_memory
diff --git a/extensions/qcom/cl_qcom_android_native_buffer_host_ptr.txt b/extensions/qcom/cl_qcom_android_native_buffer_host_ptr.txt
index 82a1c5d..2b0cc2a 100644
--- a/extensions/qcom/cl_qcom_android_native_buffer_host_ptr.txt
+++ b/extensions/qcom/cl_qcom_android_native_buffer_host_ptr.txt
@@ -1,31 +1,29 @@
-Name
-
- CL_QCOM_ANDROID_NATIVE_BUFFER_HOST_PTR
-
Name Strings
cl_qcom_android_native_buffer_host_ptr
-Contact
-
- hosseins at quicinc dot com
- ssusheel at quicinc dot com
-
-
Contributors
- Hossein Mohtasham, QUALCOMM Innovation Center Inc.
- Sushmita Susheelendra, QUALCOMM Innovation Center Inc.
- Balaji Calidas, QUALCOMM
+ Hossein Mohtasham, Qualcomm Technologies, Inc.
+ Sushmita Susheelendra, Qualcomm Innovation Center, Inc.
+ Balaji Calidas, Qualcomm Technologies, Inc.
-Status
+Contact
- ?
+ bcalidas at qti dot qualcomm dot com
+
+Version
+
+ Version 6, 2018/01/19
Number
OpenCL Extension #32
+Status
+
+ Shipping
+
Extension Type
OpenCL device extension
@@ -36,23 +34,28 @@
cl_qcom_ext_host_ptr is required.
Android OS is required.
- This extension is written against the OpenCL 1.1 specification. This extension provides
- functionality, beyond and above the cl_qcom_ion_host_ptr extension, to create buffer/image
- directly from Android native buffers.
+ This extension is written against the OpenCL 1.1 specification. This
+ extension provides functionality, beyond and above the cl_qcom_ion_host_ptr
+ extension, to create buffers and images directly from Android native
+ buffers.
+
+ If present, cl_qcom_ext_host_ptr_iocoherent extends the functionality
+ of this extension.
Overview
- This extension extends the functionality provided by clCreateBuffer, clCreateImage2D,
- and clCreateImage. It allows applications to pass an Android ANativeWindowBuffer (ANB),
- aka graphics buffer, that is based on ION memory allocator to these functions so that
- it can be mapped to the device's address space. Using this extension, we can avoid having
- to copy data back and forth between the graphic buffer and the device. This extension is
- for 2D images only; clCreateImage will fail out with CL_INVALID_VALUE if anything other
- than a 2D image is specified.
+ This extension extends the functionality provided by clCreateBuffer,
+ clCreateImage2D, and clCreateImage. It allows applications to pass an
+ Android ANativeWindowBuffer (ANB), aka graphics buffer, that is based on
+ ION memory allocator to these functions so that it can be mapped to the
+ device's address space. Using this extension, we can avoid having to copy
+ data back and forth between the graphic buffer and the device. This
+ extension is for 2D images only; clCreateImage will fail out with
+ CL_INVALID_VALUE if anything other than a 2D image is specified.
-IP Status
+Header File
- No known IP claims.
+ cl_ext.h
New Tokens
@@ -76,74 +79,102 @@
Additions to Chapter 5.2.1 of the OpenCL 1.1 Specification
(Creating Buffer Objects)
- When CL_MEM_EXT_HOST_PTR_QCOM is enabled in the <flags> argument, then <host_ptr> is
- interpreted as a pointer to cl_mem_ext_host_ptr. When <host_ptr>->allocation_type is
- equal to CL_MEM_ANDROID_NATIVE_BUFFER_HOST_PTR_QCOM then <host_ptr> can also be
+ When CL_MEM_EXT_HOST_PTR_QCOM is enabled in the <flags> argument, then
+ <host_ptr> is interpreted as a pointer to cl_mem_ext_host_ptr. When
+ <host_ptr>->allocation_type is equal to
+ CL_MEM_ANDROID_NATIVE_BUFFER_HOST_PTR_QCOM then <host_ptr> can also be
interpreted as a pointer to cl_mem_android_native_buffer_host_ptr.
- In addition to that, the application must also initialize the following struct fields:
- * <host_ptr>->host_cache_policy can be equal to CL_MEM_HOST_UNCACHED_QCOM or
- CL_MEM_HOST_WRITEBACK_QCOM.
- * <host_ptr>->anb_ptr must be the host virtual pointer associated with the ANativeBuffer.
+ In addition to that, the application must also initialize the following
+ struct fields:
- The caching policy provided in ext_host_ptr.host_cache_policy must be the same policy
- the GraphicBuffer is created with. Any mismatch will result in undefined behavior.
+ * <host_ptr>->host_cache_policy should be set as follows - If the
+ Graphic Buffer was created as cached and
+ cl_mem_ext_host_ptr_iocoherent is present,
+ <host_ptr>->host_cache_policy can be set to either
+ CL_MEM_HOST_WRITEBACK_QCOM or CL_MEM_HOST_IOCOHERENT_QCOM. If the
+ Graphic Buffer was created as cached and
+ cl_mem_ext_host_ptr_iocoherent is not present,
+ <host_ptr>->host_cache_policy should be set to
+ CL_MEM_HOST_WRITEBACK_QCOM. It must be equal to
+ CL_MEM_HOST_UNCACHED_QCOM otherwise.
- Only Buffers and 2D images are supported. Use of other image types will result in undefined behavior.
+ * <host_ptr>->anb_ptr must be the host virtual pointer associated with
+ the ANativeBuffer.
- The application is responsible for maintaining the consistency of image attributes,
- i.e. format, width, height, and pitch, between the OpenCL image and the Android native buffer
- (aka graphics buffer). Also, if an OpenCL buffer is created from a native buffer, the
- application is responsible for making sure that the size of the buffer matches the actual
- linear size of the native buffer; creating a buffer with a size different than the passed-in
- native buffer will result in undefined behavior.
+ The caching policy provided in ext_host_ptr.host_cache_policy must be
+ the same policy the GraphicBuffer is created with. Any mismatch will
+ result in undefined behavior.
- The application is responsible for ensuring that the underlying native buffer is not released
- while the cl object is in use. Proper synchronization between different APIs that share the
- underlying buffer is to be handled by the application.
+ Only Buffers and 2D images are supported. Use of other image types will
+ result in undefined behavior.
+ The application is responsible for maintaining the consistency of image
+ attributes, i.e. format, width, height, and pitch, between the OpenCL
+ image and the Android native buffer (aka graphics buffer). Also, if an
+ OpenCL buffer is created from a native buffer, the application is
+ responsible for making sure that the size of the buffer matches the
+ actual linear size of the native buffer; creating a buffer with a size
+ different than the passed-in native buffer will result in undefined
+ behavior.
+
+ The application is responsible for ensuring that the underlying native
+ buffer is not released while the cl object is in use. Proper
+ synchronization between different APIs that share the underlying buffer
+ is to be handled by the application.
Sample Code
- /* Using the extension for CL buffer objects */
+ 1) Using the extension for CL buffer objects
- cl_mem buffer_object = NULL;
- size_t buffer_size_in_bytes = 0;
- cl_mem_android_native_buffer_host_ptr myANBmem = {0};
+ cl_mem buffer_object = NULL;
+ size_t buffer_size_in_bytes = 0;
+ cl_mem_android_native_buffer_host_ptr myANBmem = {0};
+ // Create an OpenCL buffer object that uses myANBmem as its data store.
+ myANBmem.ext_host_ptr.allocation_type =
+ CL_MEM_ANDROID_NATIVE_BUFFER_HOST_PTR_QCOM;
+ myANBmem.ext_host_ptr.host_cache_policy = CL_MEM_HOST_UNCACHED_QCOM;
+ myANBmem.anb_ptr = gb->getNativeBuffer(); // gb is Android GraphicBuffer
- // Create an OpenCL buffer object that uses myANBmem as its data store.
- myANBmem.ext_host_ptr.allocation_type = CL_MEM_ANDROID_NATIVE_BUFFER_HOST_PTR_QCOM;
- myANBmem.ext_host_ptr.host_cache_policy = CL_MEM_HOST_CACHED_QCOM;
- myANBmem.ion_hostptr = gb->getNativeBuffer(); // the hostptr to a native buffer and gb is an Android GraphicBuffer
+ // The stride returned is in pixels, so we have to factor in pixel_size
+ // (4 for RGBA) when calculating buffer_size_in_bytes
+ buffer_size_in_bytes = gb->getHeight() * gb->getStride() * 4;
- buffer_size_in_bytes = gb->getHeight() * gb->getStride();
+ buffer_object = clCreateBuffer(context,
+ CL_MEM_USE_HOST_PTR | CL_MEM_EXT_HOST_PTR_QCOM,
+ buffer_size_in_bytes, &myANBmem, &errcode);
- buffer_object = clCreateBuffer(context, CL_MEM_USE_HOST_PTR | CL_MEM_EXT_HOST_PTR_QCOM, buffer_size_in_bytes, &myANBmem, &errcode);
+ 2) Using the extension for CL image objects
+ cl_mem image_object = NULL;
+ cl_mem_android_native_buffer_host_ptr myANBmem = {0};
- /* Using the extension for CL image objects */
+ // Create an OpenCL image object that uses myANBmem as its data store.
+ myANBmem.ext_host_ptr.allocation_type =
+ CL_MEM_ANDROID_NATIVE_BUFFER_HOST_PTR_QCOM;
+ myANBmem.ext_host_ptr.host_cache_policy = CL_MEM_HOST_WRITEBACK_QCOM;
+ myANBmem.anb_ptr = gb->getNativeBuffer(); // gb is Android GraphicBuffer
- cl_mem image_object = NULL;
- cl_mem_android_native_buffer_host_ptr myANBmem = {0};
+ imgw = gb->getWidth();
+ imgh = gb->getHeight();
+ // The stride returned is in pixels, so we have to factor in pixel_size
+ // (4 for RGBA) when calculating row_pitch
+ row_pitch = gb->getStride() * 4;
+ // pick any CL format as long as it is consistent with graphic buffer
+ // width and stride.
+ image_format = {CL_RGBA, CL_UNSIGNED_INT8};
-
- // Create an OpenCL image object that uses myANBmem as its data store.
- myANBmem.ext_host_ptr.allocation_type = CL_MEM_ANDROID_NATIVE_BUFFER_HOST_PTR_QCOM;
- myANBmem.ext_host_ptr.host_cache_policy = CL_MEM_HOST_WRITEBACK_QCOM;
- myANBmem.anb_ptr = gb->getNativeBuffer(); // the hostptr to a native buffer and gb is an Android GraphicBuffer
-
- imgw = gb->getWidth();
- imgh = gb->getHeight();
- row_pitch = gb->getStride();
- image_format = {CL_RGBA, CL_UNSIGNED_INT8}; // pick any CL format as long as it is consistent with the graphics buffer width and stride.
-
- image_object = clCreateImage2D(context, CL_MEM_USE_HOST_PTR|CL_MEM_EXT_HOST_PTR_QCOM, &image_fmt, imgw, imgh, row_pitch, &myANBmem, &errcode);
-
-Issues
-
- None.
+ image_object = clCreateImage2D(context,
+ CL_MEM_USE_HOST_PTR|CL_MEM_EXT_HOST_PTR_QCOM, &image_fmt, imgw,
+ imgh, row_pitch, &myANBmem, &errcode);
Revision History
Revision 1, 2014/06/05: Initial version.
+ Revision 2, 2017/06/16: Clean up. No functional changes.
+ Revision 3, 2017/10/24: Updated sample code.
+ Revision 4, 2017/11/13: Clean up. No functional changes.
+ Revision 5, 2018/01/03: Add reference to cl_qcom_ext_host_ptr_iocoherent.
+ Revision 6, 2018/01/19: Formatting and misc changes. No functional changes.
+
diff --git a/extensions/qcom/cl_qcom_ext_host_ptr.txt b/extensions/qcom/cl_qcom_ext_host_ptr.txt
index 4a741ad..6112c5e 100644
--- a/extensions/qcom/cl_qcom_ext_host_ptr.txt
+++ b/extensions/qcom/cl_qcom_ext_host_ptr.txt
@@ -1,61 +1,64 @@
-Name
-
- CL_QCOM_EXT_HOST_PTR
-
Name Strings
cl_qcom_ext_host_ptr
-Contact
-
- ssusheel at quicinc dot com
- dgarcia at qti dot qualcomm dot com
-
Contributors
- Balaji Calidas, QUALCOMM
- David Garcia, QUALCOMM
- Rajeev Rao, QUALCOMM
- Sushmita Susheelendra, QUALCOMM Innovation Center Inc.
+ Balaji Calidas, Qualcomm Technologies, Inc.
+ David Garcia, Qualcomm Technologies, Inc.
+ Rajeev Rao, Qualcomm Technologies, Inc.
+ Sushmita Susheelendra, Qualcomm Innovation Center, Inc.
-Status
+Contact
- SHIPPING
+ bcalidas at qti dot qualcomm dot com
+
+Version
+
+ Version 5, 2018/01/19
Number
OpenCL Extension #21
+Status
+
+ Shipping
+
+Extension Type
+
+ OpenCL device extension
+
Dependencies
- OpenCL 1.1 is required.
-
+ OpenCL 1.1 is required.
+
This extension is written against the OpenCL 1.1 specification
Overview
- This extension extends the functionality provided by
- clCreateBuffer, clCreateImage2D, clCreateImage3D.
- It allows applications to specify a new flag CL_MEM_EXT_HOST_PTR_QCOM
- which enables the driver to map external memory allocations
- --to be defined in future layered extensions--
- to the device's address space and thus avoiding having to
- copy data back and forth between the host and the device.
+ This extension extends the functionality provided by clCreateBuffer,
+ clCreateImage2D, clCreateImage3D. It allows applications to specify a new
+ flag CL_MEM_EXT_HOST_PTR_QCOM which enables the driver to map external
+ memory allocations, to be defined in layered extensions, to the device's
+ address space and thus avoiding having to copy data back and forth between
+ the host and the device.
-IP Status
+Header File
- No known IP claims.
+ cl_ext.h
New Procedures and Functions
- cl_int clGetDeviceImageInfoQCOM(cl_device_id device,
- size_t image_width,
- size_t image_height,
- const cl_image_format *image_format,
- cl_image_pitch_info_qcom param_name,
- size_t param_value_size,
- void *param_value,
- size_t *param_value_size_ret);
+ cl_int clGetDeviceImageInfoQCOM(
+ cl_device_id device,
+ size_t image_width,
+ size_t image_height,
+ const cl_image_format *image_format,
+ cl_image_pitch_info_qcom param_name,
+ size_t param_value_size,
+ void *param_value,
+ size_t *param_value_size_ret);
New Types
@@ -65,85 +68,107 @@
Accepted by the <param_name> argument of clGetDeviceInfo
- CL_DEVICE_EXT_MEM_PADDING_IN_BYTES_QCOM 0x40A0
+ CL_DEVICE_EXT_MEM_PADDING_IN_BYTES_QCOM 0x40A0
CL_DEVICE_PAGE_SIZE_QCOM 0x40A1
-
- Accepted by the <flags> argument of clCreateBuffer, clCreateImage2D and clCreateImage3D:
+
+ Accepted by the <flags> argument of clCreateBuffer, clCreateImage2D and
+ clCreateImage3D:
CL_MEM_EXT_HOST_PTR_QCOM (1 << 29)
- Accepted by the <host_ptr> argument of clCreateBuffer, clCreateImage2D and clCreateImage3D:
+ Accepted by the <host_ptr> argument of clCreateBuffer, clCreateImage2D and
+ clCreateImage3D:
typedef struct _cl_mem_ext_host_ptr
{
// Type of external memory allocation.
// Legal values will be defined in layered extensions.
cl_uint allocation_type;
-
+
// Host cache policy for this external memory allocation.
cl_uint host_cache_policy;
} cl_mem_ext_host_ptr;
-
+
Accepted values for cl_mem_ext_host_ptr::host_cache_policy:
-
+
CL_MEM_HOST_UNCACHED_QCOM 0x40A4
CL_MEM_HOST_WRITEBACK_QCOM 0x40A5
CL_MEM_HOST_WRITETHROUGH_QCOM 0x40A6
CL_MEM_HOST_WRITE_COMBINING_QCOM 0x40A7
Accepted by the <param_name> argument of clGetDeviceImageInfoQCOM
-
+
CL_IMAGE_ROW_ALIGNMENT_QCOM 0x40A2
CL_IMAGE_SLICE_ALIGNMENT_QCOM 0x40A3
Additions to Chapter 5.2.1 of the OpenCL 1.1 Specification
(Creating Buffer Objects)
- Add the following token to Table 5.3 (clCreateBuffer List of supported cl_mem_flags values):
-
- CL_MEM_EXT_HOST_PTR_QCOM This flag is valid only when used together with CL_MEM_USE_HOST_PTR.
- If specified, it indicates that the <host_ptr> argument provided by
- the application is actually a pointer to cl_mem_ext_host_ptr.
+ Add the following token to Table 5.3 (clCreateBuffer List of supported
+ cl_mem_flags values):
-
- When CL_MEM_EXT_HOST_PTR_QCOM is enabled in the <flags> argument, then <host_ptr> is interpreted as a pointer to cl_mem_ext_host_ptr.
- The application must then initialize cl_mem_ext_host_ptr::allocation_type to the allowed token values defined in future layered extensions.
-
- The application must also initialize cl_mem_ext_host_ptr::host_cache_policy to one of CL_MEM_HOST_UNCACHED_QCOM, CL_MEM_HOST_WRITEBACK_QCOM,
- CL_MEM_HOST_WRITETHROUGH_QCOM, or CL_MEM_HOST_WRITE_COMBINING_QCOM according to the cache policy used in the host for this memory allocation.
-
- Add the following token to Table 4.3 (clGetDeviceInfo OpenCL Device Queries):
+ CL_MEM_EXT_HOST_PTR_QCOM This flag is valid only when used
+ together with CL_MEM_USE_HOST_PTR.
+ If specified, it indicates that the
+ <host_ptr> argument provided by the
+ application is actually a pointer
+ to cl_mem_ext_host_ptr.
- CL_DEVICE_EXT_MEM_PADDING_IN_BYTES_QCOM Returns the amount of memory padding that the application must add
- to the end of every external allocation that will be used in conjunction with
+
+ When CL_MEM_EXT_HOST_PTR_QCOM is enabled in the <flags> argument, then
+ <host_ptr> is interpreted as a pointer to cl_mem_ext_host_ptr. The
+ application must then initialize cl_mem_ext_host_ptr::allocation_type to
+ the allowed token values defined in future layered extensions.
+
+ The application must also initialize
+ cl_mem_ext_host_ptr::host_cache_policy to one of
+ CL_MEM_HOST_UNCACHED_QCOM, CL_MEM_HOST_WRITEBACK_QCOM,
+ CL_MEM_HOST_WRITETHROUGH_QCOM, or CL_MEM_HOST_WRITE_COMBINING_QCOM
+ according to the cache policy used in the host for this memory
+ allocation.
+
+ Add the following token to Table 4.3 (clGetDeviceInfo OpenCL Device
+ Queries):
+
+ CL_DEVICE_EXT_MEM_PADDING_IN_BYTES_QCOM Returns the amount of memory
+ padding that the application
+ must add to the end of every
+ external allocation that will
+ be used in conjunction with
CL_MEM_EXT_HOST_PTR_QCOM.
- CL_DEVICE_PAGE_SIZE_QCOM Returns the device's page size.
-
- The application may query the row and slice pitch values using clGetDeviceImageInfoQCOM
- and provide the queried values or any other supported value to clCreateImage2D and clCreateImage3D
- when using CL_MEM_EXT_HOST_PTR_QCOM.
+ CL_DEVICE_PAGE_SIZE_QCOM Returns the device's page
+ size.
- A supported value for row pitch and slice pitch is defined respectively as:
-
- * Any value greater than or equal to CL_IMAGE_ROW_PITCH that is also a multiple of CL_IMAGE_ROW_ALIGNMENT_QCOM
- * Any value greater than or equal to CL_IMAGE_SLICE_PITCH that is also a multiple of CL_IMAGE_SLICE_ALIGNMENT_QCOM
-
+ The application may query the row and slice pitch values using
+ clGetDeviceImageInfoQCOM and provide the queried values or any other
+ supported value to clCreateImage2D and clCreateImage3D when using
+ CL_MEM_EXT_HOST_PTR_QCOM.
+
+ A supported value for row pitch and slice pitch is defined respectively
+ as:
+
+ * Any value greater than or equal to CL_IMAGE_ROW_PITCH that is also a
+ multiple of CL_IMAGE_ROW_ALIGNMENT_QCOM.
+ * Any value greater than or equal to CL_IMAGE_SLICE_PITCH that is also
+ a multiple of CL_IMAGE_SLICE_ALIGNMENT_QCOM.
+
Additions to Section 5.3 after clGetImageInfo
- An application that creates OpenCL image objects with the CL_MEM_EXT_HOST_PTR_QCOM flag
- can invoke the following function to query the required row pitch, slice pitch and
- alignment for a particular device:
+ An application that creates OpenCL image objects with the
+ CL_MEM_EXT_HOST_PTR_QCOM flag can invoke the following function to query the
+ required row pitch, slice pitch and alignment for a particular device:
- cl_int clGetDeviceImageInfoQCOM(cl_device_id device,
- size_t image_width,
- size_t image_height,
- const cl_image_format *image_format,
- cl_image_pitch_info_qcom param_name,
- size_t param_value_size,
- void *param_value,
- size_t *param_value_size_ret);
+ cl_int clGetDeviceImageInfoQCOM(
+ cl_device_id device,
+ size_t image_width,
+ size_t image_height,
+ const cl_image_format *image_format,
+ cl_image_pitch_info_qcom param_name,
+ size_t param_value_size,
+ void *param_value,
+ size_t *param_value_size_ret);
device - is a valid device
@@ -151,42 +176,66 @@
image_height - height of the image in image elements (pixels)
- image_row_pitch - scan-line pitch in bytes
+ image_format - pointer to image format descriptor structure
- param_name - specifies the information to query. The list of supported param_name types and the
- information returned in param_value by clGetImageInfo is described in table 5.XXX
+ param_name - specifies the information to query. The list of
+ supported param_name types and the information
+ returned in param_value by clGetImageInfo is
+ described in Table 5.XXX
- 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 - 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 table 5.8.
+ 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 return type as described
+ in Table 5.8.
- 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.
+ 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.
- clGetDeviceImageInfoQCOM returns CL_SUCCESS if the function is executed successfully.
- Otherwise, it returns one of the following errors:
+ clGetDeviceImageInfoQCOM returns CL_SUCCESS if the function is 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 for that param_value and param_value is not NULL.
- CL_INVALID_MEM_OBJECT - if image is a not a valid image 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.
+ 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 return type for that param_value and
+ param_value is not NULL.
+
+ CL_INVALID_MEM_OBJECT - if image is a not a valid image 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.
Table 5.XXX
List of supported param_names by clGetDeviceImageInfoQCOM
- cl_image_pitch_info_qcom Return Type Info returned in param_value
- CL_IMAGE_ROW_PITCH cl_uint Returns the image row pitch supported by this device
- CL_IMAGE_ROW_ALIGNMENT_QCOM cl_uint Returns the image row pitch alignment supported by this device
- CL_IMAGE_SLICE_PITCH cl_uint Returns the image slice pitch supported by this device
- CL_IMAGE_SLICE_ALIGNMENT_QCOM cl_uint Returns the image slice pitch alignment supported by this device
+ cl_image_pitch_info_qcom Return Type Info returned in
+ param_value
-
-Additions to Section 5.3.1. (Creating Image Objects) at the end
-of the list of errors returned by clCreateImage2D and clCreateImage3D
+ CL_IMAGE_ROW_PITCH cl_uint Returns the image row pitch
+ supported by this device
+
+ CL_IMAGE_ROW_ALIGNMENT_QCOM cl_uint Returns the image row pitch
+ alignment supported by this
+ device
+
+ CL_IMAGE_SLICE_PITCH cl_uint Returns the image slice
+ pitch supported by this
+ device
+
+ CL_IMAGE_SLICE_ALIGNMENT_QCOM cl_uint Returns the image slice
+ pitch alignment supported
+ by this device
+
+Additions to Section 5.3.1. (Creating Image Objects) at the end of the list of
+errors returned by clCreateImage2D and clCreateImage3D:
CL_INVALID_VALUE if <flags> has CL_MEM_EXT_HOST_PTR_QCOM enabled and yet
CL_MEM_USE_HOST_PTR is not enabled.
@@ -194,13 +243,16 @@
CL_INVALID_VALUE if <flags> has CL_MEM_EXT_HOST_PTR_QCOM enabled and if
<image_row_pitch> and/or <image_slice_pitch> fail to match the requirements
of section 5.3
-
- CL_INVALID_VALUE if any of the fields in the struct pointed at by <host_ptr> are invalid.
-
-Issues
- None.
+ CL_INVALID_VALUE if any of the fields in the struct pointed at by <host_ptr>
+ are invalid.
Revision History
Revision 1, 2013/05/27: Initial version.
+ Revision 2, 2017/06/16: Clean up. No functional changes.
+ Revision 3, 2017/11/13: Clean up. No functional changes.
+ Revision 4, 2017/11/30: Corrected parameter description for
+ clGetDeviceImageInfoQCOM.
+ Revision 5, 2018/01/19: Formatting and misc changes. No functional changes.
+
diff --git a/extensions/qcom/cl_qcom_ext_host_ptr_iocoherent.txt b/extensions/qcom/cl_qcom_ext_host_ptr_iocoherent.txt
new file mode 100644
index 0000000..1f2eed7
--- /dev/null
+++ b/extensions/qcom/cl_qcom_ext_host_ptr_iocoherent.txt
@@ -0,0 +1,80 @@
+Name Strings
+
+ cl_qcom_ext_host_ptr_iocoherent
+
+Contributors
+
+ Balaji Calidas, Qualcomm Technologies, Inc.
+ Manali Torpe, Qualcomm Innovation Center, Inc.
+ Sreelakshmi Haridas Maruthur, Qualcomm Innovation Center, Inc.
+
+Contact
+
+ bcalidas at qti dot qualcomm dot com
+
+Version
+
+ Version 4, 2018/03/06
+
+Number
+
+ OpenCL Extension #TBD
+
+Status
+
+ Shipping
+
+Extension Type
+
+ OpenCL device extension
+
+Dependencies
+
+ OpenCL 1.1 is required.
+ cl_qcom_ext_host_ptr is required.
+
+ This extension extends the functionality of cl_qcom_ext_host_ptr.
+
+Overview
+
+ This extension extends the functionality provided by cl_qcom_ext_host_ptr by
+ adding a new host cache policy. It allows applications to specify a new
+ value, CL_MEM_HOST_IOCOHERENT_QCOM, for
+ cl_mem_ext_host_ptr::host_cache_policy. When the application selects this
+ value for host cache policy, the imported allocation is mapped as
+ io-coherent for the GPU. This in turn avoids the need for the OpenCL driver
+ to explicitly issue CPU cache operation calls. Although GPU performance can
+ be slower in some cases for io-coherent allocations, the overall performance
+ can improve due to the elimination of explicit CPU cache operations.
+
+Header File
+
+ cl_ext.h
+
+New Tokens
+
+ Modification to handling of <host_ptr> argument of clCreateBuffer,
+ clCreateImage2D and clCreateImage3D when CL_MEM_EXT_HOST_PTR_QCOM is
+ specified in the <flags> argument.
+
+ New accepted value for cl_mem_ext_host_ptr::host_cache_policy:
+
+ CL_MEM_HOST_IOCOHERENT_QCOM 0x40A9
+
+ As described in the cl_qcom_ext_host_ptr spec, when CL_MEM_EXT_HOST_PTR_QCOM
+ is enabled in the <flags> argument, then <host_ptr> is interpreted as a
+ pointer to cl_mem_ext_host_ptr. The application must initialize
+ cl_mem_ext_host_ptr::host_cache_policy to one of CL_MEM_HOST_UNCACHED_QCOM,
+ CL_MEM_HOST_WRITEBACK_QCOM, or CL_MEM_HOST_IOCOHERENT_QCOM according to the
+ cache policy used in the host for this memory allocation.
+ CL_MEM_HOST_IOCOHERENT_QCOM can only be specified when the memory was
+ originally allocated as cached. Use of this value with an uncached
+ allocation will lead to undefined results.
+
+Revision History
+
+ Revision 1, 2018/01/03: Initial version.
+ Revision 2, 2018/01/15: Minor edits.
+ Revision 3, 2018/01/19: Formatting and misc changes. No functional changes.
+ Revision 4, 2018/03/06: Corrected token value.
+
diff --git a/extensions/qcom/cl_qcom_ion_host_ptr.txt b/extensions/qcom/cl_qcom_ion_host_ptr.txt
index 8fe7354..d2057a2 100644
--- a/extensions/qcom/cl_qcom_ion_host_ptr.txt
+++ b/extensions/qcom/cl_qcom_ion_host_ptr.txt
@@ -1,51 +1,58 @@
-Name
-
- CL_QCOM_ION_HOST_PTR
-
Name Strings
cl_qcom_ion_host_ptr
-Contact
-
- ssusheel at quicinc dot com
- dgarcia at qti dot qualcomm dot com
-
Contributors
- Balaji Calidas, QUALCOMM
- David Garcia, QUALCOMM
- Sushmita Susheelendra, QUALCOMM Innovation Center Inc.
+ Balaji Calidas, Qualcomm Technologies, Inc.
+ David Garcia, Qualcomm Technologies, Inc.
+ Sushmita Susheelendra, Qualcomm Innovation Center, Inc.
-Status
+Contact
- SHIPPING
+ bcalidas at qti dot qualcomm dot com
+
+Version
+
+ Version 7, 2018/01/19
Number
OpenCL Extension #22
+Status
+
+ Shipping
+
+Extension Type
+
+ OpenCL device extension
+
Dependencies
- OpenCL 1.1 is required. cl_qcom_ext_host_ptr is required. Android OS is required.
-
+ OpenCL 1.1 is required. cl_qcom_ext_host_ptr is required.
+
This extension is written against the OpenCL 1.1 specification
+ If present, cl_qcom_ext_host_ptr_iocoherent extends the functionality of
+ this extension.
+
Overview
- This extension extends the functionality provided by
- clCreateBuffer, clCreateImage2D, clCreateImage3D.
- It allows applications to pass an Android ION memory allocation to these functions
- so that it can be mapped to the device's address space and thus avoid having to
- copy data back and forth between the host and the device.
+ This extension extends the functionality provided by clCreateBuffer,
+ clCreateImage2D, clCreateImage3D. It allows applications to pass an ION
+ memory allocation to these functions so that it can be mapped to the
+ device's address space and thus avoid having to copy data back and forth
+ between the host and the device.
-IP Status
+Header File
- No known IP claims.
+ cl_ext.h
New Tokens
- Accepted by the <host_ptr> argument of clCreateBuffer, clCreateImage2D and clCreateImage3D:
+ Accepted by the <host_ptr> argument of clCreateBuffer, clCreateImage2D and
+ clCreateImage3D:
typedef struct _cl_mem_ion_host_ptr
{
@@ -55,141 +62,196 @@
// ION file descriptor
int ion_filedesc;
-
+
// Host pointer to the ION allocated memory
void* ion_hostptr;
} cl_mem_ion_host_ptr;
Used together with CL_MEM_EXT_HOST_PTR_QCOM:
-
+
CL_MEM_ION_HOST_PTR_QCOM 0x40A8
Additions to Chapter 5.2.1 of the OpenCL 1.1 Specification
-(Creating Buffer Objects)
- When CL_MEM_EXT_HOST_PTR_QCOM is enabled in the <flags> argument, then <host_ptr> is interpreted as a pointer to cl_mem_ext_host_ptr.
- When <host_ptr>->allocation_type is equal to CL_MEM_ION_HOST_PTR_QCOM then <host_ptr> can also be interpreted as
- a pointer to cl_mem_ion_host_ptr.
+ (Creating Buffer Objects)
- In addition to that, the application must also initialize the following struct fields:
- * <host_ptr>->host_cache_policy must be equal to CL_MEM_HOST_WRITEBACK_QCOM if the ion allocation was made with the flag ION_FLAG_CACHED enabled.
- It must be equal to CL_MEM_HOST_UNCACHED_QCOM otherwise.
- * <host_ptr>->ion_filedesc must be the file descriptor of the ION memory allocation that the application
- wants to use as storage bits for the memory object.
- * <host_ptr>->ion_hostptr must be the host virtual pointer associated with the same ION memory allocation.
+ When CL_MEM_EXT_HOST_PTR_QCOM is enabled in the <flags> argument, then
+ <host_ptr> is interpreted as a pointer to cl_mem_ext_host_ptr. When
+ <host_ptr>->allocation_type is equal to CL_MEM_ION_HOST_PTR_QCOM then
+ <host_ptr> can also be interpreted as a pointer to cl_mem_ion_host_ptr.
- Memory specified this way must be aligned to the device's page size. The application can query the device's
- page size by using clGetDeviceInfo(..., CL_DEVICE_PAGE_SIZE_QCOM, ...).
+ In addition to that, the application must also initialize the following
+ struct fields:
- Once the memory object is created, the application must call clEnqueueMapBuffer/clEnqueueMapImage with
- appropriate flags before reading or writing to it on the host. The host unmaps the region when accesses
- (reads and/or writes) to this mapped region by the host are complete. As per the OpenCL 1.2 specification,
- clEnqueueMapBuffer and clEnqueueMapImage act as synchronization points for the region of the buffer
- object being mapped.
-
-Issues
+ * <host_ptr>->host_cache_policy should be set as follows - If the ion
+ allocation was made with the flag ION_FLAG_CACHED enabled and
+ cl_mem_ext_host_ptr_iocoherent is present, <host_ptr>->host_cache_policy
+ can be set to either CL_MEM_HOST_WRITEBACK_QCOM or
+ CL_MEM_HOST_IOCOHERENT_QCOM. If the ION allocation was made with the
+ flag ION_FLAG_CACHED enabled and cl_mem_ext_host_ptr_iocoherent is not
+ present, <host_ptr>->host_cache_policy should be set to
+ CL_MEM_HOST_WRITEBACK_QCOM. It must be equal to
+ CL_MEM_HOST_UNCACHED_QCOM otherwise.
+
+ * <host_ptr>->ion_filedesc must be the file descriptor of the ION memory
+ allocation that the application wants to use as storage bits for the
+ memory object.
+
+ * <host_ptr>->ion_hostptr must be the host virtual pointer associated with
+ the same ION memory allocation. If the application does not need to map
+ the newly created cl memory object for host access, it can set
+ <host_ptr>->ion_hostptr to NULL. If this happens, then calls to host
+ access functions such as clEnqueueMapBuffer will fail out and return
+ an errorcode of CL_INVALID_OPERATION. Setting <host_ptr>->ion_hostptr to
+ NULL avoids the need for the application to make an extra map call for
+ acquiring the host virtual pointer.
+
+ Memory specified this way must be aligned to the device's page size. The
+ application can query the device's page size by using
+ clGetDeviceInfo(..., CL_DEVICE_PAGE_SIZE_QCOM, ...).
+
+ Once the memory object is created, the application must call
+ clEnqueueMapBuffer/clEnqueueMapImage with appropriate flags before
+ reading or writing to it on the host. The host unmaps the region when
+ accesses (reads and/or writes) to this mapped region by the host are
+ complete. As per the OpenCL 1.2 specification, clEnqueueMapBuffer and
+ clEnqueueMapImage act as synchronization points for the region of the
+ buffer object being mapped.
Sample Code
- /* Using the extension for CL buffer objects */
+ 1) Using the extension for CL buffer objects
- cl_mem buffer_object = NULL;
- size_t buffer_size_in_bytes = 0;
- size_t buffer_size_with_padding = 0;
- cl_mem_ion_host_ptr myionmem = {0};
- size_t ext_mem_padding_in_bytes = 0;
- size_t device_page_size = 0;
-
- // Query the device's page size and the amount of padding necessary at the end of the buffer.
- clGetDeviceInfo(device, CL_DEVICE_PAGE_SIZE_QCOM, sizeof(device_page_size), &device_page_size, NULL);
- clGetDeviceInfo(device, CL_DEVICE_EXT_MEM_PADDING_IN_BYTES_QCOM, sizeof(ext_mem_padding_in_bytes), &ext_mem_padding_in_bytes, NULL);
-
- // Compute the desired size for the data in the buffer.
- buffer_size_in_bytes = foobar();
-
- // Compute amount of memory that needs to be allocated for the buffer including padding.
- buffer_size_with_padding = buffer_size_in_bytes + ext_mem_padding_in_bytes;
-
- // Make an ION memory allocation of size "buffer_size_with_padding" here.
- // Notice that allocating "buffer_size_in_bytes" instead would be a mistake! It's important to allocate the extra padding.
- // Let's say the parameters of the allocation are stored in a struct named "ion_info" that we will use below.
- // ...
+ cl_mem buffer_object = NULL;
+ size_t buffer_size_in_bytes = 0;
+ size_t buffer_size_with_padding = 0;
+ cl_mem_ion_host_ptr myionmem = {0};
+ size_t ext_mem_padding_in_bytes = 0;
+ size_t device_page_size = 0;
- // Create an OpenCL buffer object that uses "ion_info" as its data store. Notice how the buffer is created with size "buffer_size_in_bytes", not "buffer_size_with_padding".
- myionmem.ext_host_ptr.allocation_type = CL_MEM_ION_HOST_PTR_QCOM;
- myionmem.ext_host_ptr.host_cache_policy = CL_MEM_HOST_UNCACHED_QCOM;
- myionmem.ion_filedesc = ion_info_fd.file_descriptor; // the file descriptor for ION
- myionmem.ion_hostptr = ion_info.host_virtual_address; // the hostptr returned by ION which is device page size aligned
-
- if(myionmem.ion_hostptr % device_page_size)
- {
- error("Host pointer must be aligned to device_page_size!");
- }
-
- buffer_object = clCreateBuffer(context, CL_MEM_USE_HOST_PTR | CL_MEM_EXT_HOST_PTR_QCOM, buffer_size_in_bytes, &myionmem, &errcode);
+ // Query the device's page size and the amount of padding necessary at
+ // the end of the buffer.
+ clGetDeviceInfo(device, CL_DEVICE_PAGE_SIZE_QCOM,
+ sizeof(device_page_size), &device_page_size, NULL);
+ clGetDeviceInfo(device, CL_DEVICE_EXT_MEM_PADDING_IN_BYTES_QCOM,
+ sizeof(ext_mem_padding_in_bytes), &ext_mem_padding_in_bytes, NULL);
+ // Compute the desired size for the data in the buffer.
+ buffer_size_in_bytes = foobar();
- /* Using the extension for CL image objects */
+ // Compute amount of memory that needs to be allocated for the buffer
+ // including padding.
+ buffer_size_with_padding = buffer_size_in_bytes +
+ ext_mem_padding_in_bytes;
- cl_mem image_object = NULL;
- cl_mem_ion_host_ptr myionmem = {0};
- size_t ext_mem_padding_in_bytes = 0;
- size_t device_page_size = 0;
- size_t row_pitch = 0;
-
- // Query the device's page size and the amount of padding necessary at the end of the buffer.
- clGetDeviceInfo(device, CL_DEVICE_PAGE_SIZE_QCOM, sizeof(device_page_size), &device_page_size, NULL);
- clGetDeviceInfo(device, CL_DEVICE_EXT_MEM_PADDING_IN_BYTES_QCOM, sizeof(ext_mem_padding_in_bytes), &ext_mem_padding_in_bytes, NULL);
+ // Make an ION memory allocation of size buffer_size_with_padding here.
+ // Note that allocating buffer_size_in_bytes instead would be a mistake.
+ // It's important to allocate the extra padding. Let's say the
+ // parameters of the allocation are stored in a struct named ion_info
+ // that we will use below.
- // Query the device supported row and slice pitch using clGetDeviceImageInfoQCOM
- // imgw - image width
- // imgh - image height
- // img_fmt - image format
- clGetDeviceImageInfoQCOM(device, imgw, imgh, &img_fmt, CL_IMAGE_ROW_PITCH, sizeof(image_row_pitch), &image_row_pitch, NULL);
+ // Create an OpenCL buffer object that uses ion_info as its data store.
+ // Notice how the buffer is created with size buffer_size_in_bytes, not
+ // buffer_size_with_padding.
+ myionmem.ext_host_ptr.allocation_type = CL_MEM_ION_HOST_PTR_QCOM;
+ myionmem.ext_host_ptr.host_cache_policy = CL_MEM_HOST_UNCACHED_QCOM;
+ // file descriptor for ION
+ myionmem.ion_filedesc = ion_info_fd.file_descriptor;
+ // hostptr returned by ION which is device page size aligned
+ myionmem.ion_hostptr = ion_info.host_virtual_address;
- // Use the image height, row pitch obtained above and element size to compute the size of the buffer
- buffer_size_in_bytes = imgh * image_row_pitch;
+ if(myionmem.ion_hostptr % device_page_size)
+ {
+ error("Host pointer must be aligned to device_page_size!");
+ }
- // Compute amount of memory that needs to be allocated for the buffer including padding.
- buffer_size_with_padding = buffer_size_in_bytes + ext_mem_padding_in_bytes;
-
- // Make an ION memory allocation of size "buffer_size_with_padding" here.
- // Notice that allocating "buffer_size_in_bytes" instead would be a mistake! It's important to allocate the extra padding.
- // Let's say the parameters of the allocation are stored in a struct named "ion_info" that we will use below.
- // ...
+ buffer_object = clCreateBuffer(context,
+ CL_MEM_USE_HOST_PTR | CL_MEM_EXT_HOST_PTR_QCOM,
+ buffer_size_in_bytes, &myionmem, &errcode);
- // Create an OpenCL image object that uses "ion_info" as its data store.
- myionmem.ext_host_ptr.allocation_type = CL_MEM_ION_HOST_PTR_QCOM;
- myionmem.ext_host_ptr.host_cache_policy = CL_MEM_HOST_UNCACHED_QCOM;
- myionmem.ion_filedesc = ion_info_fd.file_descriptor; // the file descriptor for ION
- myionmem.ion_hostptr = ion_info.host_virtual_address; // the hostptr returned by ION which is device page size aligned
-
- if(myionmem.ion_hostptr % device_page_size)
- {
- error("Host pointer must be aligned to device_page_size!");
- }
-
- // Note that the image_row_pitch obtained by calling clGetDeviceImageInfoQCOM should be passed to clCreateImage2D
- image_object = clCreateImage2D(context, CL_MEM_USE_HOST_PTR|CL_MEM_EXT_HOST_PTR_QCOM, &image_fmt, imgw, imgh, image_row_pitch, &myionmem, &errcode);
+ 2) Using the extension for CL image objects
- // Call clEnqueueMapImage before filling input image data
- pinput = clEnqueueMapImage(command_queue, image_object, CL_TRUE, CL_MAP_WRITE, origin, region, &row_pitch, NULL,
- 0, NULL, NULL, &errcode);
+ cl_mem image_object = NULL;
+ cl_mem_ion_host_ptr myionmem = {0};
+ size_t ext_mem_padding_in_bytes = 0;
+ size_t device_page_size = 0;
+ size_t row_pitch = 0;
- // Fill the input image data using the hostptr and row_pitch returned by clEnqueueMapImage
- cl_uchar* inp = pinput;
- memset(inp, 0x0, (row_pitch * imgh));
- for(i = 0; i < (row_pitch * imgh); i+=row_pitch)
- {
- memset(inp+i, 0xff, imgw * element_size);
- }
+ // Query the device's page size and the amount of padding necessary at
+ // the end of the buffer.
+ clGetDeviceInfo(device, CL_DEVICE_PAGE_SIZE_QCOM,
+ sizeof(device_page_size), &device_page_size, NULL);
+ clGetDeviceInfo(device, CL_DEVICE_EXT_MEM_PADDING_IN_BYTES_QCOM,
+ sizeof(ext_mem_padding_in_bytes), &ext_mem_padding_in_bytes, NULL);
- errcode = clEnqueueUnmapMemObject(command_queue, image_object, pinput, 0, NULL, NULL);
+ // Query the device supported row and slice pitch using
+ // clGetDeviceImageInfoQCOM
+ // imgw - image width
+ // imgh - image height
+ // img_fmt - image format
+ clGetDeviceImageInfoQCOM(device, imgw, imgh, &img_fmt,
+ CL_IMAGE_ROW_PITCH, sizeof(image_row_pitch), &image_row_pitch,
+ NULL);
+ // Use the image height, row pitch obtained above and element size to
+ // compute the size of the buffer
+ buffer_size_in_bytes = imgh * image_row_pitch;
+
+ // Compute amount of memory that needs to be allocated for the buffer
+ // including padding.
+ buffer_size_with_padding = buffer_size_in_bytes +
+ ext_mem_padding_in_bytes;
+
+ // Make an ION memory allocation of size buffer_size_with_padding here.
+ // Note that allocating buffer_size_in_bytes instead would be a mistake.
+ // It's important to allocate the extra padding. Let's say the
+ // parameters of the allocation are stored in a struct named ion_info
+ // that we will use below.
+
+ // Create an OpenCL image object that uses ion_info as its data store.
+ myionmem.ext_host_ptr.allocation_type = CL_MEM_ION_HOST_PTR_QCOM;
+ myionmem.ext_host_ptr.host_cache_policy = CL_MEM_HOST_UNCACHED_QCOM;
+ // file descriptor for ION
+ myionmem.ion_filedesc = ion_info_fd.file_descriptor;
+ // hostptr returned by ION which is device page size aligned
+ myionmem.ion_hostptr = ion_info.host_virtual_address;
+
+ if(myionmem.ion_hostptr % device_page_size)
+ {
+ error("Host pointer must be aligned to device_page_size!");
+ }
+
+ // Note that the image_row_pitch obtained by calling
+ // clGetDeviceImageInfoQCOM should be passed to clCreateImage2D
+ image_object = clCreateImage2D(context,
+ CL_MEM_USE_HOST_PTR | CL_MEM_EXT_HOST_PTR_QCOM, &image_fmt, imgw,
+ imgh, image_row_pitch, &myionmem, &errcode);
+
+ // Call clEnqueueMapImage before filling input image data
+ pinput = clEnqueueMapImage(command_queue, image_object, CL_TRUE,
+ CL_MAP_WRITE, origin, region, &row_pitch, NULL, 0, NULL, NULL,
+ &errcode);
+
+ // Fill the input image data using the hostptr and row_pitch returned by
+ // clEnqueueMapImage
+ cl_uchar* inp = pinput;
+ memset(inp, 0x0, (row_pitch * imgh));
+ for(i = 0; i < (row_pitch * imgh); i+=row_pitch)
+ {
+ memset(inp+i, 0xff, imgw * element_size);
+ }
+
+ errcode = clEnqueueUnmapMemObject(command_queue, image_object, pinput,
+ 0, NULL, NULL);
Revision History
- Revision 3, 2013/05/17: Generalized. Cleaned-up for Khronos. Added final token values.
- Revision 2, 2012/11/01: Improved sample code.
Revision 1, 2012/10/18: Initial version.
+ Revision 2, 2012/11/01: Improved sample code.
+ Revision 3, 2013/05/17: Generalized. Cleaned-up for Khronos. Added final
+ token values.
+ Revision 4, 2017/06/16: Clean up. No functional changes.
+ Revision 5, 2017/11/13: Clean up. No functional changes.
+ Revision 6, 2018/01/03: Added reference to cl_qcom_ext_host_ptr_iocoherent.
+ Revision 7, 2018/01/19: Formatting and misc changes. No functional changes.
