extensions/qcom/cl_qcom_ion_host_ptr.txt - external/github.com/KhronosGroup/OpenCL-Registry - Git at Google

 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.

 Status

     SHIPPING

 Number

     OpenCL Extension #22

 Dependencies

     OpenCL 1.1 is required. cl_qcom_ext_host_ptr is required. Android OS 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 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.

 IP Status

     No known IP claims.

 New Tokens

     Accepted by the <host_ptr> argument of clCreateBuffer, clCreateImage2D and clCreateImage3D:

         typedef struct _cl_mem_ion_host_ptr
         {
             // Type of external memory allocation.
             // Must be CL_MEM_ION_HOST_PTR_QCOM for ION allocations.
             cl_mem_ext_host_ptr   ext_host_ptr;

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

         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.

         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.

 Issues

 Sample Code

     /*    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.
     // ...

     // 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);


     /*    Using the extension for CL image objects   */

     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);

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

     // 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);

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

	Status

	SHIPPING

	Number

	OpenCL Extension #22

	Dependencies

	OpenCL 1.1 is required. cl_qcom_ext_host_ptr is required. Android OS 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 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.

	IP Status

	No known IP claims.

	New Tokens

	Accepted by the <host_ptr> argument of clCreateBuffer, clCreateImage2D and clCreateImage3D:

	typedef struct _cl_mem_ion_host_ptr
	{
	// Type of external memory allocation.
	// Must be CL_MEM_ION_HOST_PTR_QCOM for ION allocations.
	cl_mem_ext_host_ptr ext_host_ptr;

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

	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.

	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.

	Issues

	Sample Code

	/* 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.
	// ...

	// 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);


	/* Using the extension for CL image objects */

	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);

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

	// 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);

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