cf4ocl (C Framework for OpenCL)  v2.1.0
Object-oriented framework for developing and benchmarking OpenCL projects in C/C++
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Device wrapper

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

Macros

#define ccl_device_get_info(dev, param_name, err)
 Get a CCLWrapperInfo device information object. More...
 
#define ccl_device_get_info(dev, param_name, err)
 Get a CCLWrapperInfo device information object. More...
 
#define ccl_device_get_info_array(dev, param_name, param_type, err)
 Macro which returns an array device information value. More...
 
#define ccl_device_get_info_array(dev, param_name, param_type, err)
 Macro which returns an array device information value. More...
 
#define ccl_device_get_info_scalar(dev, param_name, param_type, err)
 Macro which returns a scalar device information value. More...
 
#define ccl_device_get_info_scalar(dev, param_name, param_type, err)
 Macro which returns a scalar device information value. More...
 
#define ccl_device_ref(dev)   ccl_wrapper_ref((CCLWrapper*) dev)
 Increase the reference count of the device wrapper object. More...
 
#define ccl_device_ref(dev)   ccl_wrapper_ref((CCLWrapper*) dev)
 Increase the reference count of the device wrapper object. More...
 
#define ccl_device_unref(dev)   ccl_device_destroy(dev)
 Alias to ccl_device_destroy(). More...
 
#define ccl_device_unref(dev)   ccl_device_destroy(dev)
 Alias to ccl_device_destroy(). More...
 
#define ccl_device_unwrap(dev)   ((cl_device_id) ccl_wrapper_unwrap((CCLWrapper*) dev))
 Get the OpenCL device_id object. More...
 
#define ccl_device_unwrap(dev)   ((cl_device_id) ccl_wrapper_unwrap((CCLWrapper*) dev))
 Get the OpenCL device_id object. More...
 

Typedefs

typedef struct ccl_device CCLDevice
 Device wrapper class.
 

Functions

CCLDevice *const * ccl_device_create_subdevices (CCLDevice *dev, const cl_device_partition_property *properties, cl_uint *num_devs_ret, CCLErr **err)
 Creates a NULL-terminated array of sub-devices that each reference a non-intersecting set of compute units within the given parent device. More...
 
void ccl_device_destroy (CCLDevice *dev)
 Decrements the reference count of the device wrapper object. More...
 
cl_uint ccl_device_get_opencl_c_version (CCLDevice *dev, CCLErr **err)
 Get the OpenCL C version supported by the device. More...
 
cl_uint ccl_device_get_opencl_version (CCLDevice *dev, CCLErr **err)
 Get the OpenCL version supported by the device. More...
 
CCLDeviceccl_device_new_wrap (cl_device_id device)
 Get the device wrapper for the given OpenCL device. More...
 

Detailed Description

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

In most cases, device wrapper objects should not be directly instanced by client code. They are usually fetched from device container objects such as CCLPlatform* or CCLContext* instances, or created as sub-devices using the ccl_device_create_subdevices() function. In either case, when the parent object is destroyed, the associated devices (or sub-devices) are also destroyed. As such, and in accordance with the cf4ocl new/destroy rule, the ccl_device_destroy() destructor function will rarely be used.

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

Example: getting the first device in a context

CCLDevice* dev;
dev = ccl_context_get_device(ctx, 0, NULL);

Macro Definition Documentation

#define ccl_device_get_info (   dev,
  param_name,
  err 
)
Value:
ccl_wrapper_get_info((CCLWrapper*) dev, NULL, param_name, 0, \
CCL_INFO_DEVICE, CL_FALSE, err)
Request information about device objects.
Definition: ccl_common.h:129
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.
Base class for all OpenCL wrappers.

Get a CCLWrapperInfo device information object.

Parameters
[in]devThe device wrapper object.
[in]param_nameName of information/parameter to get.
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
The requested device information object. This object will be automatically freed when the device wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 110 of file ccl_device_wrapper.h.

#define ccl_device_get_info (   dev,
  param_name,
  err 
)
Value:
ccl_wrapper_get_info((CCLWrapper*) dev, NULL, param_name, 0, \
CCL_INFO_DEVICE, CL_FALSE, err)
Request information about device objects.
Definition: ccl_common.h:129
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.
Base class for all OpenCL wrappers.

Get a CCLWrapperInfo device information object.

Parameters
[in]devThe device wrapper object.
[in]param_nameName of information/parameter to get.
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
The requested device information object. This object will be automatically freed when the device wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 110 of file ccl_device_wrapper.h.

#define ccl_device_get_info_array (   dev,
  param_name,
  param_type,
  err 
)
Value:
(param_type) ccl_wrapper_get_info_value((CCLWrapper*) dev, \
NULL, param_name, sizeof(param_type), \
CCL_INFO_DEVICE, CL_FALSE, err)
Request information about device objects.
Definition: ccl_common.h:129
Base class for all OpenCL wrappers.
void * ccl_wrapper_get_info_value(CCLWrapper *wrapper1, CCLWrapper *wrapper2, cl_uint param_name, size_t min_size, CCLInfo info_type, cl_bool use_cache, CCLErr **err)
Get pointer to information value.

Macro which returns an array device 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]devThe device wrapper object.
[in]param_nameName of information/parameter to get value of.
[in]param_typeType of parameter (e.g. char*, size_t*, etc.).
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
The requested device information value. This value will be automatically freed when the device wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 151 of file ccl_device_wrapper.h.

#define ccl_device_get_info_array (   dev,
  param_name,
  param_type,
  err 
)
Value:
(param_type) ccl_wrapper_get_info_value((CCLWrapper*) dev, \
NULL, param_name, sizeof(param_type), \
CCL_INFO_DEVICE, CL_FALSE, err)
Request information about device objects.
Definition: ccl_common.h:129
Base class for all OpenCL wrappers.
void * ccl_wrapper_get_info_value(CCLWrapper *wrapper1, CCLWrapper *wrapper2, cl_uint param_name, size_t min_size, CCLInfo info_type, cl_bool use_cache, CCLErr **err)
Get pointer to information value.

Macro which returns an array device 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]devThe device wrapper object.
[in]param_nameName of information/parameter to get value of.
[in]param_typeType of parameter (e.g. char*, size_t*, etc.).
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
The requested device information value. This value will be automatically freed when the device wrapper object is destroyed. If an error occurs, NULL is returned.
Examples:
device_filter.c, and list_devices.c.

Definition at line 151 of file ccl_device_wrapper.h.

#define ccl_device_get_info_scalar (   dev,
  param_name,
  param_type,
  err 
)
Value:
*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) dev, \
NULL, param_name, sizeof(param_type), \
CCL_INFO_DEVICE, CL_FALSE, err))
Request information about device objects.
Definition: ccl_common.h:129
Base class for all OpenCL wrappers.
void * ccl_wrapper_get_info_value(CCLWrapper *wrapper1, CCLWrapper *wrapper2, cl_uint param_name, size_t min_size, CCLInfo info_type, cl_bool use_cache, CCLErr **err)
Get pointer to information value.

Macro which returns a scalar device 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]devThe device wrapper object.
[in]param_nameName of information/parameter to get value of.
[in]param_typeType of parameter (e.g. cl_uint, size_t, etc.).
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
The requested device information value. This value will be automatically freed when the device wrapper object is destroyed. If an error occurs, zero is returned.
Examples:
ca.c, image_fill.c, and image_filter.c.

Definition at line 130 of file ccl_device_wrapper.h.

#define ccl_device_get_info_scalar (   dev,
  param_name,
  param_type,
  err 
)
Value:
*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) dev, \
NULL, param_name, sizeof(param_type), \
CCL_INFO_DEVICE, CL_FALSE, err))
Request information about device objects.
Definition: ccl_common.h:129
Base class for all OpenCL wrappers.
void * ccl_wrapper_get_info_value(CCLWrapper *wrapper1, CCLWrapper *wrapper2, cl_uint param_name, size_t min_size, CCLInfo info_type, cl_bool use_cache, CCLErr **err)
Get pointer to information value.

Macro which returns a scalar device 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]devThe device wrapper object.
[in]param_nameName of information/parameter to get value of.
[in]param_typeType of parameter (e.g. cl_uint, size_t, etc.).
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
The requested device information value. This value will be automatically freed when the device wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 130 of file ccl_device_wrapper.h.

#define ccl_device_ref (   dev)    ccl_wrapper_ref((CCLWrapper*) dev)

Increase the reference count of the device wrapper object.

Parameters
[in]devThe device wrapper object.

Definition at line 161 of file ccl_device_wrapper.h.

#define ccl_device_ref (   dev)    ccl_wrapper_ref((CCLWrapper*) dev)

Increase the reference count of the device wrapper object.

Parameters
[in]devThe device wrapper object.

Definition at line 161 of file ccl_device_wrapper.h.

#define ccl_device_unref (   dev)    ccl_device_destroy(dev)

Alias to ccl_device_destroy().

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

Definition at line 170 of file ccl_device_wrapper.h.

#define ccl_device_unref (   dev)    ccl_device_destroy(dev)

Alias to ccl_device_destroy().

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

Definition at line 170 of file ccl_device_wrapper.h.

#define ccl_device_unwrap (   dev)    ((cl_device_id) ccl_wrapper_unwrap((CCLWrapper*) dev))

Get the OpenCL device_id object.

Parameters
[in]devThe device wrapper object.
Returns
The OpenCL device_id object.

Definition at line 178 of file ccl_device_wrapper.h.

#define ccl_device_unwrap (   dev)    ((cl_device_id) ccl_wrapper_unwrap((CCLWrapper*) dev))

Get the OpenCL device_id object.

Parameters
[in]devThe device wrapper object.
Returns
The OpenCL device_id object.

Definition at line 178 of file ccl_device_wrapper.h.

Function Documentation

CCLDevice *const * ccl_device_create_subdevices ( CCLDevice dev,
const cl_device_partition_property *  properties,
cl_uint *  num_devs_ret,
CCLErr **  err 
)

Creates a NULL-terminated array of sub-devices that each reference a non-intersecting set of compute units within the given parent device.

Note
Requires OpenCL >= 1.2
Parameters
[in]devThe parent device to be partitioned.
[in]propertiesSpecifies how dev is to be partitioned. See the documentation for the clCreateSubDevices() function.
[out]num_devs_retReturns how many sub-devices were created in the returned array of sub-devices. If NULL, this parameter is ignored and client code will have to check for the NULL termination in the returned array.
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
A NULL-terminated array of sub-devices. Sub-devices will be automatically disposed of when parent device is destroyed.

Definition at line 278 of file ccl_device_wrapper.c.

void ccl_device_destroy ( CCLDevice dev)

Decrements the reference count of the device wrapper object.

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

Parameters
[in]devThe device wrapper object.

Definition at line 145 of file ccl_device_wrapper.c.

cl_uint ccl_device_get_opencl_c_version ( CCLDevice dev,
CCLErr **  err 
)

Get the OpenCL C version supported by the device.

This information is parsed from the CL_DEVICE_OPENCL_C_VERSION parameter name. 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]devThe device wrapper object.
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
The supported OpenCL C version supported by the device. If an error occurs, 0 is returned.

Definition at line 234 of file ccl_device_wrapper.c.

cl_uint ccl_device_get_opencl_version ( CCLDevice dev,
CCLErr **  err 
)

Get the OpenCL version supported by the device.

This information is parsed from the CL_DEVICE_VERSION parameter name. 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]devThe device wrapper object.
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
The OpenCL version supported by the device. If an error occurs, 0 is returned.

Definition at line 193 of file ccl_device_wrapper.c.

CCLDevice * ccl_device_new_wrap ( cl_device_id  device)

Get the device wrapper for the given OpenCL device.

If the wrapper doesn't exist, it's 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 get the OpenCL device directly (using the clGetDeviceIDs() function) and then wrap the OpenCL device in a CCLDevice wrapper object.

Parameters
[in]deviceThe OpenCL device to be wrapped.
Returns
The device wrapper for the given OpenCL device.

Definition at line 129 of file ccl_device_wrapper.c.