--- OpenCL/OpenCL.pm 2012/05/04 14:29:35 1.71 +++ OpenCL/OpenCL.pm 2012/05/05 13:07:19 1.78 @@ -99,6 +99,37 @@ Enqueue buffer reads for your output buffer to read results. +=head1 OPENCL 1.1 VS. OPENCL 1.2 + +This module supports both OpenCL version 1.1 and 1.2, although the OpenCL +1.2 interface hasn't been tested much for lack of availability of an +actual implementation. + +Every function or method in this manual page that interfaces to a +particular OpenCL function has a link to the its C manual page. + +If the link contains a F<1.1>, then this function is an OpenCL 1.1 +function. Most but not all also exist in OpenCL 1.2, and this module +tries to emulate the missing ones for you, when told to do so at +compiletime. You cna check whether a function was removed in OpenCL 1.2 by +replacing the F<1.1> component in the URL by F<1.2>. + +If the link contains a F<1.2>, then this is a OpenCL 1.2-only +function. Even if the module was compiled with OpenCL 1.2 header files +and has an 1.2 OpenCL library, calling such a function on a platform that +doesn't implement 1.2 causes undefined behaviour, usually a crash (But +this is not guaranteed). + +You can find out whether this module was compiled to prefer 1.1 +functionality by ooking at C - if it is true, then +1.1 functions generally are implemented using 1.1 OpenCL functions. If it +is false, then 1.1 functions missing from 1.2 are emulated by calling 1.2 +fucntions. + +This is a somewhat sorry state of affairs, but the Khronos group choose to +make every release of OpenCL source and binary incompatible with previous +releases. + =head1 EXAMPLES =head2 Enumerate all devices and get contexts for them. @@ -436,13 +467,20 @@ perhaps most important, to signal completion of queued jobs (by setting callbacks on OpenCL::Event objects). +The OpenCL module converts all these callbacks into events - you can +still register callbacks, but they are not executed when your OpenCL +implementation calls the actual callback, but only later. Therefore, none +of the limitations of OpenCL callbacks apply to the perl implementation: +it is perfectly safe to make blocking operations from event callbacks, and +enqueued operations don't need to be flushed. + To facilitate this, this module maintains an event queue - each time an asynchronous event happens, it is queued, and perl will be interrupted. This is implemented via the L module. In addition, this module has L support, so it can seamlessly integrate itself into many event loops. -Since this module is a bit hard to understand, here are some case examples: +Since L is a bit hard to understand, here are some case examples: =head3 Don't use callbacks. @@ -615,6 +653,7 @@ =item $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $callback->($err, $pvt) = $print_stderr Tries to create a context from a default device and platform type - never worked for me. +Consider using C<< $platform->context_from_type >> instead. type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU, OpenCL::DEVICE_TYPE_GPU, OpenCL::DEVICE_TYPE_ACCELERATOR, OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL. @@ -623,8 +662,8 @@ =item $ctx = OpenCL::context $properties, \@devices, $callback->($err, $pvt) = $print_stderr) -Create a new OpenCL::Context object using the given device object(s). This -function isn't implemented yet, use C<< $platform->context >> instead. +Create a new OpenCL::Context object using the given device object(s). +Consider using C<< $platform->context >> instead. L @@ -771,6 +810,32 @@ See C<< $platform->info >> for details. +type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU, +OpenCL::DEVICE_TYPE_GPU, OpenCL::DEVICE_TYPE_ACCELERATOR, +OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL. + +fp_config: OpenCL::FP_DENORM, OpenCL::FP_INF_NAN, OpenCL::FP_ROUND_TO_NEAREST, +OpenCL::FP_ROUND_TO_ZERO, OpenCL::FP_ROUND_TO_INF, OpenCL::FP_FMA, +OpenCL::FP_SOFT_FLOAT, OpenCL::FP_CORRECTLY_ROUNDED_DIVIDE_SQRT. + +mem_cache_type: OpenCL::NONE, OpenCL::READ_ONLY_CACHE, OpenCL::READ_WRITE_CACHE. + +local_mem_type: OpenCL::LOCAL, OpenCL::GLOBAL. + +exec_capabilities: OpenCL::EXEC_KERNEL, OpenCL::EXEC_NATIVE_KERNEL. + +command_queue_properties: OpenCL::QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE, +OpenCL::QUEUE_PROFILING_ENABLE. + +partition_properties: OpenCL::DEVICE_PARTITION_EQUALLY, +OpenCL::DEVICE_PARTITION_BY_COUNTS, OpenCL::DEVICE_PARTITION_BY_COUNTS_LIST_END, +OpenCL::DEVICE_PARTITION_BY_AFFINITY_DOMAIN. + +affinity_domain: OpenCL::DEVICE_AFFINITY_DOMAIN_NUMA, +OpenCL::DEVICE_AFFINITY_DOMAIN_L4_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L3_CACHE, +OpenCL::DEVICE_AFFINITY_DOMAIN_L2_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L1_CACHE, +OpenCL::DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE. + L =item @devices = $device->sub_devices (\@properties) @@ -1159,7 +1224,6 @@ OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16, OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT. - type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY, OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY, @@ -1266,6 +1330,13 @@ L +=item $program = $ctx->link_program (\@devices, $options, \@programs, $cb->($program) = undef) + +Links all (already compiled) program objects specified in C<@programs> +together and returns a new OpenCL::Program object with the result. + +L + =item $packed_value = $ctx->info ($name) See C<< $platform->info >> for details. @@ -1768,6 +1839,9 @@ C<-w>, C<-Werror>, C<-cl-std=CL1.1/CL1.2>, C<-cl-kernel-arg-info>, C<-create-library>, C<-enable-link-options>. +build_status: OpenCL::BUILD_SUCCESS, OpenCL::BUILD_NONE, +OpenCL::BUILD_ERROR, OpenCL::BUILD_IN_PROGRESS. + L =item $program->build_async (\@devices = undef, $options = "", $cb->($program) = undef) @@ -1775,11 +1849,24 @@ Similar to C<< ->build >>, except it starts a thread, and never fails (you need to check the compilation status form the callback, or by polling). +=item $program->compile (\@devices = undef, $options = "", \%headers = undef, $cb->($program) = undef) + +Compiles the given program for the given devices (or all devices if +undef). If C<$headers> is given, it must be a hashref with include name => +OpenCL::Program pairs. + +L + =item $packed_value = $program->build_info ($device, $name) Similar to C<< $platform->info >>, but returns build info for a previous build attempt for the given device. +binary_type: OpenCL::PROGRAM_BINARY_TYPE_NONE, +OpenCL::PROGRAM_BINARY_TYPE_COMPILED_OBJECT, +OpenCL::PROGRAM_BINARY_TYPE_LIBRARY, +OpenCL::PROGRAM_BINARY_TYPE_EXECUTABLE. + L =item $kernel = $program->kernel ($function_name) @@ -1801,9 +1888,6 @@ Calls C with C and returns the result. -build_status: OpenCL::BUILD_SUCCESS, OpenCL::BUILD_NONE, -OpenCL::BUILD_ERROR, OpenCL::BUILD_IN_PROGRESS. - =item $string = $program->build_options ($device) Calls C with C and returns the result. @@ -1899,9 +1983,6 @@ See C<< $platform->info >> for details. -The reason this method is not called C is that there already is an -C<< ->info >> method. - L =for gengetinfo begin kernel_work_group @@ -1928,6 +2009,36 @@ =for gengetinfo end kernel_work_group +=item $packed_value = $kernel->arg_info ($idx, $name) + +See C<< $platform->info >> for details. + +L + +=for gengetinfo begin kernel_arg + +=item $kernel_arg_address_qualifier = $kernel->arg_address_qualifier ($idx) + +Calls C with C and returns the result. + +=item $kernel_arg_access_qualifier = $kernel->arg_access_qualifier ($idx) + +Calls C with C and returns the result. + +=item $string = $kernel->arg_type_name ($idx) + +Calls C with C and returns the result. + +=item $kernel_arg_type_qualifier = $kernel->arg_type_qualifier ($idx) + +Calls C with C and returns the result. + +=item $string = $kernel->arg_name ($idx) + +Calls C with C and returns the result. + +=for gengetinfo end kernel_arg + =item $kernel->setf ($format, ...) Sets the arguments of a kernel. Since OpenCL 1.1 doesn't have a generic