Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kenba/opencl3

A Rust implementation of the Khronos OpenCL 3.0 API.
https://github.com/kenba/opencl3

Last synced: 3 months ago
JSON representation

A Rust implementation of the Khronos OpenCL 3.0 API.

Awesome Lists containing this project

README 

        
# opencl3



[![crates.io](https://img.shields.io/crates/v/opencl3.svg)](https://crates.io/crates/opencl3)

[![docs.io](https://docs.rs/opencl3/badge.svg)](https://docs.rs/opencl3/)

[![OpenCL 3.0](https://img.shields.io/badge/OpenCL-3.0-blue.svg)](https://www.khronos.org/registry/OpenCL/)

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

[![Rust](https://github.com/kenba/opencl3/workflows/Rust/badge.svg)](https://github.com/kenba/opencl3/actions)



A Rust implementation of the Khronos [OpenCL](https://www.khronos.org/registry/OpenCL/) API.



## Description



A relatively simple, object based model of the OpenCL 3.0

[API](https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_API.html).  

It is built upon the [cl3](https://crates.io/crates/cl3) crate, which

provides a functional interface to the OpenCL [C API](https://github.com/KhronosGroup/OpenCL-Headers/blob/master/CL/cl.h).  



[OpenCL](https://www.khronos.org/opencl/) (Open Computing Language) is framework for general purpose parallel programming across heterogeneous devices including: CPUs, GPUs, DSPs, FPGAs and other processors or hardware accelerators. It is often considered as an open-source alternative to Nvidia's proprietary

Compute Unified Device Architecture [CUDA](https://developer.nvidia.com/cuda-zone)

for performing General-purpose computing on GPUs, see

[GPGPU](https://en.wikipedia.org/wiki/General-purpose_computing_on_graphics_processing_units).



[OpenCL 3.0](https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_API.html)

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.



### Features



This library has:



* A simple API, enabling most OpenCL objects to be created with a single function call.

* Automatic OpenCL resource management using the [Drop trait](https://doc.rust-lang.org/book/ch15-03-drop.html) to implement [RAII](https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization).

* Support for [directed acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) OpenCL control flow execution using event wait lists.

* Support for Shared Virtual Memory (SVM) with an [SvmVec](src/svm.rs) object that can be serialized and deserialized by [serde](https://serde.rs/).

* Support for OpenCL extensions, see [OpenCL Extensions](https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html).

* Support for multithreading with [Send and Sync](https://doc.rust-lang.org/nomicon/send-and-sync.html) traits.



## Design



The library is object based with most OpenCL objects represented by rust structs.

For example, an OpenCL `cl_device_id` is represented by [Device](src/device.rs) with methods to get information about the device instead of calling `clGetDeviceInfo` with the relevant `cl_device_info` value.  



![OpenCL Context](docs/images/opencl_context_objects.svg)  

*OpenCL Context Class Diagram*



The struct methods are simpler to use than their equivalent standalone functions in [cl3](https://github.com/kenba/cl3) because they convert the `InfoType` enum into the correct underlying type returned by the `clGetDeviceInfo` call for the `cl_device_info` value.



Nearly all the structs implement the `Drop` trait to release their corresponding

OpenCL objects. The exceptions are `Platform` and `Device` which don't need to be released. See the crate [documentation](https://docs.rs/opencl3/).



The API for OpenCL versions and extensions are controlled by Rust features such as "CL_VERSION_2_0" and "cl_khr_gl_sharing". To enable an OpenCL version, the feature for that version and **all** previous OpenCL versions must be enabled, e.g. for "CL_VERSION_2_0"; "CL_VERSION_1_1" and "CL_VERSION_1_2" must also be enabled.



The default features are "CL_VERSION_1_1", "CL_VERSION_1_2" and "CL_VERSION_2_0".



Rust deprecation warnings are given for OpenCL API functions that are deprecated by an enabled OpenCL version e.g., `clCreateCommandQueue` is deprecated whenever "CL_VERSION_2_0" is enabled.



## Use



Ensure that an OpenCL Installable Client Driver (ICD) and the appropriate OpenCL

hardware driver(s) are installed, see

[OpenCL Installation](https://github.com/kenba/cl3/tree/main/docs/opencl_installation.md).



`opencl3` supports OpenCL 1.2 and 2.0 ICD loaders by default. If you have an

OpenCL 2.0 ICD loader then just add the following to your project's `Cargo.toml`:



```toml

[dependencies]

opencl3 = "0.9"

```



If your OpenCL ICD loader supports higher versions of OpenCL then add the

appropriate features to opencl3, e.g. for an OpenCL 3.0 ICD loader add the

following to your project's `Cargo.toml` instead:



```toml

[dependencies.opencl3]

version = "0.9"

features = ["CL_VERSION_2_1", "CL_VERSION_2_2", "CL_VERSION_3_0"]

```



OpenCL extensions and `serde` support can also be enabled by adding their features, e.g.:



```toml

[dependencies.opencl3]

version = "0.9"

features = ["cl_khr_gl_sharing", "cl_khr_dx9_media_sharing", "serde"]

```



See the [OpenCL Guide](https://github.com/KhronosGroup/OpenCL-Guide) and [OpenCL Description](https://github.com/kenba/opencl3/tree/main/docs/opencl_description.md) for background on using OpenCL.



## Examples



There are examples in the [examples](https://github.com/kenba/opencl3/tree/main/examples/) directory.

The tests also provide examples of how the crate may be used, e.g. see:

[platform](https://github.com/kenba/opencl3/tree/main/src/platform.rs),

[device](https://github.com/kenba/opencl3/tree/main/src/device.rs),

[context](https://github.com/kenba/opencl3/tree/main/src/context.rs),

[integration_test](https://github.com/kenba/opencl3/tree/main/tests/integration_test.rs) and

[opencl2_kernel_test](https://github.com/kenba/opencl3/tree/main/tests/opencl2_kernel_test.rs).



The library is designed to support events and OpenCL 2 features such as Shared Virtual Memory (SVM) and kernel built-in work-group functions.

It also has optional support for `serde` e.g.:



```rust no-run

const PROGRAM_SOURCE: &str = r#"

kernel void inclusive_scan_int (global int* output,

                                global int const* values)

{

    int sum = 0;

    size_t lid = get_local_id(0);

    size_t lsize = get_local_size(0);



    size_t num_groups = get_num_groups(0);

    for (size_t i = 0u; i < num_groups; ++i)

    {

        size_t lidx = i * lsize + lid;

        int value = work_group_scan_inclusive_add(values[lidx]);

        output[lidx] = sum + value;



        sum += work_group_broadcast(value, lsize - 1);

    }

}"#;



const KERNEL_NAME: &str = "inclusive_scan_int";



// Create a Context on an OpenCL device

let context = Context::from_device(&device).expect("Context::from_device failed");



// Build the OpenCL program source and create the kernel.

let program = Program::create_and_build_from_source(&context, PROGRAM_SOURCE, CL_STD_2_0)

    .expect("Program::create_and_build_from_source failed");



let kernel = Kernel::create(&program, KERNEL_NAME).expect("Kernel::create failed");



// Create a command_queue on the Context's device

let queue = CommandQueue::create_default_with_properties(

    &context,

    CL_QUEUE_PROFILING_ENABLE,

    0,

)

.expect("CommandQueue::create_default_with_properties failed");



// The input data

const ARRAY_SIZE: usize = 8;

const VALUE_ARRAY: &str = "[3,2,5,9,7,1,4,2]";



// Create an OpenCL SVM vector

let mut test_values = SvmVec::::new(&context);



// Handle test_values if device only supports CL_DEVICE_SVM_COARSE_GRAIN_BUFFER

if !test_values.is_fine_grained() {

    // SVM_COARSE_GRAIN_BUFFER needs to know the size of the data to allocate the SVM

    test_values = SvmVec::::allocate(&context, ARRAY_SIZE).expect("SVM allocation failed");

    // Map the SVM for a SVM_COARSE_GRAIN_BUFFER

    unsafe { queue.enqueue_svm_map(CL_BLOCKING, CL_MAP_WRITE, &mut test_values, &[])? };

    // Clear the SVM for the deserializer

    test_values.clear();

}



ExtendSvmVec(&mut test_values)

    .deserialize(&mut deserializer)

    .expect("Error deserializing the VALUE_ARRAY JSON string.");



// Make test_values immutable

let test_values = test_values;



// Unmap test_values if not a CL_MEM_SVM_FINE_GRAIN_BUFFER

if !test_values.is_fine_grained() {

    let unmap_test_values_event = unsafe { queue.enqueue_svm_unmap(&test_values, &[])? };

    unmap_test_values_event.wait()?;

}



// The output data, an OpenCL SVM vector

let mut results =

    SvmVec::::allocate(&context, ARRAY_SIZE).expect("SVM allocation failed");



// Run the kernel on the input data

let sum_kernel_event = unsafe {

    ExecuteKernel::new(&kernel)

        .set_arg_svm(results.as_mut_ptr())

        .set_arg_svm(test_values.as_ptr())

        .set_global_work_size(ARRAY_SIZE)

        .enqueue_nd_range(&queue)?

};



// Wait for the kernel to complete execution on the device

kernel_event.wait()?;



// Map results if not a CL_MEM_SVM_FINE_GRAIN_BUFFER

if !results.is_fine_grained() {

    unsafe { queue.enqueue_svm_map(CL_BLOCKING, CL_MAP_READ, &mut results, &[])? };

}



// Convert SVM results to json

let json_results = serde_json::to_string(&results).unwrap();

println!("json results: {}", json_results);



// Unmap results if not a CL_MEM_SVM_FINE_GRAIN_BUFFER

if !results.is_fine_grained() {

    let unmap_results_event = unsafe { queue.enqueue_svm_unmap(&results, &[])? };

    unmap_results_event.wait()?;

}

```



The example above was taken from:

[opencl2serde.rs](https://github.com/kenba/opencl3/tree/main/examples/opencl2serde.rs).



## 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.:



```shell

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

```



The integration tests are marked `ignore` so use the following command to

run them:



```shell

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

```



## Recent changes



The API has changed considerably since version `0.1` of the library, with the

aim of making the library more consistent and easier to use.



[SvmVec](src/svm.rs) was changed recently to provide support for `serde` deserialization.

It also changed in version 0.5.0 to provide better support for

coarse grain buffer Shared Virtual Memory now that Nvidia is supporting it,

see [Nvidia OpenCL](https://developer.nvidia.com/opencl).



In version 0.6.0 the Info enums were removed from the underlying [cl3](https://crates.io/crates/cl3) crate and this crate so that data can be read from OpenCL devices in the future using new values that are currently undefined.



In version 0.8.0 deprecation warnings are given for OpenCL API functions that are deprecated by an enabled OpenCL version e.g., `clCreateCommandQueue` is deprecated whenever "CL_VERSION_2_0" is enabled.



In version 0.9.0 many OpenCL API functions are declared `unsafe` since they may cause undefined behaviour if called incorrectly.



For information on other changes, see [Releases](RELEASES.md).



## Contribution



If you want to contribute through code or documentation, the [Contributing](CONTRIBUTING.md) guide is the best place to start. If you have any questions, please feel free to ask.

Just please abide by our [Code of Conduct](CODE_OF_CONDUCT.md).



## License



Licensed under the Apache License, Version 2.0, as per Khronos Group OpenCL.  

You may obtain a copy of the License at: 



Any contribution intentionally submitted for inclusion in the work by you shall be licensed  as defined in the Apache-2.0 license above, without any additional terms or conditions, unless you explicitly state otherwise.



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