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 <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_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 <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.

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.