AMD Optimizing CPU Libraries FFI bindings

This crate contains AOCL (AMD Optimizing CPU Libraries) FFI bindings.

Current FFI version is AOCL 5.1, where codes are available in github organization amd. If you are using an older version of AOCL, this crate should still work if you do not explicitly call the function that only occurs in higher version of BLIS.

Feature Not Complete: AOCL is a large collection of math functions. This crate currently only have following bindgens:

• blis (for blas, cblas utilities)
• flame (for cblas, lapack, lapacke utilities)

We surely want to perform more bindgens (such as fftw, etc.) in future; but these are not of priority for project REST and RSTSR. If you wish to put these bindgens in this crate, currently you can file an issue, and we will quickly realize the bindgen of other features in AOCL.

This crate is not official bindgen project. It is originally intended to serve rust tensor toolkit RSTSR and rust electronic structure toolkit REST.

• Audience: Anyone uses AOCL function may also find it useful, not only RSTSR or REST program developers.
• Pure Extern or Dynamic Loading: This crate supports either pure extern (usual FFI, requires dynamic or static linking) and dynamic-loading, by cargo feature dynamic_loading.

Dynamic loading

This crate supports dynamic loading.

If you want to use dynamic loading, please enable cargo feature dynamic_loading when cargo build.

The dynamic loading will try to find proper library when your program initializes.

• This crate will automatically detect proper libraries, if these libraries are in environmental path LD_LIBRARY_PATH (Linux) DYLD_LIBRARY_PATH (Mac OS), PATH (Windows).
• If you want to override the library to be loaded, please set these shell environmental variable RSTSR_DYLOAD_AOCL_BLIS, RSTSR_DYLOAD_AOCL_FLAME to the dynamic library path.

NOTE: When you call BLAS and LAPACK functions with dynamic loading, please DO NOT USE other crates (such as rstsr_lapack_ffi). Please make sure you are only using rstsr_aocl_ffi::blis, rstsr_aocl_ffi::flame. Sticking to using rstsr_aocl_ffi will make sure you are calling BLAS and LAPACK functions from AOCL, instead of other BLAS vendors.

If you encountered large compile time or disk consumption, you may consider add these lines in your Cargo.toml:

[profile.dev.package.rstsr-aocl-ffi]
opt-level = 0
debug = false

Cargo features

Default features:

• blis: Include BLIS bindgens.
• flame: Include LAPACK bindgens.

Optional features:

• dynamic_loading: Supports dynamic loading.
• ilp64: Use int64_t for dimension specification, or lapack error code types if this feature specified. Otherwise, use int32_t.
  • Please note that in module blas, error code is returned by c_int; in module cblas, BLIS utility functions use c_int for input or output.

Crate structure

• header: Header files copied (or renamed) from original source.
• scripts: Script to generate FFI bindgens.
• In each bindgens, the following files are usually automatically generated by scripts:
  • ffi_base.rs: Basic type, enum, struct definitions.
  • ffi_extern.rs: Unsafe extern "C" bindgen functions. Only activated when not dynamic loading.
  • dyload_struct.rs: Struct Lib for dynamic loading.
  • dyload_initializer.rs: The initialization function of Lib for dynamic loading.
  • dyload_compatible.rs: Unsafe bindgen function that is compatible to that of ffi_extern.rs. Only activated when dynamic loading.
  • special case of cblas::ffi_base: the enums CBLAS_TRANSPOSE, CBLAS_UPLO, etc comes from crate rstsr_lapack_ffi for convenience. This crate depends on rstsr_lapack_ffi for those definitions of enums.

Changelog

• v0.2.0

  • API Breaking: Now cargo feature dynamic_loading is not default.

• v0.1.1

  • Enhancements: Updated panic information.