1 /* 2 * Copyright (C) 2012 Peng Gao <peng@multicorewareinc.com> 3 * Copyright (C) 2012 Li Cao <li@multicorewareinc.com> 4 * Copyright (C) 2012 Wei Gao <weigao@multicorewareinc.com> 5 * Copyright (C) 2013 Lenny Wang <lwanghpc@gmail.com> 6 * 7 * This file is part of FFmpeg. 8 * 9 * FFmpeg is free software; you can redistribute it and/or 10 * modify it under the terms of the GNU Lesser General Public 11 * License as published by the Free Software Foundation; either 12 * version 2.1 of the License, or (at your option) any later version. 13 * 14 * FFmpeg is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 * Lesser General Public License for more details. 18 * 19 * You should have received a copy of the GNU Lesser General Public 20 * License along with FFmpeg; if not, write to the Free Software 21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 22 */ 23 24 /** 25 * @file 26 * OpenCL wrapper 27 * 28 * This interface is considered still experimental and its API and ABI may 29 * change without prior notice. 30 */ 31 32 #ifndef LIBAVUTIL_OPENCL_H 33 #define LIBAVUTIL_OPENCL_H 34 35 #include "config.h" 36 #if HAVE_CL_CL_H 37 #include <CL/cl.h> 38 #else 39 #include <OpenCL/cl.h> 40 #endif 41 #include <stdint.h> 42 #include "dict.h" 43 44 #include "libavutil/version.h" 45 46 #define AV_OPENCL_KERNEL( ... )# __VA_ARGS__ 47 48 #define AV_OPENCL_MAX_KERNEL_NAME_SIZE 150 49 50 #define AV_OPENCL_MAX_DEVICE_NAME_SIZE 100 51 52 #define AV_OPENCL_MAX_PLATFORM_NAME_SIZE 100 53 54 typedef struct { 55 int device_type; 56 char device_name[AV_OPENCL_MAX_DEVICE_NAME_SIZE]; 57 cl_device_id device_id; 58 } AVOpenCLDeviceNode; 59 60 typedef struct { 61 cl_platform_id platform_id; 62 char platform_name[AV_OPENCL_MAX_PLATFORM_NAME_SIZE]; 63 int device_num; 64 AVOpenCLDeviceNode **device_node; 65 } AVOpenCLPlatformNode; 66 67 typedef struct { 68 int platform_num; 69 AVOpenCLPlatformNode **platform_node; 70 } AVOpenCLDeviceList; 71 72 typedef struct { 73 cl_platform_id platform_id; 74 cl_device_type device_type; 75 cl_context context; 76 cl_device_id device_id; 77 cl_command_queue command_queue; 78 char *platform_name; 79 } AVOpenCLExternalEnv; 80 81 /** 82 * Get OpenCL device list. 83 * 84 * It must be freed with av_opencl_free_device_list(). 85 * 86 * @param device_list pointer to OpenCL environment device list, 87 * should be released by av_opencl_free_device_list() 88 * 89 * @return >=0 on success, a negative error code in case of failure 90 */ 91 int av_opencl_get_device_list(AVOpenCLDeviceList **device_list); 92 93 /** 94 * Free OpenCL device list. 95 * 96 * @param device_list pointer to OpenCL environment device list 97 * created by av_opencl_get_device_list() 98 */ 99 void av_opencl_free_device_list(AVOpenCLDeviceList **device_list); 100 101 /** 102 * Set option in the global OpenCL context. 103 * 104 * This options affect the operation performed by the next 105 * av_opencl_init() operation. 106 * 107 * The currently accepted options are: 108 * - platform: set index of platform in device list 109 * - device: set index of device in device list 110 * 111 * See reference "OpenCL Specification Version: 1.2 chapter 5.6.4". 112 * 113 * @param key option key 114 * @param val option value 115 * @return >=0 on success, a negative error code in case of failure 116 * @see av_opencl_get_option() 117 */ 118 int av_opencl_set_option(const char *key, const char *val); 119 120 /** 121 * Get option value from the global OpenCL context. 122 * 123 * @param key option key 124 * @param out_val pointer to location where option value will be 125 * written, must be freed with av_freep() 126 * @return >=0 on success, a negative error code in case of failure 127 * @see av_opencl_set_option() 128 */ 129 int av_opencl_get_option(const char *key, uint8_t **out_val); 130 131 /** 132 * Free option values of the global OpenCL context. 133 * 134 */ 135 void av_opencl_free_option(void); 136 137 /** 138 * Allocate OpenCL external environment. 139 * 140 * It must be freed with av_opencl_free_external_env(). 141 * 142 * @return pointer to allocated OpenCL external environment 143 */ 144 AVOpenCLExternalEnv *av_opencl_alloc_external_env(void); 145 146 /** 147 * Free OpenCL external environment. 148 * 149 * @param ext_opencl_env pointer to OpenCL external environment 150 * created by av_opencl_alloc_external_env() 151 */ 152 void av_opencl_free_external_env(AVOpenCLExternalEnv **ext_opencl_env); 153 154 /** 155 * Get OpenCL error string. 156 * 157 * @param status OpenCL error code 158 * @return OpenCL error string 159 */ 160 const char *av_opencl_errstr(cl_int status); 161 162 /** 163 * Register kernel code. 164 * 165 * The registered kernel code is stored in a global context, and compiled 166 * in the runtime environment when av_opencl_init() is called. 167 * 168 * @param kernel_code kernel code to be compiled in the OpenCL runtime environment 169 * @return >=0 on success, a negative error code in case of failure 170 */ 171 int av_opencl_register_kernel_code(const char *kernel_code); 172 173 /** 174 * Initialize the run time OpenCL environment 175 * 176 * @param ext_opencl_env external OpenCL environment, created by an 177 * application program, ignored if set to NULL 178 * @return >=0 on success, a negative error code in case of failure 179 */ 180 int av_opencl_init(AVOpenCLExternalEnv *ext_opencl_env); 181 182 /** 183 * compile specific OpenCL kernel source 184 * 185 * @param program_name pointer to a program name used for identification 186 * @param build_opts pointer to a string that describes the preprocessor 187 * build options to be used for building the program 188 * @return a cl_program object 189 */ 190 cl_program av_opencl_compile(const char *program_name, const char* build_opts); 191 192 /** 193 * get OpenCL command queue 194 * 195 * @return a cl_command_queue object 196 */ 197 cl_command_queue av_opencl_get_command_queue(void); 198 199 /** 200 * Create OpenCL buffer. 201 * 202 * The buffer is used to save the data used or created by an OpenCL 203 * kernel. 204 * The created buffer must be released with av_opencl_buffer_release(). 205 * 206 * See clCreateBuffer() function reference for more information about 207 * the parameters. 208 * 209 * @param cl_buf pointer to OpenCL buffer 210 * @param cl_buf_size size in bytes of the OpenCL buffer to create 211 * @param flags flags used to control buffer attributes 212 * @param host_ptr host pointer of the OpenCL buffer 213 * @return >=0 on success, a negative error code in case of failure 214 */ 215 int av_opencl_buffer_create(cl_mem *cl_buf, size_t cl_buf_size, int flags, void *host_ptr); 216 217 /** 218 * Write OpenCL buffer with data from src_buf. 219 * 220 * @param dst_cl_buf pointer to OpenCL destination buffer 221 * @param src_buf pointer to source buffer 222 * @param buf_size size in bytes of the source and destination buffers 223 * @return >=0 on success, a negative error code in case of failure 224 */ 225 int av_opencl_buffer_write(cl_mem dst_cl_buf, uint8_t *src_buf, size_t buf_size); 226 227 /** 228 * Read data from OpenCL buffer to memory buffer. 229 * 230 * @param dst_buf pointer to destination buffer (CPU memory) 231 * @param src_cl_buf pointer to source OpenCL buffer 232 * @param buf_size size in bytes of the source and destination buffers 233 * @return >=0 on success, a negative error code in case of failure 234 */ 235 int av_opencl_buffer_read(uint8_t *dst_buf, cl_mem src_cl_buf, size_t buf_size); 236 237 /** 238 * Write image data from memory to OpenCL buffer. 239 * 240 * The source must be an array of pointers to image plane buffers. 241 * 242 * @param dst_cl_buf pointer to destination OpenCL buffer 243 * @param dst_cl_buf_size size in bytes of OpenCL buffer 244 * @param dst_cl_buf_offset the offset of the OpenCL buffer start position 245 * @param src_data array of pointers to source plane buffers 246 * @param src_plane_sizes array of sizes in bytes of the source plane buffers 247 * @param src_plane_num number of source image planes 248 * @return >=0 on success, a negative error code in case of failure 249 */ 250 int av_opencl_buffer_write_image(cl_mem dst_cl_buf, size_t cl_buffer_size, int dst_cl_offset, 251 uint8_t **src_data, int *plane_size, int plane_num); 252 253 /** 254 * Read image data from OpenCL buffer. 255 * 256 * @param dst_data array of pointers to destination plane buffers 257 * @param dst_plane_sizes array of pointers to destination plane buffers 258 * @param dst_plane_num number of destination image planes 259 * @param src_cl_buf pointer to source OpenCL buffer 260 * @param src_cl_buf_size size in bytes of OpenCL buffer 261 * @return >=0 on success, a negative error code in case of failure 262 */ 263 int av_opencl_buffer_read_image(uint8_t **dst_data, int *plane_size, int plane_num, 264 cl_mem src_cl_buf, size_t cl_buffer_size); 265 266 /** 267 * Release OpenCL buffer. 268 * 269 * @param cl_buf pointer to OpenCL buffer to release, which was 270 * previously filled with av_opencl_buffer_create() 271 */ 272 void av_opencl_buffer_release(cl_mem *cl_buf); 273 274 /** 275 * Release OpenCL environment. 276 * 277 * The OpenCL environment is effectively released only if all the created 278 * kernels had been released with av_opencl_release_kernel(). 279 */ 280 void av_opencl_uninit(void); 281 282 /** 283 * Benchmark an OpenCL device with a user defined callback function. This function 284 * sets up an external OpenCL environment including context and command queue on 285 * the device then tears it down in the end. The callback function should perform 286 * the rest of the work. 287 * 288 * @param device pointer to the OpenCL device to be used 289 * @param platform cl_platform_id handle to which the device belongs to 290 * @param benchmark callback function to perform the benchmark, return a 291 * negative value in case of failure 292 * @return the score passed from the callback function, a negative error code in case 293 * of failure 294 */ 295 int64_t av_opencl_benchmark(AVOpenCLDeviceNode *device, cl_platform_id platform, 296 int64_t (*benchmark)(AVOpenCLExternalEnv *ext_opencl_env)); 297 298 #endif /* LIBAVUTIL_OPENCL_H */ 299