Update Qualcomm extensions Update to latest versions of: - cl_qcom_android_native_buffer_host_ptr.txt - cl_qcom_ext_host_ptr.txt - cl_qcom_ion_host_ptr.txt
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_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.