| 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. |
| |
| Status |
| |
| SHIPPING |
| |
| Number |
| |
| OpenCL Extension #21 |
| |
| Dependencies |
| |
| 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. |
| |
| IP Status |
| |
| No known IP claims. |
| |
| 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); |
| |
| New Types |
| |
| typedef cl_uint cl_image_pitch_info_qcom; |
| |
| New Tokens |
| |
| Accepted by the <param_name> argument of clGetDeviceInfo |
| |
| 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: |
| |
| CL_MEM_EXT_HOST_PTR_QCOM (1 << 29) |
| |
| 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. |
| |
| |
| 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. |
| |
| 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: |
| |
| 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 |
| |
| image_width - width of the image in image elements (pixels) |
| |
| image_height - height of the image in image elements (pixels) |
| |
| image_row_pitch - scan-line pitch in bytes |
| |
| 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_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_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: |
| |
| 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. |
| |
| 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 |
| |
| |
| 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. |
| |
| 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. |
| |
| Revision History |
| |
| Revision 1, 2013/05/27: Initial version. |
