The kernel wrapper module provides functionality for simple handling of OpenCL kernel objects. More...

Collaboration diagram for Kernel wrapper:

Modules
	Kernel argument wrappers
	This module defines the CCLArg* class which wraps kernel arguments.

Macros
#define	ccl_kernel_get_arg_info_array(krnl, idx, param_name, param_type, err)
	Macro which returns an array kernel argument information value. More...

#define	ccl_kernel_get_arg_info_array(krnl, idx, param_name, param_type, err)
	Macro which returns an array kernel argument information value. More...

#define	ccl_kernel_get_arg_info_scalar(krnl, idx, param_name, param_type, err)
	Macro which returns a scalar kernel argument information value. More...

#define	ccl_kernel_get_arg_info_scalar(krnl, idx, param_name, param_type, err)
	Macro which returns a scalar kernel argument information value. More...

#define	ccl_kernel_get_info(krnl, param_name, err)
	Get a CCLWrapperInfo kernel information object. More...

#define	ccl_kernel_get_info(krnl, param_name, err)
	Get a CCLWrapperInfo kernel information object. More...

#define	ccl_kernel_get_info_array(krnl, param_name, param_type, err)
	Macro which returns an array kernel information value. More...

#define	ccl_kernel_get_info_array(krnl, param_name, param_type, err)
	Macro which returns an array kernel information value. More...

#define	ccl_kernel_get_info_scalar(krnl, param_name, param_type, err)
	Macro which returns a scalar kernel information value. More...

#define	ccl_kernel_get_info_scalar(krnl, param_name, param_type, err)
	Macro which returns a scalar kernel information value. More...

#define	ccl_kernel_get_workgroup_info(krnl, dev, param_name, err)
	Get a CCLWrapperInfo kernel workgroup information object. More...

#define	ccl_kernel_get_workgroup_info(krnl, dev, param_name, err)
	Get a CCLWrapperInfo kernel workgroup information object. More...

#define	ccl_kernel_get_workgroup_info_array(krnl, dev, param_name, param_type, err)
	Macro which returns an array kernel workgroup information value. More...

#define	ccl_kernel_get_workgroup_info_array(krnl, dev, param_name, param_type, err)
	Macro which returns an array kernel workgroup information value. More...

#define	ccl_kernel_get_workgroup_info_scalar(krnl, dev, param_name, param_type, err)
	Macro which returns a scalar kernel workgroup information value. More...

#define	ccl_kernel_get_workgroup_info_scalar(krnl, dev, param_name, param_type, err)
	Macro which returns a scalar kernel workgroup information value. More...

#define	ccl_kernel_ref(krnl) ccl_wrapper_ref((CCLWrapper*) (krnl))
	Increase the reference count of the kernel object. More...

#define	ccl_kernel_ref(krnl) ccl_wrapper_ref((CCLWrapper*) (krnl))
	Increase the reference count of the kernel object. More...

#define	ccl_kernel_unref(krnl) ccl_kernel_destroy(krnl)
	Alias to ccl_kernel_destroy(). More...

#define	ccl_kernel_unref(krnl) ccl_kernel_destroy(krnl)
	Alias to ccl_kernel_destroy(). More...

#define	ccl_kernel_unwrap(krnl) ((cl_kernel) ccl_wrapper_unwrap((CCLWrapper*) (krnl)))
	Get the OpenCL kernel object. More...

#define	ccl_kernel_unwrap(krnl) ((cl_kernel) ccl_wrapper_unwrap((CCLWrapper*) (krnl)))
	Get the OpenCL kernel object. More...

Typedefs
typedef struct ccl_kernel	CCLKernel
	Kernel wrapper class.

Functions
void	ccl_kernel_destroy (CCLKernel *krnl)
	Decrements the reference count of the kernel wrapper object. More...

CCLEvent *	ccl_kernel_enqueue_native (CCLQueue cq, void(user_func)(void ), void args, size_t cb_args, cl_uint num_mos, CCLMemObj const mo_list, const void *args_mem_loc, CCLEventWaitList evt_wait_lst, CCLErr **err)
	Enqueues a command to execute a native C/C++ function not compiled using the OpenCL compiler. More...

CCLEvent *	ccl_kernel_enqueue_ndrange (CCLKernel krnl, CCLQueue cq, cl_uint work_dim, const size_t global_work_offset, const size_t global_work_size, const size_t local_work_size, CCLEventWaitList evt_wait_lst, CCLErr **err)
	Enqueues a kernel for execution on a device. More...

CCLWrapperInfo *	ccl_kernel_get_arg_info (CCLKernel krnl, cl_uint idx, cl_kernel_arg_info param_name, CCLErr *err)
	Get a CCLWrapperInfo kernel argument information object. More...

cl_uint	ccl_kernel_get_opencl_version (CCLKernel krnl, CCLErr *err)
	Get the OpenCL version of the platform associated with this kernel. More...

CCLKernel *	ccl_kernel_new (CCLProgram prg, const char kernel_name, CCLErr **err)
	Create a new kernel wrapper object. More...

CCLKernel *	ccl_kernel_new_wrap (cl_kernel kernel)
	Get the kernel wrapper for the given OpenCL kernel. More...

void	ccl_kernel_set_arg (CCLKernel krnl, cl_uint arg_index, void arg)
	Set one kernel argument. More...

void	ccl_kernel_set_args (CCLKernel *krnl,...)
	Set all kernel arguments. More...

CCLEvent *	ccl_kernel_set_args_and_enqueue_ndrange (CCLKernel krnl, CCLQueue cq, cl_uint work_dim, const size_t global_work_offset, const size_t global_work_size, const size_t local_work_size, CCLEventWaitList evt_wait_lst, CCLErr **err,...)
	Set kernel arguments and enqueue it for execution on a device. More...

CCLEvent *	ccl_kernel_set_args_and_enqueue_ndrange_v (CCLKernel krnl, CCLQueue cq, cl_uint work_dim, const size_t global_work_offset, const size_t global_work_size, const size_t local_work_size, CCLEventWaitList evt_wait_lst, void args, CCLErr err)
	Set kernel arguments and enqueue it for execution on a device. More...

void	ccl_kernel_set_args_v (CCLKernel krnl, void *args)
	Set all kernel arguments. More...

cl_bool	ccl_kernel_suggest_worksizes (CCLKernel krnl, CCLDevice dev, cl_uint dims, const size_t real_worksize, size_t gws, size_t lws, CCLErr *err)
	Suggest appropriate local (and optionally global) work sizes for the given real work size, based on device and kernel characteristics. More...

Detailed Description

The kernel wrapper module provides functionality for simple handling of OpenCL kernel objects.

Kernel wrappers can be obtained using two approaches:

Using the ccl_program_get_kernel() function. This function always returns the same kernel wrapper object (with the same underlying OpenCL kernel object) associated with a program. The returned object is automatically freed when the program wrapper object is destroyed; as such, client code should not call ccl_kernel_destroy().
Using the ccl_kernel_new() constructor. The created kernel wrapper should be released with the ccl_kernel_destroy() function, in accordance with the cf4ocl new/destroy rule.

While the first approach might be more convenient, it will not work properly if the same kernel function is to be handled and executed by different threads. In these cases, use the second approach to create distinct kernel wrapper instances (wrapping distinct OpenCL kernel objects) for the same kernel function, one for each thread.

This module offers several functions which simplify kernel execution. For example, the ccl_kernel_set_args_and_enqueue_ndrange() function can set all kernel arguments and execute the kernel in one call.

Information about kernel objects can be fetched using the kernel info macros:

Six additional macros are provided for getting kernel workgroup info and kernel argument info (the later are only available from OpenCL 1.2 onwards). These work in the same way as the regular info macros:

Example: getting a kernel wrapper from a program wrapper

CCLProgram* prg;

CCLKernel* krnl;

krnl = ccl_program_get_kernel(prg, "some_kernel", NULL);

Example: creating a kernel wrapper

CCLProgram* prg;

CCLKernel* krnl;

krnl = ccl_kernel_new(prg, "some_kernel", NULL);

ccl_kernel_destroy(krnl);

Macro Definition Documentation

#define ccl_kernel_get_arg_info_array	(	krnl,
		idx,
		param_name,
		param_type,
		err
	)

Value:

(ccl_kernel_get_arg_info((krnl), (idx), (param_name), (err)) != NULL) \
    ? *((param_type*) ccl_kernel_get_arg_info( \
        (krnl), (idx), (param_name), (err))) \
    : NULL

Macro which returns an array kernel argument 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]	krnl	The kernel wrapper object.
[in]	idx	Argument index.
[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 kernel argument information value. This value will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 355 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_arg_info_array	(	krnl,
		idx,
		param_name,
		param_type,
		err
	)

Value:

(ccl_kernel_get_arg_info((krnl), (idx), (param_name), (err)) != NULL) \
    ? *((param_type*) ccl_kernel_get_arg_info( \
        (krnl), (idx), (param_name), (err))) \
    : NULL

Macro which returns an array kernel argument 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]	krnl	The kernel wrapper object.
[in]	idx	Argument index.
[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 kernel argument information value. This value will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 355 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_arg_info_scalar	(	krnl,
		idx,
		param_name,
		param_type,
		err
	)

Value:

(param_type) \
    ((ccl_kernel_get_arg_info((krnl), (idx), (param_name), (err)) != NULL) \
    ? **((param_type**) ccl_kernel_get_arg_info( \
        (krnl), (idx), (param_name), (err))) \
    : 0)

Macro which returns a scalar kernel argument 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]	krnl	The kernel wrapper object.
[in]	idx	Argument index.
[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 kernel argument information value. This value will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 329 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_arg_info_scalar	(	krnl,
		idx,
		param_name,
		param_type,
		err
	)

Value:

(param_type) \
    ((ccl_kernel_get_arg_info((krnl), (idx), (param_name), (err)) != NULL) \
    ? **((param_type**) ccl_kernel_get_arg_info( \
        (krnl), (idx), (param_name), (err))) \
    : 0)

Macro which returns a scalar kernel argument 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]	krnl	The kernel wrapper object.
[in]	idx	Argument index.
[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 kernel argument information value. This value will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 329 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_info	(	krnl,
		param_name,
		err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) (krnl), NULL, (param_name), 0, \

CCL_INFO_KERNEL, CL_FALSE, (err))

ccl_wrapper::ccl_wrapper_get_info

CCLWrapperInfo * ccl_wrapper_get_info(CCLWrapper *wrapper1, CCLWrapper *wrapper2, cl_uint param_name, size_t min_size, CCLInfo info_type, cl_bool use_cache, CCLErr **err)

Get information about any wrapped OpenCL object.

Definition: ccl_abstract_wrapper.c:463

ccl_wrapper

Base class for all OpenCL wrappers.

Definition: _ccl_abstract_wrapper.h:47

CCL_INFO_KERNEL

Request information about kernel objects.

Definition: ccl_common.h:137

Get a CCLWrapperInfo kernel information object.

Parameters

[in]	krnl	The kernel 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 kernel information object. This object will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 196 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_info	(	krnl,
		param_name,
		err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) (krnl), NULL, (param_name), 0, \

CCL_INFO_KERNEL, CL_FALSE, (err))

ccl_wrapper::ccl_wrapper_get_info

CCLWrapperInfo * ccl_wrapper_get_info(CCLWrapper *wrapper1, CCLWrapper *wrapper2, cl_uint param_name, size_t min_size, CCLInfo info_type, cl_bool use_cache, CCLErr **err)

Get information about any wrapped OpenCL object.

Definition: ccl_abstract_wrapper.c:463

ccl_wrapper

Base class for all OpenCL wrappers.

Definition: _ccl_abstract_wrapper.h:47

CCL_INFO_KERNEL

Request information about kernel objects.

Definition: ccl_common.h:137

Get a CCLWrapperInfo kernel information object.

Parameters

[in]	krnl	The kernel 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 kernel information object. This object will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 196 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_info_array	(	krnl,
		param_name,
		param_type,
		err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) (krnl), \
        NULL, (param_name), sizeof(param_type), \
        CCL_INFO_KERNEL, CL_FALSE, (err))

Macro which returns an array kernel 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]	krnl	The kernel 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 kernel information value. This value will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 237 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_info_array	(	krnl,
		param_name,
		param_type,
		err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) (krnl), \
        NULL, (param_name), sizeof(param_type), \
        CCL_INFO_KERNEL, CL_FALSE, (err))

Macro which returns an array kernel 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]	krnl	The kernel 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 kernel information value. This value will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 237 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_info_scalar	(	krnl,
		param_name,
		param_type,
		err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) (krnl), \
        NULL, (param_name), sizeof(param_type), \
        CCL_INFO_KERNEL, CL_FALSE, (err)))

Macro which returns a scalar kernel 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]	krnl	The kernel 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 kernel information value. This value will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 216 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_info_scalar	(	krnl,
		param_name,
		param_type,
		err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) (krnl), \
        NULL, (param_name), sizeof(param_type), \
        CCL_INFO_KERNEL, CL_FALSE, (err)))

Macro which returns a scalar kernel 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]	krnl	The kernel 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 kernel information value. This value will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 216 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_workgroup_info	(	krnl,
		dev,
		param_name,
		err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) (krnl), (CCLWrapper*) (dev), \

(param_name), 0, CCL_INFO_KERNEL_WORKGROUP, CL_FALSE, (err))

ccl_wrapper::ccl_wrapper_get_info

CCLWrapperInfo * ccl_wrapper_get_info(CCLWrapper *wrapper1, CCLWrapper *wrapper2, cl_uint param_name, size_t min_size, CCLInfo info_type, cl_bool use_cache, CCLErr **err)

Get information about any wrapped OpenCL object.

Definition: ccl_abstract_wrapper.c:463

ccl_wrapper

Base class for all OpenCL wrappers.

Definition: _ccl_abstract_wrapper.h:47

CCL_INFO_KERNEL_WORKGROUP

Request information about kernel work-groups.

Definition: ccl_common.h:141

Get a CCLWrapperInfo kernel workgroup information object.

Parameters

[in]	krnl	The kernel wrapper object.
[in]	dev	The device 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 kernel workgroup information object. This object will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 254 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_workgroup_info	(	krnl,
		dev,
		param_name,
		err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) (krnl), (CCLWrapper*) (dev), \

(param_name), 0, CCL_INFO_KERNEL_WORKGROUP, CL_FALSE, (err))

ccl_wrapper::ccl_wrapper_get_info

CCLWrapperInfo * ccl_wrapper_get_info(CCLWrapper *wrapper1, CCLWrapper *wrapper2, cl_uint param_name, size_t min_size, CCLInfo info_type, cl_bool use_cache, CCLErr **err)

Get information about any wrapped OpenCL object.

Definition: ccl_abstract_wrapper.c:463

ccl_wrapper

Base class for all OpenCL wrappers.

Definition: _ccl_abstract_wrapper.h:47

CCL_INFO_KERNEL_WORKGROUP

Request information about kernel work-groups.

Definition: ccl_common.h:141

Get a CCLWrapperInfo kernel workgroup information object.

Parameters

[in]	krnl	The kernel wrapper object.
[in]	dev	The device 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 kernel workgroup information object. This object will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 254 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_workgroup_info_array	(	krnl,
		dev,
		param_name,
		param_type,
		err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) (krnl), \
        (CCLWrapper*) (dev), (param_name), sizeof(param_type), \
        CCL_INFO_KERNEL_WORKGROUP, CL_FALSE, (err))

Macro which returns an array kernel workgroup 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]	krnl	The kernel wrapper object.
[in]	dev	The device 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 kernel workgroup information value. This value will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 300 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_workgroup_info_array	(	krnl,
		dev,
		param_name,
		param_type,
		err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) (krnl), \
        (CCLWrapper*) (dev), (param_name), sizeof(param_type), \
        CCL_INFO_KERNEL_WORKGROUP, CL_FALSE, (err))

Macro which returns an array kernel workgroup 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]	krnl	The kernel wrapper object.
[in]	dev	The device 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 kernel workgroup information value. This value will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 300 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_workgroup_info_scalar	(	krnl,
		dev,
		param_name,
		param_type,
		err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) (krnl), \
        (CCLWrapper*) (dev), (param_name), sizeof(param_type), \
        CCL_INFO_KERNEL_WORKGROUP, CL_FALSE, (err)))

Macro which returns a scalar kernel workgroup 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]	krnl	The kernel wrapper object.
[in]	dev	The device 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 kernel workgroup information value. This value will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 276 of file ccl_kernel_wrapper.h.

#define ccl_kernel_get_workgroup_info_scalar	(	krnl,
		dev,
		param_name,
		param_type,
		err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) (krnl), \
        (CCLWrapper*) (dev), (param_name), sizeof(param_type), \
        CCL_INFO_KERNEL_WORKGROUP, CL_FALSE, (err)))

Macro which returns a scalar kernel workgroup 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]	krnl	The kernel wrapper object.
[in]	dev	The device 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 kernel workgroup information value. This value will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 276 of file ccl_kernel_wrapper.h.

#define ccl_kernel_ref ( krnl ) ccl_wrapper_ref((CCLWrapper*) (krnl))

Increase the reference count of the kernel object.

Parameters

[in] krnl The kernel wrapper object.

Definition at line 367 of file ccl_kernel_wrapper.h.

#define ccl_kernel_ref ( krnl ) ccl_wrapper_ref((CCLWrapper*) (krnl))

Increase the reference count of the kernel object.

Parameters

[in] krnl The kernel wrapper object.

Definition at line 367 of file ccl_kernel_wrapper.h.

#define ccl_kernel_unref ( krnl ) ccl_kernel_destroy(krnl)

Alias to ccl_kernel_destroy().

Parameters

[in] krnl Kernel wrapper object to destroy if reference count is 1, otherwise just decrement the reference count.

Definition at line 376 of file ccl_kernel_wrapper.h.

#define ccl_kernel_unref ( krnl ) ccl_kernel_destroy(krnl)

Alias to ccl_kernel_destroy().

Parameters

[in] krnl Kernel wrapper object to destroy if reference count is 1, otherwise just decrement the reference count.

Definition at line 376 of file ccl_kernel_wrapper.h.

#define ccl_kernel_unwrap ( krnl ) ((cl_kernel) ccl_wrapper_unwrap((CCLWrapper*) (krnl)))

Get the OpenCL kernel object.

Parameters

[in] krnl The kernel wrapper object.

Returns: The OpenCL kernel object.

Definition at line 384 of file ccl_kernel_wrapper.h.

#define ccl_kernel_unwrap ( krnl ) ((cl_kernel) ccl_wrapper_unwrap((CCLWrapper*) (krnl)))

Get the OpenCL kernel object.

Parameters

[in] krnl The kernel wrapper object.

Returns: The OpenCL kernel object.

Definition at line 384 of file ccl_kernel_wrapper.h.

Function Documentation

void ccl_kernel_destroy ( CCLKernel * krnl )

Decrements the reference count of the kernel wrapper object.

If it reaches 0, the kernel wrapper object is destroyed.

Parameters

[in] krnl The kernel wrapper object.

Definition at line 177 of file ccl_kernel_wrapper.c.

CCLEvent * ccl_kernel_enqueue_native	(	CCLQueue *	cq,
		void()(void )	user_func,
		void *	args,
		size_t	cb_args,
		cl_uint	num_mos,
		CCLMemObj const	mo_list,
		const void **	args_mem_loc,
		CCLEventWaitList *	evt_wait_lst,
		CCLErr **	err
	)

Enqueues a command to execute a native C/C++ function not compiled using the OpenCL compiler.

This function is a wrapper for the clEnqueueNativeKernel() OpenCL function, the documentation of which provides additional information.

Parameters

[in]	cq	A command queue wrapper object.
[in]	user_func	A pointer to a host-callable user function.
[in]	args	A pointer to the args list that `user_func` should be called with.
[in]	cb_args	The size in bytes of the args list that args points to.
[in]	num_mos	The number of CCLMemObj* objects that are passed in `mo_list`.
[in]	mo_list	A list of CCLMemObj* objects (or `NULL` references), if num_mos > 0.
[in]	args_mem_loc	A pointer to appropriate locations that `args` points to where `cl_mem` values (unwrapped from the respective CCLMemObj* objects) are stored. Before the user function is executed, the `cl_mem` values are replaced by pointers to global memory.
[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 706 of file ccl_kernel_wrapper.c.

CCLEvent * ccl_kernel_enqueue_ndrange	(	CCLKernel *	krnl,
		CCLQueue *	cq,
		cl_uint	work_dim,
		const size_t *	global_work_offset,
		const size_t *	global_work_size,
		const size_t *	local_work_size,
		CCLEventWaitList *	evt_wait_lst,
		CCLErr **	err
	)

Enqueues a kernel for execution on a device.

Internally, this function calls the clSetKernelArg() OpenCL function for each argument defined with the ccl_kernel_set_arg() function, and the executes the kernel using the clEnqueueNDRangeKernel() OpenCL function.

Warning: This function is not thread-safe. For multi-threaded access to the same kernel function, create multiple instances of a kernel wrapper for the given kernel function with ccl_kernel_new(), one for each thread.

Parameters

[in]	krnl	A kernel wrapper object.
[in]	cq	A command queue wrapper object.
[in]	work_dim	The number of dimensions used to specify the global work-items and work-items in the work-group.
[in]	global_work_offset	Can be used to specify an array of `work_dim` unsigned values that describe the offset used to calculate the global ID of a work-item.
[in]	global_work_size	An array of `work_dim` unsigned values that describe the number of global work-items in `work_dim` dimensions that will execute the kernel function.
[in]	local_work_size	An array of `work_dim` unsigned values that describe the number of work-items that make up a work-group that will execute the specified kernel.
[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 393 of file ccl_kernel_wrapper.c.

CCLWrapperInfo * ccl_kernel_get_arg_info	(	CCLKernel *	krnl,
		cl_uint	idx,
		cl_kernel_arg_info	param_name,
		CCLErr **	err
	)

Get a CCLWrapperInfo kernel argument information object.

See also: ccl_wrapper_get_info()

Note: Requires OpenCL >= 1.2

Parameters

[in]	krnl	The kernel wrapper object.
[in]	idx	Argument index.
[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 kernel argument information object. This object will be automatically freed when the kernel wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 1178 of file ccl_kernel_wrapper.c.

cl_uint ccl_kernel_get_opencl_version	(	CCLKernel *	krnl,
		CCLErr **	err
	)

Get the OpenCL version of the platform associated with this kernel.

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]	krnl	A kernel 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 kernel as an integer. If an error occurs, 0 is returned.

Definition at line 799 of file ccl_kernel_wrapper.c.

CCLKernel * ccl_kernel_new	(	CCLProgram *	prg,
		const char *	kernel_name,
		CCLErr **	err
	)

Create a new kernel wrapper object.

Parameters

[in]	prg	A program wrapper object.
[in]	kernel_name	The kernel name.
[out]	err	Return location for a CCLErr object, or `NULL` if error reporting is to be ignored.

Returns: A new kernel wrapper object.

Definition at line 118 of file ccl_kernel_wrapper.c.

CCLKernel * ccl_kernel_new_wrap ( cl_kernel kernel )

Get the kernel wrapper for the given OpenCL kernel.

If the wrapper doesn't exist, its created with a reference count of 1. Otherwise, the existing wrapper is returned and its reference count is incremented by 1.

This function will rarely be called from client code, except when clients wish to create the OpenCL kernel directly (using the clCreateKernel() function) and then wrap the OpenCL kernel in a CCLKernel wrapper object.

Parameters

[in] kernel The OpenCL kernel to be wrapped.

Returns: The CCLKernel wrapper for the given OpenCL kernel.

Definition at line 99 of file ccl_kernel_wrapper.c.

void ccl_kernel_set_arg	(	CCLKernel *	krnl,
		cl_uint	arg_index,
		void *	arg
	)

Set one kernel argument.

The argument is not immediatly set with the clSetKernelArg() OpenCL function, but is instead kept in an argument table for this kernel. The clSetKernelArg() function is called only before kernel execution for arguments which have not yet been set or have not been updated meanwhile.

Warning: This function is not thread-safe. For multi-threaded access to the same kernel function, create multiple instances of a kernel wrapper for the given kernel function with ccl_kernel_new(), one for each thread.

Parameters

[in]	krnl	A kernel wrapper object.
[in]	arg_index	Argument index.
[in]	arg	Argument to set. Arguments must be of type CCLArg, CCLBuffer, CCLImage* or CCLSampler*.

Definition at line 205 of file ccl_kernel_wrapper.c.

void ccl_kernel_set_args	(	CCLKernel *	krnl,
			...
	)

Set all kernel arguments.

This function accepts a variable list of arguments which must end with NULL. Internally, this method sets each argument individually using the ccl_kernel_set_arg() function.

If the ccl_arg_skip constant is passed in place of a specific argument, that argument will not be set by this function call. Any previously set argument continues to be valid.

The ccl_kernel_set_args_v() function performs the same operation but accepts an array of kernel arguments instead.

Attention: The variable argument list must end with NULL.

Warning: This function is not thread-safe. For multi-threaded access to the same kernel function, create multiple instances of a kernel wrapper for the given kernel function with ccl_kernel_new(), one for each thread.

Parameters

[in]	krnl	A kernel wrapper object.
[in]	...	A `NULL`-terminated list of arguments to set. Arguments must be of type CCLArg, CCLBuffer, CCLImage* or CCLSampler*.

Definition at line 250 of file ccl_kernel_wrapper.c.

CCLEvent * ccl_kernel_set_args_and_enqueue_ndrange	(	CCLKernel *	krnl,
		CCLQueue *	cq,
		cl_uint	work_dim,
		const size_t *	global_work_offset,
		const size_t *	global_work_size,
		const size_t *	local_work_size,
		CCLEventWaitList *	evt_wait_lst,
		CCLErr **	err,
			...
	)

Set kernel arguments and enqueue it for execution on a device.

Internally this function sets kernel arguments by calling ccl_kernel_set_args_v(), and enqueues the kernel for execution by calling ccl_kernel_enqueue_ndrange().

The ccl_kernel_set_args_and_enqueue_ndrange_v() function performs the same operation but accepts an array of arguments instead.

If the ccl_arg_skip constant is passed in place of a specific argument, that argument will not be set by this function call. Any previously set argument continues to be valid.

Attention: The variable argument list must end with NULL.

Warning: This function is not thread-safe. For multi-threaded access to the same kernel function, create multiple instances of a kernel wrapper for the given kernel function with ccl_kernel_new(), one for each thread.

Parameters

[in]	krnl	A kernel wrapper object.
[in]	cq	A command queue wrapper object.
[in]	work_dim	The number of dimensions used to specify the global work-items and work-items in the work-group.
[in]	global_work_offset	Can be used to specify an array of `work_dim` unsigned values that describe the offset used to calculate the global ID of a work-item.
[in]	global_work_size	An array of `work_dim` unsigned values that describe the number of global work-items in `work_dim` dimensions that will execute the kernel function.
[in]	local_work_size	An array of `work_dim` unsigned values that describe the number of work-items that make up a work-group that will execute the specified kernel.
[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.
[in]	...	A `NULL`-terminated list of arguments to set.

Returns: Event wrapper object that identifies this command.

Examples:: ca.c, and image_filter.c.

Definition at line 516 of file ccl_kernel_wrapper.c.

CCLEvent * ccl_kernel_set_args_and_enqueue_ndrange_v	(	CCLKernel *	krnl,
		CCLQueue *	cq,
		cl_uint	work_dim,
		const size_t *	global_work_offset,
		const size_t *	global_work_size,
		const size_t *	local_work_size,
		CCLEventWaitList *	evt_wait_lst,
		void **	args,
		CCLErr **	err
	)

Set kernel arguments and enqueue it for execution on a device.

Internally this function sets kernel arguments by calling ccl_kernel_set_args_v(), and enqueues the kernel for execution by calling ccl_kernel_enqueue_ndrange().

The ccl_kernel_set_args_and_enqueue_ndrange() function performs the same operation but accepts a NULL-terminated variable list of arguments instead.

If the ccl_arg_skip constant is passed in place of a specific argument, that argument will not be set by this function call. Any previously set argument continues to be valid.

Warning: This function is not thread-safe. For multi-threaded access to the same kernel function, create multiple instances of a kernel wrapper for the given kernel function with ccl_kernel_new(), one for each thread.

Parameters

[in]	krnl	A kernel wrapper object.
[in]	cq	A command queue wrapper object.
[in]	work_dim	The number of dimensions used to specify the global work-items and work-items in the work-group.
[in]	global_work_offset	Can be used to specify an array of `work_dim` unsigned values that describe the offset used to calculate the global ID of a work-item.
[in]	global_work_size	An array of `work_dim` unsigned values that describe the number of global work-items in `work_dim` dimensions that will execute the kernel function.
[in]	local_work_size	An array of `work_dim` unsigned values that describe the number of work-items that make up a work-group that will execute the specified kernel.
[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.
[in]	args	A `NULL`-terminated list of arguments to set. Arguments must be of type CCLArg, CCLBuffer, CCLImage* or CCLSampler*.
[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 635 of file ccl_kernel_wrapper.c.

void ccl_kernel_set_args_v	(	CCLKernel *	krnl,
		void **	args
	)

Set all kernel arguments.

This function accepts a NULL-terminated array of kernel arguments. Each argument is individually set using the ccl_kernel_set_arg() function.

The ccl_kernel_set_args() function performs the same operation but accepts a NULL-terminated variable list of arguments instead.

If the ccl_arg_skip constant is passed in place of a specific argument, that argument will not be set by this function call. Any previously set argument continues to be valid.

Warning: This function is not thread-safe. For multi-threaded access to the same kernel function, create multiple instances of a kernel wrapper for the given kernel function with ccl_kernel_new(), one for each thread.

Parameters

[in]	krnl	A kernel wrapper object.
[in]	args	A `NULL`-terminated array of arguments to set. Arguments must be of type CCLArg, CCLBuffer, CCLImage* or CCLSampler*.

Definition at line 334 of file ccl_kernel_wrapper.c.

cl_bool ccl_kernel_suggest_worksizes	(	CCLKernel *	krnl,
		CCLDevice *	dev,
		cl_uint	dims,
		const size_t *	real_worksize,
		size_t *	gws,
		size_t *	lws,
		CCLErr **	err
	)

Suggest appropriate local (and optionally global) work sizes for the given real work size, based on device and kernel characteristics.

If the gws parameter is not NULL, it will be populated with a global worksize which may be larger than the real work size in order to better fit the kernel preferred multiple work size. As such, kernels enqueued with global work sizes suggested by this function should check if their global ID is within real_worksize.

Parameters

[in]	krnl	Kernel wrapper object. If `NULL`, use only device information for determining global and local worksizes.
[in]	dev	Device wrapper object.
[in]	dims	The number of dimensions used to specify the global work-items and work-items in the work-group.
[in]	real_worksize	The real worksize.
[out]	gws	Location where to place a "nice" global worksize for the given kernel and device, which must be equal or larger than the `real_worksize` and a multiple of `lws`. This memory location should be pre-allocated with space for `dims` values of size `size_t`. If `NULL` it is assumed that the global worksize must be equal to `real_worksize`.
[in,out]	lws	This memory location, of size `dims * sizeof(size_t)`, serves a dual purpose: 1) as an input, containing the maximum allowed local work size for each dimension, or zeros if these maximums are to be fetched from the given device `CL_DEVICE_MAX_WORK_ITEM_SIZES` information (if the specified values are larger than the device limits, the device limits are used instead); 2) as an output, where to place a "nice" local worksize, which is based and respects the limits of the given kernel and device (and of the non-zero values given as input).
[out]	err	Return location for a CCLErr object, or `NULL` if error reporting is to be ignored.

Returns: CL_TRUE if function returns successfully, CL_FALSE otherwise.

Examples:: ca.c, canon.c, and image_filter.c.

Definition at line 903 of file ccl_kernel_wrapper.c.

Modules

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Function Documentation