ccl_program_wrapper.h

Go to the documentation of this file.

/*
 * This file is part of cf4ocl (C Framework for OpenCL).
 *
 * cf4ocl is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * cf4ocl is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with cf4ocl. If not, see
 * <http://www.gnu.org/licenses/>.
 * */

#ifndef _CCL_PROGRAM_WRAPPER_H_
#define _CCL_PROGRAM_WRAPPER_H_

#include <glib.h>
#include "ccl_oclversions.h"
#include "ccl_context_wrapper.h"
#include "ccl_abstract_wrapper.h"
#include "ccl_event_wrapper.h"
#include "ccl_queue_wrapper.h"
#include "ccl_kernel_wrapper.h"

typedef struct ccl_program_binary CCLProgramBinary;

typedef void (CL_CALLBACK* ccl_program_callback)(
    cl_program program, void* user_data);

/* *********** */
/* WRAPPER API */
/* *********** */

/* Get the program wrapper for the given OpenCL program. */
CCL_EXPORT
CCLProgram* ccl_program_new_wrap(cl_program program);

/* Decrements the reference count of the program wrapper object.
 * If it reaches 0, the program wrapper object is destroyed. */
CCL_EXPORT
void ccl_program_destroy(CCLProgram* prg);

/* *********************** */
/* CREATE FROM SOURCES API */
/* *********************** */

/* Create a new program wrapper object from a source file. */
CCL_EXPORT
CCLProgram* ccl_program_new_from_source_file(CCLContext* ctx,
    const char* filename, CCLErr** err);

/* Create a new program wrapper object from several source files. */
CCL_EXPORT
CCLProgram* ccl_program_new_from_source_files(CCLContext* ctx,
    cl_uint count, const char** filenames, CCLErr** err);

/* Create a new program wrapper object from a null-terminated source
 * string. */
CCL_EXPORT
CCLProgram* ccl_program_new_from_source(CCLContext* ctx,
    const char* string, CCLErr** err);

/* Create a new program wrapper object from several source code
 * strings. */
CCL_EXPORT
CCLProgram* ccl_program_new_from_sources(CCLContext* ctx,
    cl_uint count, const char** strings, const size_t* lengths,
    CCLErr** err);

/* ************************ */
/* CREATE FROM BINARIES API */
/* ************************ */

/* Create a new program wrapper object with binary code from a specific
 * device. */
CCL_EXPORT
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 files containing binary
 * code executable on the given device list, one file per device. */
CCL_EXPORT
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 binary code executable on a
 * specific device. */
CCL_EXPORT
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 a list of binary code
 * strings executable on the given device list, one binary string per
 * device. */
CCL_EXPORT
CCLProgram* ccl_program_new_from_binaries(CCLContext* ctx,
    cl_uint num_devices, CCLDevice* const* devs, CCLProgramBinary** bins,
    cl_int *binary_status, CCLErr** err);

/* ******************************** */
/* CREATE FROM BUILT-IN KERNELS API */
/* ******************************** */

/* Create a new program wrapper object from device built-in kernels. */
CCL_EXPORT
CCLProgram* ccl_program_new_from_built_in_kernels(CCLContext* ctx,
    cl_uint num_devices, CCLDevice* const* devs, const char *kernel_names,
    CCLErr** err);

/* ************************ */
/* BUILD, COMPILE, LINK API */
/* ************************ */

/* Utility function which builds (compiles and links) a program
 * executable from the program source or binary. */
CCL_EXPORT
cl_bool ccl_program_build(
    CCLProgram* prg, const char* options, CCLErr** err);

/* Builds (compiles and links) a program executable from the program
 * source or binary. This function wraps the clBuildProgram() OpenCL
 * function. */
CCL_EXPORT
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);

/* Get a general build log of most recent build, compile or link, for
 * all devices. */
CCL_EXPORT
const char* ccl_program_get_build_log(CCLProgram* prg, CCLErr** err);

/* Get build log for most recent build, compile or link for the
 * specified device. */
CCL_EXPORT
const char* ccl_program_get_device_build_log(
    CCLProgram* prg, CCLDevice* dev, CCLErr** err);

/* Compile a program's source code. */
CCL_EXPORT
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);

/* Link a set of compiled programs. */
CCL_EXPORT
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);

/* ********************** */
/* PROGRAM OPENCL VERSION */
/* ********************** */

/* Get the OpenCL version of the platform associated with this
 * program. */
CCL_EXPORT
cl_uint ccl_program_get_opencl_version(CCLProgram* prg, CCLErr** err);

/* ******************************* */
/* KERNEL RELATED HELPER FUNCTIONS */
/* ******************************* */

/* Get the kernel wrapper object for the given program kernel
 * function. */
CCL_EXPORT
CCLKernel* ccl_program_get_kernel(
    CCLProgram* prg, const char* kernel_name, CCLErr** err);

/* Enqueues a program kernel function for execution on a device. */
CCL_EXPORT
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, ...) G_GNUC_NULL_TERMINATED;

/* Enqueues a program kernel function for execution on a device. */
CCL_EXPORT
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);

/* ************************* */
/* BINARY HANDLING FUNCTIONS */
/* ************************* */

/* Get the program's binary object for the the specified device. */
CCL_EXPORT
CCLProgramBinary* ccl_program_get_binary(
    CCLProgram* prg, CCLDevice* dev, CCLErr** err);

/* Save the program's binary code for a specified device to a file. */
CCL_EXPORT
cl_bool ccl_program_save_binary(CCLProgram* prg, CCLDevice* dev,
    const char* filename, CCLErr** err);

/* Save the program binaries for all associated devices to files, one
 * file per device. */
CCL_EXPORT
cl_bool ccl_program_save_all_binaries(CCLProgram* prg,
    const char* file_prefix, const char* file_suffix, char*** filenames,
    CCLErr** err);

/* ***************************************** */
/* DEVICE CONTAINER FUNCTION IMPLEMENTATIONS */
/* ***************************************** */

/* Get ::CCLDevice wrapper at given index. */
CCL_EXPORT
CCLDevice* ccl_program_get_device(
    CCLProgram* prg, cl_uint index, CCLErr** err);

/* Return number of devices in program. */
CCL_EXPORT
cl_uint ccl_program_get_num_devices(CCLProgram* prg, CCLErr** err);

/* Get all device wrappers in program. */
CCL_EXPORT
CCLDevice* const* ccl_program_get_all_devices(CCLProgram* prg,
    CCLErr** err);

/* ************************************************* */
/* ABSTRACT WRAPPER MACROS (INFO, REF/UNREF, UNWRAP) */
/* ************************************************* */

#define ccl_program_get_info(prg, param_name, err) \
    (param_name == CL_PROGRAM_BINARIES) \
    ? NULL \
    : ccl_wrapper_get_info((CCLWrapper*) prg, NULL, param_name, 0, \
        CCL_INFO_PROGRAM, CL_FALSE, err)

#define ccl_program_get_info_scalar(prg, param_name, param_type, err) \
    (param_name == CL_PROGRAM_BINARIES) \
    ? (param_type) 0 \
    : *((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) prg, \
        NULL, param_name, sizeof(param_type), \
        CCL_INFO_PROGRAM, CL_FALSE, err))

#define ccl_program_get_info_array(prg, param_name, param_type, err) \
    (param_name == CL_PROGRAM_BINARIES) \
    ? NULL \
    : (param_type) ccl_wrapper_get_info_value((CCLWrapper*) prg, \
        NULL, param_name, sizeof(param_type), \
        CCL_INFO_PROGRAM, CL_FALSE, err)

#define ccl_program_get_build_info(prg, dev, param_name, err) \
    ccl_wrapper_get_info((CCLWrapper*) prg, (CCLWrapper*) dev, \
        param_name, 0, CCL_INFO_PROGRAM_BUILD, CL_FALSE, err)

#define ccl_program_get_build_info_scalar(prg, dev, param_name, \
    param_type, err) \
    *((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) prg, \
        (CCLWrapper*) dev, param_name, sizeof(param_type), \
        CCL_INFO_PROGRAM_BUILD, CL_FALSE, err))

#define ccl_program_get_build_info_array(prg, dev, param_name, \
    param_type, err) \
    (param_type) ccl_wrapper_get_info_value((CCLWrapper*) prg, \
        (CCLWrapper*) dev, param_name, sizeof(param_type), \
        CCL_INFO_PROGRAM_BUILD, CL_FALSE, err)

#define ccl_program_ref(prg) \
    ccl_wrapper_ref((CCLWrapper*) prg)

#define ccl_program_unref(prg) ccl_program_destroy(prg)

#define ccl_program_unwrap(prg) \
    ((cl_program) ccl_wrapper_unwrap((CCLWrapper*) prg))

#endif