Loading...
Searching...
No Matches
OpenCL Extensions

## Data Structures

struct | starpu_opencl_program

## Macros

#define | STARPU_USE_OPENCL
#define | STARPU_OPENCL_DATADIR
#define | STARPU_MAXOPENCLDEVS

## 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).

void | starpu_opencl_load_program_source (const char *source_file_name, char *located_file_name, char *located_dir_name, char *opencl_program_source)
void | starpu_opencl_load_program_source_malloc (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)
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)

## 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

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_allocate_memory (int devid, cl_mem *addr, size_t size, cl_mem_flags flags)
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)
#define | STARPU_OPENCL_DISPLAY_ERROR(status)
#define | STARPU_OPENCL_REPORT_ERROR(status)
#define | STARPU_OPENCL_REPORT_ERROR_WITH_MSG(msg, status)

## Detailed Description

## Data Structure Documentation

## starpu_opencl_program

struct starpu_opencl_program

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

Data Fields
cl_program | programs[STARPU_MAXOPENCLDEVS] | Store each program for each OpenCL device.

## Macro Definition Documentation

## STARPU_USE_OPENCL

#define STARPU_USE_OPENCL

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.

## STARPU_OPENCL_DATADIR

#define STARPU_OPENCL_DATADIR

Define the directory in which the OpenCL codelets of the applications provided with StarPU have been installed.

## STARPU_MAXOPENCLDEVS

#define STARPU_MAXOPENCLDEVS

Define the maximum number of OpenCL devices that are supported by StarPU.

## STARPU_OPENCL_DISPLAY_ERROR

#define STARPU_OPENCL_DISPLAY_ERROR | ( |  | status | ) |

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

## STARPU_OPENCL_REPORT_ERROR

#define STARPU_OPENCL_REPORT_ERROR | ( |  | status | ) |

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

## STARPU_OPENCL_REPORT_ERROR_WITH_MSG

#define STARPU_OPENCL_REPORT_ERROR_WITH_MSG | ( |  | msg,
|  |  | status
| ) |  |

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

## Function Documentation

## starpu_opencl_get_context()

void starpu_opencl_get_context | ( | int | devid,
|  | cl_context * | context
| ) |  |

Return the OpenCL context of the device designated by `devid` in `context`.

## starpu_opencl_get_device()

void starpu_opencl_get_device | ( | int | devid,
|  | cl_device_id * | device
| ) |  |

Return the cl_device_id corresponding to `devid` in `device`.

## starpu_opencl_get_queue()

void starpu_opencl_get_queue | ( | int | devid,
|  | cl_command_queue * | queue
| ) |  |

Return the command queue of the device designated by `devid` into `queue`.

## starpu_opencl_get_current_context()

void starpu_opencl_get_current_context | ( | cl_context * | context | ) |

Return the context of the current worker.

## starpu_opencl_get_current_queue()

void starpu_opencl_get_current_queue | ( | cl_command_queue * | queue | ) |

Return the computation kernel command queue of the current worker.

## starpu_opencl_set_kernel_args()

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

Set 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. Return the number of arguments that were successfully set. In case of failure, return the id of the argument that could not be set and `err` is set to the error returned by OpenCL. Otherwise, return 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);
starpu_opencl_set_kernel_args
int starpu_opencl_set_kernel_args(cl_int *err, cl_kernel *kernel,...)

## starpu_opencl_load_program_source()

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.

## starpu_opencl_load_program_source_malloc()

void starpu_opencl_load_program_source_malloc | ( | const char * | source_file_name,
|  | char ** | located_file_name,
|  | char ** | located_dir_name,
|  | char ** | opencl_program_source
| ) |  |

Similar to function starpu_opencl_load_program_source() but allocate the buffers `located_file_name`, `located_dir_name` and `opencl_program_source`.

## starpu_opencl_compile_opencl_from_file()

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 store 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.

## starpu_opencl_compile_opencl_from_string()

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 store 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.

## starpu_opencl_load_binary_opencl()

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>`.

## starpu_opencl_load_opencl_from_file()

int starpu_opencl_load_opencl_from_file | ( | const char * | source_file_name,
|  | struct starpu_opencl_program * | opencl_programs,
|  | const char * | build_options
| ) |  |

Compile an OpenCL source code stored in a file.

## starpu_opencl_load_opencl_from_string()

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

Compile an OpenCL source code stored in a string.

## starpu_opencl_unload_opencl()

int starpu_opencl_unload_opencl | ( | struct starpu_opencl_program * | opencl_programs | ) |

Unload an OpenCL compiled code.

## starpu_opencl_load_kernel()

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`.

## starpu_opencl_release_kernel()

int starpu_opencl_release_kernel | ( | cl_kernel | kernel | ) |

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

## starpu_opencl_collect_stats()

int starpu_opencl_collect_stats | ( | cl_event | event | ) |

Collect statistics on a kernel execution. After termination of the kernels, the OpenCL codelet should call this function with the event returned by `clEnqueueNDRangeKernel()`, to let StarPU collect statistics about the kernel execution (used cycles, consumed energy).

## starpu_opencl_error_string()

const char * starpu_opencl_error_string | ( | cl_int | status | ) |

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

## starpu_opencl_display_error()

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

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

## starpu_opencl_report_error()

static __starpu_inline 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.

## starpu_opencl_allocate_memory()

cl_int starpu_opencl_allocate_memory | ( | int | devid,
|  | cl_mem * | addr,
|  | size_t | size,
|  | cl_mem_flags | flags
| ) |  |

Allocate `size` bytes of memory, stored in `addr`. `flags` must be a valid combination of `cl_mem_flags` values.

## starpu_opencl_copy_ram_to_opencl()

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`.

## starpu_opencl_copy_opencl_to_ram()

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`.

## starpu_opencl_copy_opencl_to_opencl()

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`.

## starpu_opencl_copy_async_sync()

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.