#opencl #gpu #gpgpu

cl3

A Rust implementation of the Khronos OpenCL 3.0 API

6 releases

0.1.5 Jan 13, 2021
0.1.4 Jan 10, 2021
0.1.3 Dec 31, 2020

#239 in Asynchronous

44 downloads per month
Used in opencl3

Apache-2.0

230KB
4.5K SLoC

cl3

crates.io docs.io OpenCL 3.0 License Rust

A Rust adapter for the Khronos OpenCL API.

Description

A functional, safe Rust interface to the Khronos OpenCL 3.0 C API based upon the cl-sys OpenCL FFI bindings.
It is the foundation of the opencl3 crate which provides a simpler, object based model of the OpenCL 3.0 API.

OpenCL 3.0 is a unified specification that adds little new functionality to previous OpenCL versions.
It specifies that all OpenCL 1.2 features are mandatory, while all OpenCL 2.x and 3.0 features are now optional.

Design

This crate applies the adapter pattern to convert OpenCL C API functions into Rust functions that return a Result containing the desired result of the C function or the OpenCL error code. The only exception is svm_free, which just provides a safe wrapper for the clSVMFree C API function.

Most of the modules are named after their equivalent "API" sections in cl.h. They contain Rust adapter functions for the OpenCL API C functions defined in those sections with their associated types and constants.
For more information see the Rust documentation.

Use

Ensure that an OpenCL Installable Client Driver (ICD) and the appropriate OpenCL hardware driver(s) are installed, see OpenCL Installation.

cl3 supports OpenCL 1.2 and 2.0 ICD loaders by default. If you have an OpenCL 2.0 ICD loader then add the following to your project's Cargo.toml:

[dependencies]
cl3 = "0.1"

If your OpenCL ICD loader supports higher versions of OpenCL then add the appropriate features to cl3, e.g. for an OpenCL 2.2 ICD loader add the following to your project's Cargo.toml instead:

[dependencies.cl3]
version = "0.1"
features = ["CL_VERSION_2_1", "CL_VERSION_2_2"]

Whichever version of OpenCL ICD loader you use, add the following to your crate root (lib.rs or main.rs):

extern crate cl3;

Tests

The crate contains unit, documentation and integration tests.
The tests run the platform and device info functions (among others) so they can provide useful information about OpenCL capabilities of the system.

It is recommended to run the tests in single-threaded mode, since some of them can interfere with each other when run multi-threaded, e.g.:

cargo test -- --test-threads=1 --show-output

The integration tests are marked ignore so use the following command to run them:

cargo test -- --test-threads=1 --show-output --ignored

Examples

The tests provide examples of how the crate may be used, e.g. see: platform, device, context and integration_test.

License

Licensed under the Apache License, Version 2.0, as per Khronos Group OpenCL.
You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0

OpenCL and the OpenCL logo are trademarks of Apple Inc. used under license by Khronos.

Dependencies

~450KB