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
ccl_program_wrapper.h
Go to the documentation of this file.
1 /*
2  * This file is part of cf4ocl (C Framework for OpenCL).
3  *
4  * cf4ocl is free software: you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License as
6  * published by the Free Software Foundation, either version 3 of the
7  * License, or (at your option) any later version.
8  *
9  * cf4ocl is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  * GNU Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with cf4ocl. If not, see
16  * <http://www.gnu.org/licenses/>.
17  * */
18 
29 #ifndef _CCL_PROGRAM_WRAPPER_H_
30 #define _CCL_PROGRAM_WRAPPER_H_
31 
32 #include <glib.h>
33 #include "ccl_oclversions.h"
34 #include "ccl_context_wrapper.h"
35 #include "ccl_abstract_wrapper.h"
36 #include "ccl_event_wrapper.h"
37 #include "ccl_queue_wrapper.h"
38 #include "ccl_kernel_wrapper.h"
39 
196 
206 typedef void (CL_CALLBACK* ccl_program_callback)(
207  cl_program program, void* user_data);
208 
209 /* *********** */
210 /* WRAPPER API */
211 /* *********** */
212 
213 /* Get the program wrapper for the given OpenCL program. */
214 CCL_EXPORT
215 CCLProgram* ccl_program_new_wrap(cl_program program);
216 
217 /* Decrements the reference count of the program wrapper object.
218  * If it reaches 0, the program wrapper object is destroyed. */
219 CCL_EXPORT
221 
222 /* *********************** */
223 /* CREATE FROM SOURCES API */
224 /* *********************** */
225 
226 /* Create a new program wrapper object from a source file. */
227 CCL_EXPORT
229  const char* filename, CCLErr** err);
230 
231 /* Create a new program wrapper object from several source files. */
232 CCL_EXPORT
234  cl_uint count, const char** filenames, CCLErr** err);
235 
236 /* Create a new program wrapper object from a null-terminated source
237  * string. */
238 CCL_EXPORT
240  const char* string, CCLErr** err);
241 
242 /* Create a new program wrapper object from several source code
243  * strings. */
244 CCL_EXPORT
246  cl_uint count, const char** strings, const size_t* lengths,
247  CCLErr** err);
248 
249 /* ************************ */
250 /* CREATE FROM BINARIES API */
251 /* ************************ */
252 
253 /* Create a new program wrapper object with binary code from a specific
254  * device. */
255 CCL_EXPORT
257  CCLDevice* dev, const char* filename, cl_int *binary_status,
258  CCLErr** err);
259 
260 /* Create a new program wrapper object from files containing binary
261  * code executable on the given device list, one file per device. */
262 CCL_EXPORT
264  cl_uint num_devices, CCLDevice* const* devs, const char** filenames,
265  cl_int *binary_status, CCLErr** err);
266 
267 /* Create a new program wrapper object from binary code executable on a
268  * specific device. */
269 CCL_EXPORT
271  CCLProgramBinary* binary, cl_int *binary_status, CCLErr** err);
272 
273 /* Create a new program wrapper object from a list of binary code
274  * strings executable on the given device list, one binary string per
275  * device. */
276 CCL_EXPORT
278  cl_uint num_devices, CCLDevice* const* devs, CCLProgramBinary** bins,
279  cl_int *binary_status, CCLErr** err);
280 
281 /* ******************************** */
282 /* CREATE FROM BUILT-IN KERNELS API */
283 /* ******************************** */
284 
285 /* Create a new program wrapper object from device built-in kernels. */
286 CCL_EXPORT
288  cl_uint num_devices, CCLDevice* const* devs, const char *kernel_names,
289  CCLErr** err);
290 
291 /* ************************ */
292 /* BUILD, COMPILE, LINK API */
293 /* ************************ */
294 
295 /* Utility function which builds (compiles and links) a program
296  * executable from the program source or binary. */
297 CCL_EXPORT
298 cl_bool ccl_program_build(
299  CCLProgram* prg, const char* options, CCLErr** err);
300 
301 /* Builds (compiles and links) a program executable from the program
302  * source or binary. This function wraps the clBuildProgram() OpenCL
303  * function. */
304 CCL_EXPORT
306  cl_uint num_devices, CCLDevice* const* devs, const char* options,
307  ccl_program_callback pfn_notify, void* user_data, CCLErr** err);
308 
309 /* Get a general build log of most recent build, compile or link, for
310  * all devices. */
311 CCL_EXPORT
312 const char* ccl_program_get_build_log(CCLProgram* prg, CCLErr** err);
313 
314 /* Get build log for most recent build, compile or link for the
315  * specified device. */
316 CCL_EXPORT
318  CCLProgram* prg, CCLDevice* dev, CCLErr** err);
319 
320 /* Compile a program's source code. */
321 CCL_EXPORT
322 cl_bool ccl_program_compile(CCLProgram* prg, cl_uint num_devices,
323  CCLDevice* const* devs, const char* options, cl_uint num_input_headers,
324  CCLProgram** prg_input_headers, const char** header_include_names,
325  ccl_program_callback pfn_notify, void* user_data, CCLErr** err);
326 
327 /* Link a set of compiled programs. */
328 CCL_EXPORT
329 CCLProgram* ccl_program_link(CCLContext* ctx, cl_uint num_devices,
330  CCLDevice* const* devs, const char* options, cl_uint num_input_programs,
331  CCLProgram** input_prgs, ccl_program_callback pfn_notify,
332  void* user_data, CCLErr** err);
333 
334 /* ********************** */
335 /* PROGRAM OPENCL VERSION */
336 /* ********************** */
337 
338 /* Get the OpenCL version of the platform associated with this
339  * program. */
340 CCL_EXPORT
342 
343 /* ******************************* */
344 /* KERNEL RELATED HELPER FUNCTIONS */
345 /* ******************************* */
346 
347 /* Get the kernel wrapper object for the given program kernel
348  * function. */
349 CCL_EXPORT
351  CCLProgram* prg, const char* kernel_name, CCLErr** err);
352 
353 /* Enqueues a program kernel function for execution on a device. */
354 CCL_EXPORT
356  const char* kernel_name, CCLQueue* cq, cl_uint work_dim,
357  const size_t* global_work_offset, const size_t* global_work_size,
358  const size_t* local_work_size, CCLEventWaitList* evt_wait_lst,
359  CCLErr** err, ...) G_GNUC_NULL_TERMINATED;
360 
361 /* Enqueues a program kernel function for execution on a device. */
362 CCL_EXPORT
364  const char* kernel_name, CCLQueue* cq, cl_uint work_dim,
365  const size_t* global_work_offset, const size_t* global_work_size,
366  const size_t* local_work_size, CCLEventWaitList* evt_wait_lst,
367  void** args, CCLErr** err);
368 
369 /* ************************* */
370 /* BINARY HANDLING FUNCTIONS */
371 /* ************************* */
372 
373 /* Get the program's binary object for the the specified device. */
374 CCL_EXPORT
376  CCLProgram* prg, CCLDevice* dev, CCLErr** err);
377 
378 /* Save the program's binary code for a specified device to a file. */
379 CCL_EXPORT
380 cl_bool ccl_program_save_binary(CCLProgram* prg, CCLDevice* dev,
381  const char* filename, CCLErr** err);
382 
383 /* Save the program binaries for all associated devices to files, one
384  * file per device. */
385 CCL_EXPORT
387  const char* file_prefix, const char* file_suffix, char*** filenames,
388  CCLErr** err);
389 
390 /* ***************************************** */
391 /* DEVICE CONTAINER FUNCTION IMPLEMENTATIONS */
392 /* ***************************************** */
393 
394 /* Get ::CCLDevice wrapper at given index. */
395 CCL_EXPORT
397  CCLProgram* prg, cl_uint index, CCLErr** err);
398 
399 /* Return number of devices in program. */
400 CCL_EXPORT
401 cl_uint ccl_program_get_num_devices(CCLProgram* prg, CCLErr** err);
402 
403 /* Get all device wrappers in program. */
404 CCL_EXPORT
406  CCLErr** err);
407 
408 /* ************************************************* */
409 /* ABSTRACT WRAPPER MACROS (INFO, REF/UNREF, UNWRAP) */
410 /* ************************************************* */
411 
427 #define ccl_program_get_info(prg, param_name, err) \
428  (param_name == CL_PROGRAM_BINARIES) \
429  ? NULL \
430  : ccl_wrapper_get_info((CCLWrapper*) prg, NULL, param_name, 0, \
431  CCL_INFO_PROGRAM, CL_FALSE, err)
432 
450 #define ccl_program_get_info_scalar(prg, param_name, param_type, err) \
451  (param_name == CL_PROGRAM_BINARIES) \
452  ? (param_type) 0 \
453  : *((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) prg, \
454  NULL, param_name, sizeof(param_type), \
455  CCL_INFO_PROGRAM, CL_FALSE, err))
456 
477 #define ccl_program_get_info_array(prg, param_name, param_type, err) \
478  (param_name == CL_PROGRAM_BINARIES) \
479  ? NULL \
480  : (param_type) ccl_wrapper_get_info_value((CCLWrapper*) prg, \
481  NULL, param_name, sizeof(param_type), \
482  CCL_INFO_PROGRAM, CL_FALSE, err)
483 
496 #define ccl_program_get_build_info(prg, dev, param_name, err) \
497  ccl_wrapper_get_info((CCLWrapper*) prg, (CCLWrapper*) dev, \
498  param_name, 0, CCL_INFO_PROGRAM_BUILD, CL_FALSE, err)
499 
517 #define ccl_program_get_build_info_scalar(prg, dev, param_name, \
518  param_type, err) \
519  *((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) prg, \
520  (CCLWrapper*) dev, param_name, sizeof(param_type), \
521  CCL_INFO_PROGRAM_BUILD, CL_FALSE, err))
522 
540 #define ccl_program_get_build_info_array(prg, dev, param_name, \
541  param_type, err) \
542  (param_type) ccl_wrapper_get_info_value((CCLWrapper*) prg, \
543  (CCLWrapper*) dev, param_name, sizeof(param_type), \
544  CCL_INFO_PROGRAM_BUILD, CL_FALSE, err)
545 
551 #define ccl_program_ref(prg) \
552  ccl_wrapper_ref((CCLWrapper*) prg)
553 
560 #define ccl_program_unref(prg) ccl_program_destroy(prg)
561 
568 #define ccl_program_unwrap(prg) \
569  ((cl_program) ccl_wrapper_unwrap((CCLWrapper*) prg))
570 
573 #endif
574 
575 
const char * ccl_program_get_device_build_log(CCLProgram *prg, CCLDevice *dev, CCLErr **err)
Get build log for most recent build, compile or link for the specified device.
Definition of a wrapper class and its methods for OpenCL kernel objects.
CCLDevice *const * ccl_program_get_all_devices(CCLProgram *prg, CCLErr **err)
Get all device wrappers in program.
CCLEvent * ccl_program_enqueue_kernel(CCLProgram *prg, const char *kernel_name, 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 program kernel function for execution on a device.
CCLEvent * ccl_program_enqueue_kernel_v(CCLProgram *prg, const char *kernel_name, 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)
Enqueues a program kernel function for execution on a device.
GPtrArray * CCLEventWaitList
A list of event objects on which enqueued commands can wait.
CCLProgram * ccl_program_new_from_binary_file(CCLContext *ctx, CCLDevice *dev, const char *filename, cl_int *binary_status, CCLErr **err)
Create a new program wrapper object from a file containing binary code executable on a specific devic...
CCLProgram * ccl_program_new_from_built_in_kernels(CCLContext *ctx, cl_uint num_devices, CCLDevice *const *devs, const char *kernel_names, CCLErr **err)
Create a new program wrapper object from device built-in kernels.
Definition of a wrapper class and its methods for OpenCL context objects.
Definition of a wrapper class and its methods for OpenCL event objects.
The context wrapper class.
CCLProgram * ccl_program_new_from_source(CCLContext *ctx, const char *string, CCLErr **err)
Create a new program wrapper object from a null-terminated source string.
Command queue wrapper class.
cl_uint ccl_program_get_opencl_version(CCLProgram *prg, CCLErr **err)
Get the OpenCL version of the platform associated with this program.
CCLProgram * ccl_program_new_wrap(cl_program program)
Get the program wrapper for the given OpenCL program.
CCLProgramBinary * ccl_program_get_binary(CCLProgram *prg, CCLDevice *dev, CCLErr **err)
Get the program binary object for the specified device.
CCLProgram * ccl_program_new_from_binaries(CCLContext *ctx, cl_uint num_devices, CCLDevice *const *devs, CCLProgramBinary **bins, cl_int *binary_status, CCLErr **err)
Create a new program wrapper object from a list of binary code strings executable on the given device...
cl_bool ccl_program_build(CCLProgram *prg, const char *options, CCLErr **err)
Utility function which builds (compiles and links) a program executable from the program source or bi...
Event wrapper class.
cl_bool ccl_program_save_all_binaries(CCLProgram *prg, const char *file_prefix, const char *file_suffix, char ***filenames, CCLErr **err)
Save the program binaries for all associated devices to files, one file per device.
const char * ccl_program_get_build_log(CCLProgram *prg, CCLErr **err)
Get a general build log of most recent build, compile or link, for all devices.
CCLProgram * ccl_program_new_from_source_file(CCLContext *ctx, const char *filename, CCLErr **err)
Create a new program wrapper object from a source file.
CCLProgram * ccl_program_link(CCLContext *ctx, cl_uint num_devices, CCLDevice *const *devs, const char *options, cl_uint num_input_programs, CCLProgram **input_prgs, ccl_program_callback pfn_notify, void *user_data, CCLErr **err)
Link a set of compiled programs and create an executable program wrapper.
Program wrapper class.
Definition of an abstract wrapper class and its methods for OpenCL objects.
CCLProgram * ccl_program_new_from_binary(CCLContext *ctx, CCLDevice *dev, CCLProgramBinary *binary, cl_int *binary_status, CCLErr **err)
Create a new program wrapper object from binary code executable on a specific device.
CCLProgram * ccl_program_new_from_source_files(CCLContext *ctx, cl_uint count, const char **filenames, CCLErr **err)
Create a new program wrapper object from several source files.
Header for normalizing OpenCL versions within cf4ocl.
void(* ccl_program_callback)(cl_program program, void *user_data)
Prototype of callback functions for program build, compile and link.
CCLProgram * ccl_program_new_from_binary_files(CCLContext *ctx, cl_uint num_devices, CCLDevice *const *devs, const char **filenames, cl_int *binary_status, CCLErr **err)
Create a new program wrapper object from files containing binary code executable on the given device ...
Kernel wrapper class.
cl_bool ccl_program_compile(CCLProgram *prg, cl_uint num_devices, CCLDevice *const *devs, const char *options, cl_uint num_input_headers, CCLProgram **prg_input_headers, const char **header_include_names, ccl_program_callback pfn_notify, void *user_data, CCLErr **err)
Compile a program's source code.
GError CCLErr
Error handling class.
Definition: ccl_common.h:291
cl_bool ccl_program_save_binary(CCLProgram *prg, CCLDevice *dev, const char *filename, CCLErr **err)
Save the program binary code for a specified device to a file.
CCLDevice * ccl_program_get_device(CCLProgram *prg, cl_uint index, CCLErr **err)
Get CCLDevice wrapper at given index.
CCLKernel * ccl_program_get_kernel(CCLProgram *prg, const char *kernel_name, CCLErr **err)
Get the kernel wrapper object for the given program kernel function.
Definition of a wrapper class and its methods for OpenCL queue objects.
cl_bool ccl_program_build_full(CCLProgram *prg, cl_uint num_devices, CCLDevice *const *devs, const char *options, ccl_program_callback pfn_notify, void *user_data, CCLErr **err)
Builds (compiles and links) a program executable from the program source or binary.
void ccl_program_destroy(CCLProgram *prg)
Decrements the reference count of the program wrapper object.
Class which represents a binary object associated with a program and a device.
CCLProgram * ccl_program_new_from_sources(CCLContext *ctx, cl_uint count, const char **strings, const size_t *lengths, CCLErr **err)
Create a new program wrapper object from several source code strings.
Device wrapper class.
cl_uint ccl_program_get_num_devices(CCLProgram *prg, CCLErr **err)
Return number of devices in program.