Memory object wrapper

The memory object wrapper module provides functionality for simple handling of generic OpenCL memory objects. More...

Data Structures
struct	ccl_memobj
	Base class for memory object wrappers, i.e., CCLBuffer and CCLImage. More...

Macros
#define	ccl_memobj_get_info(mo, param_name, err)
	Get a CCLWrapperInfo memory object information object. More...
#define	ccl_memobj_get_info(mo, param_name, err)
	Get a CCLWrapperInfo memory object information object. More...
#define	ccl_memobj_get_info_array(mo, param_name, param_type, err)
	Macro which returns an array memory object information value. More...
#define	ccl_memobj_get_info_array(mo, param_name, param_type, err)
	Macro which returns an array memory object information value. More...
#define	ccl_memobj_get_info_scalar(mo, param_name, param_type, err)
	Macro which returns a scalar memory object information value. More...
#define	ccl_memobj_get_info_scalar(mo, param_name, param_type, err)
	Macro which returns a scalar memory object information value. More...
#define	ccl_memobj_ref(mo)   ccl_wrapper_ref((CCLWrapper*) mo)
	Increase the reference count of the cl_mem wrapper object. More...
#define	ccl_memobj_ref(mo)   ccl_wrapper_ref((CCLWrapper*) mo)
	Increase the reference count of the cl_mem wrapper object. More...
#define	ccl_memobj_unwrap(mo)   ((cl_mem) ccl_wrapper_unwrap((CCLWrapper*) mo))
	Get the OpenCL cl_mem object. More...
#define	ccl_memobj_unwrap(mo)   ((cl_mem) ccl_wrapper_unwrap((CCLWrapper*) mo))
	Get the OpenCL cl_mem object. More...

Typedefs
typedef void(*	ccl_memobj_destructor_callback )(cl_mem memobj, void *user_data)
	Prototype for memory object destructor callback functions. More...
typedef void(*	ccl_memobj_destructor_callback )(cl_mem memobj, void *user_data)
	Prototype for memory object destructor callback functions. More...
typedef struct ccl_memobj	CCLMemObj
	Base class for memory object wrappers, i.e., CCLBuffer and CCLImage.

Functions
CCLEvent *	ccl_memobj_enqueue_migrate (CCLMemObj **mos, cl_uint num_mos, CCLQueue *cq, cl_mem_migration_flags flags, CCLEventWaitList *evt_wait_lst, CCLErr **err)
	Enqueues a command to indicate which device a set of memory objects should be associated with. More...
CCLEvent *	ccl_memobj_enqueue_unmap (CCLMemObj *mo, CCLQueue *cq, void *mapped_ptr, CCLEventWaitList *evt_wait_lst, CCLErr **err)
	Enqueues a command to unmap a previously mapped region of a memory object. More...
cl_uint	ccl_memobj_get_opencl_version (CCLMemObj *mo, CCLErr **err)
	Get the OpenCL version of the platform associated with this memory object. More...
cl_bool	ccl_memobj_set_destructor_callback (CCLMemObj *mo, ccl_memobj_destructor_callback pfn_notify, void *user_data, CCLErr **err)
	Wrapper for OpenCL clSetMemObjectDestructorCallback() function. More...

Detailed Description

The memory object wrapper module provides functionality for simple handling of generic OpenCL memory objects.

All the functions in this module are direct wrappers of the respective OpenCL memory object functions, with the exception of ccl_memobj_get_opencl_version(), which returns the OpenCL version of the platform associated with the memory object.

For specific buffer and image handling, see the buffer wrapper and image wrapper modules.

Information about memory objects can be fetched using the memory object info macros:

• ccl_memobj_get_info_scalar()
• ccl_memobj_get_info_array()
• ccl_memobj_get_info()

Macro Definition Documentation

#define ccl_memobj_get_info	(		mo,
			param_name,
			err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) mo, NULL, param_name, 0, \
        CCL_INFO_MEMOBJ, CL_FALSE, err)

Get a CCLWrapperInfo memory object information object.

Parameters

[in]	mo	The memory object wrapper object.
[in]	param_name	Name of information/parameter to get.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested memory object information object. This object will be automatically freed when the memory object wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 110 of file ccl_memobj_wrapper.h.

#define ccl_memobj_get_info	(		mo,
			param_name,
			err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) mo, NULL, param_name, 0, \
        CCL_INFO_MEMOBJ, CL_FALSE, err)

Get a CCLWrapperInfo memory object information object.

Parameters

[in]	mo	The memory object wrapper object.
[in]	param_name	Name of information/parameter to get.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested memory object information object. This object will be automatically freed when the memory object wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 110 of file ccl_memobj_wrapper.h.

#define ccl_memobj_get_info_array	(		mo,
			param_name,
			param_type,
			err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) mo, \
        NULL, param_name, sizeof(param_type), CCL_INFO_MEMOBJ, CL_FALSE, err)

Macro which returns an array memory object information value.

Use with care. In case an error occurs, NULL is returned, which might be ambiguous if NULL is a valid return value. In this case, it is necessary to check the error object.

Parameters

[in]	mo	The memory object wrapper object.
[in]	param_name	Name of information/parameter to get value of.
[in]	param_type	Type of parameter (e.g. char*, size_t*, etc.).
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested memory object information value. This value will be automatically freed when the memory object wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 150 of file ccl_memobj_wrapper.h.

#define ccl_memobj_get_info_array	(		mo,
			param_name,
			param_type,
			err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) mo, \
        NULL, param_name, sizeof(param_type), CCL_INFO_MEMOBJ, CL_FALSE, err)

Macro which returns an array memory object information value.

Use with care. In case an error occurs, NULL is returned, which might be ambiguous if NULL is a valid return value. In this case, it is necessary to check the error object.

Parameters

[in]	mo	The memory object wrapper object.
[in]	param_name	Name of information/parameter to get value of.
[in]	param_type	Type of parameter (e.g. char*, size_t*, etc.).
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested memory object information value. This value will be automatically freed when the memory object wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 150 of file ccl_memobj_wrapper.h.

#define ccl_memobj_get_info_scalar	(		mo,
			param_name,
			param_type,
			err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) mo, \
        NULL, param_name, sizeof(param_type), CCL_INFO_MEMOBJ, CL_FALSE, err))

Macro which returns a scalar memory object information value.

Use with care. In case an error occurs, zero is returned, which might be ambiguous if zero is a valid return value. In this case, it is necessary to check the error object.

Parameters

[in]	mo	The memory object wrapper object.
[in]	param_name	Name of information/parameter to get value of.
[in]	param_type	Type of parameter (e.g. cl_uint, size_t, etc.).
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested memory object information value. This value will be automatically freed when the memory object wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 130 of file ccl_memobj_wrapper.h.

#define ccl_memobj_get_info_scalar	(		mo,
			param_name,
			param_type,
			err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) mo, \
        NULL, param_name, sizeof(param_type), CCL_INFO_MEMOBJ, CL_FALSE, err))

Macro which returns a scalar memory object information value.

Use with care. In case an error occurs, zero is returned, which might be ambiguous if zero is a valid return value. In this case, it is necessary to check the error object.

Parameters

[in]	mo	The memory object wrapper object.
[in]	param_name	Name of information/parameter to get value of.
[in]	param_type	Type of parameter (e.g. cl_uint, size_t, etc.).
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested memory object information value. This value will be automatically freed when the memory object wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 130 of file ccl_memobj_wrapper.h.

#define ccl_memobj_ref

(

mo

)

ccl_wrapper_ref((CCLWrapper*) mo)

Increase the reference count of the cl_mem wrapper object.

Parameters

[in]

mo

The cl_mem wrapper object.

Definition at line 159 of file ccl_memobj_wrapper.h.

#define ccl_memobj_ref

(

mo

)

ccl_wrapper_ref((CCLWrapper*) mo)

Increase the reference count of the cl_mem wrapper object.

Parameters

[in]

mo

The cl_mem wrapper object.

Definition at line 159 of file ccl_memobj_wrapper.h.

#define ccl_memobj_unwrap

(

mo

)

((cl_mem) ccl_wrapper_unwrap((CCLWrapper*) mo))

Get the OpenCL cl_mem object.

Parameters

[in]

mo

The cl_mem wrapper object.

Returns

The OpenCL cl_mem object.

Definition at line 168 of file ccl_memobj_wrapper.h.

#define ccl_memobj_unwrap

(

mo

)

((cl_mem) ccl_wrapper_unwrap((CCLWrapper*) mo))

Get the OpenCL cl_mem object.

Parameters

[in]

mo

The cl_mem wrapper object.

Returns

The OpenCL cl_mem object.

Definition at line 168 of file ccl_memobj_wrapper.h.

Typedef Documentation

typedef void( * ccl_memobj_destructor_callback)(cl_mem memobj, void *user_data)

Prototype for memory object destructor callback functions.

Parameters

[in]	memobj	The OpenCL memory object for which the callback function is associated.
[in]	user_data	A pointer to user supplied data.

Definition at line 72 of file ccl_memobj_wrapper.h.

typedef void( * ccl_memobj_destructor_callback)(cl_mem memobj, void *user_data)

Prototype for memory object destructor callback functions.

Parameters

[in]	memobj	The OpenCL memory object for which the callback function is associated.
[in]	user_data	A pointer to user supplied data.

Definition at line 72 of file ccl_memobj_wrapper.h.

Function Documentation

CCLEvent * ccl_memobj_enqueue_migrate	(	CCLMemObj **	mos,
		cl_uint	num_mos,
		CCLQueue *	cq,
		cl_mem_migration_flags	flags,
		CCLEventWaitList *	evt_wait_lst,
		CCLErr **	err
	)

Enqueues a command to indicate which device a set of memory objects should be associated with.

Wrapper for OpenCL clEnqueueMigrateMemObjects() function.

Note

Requires OpenCL >= 1.2

Parameters

[in]	mos	A pointer to a list of memory object wrappers.
[in]	num_mos	The number of memory objects specified in mos.
[in]	cq	A command queue wrapper object.
[in]	flags	Migration options
[in,out]	evt_wait_lst	List of events that need to complete before this command can be executed. The list will be cleared and can be reused by client code.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

Definition at line 310 of file ccl_memobj_wrapper.c.

CCLEvent * ccl_memobj_enqueue_unmap	(	CCLMemObj *	mo,
		CCLQueue *	cq,
		void *	mapped_ptr,
		CCLEventWaitList *	evt_wait_lst,
		CCLErr **	err
	)

Enqueues a command to unmap a previously mapped region of a memory object.

This function wraps the clEnqueueUnmapMemObject() OpenCL function.

Parameters

[in]	mo	A memory object wrapper object.
[in]	cq	A command queue wrapper object.
[in]	mapped_ptr	The host address returned by a previous call to ccl_buffer_enqueue_map() or ccl_image_enqueue_map() for mo.
[in,out]	evt_wait_lst	List of events that need to complete before this command can be executed. The list will be cleared and can be reused by client code.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

Event wrapper object that identifies this command.

Definition at line 142 of file ccl_memobj_wrapper.c.

cl_uint ccl_memobj_get_opencl_version	(	CCLMemObj *	mo,
		CCLErr **	err
	)

Get the OpenCL version of the platform associated with this memory object.

The version is returned as an integer, in the following format:

• 100 for OpenCL 1.0
• 110 for OpenCL 1.1
• 120 for OpenCL 1.2
• 200 for OpenCL 2.0
• etc.

Parameters

[in]	mo	A memory object wrapper object.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The OpenCL version of the platform associated with this memory object as an integer. If an error occurs, 0 is returned.

Definition at line 79 of file ccl_memobj_wrapper.c.

cl_bool ccl_memobj_set_destructor_callback	(	CCLMemObj *	mo,
		ccl_memobj_destructor_callback	pfn_notify,
		void *	user_data,
		CCLErr **	err
	)

Wrapper for OpenCL clSetMemObjectDestructorCallback() function.

Note

Requires OpenCL >= 1.1

Parameters

[in]	mo	A memory object wrapper object.
[in]	pfn_notify	The callback function that can be registered by the application.
[in]	user_data	A pointer to user supplied data.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

CL_TRUE if device if operation completes successfully, CL_FALSE otherwise.

Definition at line 213 of file ccl_memobj_wrapper.c.