rstsr-openblas-ffi 0.4.0

OpenBLAS FFI bindings
Documentation

OpenBLAS FFI bindings

This crate contains OpenBLAS FFI bindings.

Current FFI version is OpenBLAS v0.3.30. If you are using an older version of OpenBLAS, this crate should still work if you do not explicitly call the function that only occurs in higher version of OpenBLAS.

OpenBLAS (C/Fortran/ASM) source code is available on github.

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 OpenBLAS 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 by default.

If you do not want to use dynamic loading, please disable default cargo features (--no-default-features when cargo build).

The dynamic loading will try to find proper library when your program initializes. If you want to override the library to be loaded, please set these shell environmental variable RSTSR_DYLOAD_OPENBLAS 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_openblas_ffi::blas, rstsr_openblas_ffi::cblas and rstsr_openblas_ffi::lapack. Sticking to using rstsr_openblas_ffi will make sure you are calling BLAS and LAPACK functions from OpenBLAS, instead of other BLAS vendors.

Cargo features

Default features:

  • dynamic_loading: Supports dynamic loading.
  • blas: Inclulde BLAS bindgens.
  • cblas: Include CBLAS bindgens.
  • lapack: Include LAPACK bindgens.

Optional features:

  • 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, OpenBLAS utility functions use c_int for input or output.
  • lapacke: Include LAPACKE bindgens.
  • quad_precision and ex_precision: Specify type extra-precision xdouble type in module blas. Probably few people will require these features.

Crate structure

  • header: Header files copied (or renamed) from original source.
  • scripts: Script to generate FFI bindgens.
  • src: FFI bindings:
    • blas: Corresponds to f77blas.h header in compiled library include (or common_interface.h in OpenBLAS original source code). BLAS and some LAPACK functions that implemented by OpenBLAS, no post-suffix underscore.
    • cblas: Corresponds to cblas.h header. Original CBLAS included, along with OpenBLAS utility functions (e.g. openblas_get_num_threads) and some BLAS extensions (e.g. cblas_zgemm_batch).
  • 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.4

    • API breaking change: Supports and defaults to dynamic loading.
    • Added omp_set_num_threads and omp_get_max_threads for convenience.