| 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 | #if FF_API_OLD_OPENCL |
| 73 | typedef struct { |
| 74 | cl_command_queue command_queue; |
| 75 | cl_kernel kernel; |
| 76 | char kernel_name[AV_OPENCL_MAX_KERNEL_NAME_SIZE]; |
| 77 | } AVOpenCLKernelEnv; |
| 78 | #endif |
| 79 | |
| 80 | typedef struct { |
| 81 | cl_platform_id platform_id; |
| 82 | cl_device_type device_type; |
| 83 | cl_context context; |
| 84 | cl_device_id device_id; |
| 85 | cl_command_queue command_queue; |
| 86 | char *platform_name; |
| 87 | } AVOpenCLExternalEnv; |
| 88 | |
| 89 | /** |
| 90 | * Get OpenCL device list. |
| 91 | * |
| 92 | * It must be freed with av_opencl_free_device_list(). |
| 93 | * |
| 94 | * @param device_list pointer to OpenCL environment device list, |
| 95 | * should be released by av_opencl_free_device_list() |
| 96 | * |
| 97 | * @return >=0 on success, a negative error code in case of failure |
| 98 | */ |
| 99 | int av_opencl_get_device_list(AVOpenCLDeviceList **device_list); |
| 100 | |
| 101 | /** |
| 102 | * Free OpenCL device list. |
| 103 | * |
| 104 | * @param device_list pointer to OpenCL environment device list |
| 105 | * created by av_opencl_get_device_list() |
| 106 | */ |
| 107 | void av_opencl_free_device_list(AVOpenCLDeviceList **device_list); |
| 108 | |
| 109 | /** |
| 110 | * Set option in the global OpenCL context. |
| 111 | * |
| 112 | * This options affect the operation performed by the next |
| 113 | * av_opencl_init() operation. |
| 114 | * |
| 115 | * The currently accepted options are: |
| 116 | * - platform: set index of platform in device list |
| 117 | * - device: set index of device in device list |
| 118 | * |
| 119 | * See reference "OpenCL Specification Version: 1.2 chapter 5.6.4". |
| 120 | * |
| 121 | * @param key option key |
| 122 | * @param val option value |
| 123 | * @return >=0 on success, a negative error code in case of failure |
| 124 | * @see av_opencl_get_option() |
| 125 | */ |
| 126 | int av_opencl_set_option(const char *key, const char *val); |
| 127 | |
| 128 | /** |
| 129 | * Get option value from the global OpenCL context. |
| 130 | * |
| 131 | * @param key option key |
| 132 | * @param out_val pointer to location where option value will be |
| 133 | * written, must be freed with av_freep() |
| 134 | * @return >=0 on success, a negative error code in case of failure |
| 135 | * @see av_opencl_set_option() |
| 136 | */ |
| 137 | int av_opencl_get_option(const char *key, uint8_t **out_val); |
| 138 | |
| 139 | /** |
| 140 | * Free option values of the global OpenCL context. |
| 141 | * |
| 142 | */ |
| 143 | void av_opencl_free_option(void); |
| 144 | |
| 145 | /** |
| 146 | * Allocate OpenCL external environment. |
| 147 | * |
| 148 | * It must be freed with av_opencl_free_external_env(). |
| 149 | * |
| 150 | * @return pointer to allocated OpenCL external environment |
| 151 | */ |
| 152 | AVOpenCLExternalEnv *av_opencl_alloc_external_env(void); |
| 153 | |
| 154 | /** |
| 155 | * Free OpenCL external environment. |
| 156 | * |
| 157 | * @param ext_opencl_env pointer to OpenCL external environment |
| 158 | * created by av_opencl_alloc_external_env() |
| 159 | */ |
| 160 | void av_opencl_free_external_env(AVOpenCLExternalEnv **ext_opencl_env); |
| 161 | |
| 162 | /** |
| 163 | * Get OpenCL error string. |
| 164 | * |
| 165 | * @param status OpenCL error code |
| 166 | * @return OpenCL error string |
| 167 | */ |
| 168 | const char *av_opencl_errstr(cl_int status); |
| 169 | |
| 170 | /** |
| 171 | * Register kernel code. |
| 172 | * |
| 173 | * The registered kernel code is stored in a global context, and compiled |
| 174 | * in the runtime environment when av_opencl_init() is called. |
| 175 | * |
| 176 | * @param kernel_code kernel code to be compiled in the OpenCL runtime environment |
| 177 | * @return >=0 on success, a negative error code in case of failure |
| 178 | */ |
| 179 | int av_opencl_register_kernel_code(const char *kernel_code); |
| 180 | |
| 181 | /** |
| 182 | * Initialize the run time OpenCL environment |
| 183 | * |
| 184 | * @param ext_opencl_env external OpenCL environment, created by an |
| 185 | * application program, ignored if set to NULL |
| 186 | * @return >=0 on success, a negative error code in case of failure |
| 187 | */ |
| 188 | int av_opencl_init(AVOpenCLExternalEnv *ext_opencl_env); |
| 189 | |
| 190 | #if FF_API_OLD_OPENCL |
| 191 | /** |
| 192 | * Create kernel object in the specified kernel environment. |
| 193 | * |
| 194 | * @param env pointer to kernel environment which is filled with |
| 195 | * the environment used to run the kernel |
| 196 | * @param kernel_name kernel function name |
| 197 | * @return >=0 on success, a negative error code in case of failure |
| 198 | * @deprecated, use clCreateKernel |
| 199 | */ |
| 200 | int av_opencl_create_kernel(AVOpenCLKernelEnv *env, const char *kernel_name); |
| 201 | #endif |
| 202 | |
| 203 | /** |
| 204 | * compile specific OpenCL kernel source |
| 205 | * |
| 206 | * @param program_name pointer to a program name used for identification |
| 207 | * @param build_opts pointer to a string that describes the preprocessor |
| 208 | * build options to be used for building the program |
| 209 | * @return a cl_program object |
| 210 | */ |
| 211 | cl_program av_opencl_compile(const char *program_name, const char* build_opts); |
| 212 | |
| 213 | /** |
| 214 | * get OpenCL command queue |
| 215 | * |
| 216 | * @return a cl_command_queue object |
| 217 | */ |
| 218 | cl_command_queue av_opencl_get_command_queue(void); |
| 219 | |
| 220 | /** |
| 221 | * Create OpenCL buffer. |
| 222 | * |
| 223 | * The buffer is used to save the data used or created by an OpenCL |
| 224 | * kernel. |
| 225 | * The created buffer must be released with av_opencl_buffer_release(). |
| 226 | * |
| 227 | * See clCreateBuffer() function reference for more information about |
| 228 | * the parameters. |
| 229 | * |
| 230 | * @param cl_buf pointer to OpenCL buffer |
| 231 | * @param cl_buf_size size in bytes of the OpenCL buffer to create |
| 232 | * @param flags flags used to control buffer attributes |
| 233 | * @param host_ptr host pointer of the OpenCL buffer |
| 234 | * @return >=0 on success, a negative error code in case of failure |
| 235 | */ |
| 236 | int av_opencl_buffer_create(cl_mem *cl_buf, size_t cl_buf_size, int flags, void *host_ptr); |
| 237 | |
| 238 | /** |
| 239 | * Write OpenCL buffer with data from src_buf. |
| 240 | * |
| 241 | * @param dst_cl_buf pointer to OpenCL destination buffer |
| 242 | * @param src_buf pointer to source buffer |
| 243 | * @param buf_size size in bytes of the source and destination buffers |
| 244 | * @return >=0 on success, a negative error code in case of failure |
| 245 | */ |
| 246 | int av_opencl_buffer_write(cl_mem dst_cl_buf, uint8_t *src_buf, size_t buf_size); |
| 247 | |
| 248 | /** |
| 249 | * Read data from OpenCL buffer to memory buffer. |
| 250 | * |
| 251 | * @param dst_buf pointer to destination buffer (CPU memory) |
| 252 | * @param src_cl_buf pointer to source OpenCL buffer |
| 253 | * @param buf_size size in bytes of the source and destination buffers |
| 254 | * @return >=0 on success, a negative error code in case of failure |
| 255 | */ |
| 256 | int av_opencl_buffer_read(uint8_t *dst_buf, cl_mem src_cl_buf, size_t buf_size); |
| 257 | |
| 258 | /** |
| 259 | * Write image data from memory to OpenCL buffer. |
| 260 | * |
| 261 | * The source must be an array of pointers to image plane buffers. |
| 262 | * |
| 263 | * @param dst_cl_buf pointer to destination OpenCL buffer |
| 264 | * @param dst_cl_buf_size size in bytes of OpenCL buffer |
| 265 | * @param dst_cl_buf_offset the offset of the OpenCL buffer start position |
| 266 | * @param src_data array of pointers to source plane buffers |
| 267 | * @param src_plane_sizes array of sizes in bytes of the source plane buffers |
| 268 | * @param src_plane_num number of source image planes |
| 269 | * @return >=0 on success, a negative error code in case of failure |
| 270 | */ |
| 271 | int av_opencl_buffer_write_image(cl_mem dst_cl_buf, size_t cl_buffer_size, int dst_cl_offset, |
| 272 | uint8_t **src_data, int *plane_size, int plane_num); |
| 273 | |
| 274 | /** |
| 275 | * Read image data from OpenCL buffer. |
| 276 | * |
| 277 | * @param dst_data array of pointers to destination plane buffers |
| 278 | * @param dst_plane_sizes array of pointers to destination plane buffers |
| 279 | * @param dst_plane_num number of destination image planes |
| 280 | * @param src_cl_buf pointer to source OpenCL buffer |
| 281 | * @param src_cl_buf_size size in bytes of OpenCL buffer |
| 282 | * @return >=0 on success, a negative error code in case of failure |
| 283 | */ |
| 284 | int av_opencl_buffer_read_image(uint8_t **dst_data, int *plane_size, int plane_num, |
| 285 | cl_mem src_cl_buf, size_t cl_buffer_size); |
| 286 | |
| 287 | /** |
| 288 | * Release OpenCL buffer. |
| 289 | * |
| 290 | * @param cl_buf pointer to OpenCL buffer to release, which was |
| 291 | * previously filled with av_opencl_buffer_create() |
| 292 | */ |
| 293 | void av_opencl_buffer_release(cl_mem *cl_buf); |
| 294 | |
| 295 | #if FF_API_OLD_OPENCL |
| 296 | /** |
| 297 | * Release kernel object. |
| 298 | * |
| 299 | * @param env kernel environment where the kernel object was created |
| 300 | * with av_opencl_create_kernel() |
| 301 | * @deprecated, use clReleaseKernel |
| 302 | */ |
| 303 | void av_opencl_release_kernel(AVOpenCLKernelEnv *env); |
| 304 | #endif |
| 305 | |
| 306 | /** |
| 307 | * Release OpenCL environment. |
| 308 | * |
| 309 | * The OpenCL environment is effectively released only if all the created |
| 310 | * kernels had been released with av_opencl_release_kernel(). |
| 311 | */ |
| 312 | void av_opencl_uninit(void); |
| 313 | |
| 314 | /** |
| 315 | * Benchmark an OpenCL device with a user defined callback function. This function |
| 316 | * sets up an external OpenCL environment including context and command queue on |
| 317 | * the device then tears it down in the end. The callback function should perform |
| 318 | * the rest of the work. |
| 319 | * |
| 320 | * @param device pointer to the OpenCL device to be used |
| 321 | * @param platform cl_platform_id handle to which the device belongs to |
| 322 | * @param benchmark callback function to perform the benchmark, return a |
| 323 | * negative value in case of failure |
| 324 | * @return the score passed from the callback function, a negative error code in case |
| 325 | * of failure |
| 326 | */ |
| 327 | int64_t av_opencl_benchmark(AVOpenCLDeviceNode *device, cl_platform_id platform, |
| 328 | int64_t (*benchmark)(AVOpenCLExternalEnv *ext_opencl_env)); |
| 329 | |
| 330 | #endif /* LIBAVUTIL_OPENCL_H */ |