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
Macros | Typedefs | Functions
Platform wrapper

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

Macros

#define ccl_platform_get_info(platf, param_name, err)
 Get a CCLWrapperInfo platform information object. More...
 
#define ccl_platform_get_info(platf, param_name, err)
 Get a CCLWrapperInfo platform information object. More...
 
#define ccl_platform_get_info_array(platf, param_name, param_type, err)
 Macro which returns an array platform information value. More...
 
#define ccl_platform_get_info_array(platf, param_name, param_type, err)
 Macro which returns an array platform information value. More...
 
#define ccl_platform_get_info_scalar(platf, param_name, param_type, err)
 Macro which returns a scalar platform information value. More...
 
#define ccl_platform_get_info_scalar(platf, param_name, param_type, err)
 Macro which returns a scalar platform information value. More...
 
#define ccl_platform_get_info_string(platf, param_name, err)   ccl_platform_get_info_array(platf, param_name, char*, err)
 Helper macro which gets a platform information string. More...
 
#define ccl_platform_get_info_string(platf, param_name, err)   ccl_platform_get_info_array(platf, param_name, char*, err)
 Helper macro which gets a platform information string. More...
 
#define ccl_platform_ref(platform)   ccl_wrapper_ref((CCLWrapper*) platform)
 Increase the reference count of the platform wrapper object. More...
 
#define ccl_platform_ref(platform)   ccl_wrapper_ref((CCLWrapper*) platform)
 Increase the reference count of the platform wrapper object. More...
 
#define ccl_platform_unref(platform)   ccl_platform_destroy(platform)
 Alias to ccl_platform_destroy(). More...
 
#define ccl_platform_unref(platform)   ccl_platform_destroy(platform)
 Alias to ccl_platform_destroy(). More...
 
#define ccl_platform_unwrap(platform)   ((cl_platform_id) ccl_wrapper_unwrap((CCLWrapper*) platform))
 Get the OpenCL platform object. More...
 
#define ccl_platform_unwrap(platform)   ((cl_platform_id) ccl_wrapper_unwrap((CCLWrapper*) platform))
 Get the OpenCL platform object. More...
 

Typedefs

typedef struct ccl_platform CCLPlatform
 Platform wrapper class.
 

Functions

void ccl_platform_destroy (CCLPlatform *platf)
 Decrements the reference count of the platform wrapper object. More...
 
CCLDevice *const * ccl_platform_get_all_devices (CCLPlatform *platf, CCLErr **err)
 Get all device wrappers in platform. More...
 
CCLDevice * ccl_platform_get_device (CCLPlatform *platf, cl_uint index, CCLErr **err)
 Get CCLDevice wrapper at given index. More...
 
cl_uint ccl_platform_get_num_devices (CCLPlatform *platf, CCLErr **err)
 Return number of devices in platform. More...
 
cl_uint ccl_platform_get_opencl_version (CCLPlatform *platf, CCLErr **err)
 Get the OpenCL version of this platform. More...
 
CCLPlatform * ccl_platform_new_from_device (CCLDevice *dev, CCLErr **err)
 Get the platform wrapper for the given device wrapper. More...
 
CCLPlatform * ccl_platform_new_wrap (cl_platform_id platform)
 Get the platform wrapper for the given OpenCL platform. More...
 

Detailed Description

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

Platform wrappers can be obtained in two ways:

  1. From a given CCLDevice* device wrapper, using the ccl_platform_new_from_device() function (in which case, the object must be destroyed with ccl_platform_destroy(), following the cf4ocl new/destroy rule).
  2. From a CCLPlatforms* object (which contains the list of platforms in the system), using the ccl_platforms_get() function. In this case the platform wrapper is automatically destroyed when the CCLPlatforms* object is freed; as such, client code should not directly destroy the platform wrapper. See the platforms module for more details.

The provided functions allow to get the device wrappers associated with the given platform wrapper, as well as to obtain the supported OpenCL version of the underlying OpenCL platform object.

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

However, because the platform info return type is always char*, cf4ocl provides an additional helper macro for platform wrappers, ccl_platform_get_info_string(), which is simpler to use.

The CCLPlatform* class extends the CCLDevContainer* class; as such, it provides methods for handling a list of devices associated with the platform:

Usage example:

CCLPlatform* platf;
CCLDevice* dev;
char* platf_name;
cl_uint platf_ver;
platf = ccl_platform_new_from_device(dev, NULL);
platf_name =
ccl_platform_get_info_string(platf, CL_PLATFORM_NAME, NULL);
platf_ver = ccl_platform_get_opencl_version(platf, NULL);
printf("Platform name is %s\n: ", platf_name);
printf("Platform version is %f\n: ", platf_ver / 100.0f);
ccl_platform_destroy(platf);

Macro Definition Documentation

#define ccl_platform_get_info (   platf,
  param_name,
  err 
)
Value:
ccl_wrapper_get_info((CCLWrapper*) platf, NULL, param_name, 0, \
CCL_INFO_PLATFORM, CL_FALSE, err)
CCL_INFO_PLATFORM
Request information about platform objects.
Definition: ccl_common.h:147
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

Get a CCLWrapperInfo platform information object.

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

Definition at line 136 of file ccl_platform_wrapper.h.

#define ccl_platform_get_info (   platf,
  param_name,
  err 
)
Value:
ccl_wrapper_get_info((CCLWrapper*) platf, NULL, param_name, 0, \
CCL_INFO_PLATFORM, CL_FALSE, err)
CCL_INFO_PLATFORM
Request information about platform objects.
Definition: ccl_common.h:147
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

Get a CCLWrapperInfo platform information object.

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

Definition at line 136 of file ccl_platform_wrapper.h.

#define ccl_platform_get_info_array (   platf,
  param_name,
  param_type,
  err 
)
Value:
(param_type) ccl_wrapper_get_info_value((CCLWrapper*) platf, \
NULL, param_name, sizeof(param_type), \
CCL_INFO_PLATFORM, CL_FALSE, err)
CCL_INFO_PLATFORM
Request information about platform objects.
Definition: ccl_common.h:147
ccl_wrapper
Base class for all OpenCL wrappers.
Definition: _ccl_abstract_wrapper.h:47
ccl_wrapper::ccl_wrapper_get_info_value
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.
Definition: ccl_abstract_wrapper.c:600

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

Definition at line 177 of file ccl_platform_wrapper.h.

#define ccl_platform_get_info_array (   platf,
  param_name,
  param_type,
  err 
)
Value:
(param_type) ccl_wrapper_get_info_value((CCLWrapper*) platf, \
NULL, param_name, sizeof(param_type), \
CCL_INFO_PLATFORM, CL_FALSE, err)
CCL_INFO_PLATFORM
Request information about platform objects.
Definition: ccl_common.h:147
ccl_wrapper
Base class for all OpenCL wrappers.
Definition: _ccl_abstract_wrapper.h:47
ccl_wrapper::ccl_wrapper_get_info_value
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.
Definition: ccl_abstract_wrapper.c:600

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

Definition at line 177 of file ccl_platform_wrapper.h.

#define ccl_platform_get_info_scalar (   platf,
  param_name,
  param_type,
  err 
)
Value:
*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) platf, \
NULL, param_name, sizeof(param_type), \
CCL_INFO_PLATFORM, CL_FALSE, err))
CCL_INFO_PLATFORM
Request information about platform objects.
Definition: ccl_common.h:147
ccl_wrapper
Base class for all OpenCL wrappers.
Definition: _ccl_abstract_wrapper.h:47
ccl_wrapper::ccl_wrapper_get_info_value
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.
Definition: ccl_abstract_wrapper.c:600

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

Definition at line 156 of file ccl_platform_wrapper.h.

#define ccl_platform_get_info_scalar (   platf,
  param_name,
  param_type,
  err 
)
Value:
*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) platf, \
NULL, param_name, sizeof(param_type), \
CCL_INFO_PLATFORM, CL_FALSE, err))
CCL_INFO_PLATFORM
Request information about platform objects.
Definition: ccl_common.h:147
ccl_wrapper
Base class for all OpenCL wrappers.
Definition: _ccl_abstract_wrapper.h:47
ccl_wrapper::ccl_wrapper_get_info_value
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.
Definition: ccl_abstract_wrapper.c:600

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

Definition at line 156 of file ccl_platform_wrapper.h.

#define ccl_platform_get_info_string (   platf,
  param_name,
  err 
)    ccl_platform_get_info_array(platf, param_name, char*, err)

Helper macro which gets a platform information string.

This macro simply wraps the ccl_platform_get_info_array() macro, because (as of OpenCL 2.0) all platform information return types are char*.

Parameters
[in]platfThe platform 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 platform information string. This information will be automatically freed when the platform wrapper object is destroyed. If an error occurs, NULL is returned.
Examples:
list_devices.c.

Definition at line 195 of file ccl_platform_wrapper.h.

#define ccl_platform_get_info_string (   platf,
  param_name,
  err 
)    ccl_platform_get_info_array(platf, param_name, char*, err)

Helper macro which gets a platform information string.

This macro simply wraps the ccl_platform_get_info_array() macro, because (as of OpenCL 2.0) all platform information return types are char*.

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

Definition at line 195 of file ccl_platform_wrapper.h.

#define ccl_platform_ref (   platform)    ccl_wrapper_ref((CCLWrapper*) platform)

Increase the reference count of the platform wrapper object.

Parameters
[in]platformThe platform wrapper object.

Definition at line 203 of file ccl_platform_wrapper.h.

#define ccl_platform_ref (   platform)    ccl_wrapper_ref((CCLWrapper*) platform)

Increase the reference count of the platform wrapper object.

Parameters
[in]platformThe platform wrapper object.

Definition at line 203 of file ccl_platform_wrapper.h.

#define ccl_platform_unref (   platform)    ccl_platform_destroy(platform)

Alias to ccl_platform_destroy().

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

Definition at line 212 of file ccl_platform_wrapper.h.

#define ccl_platform_unref (   platform)    ccl_platform_destroy(platform)

Alias to ccl_platform_destroy().

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

Definition at line 212 of file ccl_platform_wrapper.h.

#define ccl_platform_unwrap (   platform)    ((cl_platform_id) ccl_wrapper_unwrap((CCLWrapper*) platform))

Get the OpenCL platform object.

Parameters
[in]platformThe platform wrapper object.
Returns
The OpenCL platform object.

Definition at line 220 of file ccl_platform_wrapper.h.

#define ccl_platform_unwrap (   platform)    ((cl_platform_id) ccl_wrapper_unwrap((CCLWrapper*) platform))

Get the OpenCL platform object.

Parameters
[in]platformThe platform wrapper object.
Returns
The OpenCL platform object.

Definition at line 220 of file ccl_platform_wrapper.h.

Function Documentation

void ccl_platform_destroy ( CCLPlatform *  platf)

Decrements the reference count of the platform wrapper object.

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

Parameters
[in]platfThe platform wrapper object.

Definition at line 210 of file ccl_platform_wrapper.c.

CCLDevice *const * ccl_platform_get_all_devices ( CCLPlatform *  platf,
CCLErr **  err 
)

Get all device wrappers in platform.

This function returns the internal array containing the platform device wrappers. As such, clients should not modify the returned array (e.g. they should not free it directly).

Parameters
[in]platfThe platform wrapper object.
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
An array containing the CCLDevice wrappers which belong to this platform, or NULL if an error occurs.

Definition at line 275 of file ccl_platform_wrapper.c.

CCLDevice * ccl_platform_get_device ( CCLPlatform *  platf,
cl_uint  index,
CCLErr **  err 
)

Get CCLDevice wrapper at given index.

Parameters
[in]platfThe platform wrapper object.
[in]indexIndex of device in platform.
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
The CCLDevice wrapper at given index or NULL if an error occurs.
Examples:
list_devices.c.

Definition at line 295 of file ccl_platform_wrapper.c.

cl_uint ccl_platform_get_num_devices ( CCLPlatform *  platf,
CCLErr **  err 
)

Return number of devices in platform.

Parameters
[in]platfThe platform wrapper object.
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
The number of devices in platform or 0 if an error occurs or is otherwise not possible to get any device.
Examples:
list_devices.c.

Definition at line 315 of file ccl_platform_wrapper.c.

cl_uint ccl_platform_get_opencl_version ( CCLPlatform *  platf,
CCLErr **  err 
)

Get the OpenCL version of this platform.

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]platfThe platform wrapper object.
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
OpenCL version of platform as an integer. If an error occurs, 0 is returned.

Definition at line 237 of file ccl_platform_wrapper.c.

CCLPlatform * ccl_platform_new_from_device ( CCLDevice *  dev,
CCLErr **  err 
)

Get the platform wrapper for the given device wrapper.

Parameters
[in]devThe device wrapper from where to get a platform wrapper.
[out]errReturn location for a CCLErr object, or NULL if error reporting is to be ignored.
Returns
The platform wrapper for the given device wrapper or NULL in case an error occurs.

Definition at line 164 of file ccl_platform_wrapper.c.

CCLPlatform * ccl_platform_new_wrap ( cl_platform_id  platform)

Get the platform wrapper for the given OpenCL platform.

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 platform directly (using the clGetPlatformIDs() function) and then wrap the OpenCL platform in a CCLPlatform wrapper object.

Parameters
[in]platformThe OpenCL platform to be wrapped.
Returns
The CCLPlatform wrapper for the given OpenCL platform.

Definition at line 144 of file ccl_platform_wrapper.c.