NAME OpenCL - Open Computing Language Bindings SYNOPSIS use OpenCL; DESCRIPTION This is an early release which might be useful, but hasn't seen much testing. OpenCL FROM 10000 FEET HEIGHT Here is a high level overview of OpenCL: First you need to find one or more OpenCL::Platforms (kind of like vendors) - usually there is only one. Each platform gives you access to a number of OpenCL::Device objects, e.g. your graphics card. From a platform and some device(s), you create an OpenCL::Context, which is a very central object in OpenCL: Once you have a context you can create most other objects: OpenCL::Program objects, which store source code and, after building for a specific device ("compiling and linking"), also binary programs. For each kernel function in a program you can then create an OpenCL::Kernel object which represents basically a function call with argument values. OpenCL::Memory objects of various flavours: OpenCL::Buffers objects (flat memory areas, think arrays or structs) and OpenCL::Image objects (think 2d or 3d array) for bulk data and input and output for kernels. OpenCL::Sampler objects, which are kind of like texture filter modes in OpenGL. OpenCL::Queue objects - command queues, which allow you to submit memory reads, writes and copies, as well as kernel calls to your devices. They also offer a variety of methods to synchronise request execution, for example with barriers or OpenCL::Event objects. OpenCL::Event objects are used to signal when something is complete. HELPFUL RESOURCES The OpenCL spec used to develop this module (1.2 spec was available, but no implementation was available to me :). http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf OpenCL manpages: http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/ If you are into UML class diagrams, the following diagram might help - if not, it will be mildly cobfusing: http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/classDiagram.html Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it is, but at least it's free of charge: http://developer.amd.com/zones/OpenCLZone/courses/Documents/Introduction_to_OpenCL_Programming%20Training_Guide%20%28201005%29.pdf And here's NVIDIA's OpenCL Best Practises Guide: http://developer.download.nvidia.com/compute/cuda/3_2/toolkit/docs/OpenCL_Best_Practices_Guide.pdf BASIC WORKFLOW To get something done, you basically have to do this once (refer to the examples below for actual code, this is just a high-level description): Find some platform (e.g. the first one) and some device(s) (e.g. the first device of the platform), and create a context from those. Create program objects from your OpenCL source code, then build (compile) the programs for each device you want to run them on. Create kernel objects for all kernels you want to use (surprisingly, these are not device-specific). Then, to execute stuff, you repeat these steps, possibly resuing or sharing some buffers: Create some input and output buffers from your context. Set these as arguments to your kernel. Enqueue buffer writes to initialise your input buffers (when not initialised at creation time). Enqueue the kernel execution. Enqueue buffer reads for your output buffer to read results. EXAMPLES Enumerate all devices and get contexts for them. Best run this once to get a feel for the platforms and devices in your system. for my $platform (OpenCL::platforms) { printf "platform: %s\n", $platform->info (OpenCL::PLATFORM_NAME); printf "extensions: %s\n", $platform->info (OpenCL::PLATFORM_EXTENSIONS); for my $device ($platform->devices) { printf "+ device: %s\n", $device->info (OpenCL::DEVICE_NAME); my $ctx = $device->context; # do stuff } } Get a useful context and a command queue. This is a useful boilerplate for any OpenCL program that only wants to use one device, my ($platform) = OpenCL::platforms; # find first platform my ($dev) = $platform->devices; # find first device of platform my $ctx = $platform->context (undef, [$dev]); # create context out of those my $queue = $ctx->queue ($dev); # create a command queue for the device Print all supported image formats of a context. Best run this once for your context, to see whats available and how to gather information. for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) { print "supported image formats for ", OpenCL::enum2str $type, "\n"; for my $f ($ctx->supported_image_formats (0, $type)) { printf " %-10s %-20s\n", OpenCL::enum2str $f->[0], OpenCL::enum2str $f->[1]; } } Create a buffer with some predefined data, read it back synchronously, then asynchronously. my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut"); $queue->enqueue_read_buffer ($buf, 1, 1, 3, my $data); print "$data\n"; my $ev = $queue->enqueue_read_buffer ($buf, 0, 1, 3, my $data); $ev->wait; print "$data\n"; # prints "elm" Create and build a program, then create a kernel out of one of its functions. my $src = ' __kernel void squareit (__global float *input, __global float *output) { $id = get_global_id (0); output [id] = input [id] * input [id]; } '; my $prog = $ctx->program_with_source ($src); # build croaks on compile errors, so catch it and print the compile errors eval { $prog->build ($dev); 1 } or die $prog->build_info ($dev, OpenCL::PROGRAM_BUILD_LOG); my $kernel = $prog->kernel ("squareit"); Create some input and output float buffers, then call the 'squareit' kernel on them. my $input = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, pack "f*", 1, 2, 3, 4.5); my $output = $ctx->buffer (0, OpenCL::SIZEOF_FLOAT * 5); # set buffer $kernel->set_buffer (0, $input); $kernel->set_buffer (1, $output); # execute it for all 4 numbers $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef); # enqueue a synchronous read $queue->enqueue_read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data); # print the results: printf "%s\n", join ", ", unpack "f*", $data; The same enqueue operations as before, but assuming an out-of-order queue, showing off barriers. # execute it for all 4 numbers $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef); # enqueue a barrier to ensure in-order execution $queue->enqueue_barrier; # enqueue an async read $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data); # wait for all requests to finish $queue->finish; The same enqueue operations as before, but assuming an out-of-order queue, showing off event objects and wait lists. # execute it for all 4 numbers my $ev = $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef); # enqueue an async read $ev = $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data, $ev); # wait for the last event to complete $ev->wait; DOCUMENTATION BASIC CONVENTIONS This is not a one-to-one C-style translation of OpenCL to Perl - instead I attempted to make the interface as type-safe as possible by introducing object syntax where it makes sense. There are a number of important differences between the OpenCL C API and this module: * Object lifetime managament is automatic - there is no need to free objects explicitly ("clReleaseXXX"), the release function is called automatically once all Perl references to it go away. * OpenCL uses CamelCase for function names ("clGetPlatformInfo"), while this module uses underscores as word separator and often leaves out prefixes ("$platform->info"). * OpenCL often specifies fixed vector function arguments as short arrays ($origin[3]), while this module explicitly expects the components as separate arguments- * Structures are often specified with their components, and returned as arrayrefs. * Where possible, one of the pitch values is calculated from the perl scalar length and need not be specified. * When enqueuing commands, the wait list is specified by adding extra arguments to the function - anywhere a "$wait_events..." argument is documented this can be any number of event objects. * When enqueuing commands, if the enqueue method is called in void context, no event is created. In all other contexts an event is returned by the method. * This module expects all functions to return "CL_SUCCESS". If any other status is returned the function will throw an exception, so you don't normally have to to any error checking. PERL AND OPENCL TYPES This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack format equivalents: OpenCL perl PDL pack/unpack char IV - c uchar IV byte C short IV short s ushort IV ushort S int IV long? l uint IV - L long IV longlong q ulong IV - Q float NV float f half IV ushort S double NV double d THE OpenCL PACKAGE $int = OpenCL::errno The last error returned by a function - it's only valid after an error occured and before calling another OpenCL function. $str = OpenCL::err2str $errval Comverts an error value into a human readable string. $str = OpenCL::enum2str $enum Converts most enum values (inof parameter names, image format constants, object types, addressing and filter modes, command types etc.) into a human readbale string. When confronted with some random integer it can be very helpful to pass it through this function to maybe get some readable string out of it. @platforms = OpenCL::platforms Returns all available OpenCL::Platform objects. $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef Tries to create a context from a default device and platform - never worked for me. OpenCL::wait_for_events $wait_events... Waits for all events to complete. THE OpenCL::Platform CLASS $packed_value = $platform->info ($name) Calls "clGetPlatformInfo" and returns the packed, raw value - for strings, this will be the string, for other values you probably need to use the correct "unpack". This might get improved in the future. Hopefully. @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL) Returns a list of matching OpenCL::Device objects. $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef) Tries to create a context. Never worked for me, and you need devices explitly anyway. $ctx = $device->context ($properties = undef, @$devices, $notify = undef) Create a new OpenCL::Context object using the given device object(s)- a CL_CONTEXT_PLATFORM property is supplied automatically. THE OpenCL::Device CLASS $packed_value = $device->info ($name) See "$platform->info" for details. THE OpenCL::Context CLASS $packed_value = $ctx->info ($name) See "$platform->info" for details. $queue = $ctx->queue ($device, $properties) Create a new OpenCL::Queue object from the context and the given device. $ev = $ctx->user_event Creates a new OpenCL::UserEvent object. $buf = $ctx->buffer ($flags, $len) Creates a new OpenCL::Buffer object with the given flags and octet-size. $buf = $ctx->buffer_sv ($flags, $data) Creates a new OpenCL::Buffer object and initialise it with the given data values. $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef) Creates a new OpenCL::Image2D object and optionally initialises it with the given data values. $img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $row_pitch = 0, $slice_pitch = 0, $data = undef) Creates a new OpenCL::Image3D object and optionally initialises it with the given data values. @formats = $ctx->supported_image_formats ($flags, $image_type) Returns a list of matching image formats - each format is an arrayref with two values, $channel_order and $channel_type, in it. $sampler = $ctx->sampler ($normalized_coords, $addressing_mode, $filter_mode) Creates a new OpenCL::Sampler object. $program = $ctx->program_with_source ($string) Creates a new OpenCL::Program object from the given source code. THE OpenCL::Queue CLASS An OpenCL::Queue represents an execution queue for OpenCL. You execute requests by calling their respective "enqueue_xxx" method and waitinf for it to complete in some way. All the enqueue methods return an event object that can be used to wait for completion, unless the method is called in void context, in which case no event object is created. They also allow you to specify any number of other event objects that this request has to wait for before it starts executing, by simply passing the event objects as extra parameters to the enqueue methods. Queues execute in-order by default, without any parallelism, so in most cases (i.e. you use only one queue) it's not necessary to wait for or create event objects. $packed_value = $ctx->info ($name) See "$platform->info" for details. $ev = $queue->enqueue_read_buffer ($buffer, $blocking, $offset, $len, $data, $wait_events...) Reads data from buffer into the given string. $ev = $queue->enqueue_write_buffer ($buffer, $blocking, $offset, $data, $wait_events...) Writes data to buffer from the given string. $ev = $queue->enqueue_copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...) $ev = $queue->enqueue_read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...) $ev = $queue->enqueue_write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...) $ev = $queue->enqueue_copy_buffer_rect ($src, $dst, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $src_row_pitch, $src_slice_pitch, $dst_row_pitch, $dst_slice_pitch, $wait_event...) Yeah. $ev = $queue->enqueue_copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...) . $ev = $queue->enqueue_copy_image ($src_image, $dst_image, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...) $ev = $queue->enqueue_copy_image_to_buffer ($src_image, $dst_image, $src_x, $src_y, $src_z, $width, $height, $depth, $dst_offset, $wait_events...) $ev = $queue->enqueue_task ($kernel, $wait_events...) $ev = $queue->enqueue_nd_range_kernel ($kernel, @$global_work_offset, @$global_work_size, @$local_work_size, $wait_events...) Enqueues a kernel execution. @$global_work_size must be specified as a reference to an array of integers specifying the work sizes (element counts). @$global_work_offset must be either "undef" (in which case all offsets are 0), or a reference to an array of work offsets, with the same number of elements as @$global_work_size. @$local_work_size must be either "undef" (in which case the implementation is supposed to choose good local work sizes), or a reference to an array of local work sizes, with the same number of elements as @$global_work_size. $ev = $queue->enqueue_marker $ev = $queue->enqueue_wait_for_events ($wait_events...) $queue->enqueue_barrier $queue->flush $queue->finish THE OpenCL::Memory CLASS This the superclass of all memory objects - OpenCL::Buffer, OpenCL::Image, OpenCL::Image2D and OpenCL::Image3D. The subclasses of this class currently only exist to allow type-checking. $packed_value = $memory->info ($name) See "$platform->info" for details. THE OpenCL::Sampler CLASS $packed_value = $sampler->info ($name) See "$platform->info" for details. THE OpenCL::Program CLASS $packed_value = $program->info ($name) See "$platform->info" for details. $program->build ($device, $options = "") Tries to build the program with the givne options. $packed_value = $program->build_info ($device, $name) Similar to "$platform->info", but returns build info for a previous build attempt for the given device. $kernel = $program->kernel ($function_name) Creates an OpenCL::Kernel object out of the named "__kernel" function in the program. THE OpenCL::Kernel CLASS $packed_value = $kernel->info ($name) See "$platform->info" for details. $kernel->set_TYPE ($index, $value) This is a family of methods to set the kernel argument with the number $index to the give $value. TYPE is one of "char", "uchar", "short", "ushort", "int", "uint", "long", "ulong", "half", "float", "double", "memory", "buffer", "image2d", "image3d", "sampler" or "event". Chars and integers (including the half type) are specified as integers, float and double as floating point values, memory/buffer/image2d/image3d must be an object of that type or "undef", and sampler and event must be objects of that type. THE OpenCL::Event CLASS This is the superclass for all event objects (including OpenCL::UserEvent objects). $packed_value = $ev->info ($name) See "$platform->info" for details. $ev->wait Waits for the event to complete. THE OpenCL::UserEvent CLASS This is a subclass of OpenCL::Event. $ev->set_status ($execution_status) AUTHOR Marc Lehmann http://home.schmorp.de/