StarPU Handbook
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Macros
OpenCL Extensions

Data Structures

struct  starpu_opencl_program

Macros

#define STARPU_USE_OPENCL
#define STARPU_MAXOPENCLDEVS
#define STARPU_OPENCL_DATADIR

Writing OpenCL kernels

void starpu_opencl_get_context (int devid, cl_context *context)
void starpu_opencl_get_device (int devid, cl_device_id *device)
void starpu_opencl_get_queue (int devid, cl_command_queue *queue)
void starpu_opencl_get_current_context (cl_context *context)
void starpu_opencl_get_current_queue (cl_command_queue *queue)
int starpu_opencl_set_kernel_args (cl_int *err, cl_kernel *kernel,...)

Compiling OpenCL kernels

Source codes for OpenCL kernels can be stored in a file or in a string. StarPU provides functions to build the program executable for each available OpenCL device as a cl_program object. This program executable can then be loaded within a specific queue as explained in the next section. These are only helpers, Applications can also fill a starpu_opencl_program array by hand for more advanced use (e.g. different programs on the different OpenCL devices, for relocation purpose for instance).

int starpu_opencl_load_opencl_from_file (const char *source_file_name, struct starpu_opencl_program *opencl_programs, const char *build_options)
int starpu_opencl_load_opencl_from_string (const char *opencl_program_source, struct starpu_opencl_program *opencl_programs, const char *build_options)
int starpu_opencl_unload_opencl (struct starpu_opencl_program *opencl_programs)
void starpu_opencl_load_program_source (const char *source_file_name, char *located_file_name, char *located_dir_name, char *opencl_program_source)
int starpu_opencl_compile_opencl_from_file (const char *source_file_name, const char *build_options)
int starpu_opencl_compile_opencl_from_string (const char *opencl_program_source, const char *file_name, const char *build_options)
int starpu_opencl_load_binary_opencl (const char *kernel_id, struct starpu_opencl_program *opencl_programs)

Loading OpenCL kernels

int starpu_opencl_load_kernel (cl_kernel *kernel, cl_command_queue *queue, struct starpu_opencl_program *opencl_programs, const char *kernel_name, int devid)
int starpu_opencl_release_kernel (cl_kernel kernel)

OpenCL statistics

int starpu_opencl_collect_stats (cl_event event)

OpenCL utilities

#define STARPU_OPENCL_DISPLAY_ERROR(status)
#define STARPU_OPENCL_REPORT_ERROR(status)
#define STARPU_OPENCL_REPORT_ERROR_WITH_MSG(msg, status)
const char * starpu_opencl_error_string (cl_int status)
void starpu_opencl_display_error (const char *func, const char *file, int line, const char *msg, cl_int status)
static __starpu_inline void starpu_opencl_report_error (const char *func, const char *file, int line, const char *msg, cl_int status)
cl_int starpu_opencl_copy_ram_to_opencl (void *ptr, unsigned src_node, cl_mem buffer, unsigned dst_node, size_t size, size_t offset, cl_event *event, int *ret)
cl_int starpu_opencl_copy_opencl_to_ram (cl_mem buffer, unsigned src_node, void *ptr, unsigned dst_node, size_t size, size_t offset, cl_event *event, int *ret)
cl_int starpu_opencl_copy_opencl_to_opencl (cl_mem src, unsigned src_node, size_t src_offset, cl_mem dst, unsigned dst_node, size_t dst_offset, size_t size, cl_event *event, int *ret)
cl_int starpu_opencl_copy_async_sync (uintptr_t src, size_t src_offset, unsigned src_node, uintptr_t dst, size_t dst_offset, unsigned dst_node, size_t size, cl_event *event)

Detailed Description


Data Structure Documentation

struct starpu_opencl_program

Stores the OpenCL programs as compiled for the different OpenCL devices.

Data Fields
cl_program programs Stores each program for each OpenCL device.

Macro Definition Documentation

#define STARPU_USE_OPENCL

This macro is defined when StarPU has been installed with OpenCL support. It should be used in your code to detect the availability of OpenCL as shown in Full source code for the ’Scaling a Vector’ example.

#define STARPU_MAXOPENCLDEVS

This macro defines the maximum number of OpenCL devices that are supported by StarPU.

#define STARPU_OPENCL_DATADIR

This macro defines the directory in which the OpenCL codelets of the applications provided with StarPU have been installed.

#define STARPU_OPENCL_DISPLAY_ERROR (   status)

Call the function starpu_opencl_display_error() with the given error status, the current function name, current file and line number, and a empty message.

#define STARPU_OPENCL_REPORT_ERROR (   status)

Call the function starpu_opencl_report_error() with the given error status, with the current function name, current file and line number, and a empty message.

#define STARPU_OPENCL_REPORT_ERROR_WITH_MSG (   msg,
  status 
)

Call the function starpu_opencl_report_error() with the given msg and the given error status, with the current function name, current file and line number.

Function Documentation

void starpu_opencl_get_context ( int  devid,
cl_context *  context 
)

Places the OpenCL context of the device designated by devid into context.

void starpu_opencl_get_device ( int  devid,
cl_device_id *  device 
)

Places the cl_device_id corresponding to devid in device.

void starpu_opencl_get_queue ( int  devid,
cl_command_queue *  queue 
)

Places the command queue of the device designated by devid into queue.

void starpu_opencl_get_current_context ( cl_context *  context)

Return the context of the current worker.

void starpu_opencl_get_current_queue ( cl_command_queue *  queue)

Return the computation kernel command queue of the current worker.

int starpu_opencl_set_kernel_args ( cl_int *  err,
cl_kernel *  kernel,
  ... 
)

Sets the arguments of a given kernel. The list of arguments must be given as (size_t size_of_the_argument, cl_mem * pointer_to_the_argument). The last argument must be 0. Returns the number of arguments that were successfully set. In case of failure, returns the id of the argument that could not be set and err is set to the error returned by OpenCL. Otherwise, returns the number of arguments that were set.

Here an example:

int n;
cl_int err;
cl_kernel kernel;
n = starpu_opencl_set_kernel_args(&err, 2, &kernel,
sizeof(foo), &foo,
sizeof(bar), &bar,
0);
if (n != 2)
fprintf(stderr, "Error : %d\n", err);
int starpu_opencl_load_opencl_from_file ( const char *  source_file_name,
struct starpu_opencl_program opencl_programs,
const char *  build_options 
)

This function compiles an OpenCL source code stored in a file.

int starpu_opencl_load_opencl_from_string ( const char *  opencl_program_source,
struct starpu_opencl_program opencl_programs,
const char *  build_options 
)

This function compiles an OpenCL source code stored in a string.

int starpu_opencl_unload_opencl ( struct starpu_opencl_program opencl_programs)

This function unloads an OpenCL compiled code.

void starpu_opencl_load_program_source ( const char *  source_file_name,
char *  located_file_name,
char *  located_dir_name,
char *  opencl_program_source 
)

Store the contents of the file source_file_name in the buffer opencl_program_source. The file source_file_name can be located in the current directory, or in the directory specified by the environment variable STARPU_OPENCL_PROGRAM_DIR, or in the directory share/starpu/opencl of the installation directory of StarPU, or in the source directory of StarPU. When the file is found, located_file_name is the full name of the file as it has been located on the system, located_dir_name the directory where it has been located. Otherwise, they are both set to the empty string.

int starpu_opencl_compile_opencl_from_file ( const char *  source_file_name,
const char *  build_options 
)

Compile the OpenCL kernel stored in the file source_file_name with the given options build_options and stores the result in the directory $STARPU_HOME/.starpu/opencl with the same filename as source_file_name. The compilation is done for every OpenCL device, and the filename is suffixed with the vendor id and the device id of the OpenCL device.

int starpu_opencl_compile_opencl_from_string ( const char *  opencl_program_source,
const char *  file_name,
const char *  build_options 
)

Compile the OpenCL kernel in the string opencl_program_source with the given options build_options and stores the result in the directory $STARPU_HOME/.starpu/opencl with the filename file_name. The compilation is done for every OpenCL device, and the filename is suffixed with the vendor id and the device id of the OpenCL device.

int starpu_opencl_load_binary_opencl ( const char *  kernel_id,
struct starpu_opencl_program opencl_programs 
)

Compile the binary OpenCL kernel identified with kernel_id. For every OpenCL device, the binary OpenCL kernel will be loaded from the file $STARPU_HOME/.starpu/opencl/<kernel_id>.<device_type>.vendor_id_<vendor_id>_device_id_<device_id>.

int starpu_opencl_load_kernel ( cl_kernel *  kernel,
cl_command_queue *  queue,
struct starpu_opencl_program opencl_programs,
const char *  kernel_name,
int  devid 
)

Create a kernel kernel for device devid, on its computation command queue returned in queue, using program opencl_programs and name kernel_name.

int starpu_opencl_release_kernel ( cl_kernel  kernel)

Release the given kernel, to be called after kernel execution.

int starpu_opencl_collect_stats ( cl_event  event)

This function allows to collect statistics on a kernel execution. After termination of the kernels, the OpenCL codelet should call this function to pass it the even returned by clEnqueueNDRangeKernel, to let StarPU collect statistics about the kernel execution (used cycles, consumed power).

const char * starpu_opencl_error_string ( cl_int  status)

Return the error message in English corresponding to status, an OpenCL error code.

void starpu_opencl_display_error ( const char *  func,
const char *  file,
int  line,
const char *  msg,
cl_int  status 
)

Given a valid error status, prints the corresponding error message on stdout, along with the given function name func, the given filename file, the given line number line and the given message msg.

void starpu_opencl_report_error ( const char *  func,
const char *  file,
int  line,
const char *  msg,
cl_int  status 
)
static

Call the function starpu_opencl_display_error() and abort.

cl_int starpu_opencl_copy_ram_to_opencl ( void *  ptr,
unsigned  src_node,
cl_mem  buffer,
unsigned  dst_node,
size_t  size,
size_t  offset,
cl_event *  event,
int *  ret 
)

Copy size bytes from the given ptr on RAM src_node to the given buffer on OpenCL dst_node. offset is the offset, in bytes, in buffer. if event is NULL, the copy is synchronous, i.e the queue is synchronised before returning. If not NULL, event can be used after the call to wait for this particular copy to complete. This function returns CL_SUCCESS if the copy was successful, or a valid OpenCL error code otherwise. The integer pointed to by ret is set to -EAGAIN if the asynchronous launch was successful, or to 0 if event was NULL.

cl_int starpu_opencl_copy_opencl_to_ram ( cl_mem  buffer,
unsigned  src_node,
void *  ptr,
unsigned  dst_node,
size_t  size,
size_t  offset,
cl_event *  event,
int *  ret 
)

Copy size bytes asynchronously from the given buffer on OpenCL src_node to the given ptr on RAM dst_node. offset is the offset, in bytes, in buffer. if event is NULL, the copy is synchronous, i.e the queue is synchronised before returning. If not NULL, event can be used after the call to wait for this particular copy to complete. This function returns CL_SUCCESS if the copy was successful, or a valid OpenCL error code otherwise. The integer pointed to by ret is set to -EAGAIN if the asynchronous launch was successful, or to 0 if event was NULL.

cl_int starpu_opencl_copy_opencl_to_opencl ( cl_mem  src,
unsigned  src_node,
size_t  src_offset,
cl_mem  dst,
unsigned  dst_node,
size_t  dst_offset,
size_t  size,
cl_event *  event,
int *  ret 
)

Copy size bytes asynchronously from byte offset src_offset of src on OpenCL src_node to byte offset dst_offset of dst on OpenCL dst_node. if event is NULL, the copy is synchronous, i.e. the queue is synchronised before returning. If not NULL, event can be used after the call to wait for this particular copy to complete. This function returns CL_SUCCESS if the copy was successful, or a valid OpenCL error code otherwise. The integer pointed to by ret is set to -EAGAIN if the asynchronous launch was successful, or to 0 if event was NULL.

cl_int starpu_opencl_copy_async_sync ( uintptr_t  src,
size_t  src_offset,
unsigned  src_node,
uintptr_t  dst,
size_t  dst_offset,
unsigned  dst_node,
size_t  size,
cl_event *  event 
)

Copy size bytes from byte offset src_offset of src on src_node to byte offset dst_offset of dst on dst_node. if event is NULL, the copy is synchronous, i.e. the queue is synchronised before returning. If not NULL, event can be used after the call to wait for this particular copy to complete. The function returns -EAGAIN if the asynchronous launch was successfull. It returns 0 if the synchronous copy was successful, or fails otherwise.