Crate ocl_core

source ·
Expand description

Thin wrappers for the OpenCL FFI functions and types.

Allows access to OpenCL FFI functions with a minimal layer of zero-cost abstraction, providing, safety, performance, and convenience. The ocl crate contains higher level and easier to use interfaces to the functionality contained within.

Even Lower Level: cl-sys

If there’s still something missing or for some reason you need direct FFI access, use the functions in the cl-sys module. The pointers used by cl-sys functions can be wrapped in ocl-core wrappers (ocl_core::PlatformId, ocl_core::Context, etc.) and passed to ocl-core module functions. Likewise the other way around (using, for example: [EventRaw::as_ptr]).

Performance

Performance between all three interface layers, cl-sys, ocl-core, and the ‘standard’ (ocl) types, is identical or virtually identical (if not, please file an issue).

Safety

Running any kernel at all is inherently unsafe. The guarantee we aim to make in this library is that if there is a segfault or invalid memory access, the fault lies within the kernel. No effort is or will be made to verify or sanitize kernels. Consider all kernels within user-supplied programs just as if you would an unsafe fn.

Length vs Size

No, not that…

Quantifiers passed to functions in the OpenCL API are generally expressed in bytes. Units passed to functions in this library are expected to be bytes / sizeof(T) (corresponding with units returned by the ubiquitous .len() method). The suffix ‘_size’ or ‘_bytes’ is generally used when a parameter deviates from this convention.

Version Control

The version control system is in place to ensure that you don’t call functions that your hardware/driver does not support.

Functions in this crate with the [Version Controlled: OpenCL {...}+] tag in the description require an additional parameter, device_version or device_versions: a parsed result (or slice of results) of DeviceInfo::Version. This is a runtime check to ensure that the device supports the function being called. Calling a function which a particular device does not support will likely cause a segmentation fault and possibly data corruption.

Saving the OpenclVersion returned from device_version() for your device(s) at the start of your program and passing it each time you call a version controlled function is the fastest and safest method (see the ocl library for an example). The cost of this check is little more than a single if statement.

Passing None for device_version will cause an automated version check which has a small cost (calling info function, parsing the version number etc.) but is a safe option if you are not sure what to do.

Passing the result of a call to OpenclVersion::max() or passing a fake version will bypass any safety checks and has all of the risks described above. Only do this if you’re absolutely sure you know what you’re doing and are not concerned about segfaults and data integrity.

More Documentation

As most of the functions here are minimally documented, please refer to the official OpenCL documentation linked below. Although there isn’t a precise 1:1 parameter mapping between the core and original functions, it’s close enough (modulo the size/len difference discussed above) to help sort out any questions you may have until a more thorough documentation pass can be made. View the source code in src/types/functions.rs for more mapping details.

‘OpenCL’ 1.2 SDK Reference: https://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/

Re-exports

Modules

  • error
    Standard error type for ocl.
  • types
  • util
    Utility and debugging functions.

Structs

Enums

Constants

Traits

  • OclNum
    A set of traits common to numeric built-in OpenCL scalar and vector primitives.
  • OclPrm
    A primitive type usable within OpenCL kernels.
  • OclScl
    A scalar type usable within OpenCL kernels.
  • OclVec
    A vector type usable within OpenCL kernels.

Functions

Type Aliases