OpenCL

• OpenCL (Open Computing Language，开放计算语言)
• 一个为异构平台编写程序的框架
• 异构平台可由CPU，GPU或其他类型的处理器组成
• 由一门用于编写kernels（在OpenCL设备上运行的函数）的语言（基于C99）和一组用于定义并控制平台的API组成
• OpenCL提供了基于数据分区和任务分区的并行计算机制

OpenCL架构

OpenCL类图

名词

架构

OpenCL架构

• 硬件模型
• 执行模型
• 内存模型
• 编程模型

硬件模型

• 一个host有一个或者多个device
• 一个device可以分成一个或者多个compute unit
• 一个compute unit可以进一步分成一个或者多个processing element

执行模型

• OpenCL application一般包含两个部分：在一个或多个device上执行的kernel，以及运行在host上的 host program
• kernel如何运行，决定了OpenCL的执行模型
• kernel的实例是一个work-item，并通过 index space 定位
• 一系列的work-item组成work-group，每一个work-group有唯一的work-group ID
• OpenCL里面的 index space 被称为 NDRange，是一个N维的 index space （N=1,2,3）一系列的work-item组成work-group，每一个work-group有唯一的work-group ID

NDRange

Context 以及 Command Queues

Context 包含下面的内容

Devices：host使用的OpenCLdevice

Kernels：在OpenCLdevice上运行的OpenCL函数

Program Objects：能被kernel执行的二进制或者OpenCL C源码

Memory Objects

Command Queues 的类型

Kernel execution commands：在device的processing element上执行kernel

Memory commands：在memory object之间传递数据，从host的地址空间映射memory object

Synchronization commands：控制command执行的顺序

内存模型

• Global Memory：所有work-group里的所有work-item都可以读写的内存区域。根据device的不通，有可能存在缓存
• Constant Memory：Global Memory里的一块内存区域，用于存放kernel运行时的常量
• Local Memory：在work-group中使用的内存区域，work-group里面所有的work-item都可以访问
• Private Memory：Work-item的私有内存区域，其它的work-item无法访问

内存结构

编程模型

• Data Parallel Programming Model
• Task Parallel Programming Model

Platform API

Querying Platform Info

cl_int clGetPlatformIDs (cl_uint num_entries,
                         cl_platform_id *platforms,
                         cl_uint *num_platforms)
						

cl_int clGetPlatformInfo (cl_platform_id platform,
                          cl_platform_info param_name,
                          size_t param_value_size,
                          void *param_value,
                          size_t *param_value_size_ret)
						

Querying Devices

cl_int clGetDeviceIDs (cl_platform_id platform,
                       cl_device_type device_type,
                       cl_uint num_entries,
                       cl_device_id *devices,
                       cl_uint *num_devices)
						

cl_int clGetDeviceInfo (cl_device_id device,
                        cl_device_info param_name,
                        size_t param_value_size,
                        void *param_value,
                        size_t *param_value_size_ret)
						

Partitioning a Device

cl_int clCreateSubDevices (cl_device_id in_device,
                           const cl_device_partition_property *properties,
                           cl_uint num_devices,
                           cl_device_id *out_devices,
                           cl_uint *num_devices_ret)
						

cl_int clRetainDevice (cl_device_id device)
						

cl_int clReleaseDevice (cl_device_id device)
						

Contexts

cl_context
clCreateContext (const cl_context_properties *properties,
                 cl_uint num_devices,
                 const cl_device_id *devices,
                 void (CL_CALLBACK *pfn_notify)(const char *errinfo,
                                                const void *private_info, size_t cb,
                                                void *user_data),
                 void *user_data,
                 cl_int *errcode_ret)
						

cl_int clGetContextInfo (cl_context context,
                         cl_context_info param_name,
                         size_t param_value_size,
                         void *param_value,
                         size_t *param_value_size_ret)
						

Contexts

cl_context
clCreateContextFromType (const cl_context_properties *properties,
                         cl_device_type device_type,
                         void (CL_CALLBACK *pfn_notify)(const char *errinfo,
                                                        const void *private_info, size_t cb,
                                                        void *user_data),
                         void *user_data,
                         cl_int *errcode_ret)
						

cl_int clRetainContext (cl_context context)
						

cl_int clReleaseContext (cl_context context)
						

Runtime API

Command Queues

cl_command_queue clCreateCommandQueue (cl_context context,
                                       cl_device_id device,
                                       cl_command_queue_properties properties,
                                       cl_int *errcode_ret)
						

cl_int clRetainCommandQueue (cl_command_queue command_queue)
						

cl_int clReleaseCommandQueue (cl_command_queue command_queue)
						

cl_int clGetCommandQueueInfo (cl_command_queue command_queue,
                              cl_command_queue_info param_name,
                              size_t param_value_size,
                              void *param_value,
                              size_t *param_value_size_ret)
						

Buffer Objects

cl_mem clCreateBuffer (cl_context context,
                       cl_mem_flags flags,
                       size_t size,
                       void *host_ptr,
                       cl_int *errcode_ret)
						

cl_mem clCreateSubBuffer (cl_mem buffer,
                          cl_mem_flags flags,
                          cl_buffer_create_type buffer_create_type,
                          const void *buffer_create_info,
                          cl_int *errcode_ret)
						

Buffer Objects

cl_int clEnqueueReadBuffer (cl_command_queue command_queue,
                            cl_mem buffer,
                            cl_bool blocking_read,
                            size_t offset,
                            size_t size,
                            void *ptr,
                            cl_uint num_events_in_wait_list,
                            const cl_event *event_wait_list,
                            cl_event *event)
						

Buffer Objects

cl_int clEnqueueWriteBuffer (cl_command_queue command_queue,
                             cl_mem buffer,
                             cl_bool blocking_write,
                             size_t offset,
                             size_t size,
                             const void *ptr,
                             cl_uint num_events_in_wait_list,
                             const cl_event *event_wait_list,
                             cl_event *event)
						

Buffer Objects

入队一个 command，将一块2D或3D矩形区域从buffer object写到host的内存中

cl_int clEnqueueReadBufferRect (cl_command_queue command_queue,
                                cl_mem buffer,
                                cl_bool blocking_read,
                                const size_t *buffer_origin,
                                const size_t *host_origin,
                                const size_t *region,
                                size_t buffer_row_pitch,
                                size_t buffer_slice_pitch,
                                size_t host_row_pitch,
                                size_t host_slice_pitch,
                                void *ptr,
                                cl_uint num_events_in_wait_list,
                                const cl_event *event_wait_list,
                                cl_event *event)
						

Buffer Objects

入队一个 command，将一块2D或3D矩形区域从host的内存中写入到buffer object

cl_int clEnqueueWriteBufferRect (cl_command_queue command_queue,
                                 cl_mem buffer,
                                 cl_bool blocking_write,
                                 const size_t *buffer_origin,
                                 const size_t *host_origin,
                                 const size_t *region,
                                 size_t buffer_row_pitch,
                                 size_t buffer_slice_pitch,
                                 size_t host_row_pitch,
                                 size_t host_slice_pitch,
                                 const void *ptr,
                                 cl_uint num_events_in_wait_list,
                                 const cl_event *event_wait_list,
                                 cl_event *event)
						

Buffer Objects

入队一个 command，将src_buffer指定的buffer object拷贝到由dst_buffer指定的buffer object

cl_int clEnqueueCopyBuffer (cl_command_queue command_queue,
                            cl_mem src_buffer,
                            cl_mem dst_buffer,
                            size_t src_offset,
                            size_t dst_offset,
                            size_t size,
                            cl_uint num_events_in_wait_list,
                            const cl_event *event_wait_list,
                            cl_event *event)
						

Buffer Objects

入队一个 command，将一块2D或3D矩形区域从src_buffer指定的buffer object拷贝到由dst_buffer指定的buffer object

cl_int clEnqueueCopyBufferRect (cl_command_queue command_queue,
                                cl_mem src_buffer,
                                cl_mem dst_buffer,
                                const size_t *src_origin,
                                const size_t *dst_origin,
                                const size_t *region,
                                size_t src_row_pitch,
                                size_t src_slice_pitch,
                                size_t dst_row_pitch,
                                size_t dst_slice_pitch,
                                cl_uint num_events_in_wait_list,
                                const cl_event *event_wait_list,
                                cl_event *event)
						

Buffer Objects

入队一个 command，通过pattern和pattern_size过滤一个buffer object

cl_int clEnqueueFillBuffer (cl_command_queue command_queue,
                            cl_mem buffer,
                            const void *pattern,
                            size_t pattern_size,
                            size_t offset,
                            size_t size,
                            cl_uint num_events_in_wait_list,
                            const cl_event *event_wait_list,
                            cl_event *event)
						

Buffer Objects

入队一个 command，将buffer指定的buffer object映射到host的内存空间中，并返回一个指向映射空间的指针

void * clEnqueueMapBuffer (cl_command_queue command_queue,
                           cl_mem buffer,
                           cl_bool blocking_map,
                           cl_map_flags map_flags,
                           size_t offset,
                           size_t size,
                           cl_uint num_events_in_wait_list,
                           const cl_event *event_wait_list,
                           cl_event *event,
                           cl_int *errcode_ret)
						

Image Objects

Image 格式描述

typedef struct _cl_image_format {
        cl_channel_order  image_channel_order;
        cl_channel_type   image_channel_data_type;
} cl_image_format;
						

Image 描述

typedef struct _cl_image_desc {
        cl_mem_object_type  image_type,
        size_t              image_width;
        size_t              image_height;
        size_t              image_depth;
        size_t              image_array_size;
        size_t              image_row_pitch;
        size_t              image_slice_pitch;
        cl_uint             num_mip_levels;
        cl_uint             num_samples;
        cl_mem              buffer;
} cl_image_desc;
						

Image Objects

创建 1D image，1D image buffer，1D image array，2D image，2D image array 和 3D image object

cl_mem clCreateImage (cl_context context,
                      cl_mem_flags flags,
                      const cl_image_format *image_format,
                      const cl_image_desc *image_desc,
                      void *host_ptr,
                      cl_int *errcode_ret)
						

获取OpenCL实现所支持的 image 格式

cl_int clGetSupportedImageFormats (cl_context context,
                                   cl_mem_flags flags,
                                   cl_mem_object_type image_type,
                                   cl_uint num_entries,
                                   cl_image_format *image_formats,
                                   cl_uint *num_image_formats)
						

Image Objects

入队一个 command，从 image 或者 image array 对象读取到 host 的内存中

cl_int clEnqueueReadImage (cl_command_queue command_queue,
                           cl_mem image,
                           cl_bool blocking_read,
                           const size_t *origin,
                           const size_t *region,
                           size_t row_pitch,
                           size_t slice_pitch,
                           void *ptr,
                           cl_uint num_events_in_wait_list,
                           const cl_event *event_wait_list,
                           cl_event *event)
						

Image Objects

入队一个 command，从 host 的内存中将数据写入到 image 或者 image array 对象

cl_int clEnqueueWriteImage (cl_command_queue command_queue,
                            cl_mem image,
                            cl_bool blocking_write,
                            const size_t *origin,
                            const size_t *region,
                            size_t input_row_pitch,
                            size_t input_slice_pitch,
                            const void * ptr,
                            cl_uint num_events_in_wait_list,
                            const cl_event *event_wait_list,
                            cl_event *event)
						

Image Objects

入队一个 command，拷贝 image 对象，src_image和dst_image可以为 1D, 2D, 3D image 或者 a 1D, 2D image array

cl_int clEnqueueCopyImage (cl_command_queue command_queue,
                           cl_mem src_image,
                           cl_mem dst_image,
                           const size_t *src_origin,
                           const size_t *dst_origin,
                           const size_t *region,
                           cl_uint num_events_in_wait_list,
                           const cl_event *event_wait_list,
                           cl_event *event)
						

Image Objects

入队一个 command，将 image 对象填充特定的颜色fill_color

cl_int clEnqueueFillImage (cl_command_queue command_queue,
                           cl_mem image,
                           const void *fill_color,
                           const size_t *origin,
                           const size_t *region,
                           cl_uint num_events_in_wait_list,
                           const cl_event *event_wait_list,
                           cl_event *event)
						

Image Objects

入队一个 command，拷贝 image 对象src_image到 buffer 对象dst_buffer

cl_int clEnqueueCopyImageToBuffer (cl_command_queue command_queue,
                                   cl_mem src_image,
                                   cl_mem dst_buffer,
                                   const size_t *src_origin,
                                   const size_t *region,
                                   size_t dst_offset,
                                   cl_uint num_events_in_wait_list,
                                   const cl_event *event_wait_list,
                                   cl_event *event)
						

Image Objects

入队一个 command，拷贝 buffer 对象dst_buffer到 image 对象src_image

cl_int clEnqueueCopyBufferToImage (cl_command_queue command_queue,
                                   cl_mem src_buffer,
                                   cl_mem dst_image,
                                   size_t src_offset,
                                   const size_t *dst_origin,
                                   const size_t *region,
                                   cl_uint num_events_in_wait_list,
                                   const cl_event *event_wait_list,
                                   cl_event *event)
						

Image Objects

入队一个 command，将 image 对象image内的一块区域映射到 host 的内存空间，并返回一个指向该空间的指针

void * clEnqueueMapImage (cl_command_queue command_queue,
                          cl_mem image,
                          cl_bool blocking_map,
                          cl_map_flags map_flags,
                          const size_t *origin,
                          const size_t *region,
                          size_t *image_row_pitch,
                          size_t *image_slice_pitch,
                          cl_uint num_events_in_wait_list,
                          const cl_event *event_wait_list,
                          cl_event *event,
                          cl_int *errcode_ret)
						

Image Objects

获取 image 对象image的信息

cl_int clGetImageInfo (cl_mem image,
                       cl_image_info param_name,
                       size_t param_value_size,
                       void *param_value,
                       size_t *param_value_size_ret)
						

Memory Objects

cl_int clRetainMemObject (cl_mem memobj)
						

cl_int clReleaseMemObject (cl_mem memobj)
						

注册一个 memory 对象销毁时的回调函数

cl_int clSetMemObjectDestructorCallback (cl_mem memobj,
                                         void (CL_CALLBACK *pfn_notify)(cl_mem memobj,
                                                                        void *user_data),
                                         void *user_data)
						

Memory Objects

入队一个 command，将之前映射过的 memory 对象取消映射关系

cl_int clEnqueueUnmapMemObject (cl_command_queue command_queue,
                                cl_mem memobj,
                                void *mapped_ptr,
                                cl_uint num_events_in_wait_list,
                                const cl_event *event_wait_list,
                                cl_event *event)
						

入队一个 command，用于在不同的 device 间同步 memory 对象

cl_int clEnqueueMigrateMemObjects (cl_command_queue command_queue,
                                   cl_uint num_mem_objects,
                                   const cl_mem *mem_objects,
                                   cl_mem_migration_flags flags,
                                   cl_uint num_events_in_wait_list,
                                   const cl_event *event_wait_list,
                                   cl_event *event)
						

Memory Objects

获取 memory 对象memobj的信息

cl_int clGetMemObjectInfo (cl_mem memobj,
                           cl_mem_info param_name,
                           size_t param_value_sizMemorye,
                           void *param_value,
                           size_t *param_value_size_ret)
						

Sampler Objects

创建 sampler 对象cl_sampler

cl_sampler clCreateSampler (cl_context context,
                            cl_bool normalized_coords,
                            cl_addressing_mode addressing_mode,
                            cl_filter_mode filter_mode,
                            cl_int *errcode_ret)
						

cl_int clRetainSampler (cl_sampler sampler)
						

cl_int clReleaseSampler (cl_sampler sampler)
						

Sampler Objects

获取 sampler 对象sampler信息

cl_int clGetSamplerInfo (cl_sampler sampler,
                         cl_sampler_info param_name,
                         size_t param_value_size,
                         void *param_value,
                         size_t *param_value_size_ret)
						

Program Objects

通过文本源码strings创建 program 对象

cl_program clCreateProgramWithSource (cl_context context,
                                      cl_uint count,
                                      const char **strings,
                                      const size_t *lengths,
                                      cl_int *errcode_ret)
						

通过二进制内容binaries创建 program 对象

cl_program clCreateProgramWithBinary (cl_context context,
                                      cl_uint num_devices,
                                      const cl_device_id *device_list,
                                      const size_t *lengths,
                                      const unsigned char **binaries,
                                      cl_int *binary_status,
                                      cl_int *errcode_ret)
						

Program Objects

通过内建的 kernel kernel_names创建 program 对象

cl_program clCreateProgramWithBuiltInKernels (cl_context context,
                                              cl_uint num_devices,
                                              const cl_device_id *device_list,
                                              const char *kernel_names,
                                              cl_int *errcode_ret)
						

cl_int clRetainProgram (cl_program program)
						

cl_int clReleaseProgram (cl_program program)
						

Program Objects

构建(build) program 对象，包含了编译(compile)和链接(link)两个步骤，一起完成

cl_int clBuildProgram (cl_program program,
                       cl_uint num_devices,
                       const cl_device_id *device_list,
                       const char *options,
                       void (CL_CALLBACK *pfn_notify)(cl_program program,
                                                      void *user_data),
                       void *user_data)
						

Program Objects

编译(compile) program 对象

cl_int clCompileProgram (cl_program program,
                         cl_uint num_devices,
                         const cl_device_id *device_list,
                         const char *options,
                         cl_uint num_input_headers,
                         const cl_program *input_headers,
                         const char **header_include_names,
                         void (CL_CALLBACK *pfn_notify)(cl_program program,
                                                        void *user_data),
                         void *user_data)
						

Program Objects

链接(link) program 对象

cl_program clLinkProgram (cl_context context,
                          cl_uint num_devices,
                          const cl_device_id *device_list,
                          const char *options,
                          cl_uint num_input_programs,
                          const cl_program *input_programs,
                          void (CL_CALLBACK *pfn_notify)(cl_program program,
                                                         void *user_data),
                          void *user_data,
                          cl_int *errcode_ret)
						

Compiler Options

预处理选项

-D name

-D name=definition

-I dir

数学内部函数选项

-cl-single-precision-constant

-cl-denorms-are-zero

-cl-fp32-correctly-rounded-divide-sqrt

优化选项

-cl-opt-disable

-cl-mad-enable

-cl-no-signed-zeros

-cl-unsafe-math-optimizations

-cl-finite-math-only

-cl-fast-relaxed-math

Compiler Options

请求或禁止显示警告

-w

-Werror

OpenCL C 版本

-cl-std=

Kernel 参数信息

-cl-kernel-arg-info

Linker Options

Library 链接选项

-create-library

-enable-link-options

Program 链接选项

-cl-denorms-are-zero

-cl-no-signed-zeroes

-cl-unsafe-math-optimizations

-cl-finite-math-only

-cl-fast-relaxed-math

Program Objects

释放编译(compile) program 对象时用到的资源

cl_int clUnloadPlatformCompiler (cl_platform_id platform)
						

获取 program 对象的信息

cl_int clGetProgramInfo (cl_program program,
                         cl_program_info param_name,
                         size_t param_value_size,
                         void *param_value,
                         size_t *param_value_size_ret)
						

Program Objects

获取 program 对象构建(build)的信息

cl_int clGetProgramBuildInfo (cl_program program,
                              cl_device_id device,
                              cl_program_build_info param_name,
                              size_t param_value_size,
                              void *param_value,
                              size_t *param_value_size_ret)
						

Kernel Objects

创建一个 kernel 对象

cl_kernel clCreateKernel (cl_program program,
                          const char *kernel_name,
                          cl_int *errcode_ret)
						

创建 program 里面所有的 kernel 对象

cl_int clCreateKernelsInProgram (cl_program program,
                                 cl_uint num_kernels,
                                 cl_kernel *kernels,
                                 cl_uint *num_kernels_ret)
						

cl_int clRetainKernel (cl_kernel kernel)
						

cl_int clReleaseKernel (cl_kernel kernel)
						

Kernel Objects

设置 kernel 参数

cl_int clSetKernelArg (cl_kernel kernel,
                       cl_uint arg_index,
                       size_t arg_size,
                       const void *arg_value)
						

获取 kernel 参数信息

cl_int clGetKernelArgInfo (cl_kernel kernel,
                           cl_uint arg_indx,
                           cl_kernel_arg_info param_name,
                           size_t param_value_size,
                           void *param_value,
                           size_t *param_value_size_ret)
						

Kernel Objects

获取 kernel 对象的信息

cl_int clGetKernelInfo (cl_kernel kernel,
                        cl_kernel_info param_name,
                        size_t param_value_size,
                        void *param_value,
                        size_t *param_value_size_ret)
						

获取 kernel 对象里面 work-group 的信息

cl_int clGetKernelWorkGroupInfo (cl_kernel kernel,
                                 cl_device_id device,
                                 cl_kernel_work_group_info param_name,
                                 size_t param_value_size,
                                 void *param_value,
                                 size_t *param_value_size_ret)
						

Executing Kernels

入队一个 command，在 kernel 里面执行，Data Parallel Programming Model

cl_int clEnqueueNDRangeKernel (cl_command_queue command_queue,
                               cl_kernel kernel,
                               cl_uint work_dim,
                               const size_t *global_work_offset,
                               const size_t *global_work_size,
                               const size_t *local_work_size,
                               cl_uint num_events_in_wait_list,
                               const cl_event *event_wait_list,
                               cl_event *event)
						

Executing Kernels

入队一个 command，在 kernel 里面执行，Task Parallel Programming Model

cl_int clEnqueueTask (cl_command_queue command_queue,
                      cl_kernel kernel,
                      cl_uint num_events_in_wait_list,
                      const cl_event *event_wait_list,
                      cl_event *event)
						

Executing Kernels

入队一个 command，执行 native kernel

cl_int clEnqueueNativeKernel (cl_command_queue command_queue,
                              void (CL_CALLBACK *user_func)(void *)
                              void *args,
                              size_t cb_args,
                              cl_uint num_mem_objects,
                              const cl_mem *mem_list,
                              const void **args_mem_loc,
                              cl_uint num_events_in_wait_list,
                              const cl_event *event_wait_list,
                              cl_event *event)
						

Event Objects

kernel execution command

Event Objects

memory objects command

Event Objects

cl_event clCreateUserEvent (cl_context context, cl_int *errcode_ret)
						

cl_int clSetUserEventStatus (cl_event event, cl_int execution_status)
						

cl_int clWaitForEvents (cl_uint num_events, const cl_event *event_list)
						

cl_int clGetEventInfo (cl_event event,
                       cl_event_info param_name,
                       size_t param_value_size,
                       void *param_value,
                       size_t *param_value_size_ret)
						

Event Objects

cl_int clSetEventCallback (cl_event event,
                           cl_int command_exec_callback_type,
                           void (CL_CALLBACK *pfn_event_notify)(cl_event event,
                                                                cl_int event_command_exec_status,
                                                                void *user_data),
                           void *user_data)
						

cl_int clRetainEvent (cl_event event)
						

cl_int clReleaseEvent (cl_event event)
						

Markers

cl_int clEnqueueMarkerWithWaitList (cl_command_queue command_queue,
                                    cl_uint num_events_in_wait_list,
                                    const cl_event *event_wait_list,
                                    cl_event *event)
						

Barriers

cl_int clEnqueueBarrierWithWaitList (cl_command_queue command_queue,
                                     cl_uint num_events_in_wait_list,
                                     const cl_event *event_wait_list,
                                     cl_event *event)
						

Profiling

cl_int clGetEventProfilingInfo (cl_event event,
                                cl_profiling_info param_name,
                                size_t param_value_size,
                                void *param_value,
                                size_t *param_value_size_ret)
						

Flush

cl_int clFlush (cl_command_queue command_queue)
						

Finish

cl_int clFinish (cl_command_queue command_queue)
						

OpenCL C

Querying Platform Info

cl_int clGetPlatformIDs (cl_uint num_entries,
                         cl_platform_id *platforms,
                         cl_uint *num_platforms)
						

cl_int clGetPlatformInfo (cl_platform_id platform,
                          cl_platform_info param_name,
                          size_t param_value_size,
                          void *param_value,
                          size_t *param_value_size_ret)