Name Strings cl_qcom_ext_host_ptr Contributors Balaji Calidas, Qualcomm Technologies, Inc. David Garcia, Qualcomm Technologies, Inc. Rajeev Rao, Qualcomm Technologies, Inc. Sushmita Susheelendra, Qualcomm Innovation Center, Inc. Contact 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. 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 layered extensions, to the device's address space and thus avoiding having to copy data back and forth between the host and the device. Header File 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); New Types typedef cl_uint cl_image_pitch_info_qcom; New Tokens Accepted by the argument of clGetDeviceInfo CL_DEVICE_EXT_MEM_PADDING_IN_BYTES_QCOM 0x40A0 CL_DEVICE_PAGE_SIZE_QCOM 0x40A1 Accepted by the argument of clCreateBuffer, clCreateImage2D and clCreateImage3D: CL_MEM_EXT_HOST_PTR_QCOM (1 << 29) Accepted by the 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 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 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 argument, then 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_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_value - is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored. param_value_size - is used to specify the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of 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 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 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 has CL_MEM_EXT_HOST_PTR_QCOM enabled and yet CL_MEM_USE_HOST_PTR is not enabled. CL_INVALID_VALUE if has CL_MEM_EXT_HOST_PTR_QCOM enabled and if and/or fail to match the requirements of section 5.3 CL_INVALID_VALUE if any of the fields in the struct pointed at by 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.