Crate rstsr_blis_ffi

Crate rstsr_blis_ffi 

Source
Expand description

§BLIS (FLAME framework) FFI bindings

This crate contains BLIS FFI bindings.

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

Architecture Not Complete: The current bindgen is generated in x86_64. We are planning to generate arm64 in future.

This crate aims to provide common usage (architecture-independent) of BLIS and FLAME. All architecture-independent functions/constants are actually included in this crate. However, if you are interested in other architectures, you either

  • do not use architecture-dependent functions,
  • file an issue to let us know some other architecture is required,
  • use blis-sys crate for usual extern FFIs (without dynamic loading).

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 BLIS 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.

§Configuration of BLIS/FLAME header

BLIS/FLAME header, used in this project, is not directly obtained from BLIS repository, but from the installed library.

The header file for x86_64 architectures is obtained by

# BLIS
./configure --enable-shared --enable-cblas --enable-blas --enable-threading=openmp,pthread x86_64
# FLAME
LDFLAGS=-L<blis_dir> LIBS=-lblis ./configure --enable-dynamic-build --enable-lapack2flame

§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_BLIS, RSTSR_DYLOAD_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_blis_ffi::blis, rstsr_blis_ffi::lapack. Sticking to using rstsr_blis_ffi will make sure you are calling BLAS and LAPACK functions from BLIS, 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-blis-ffi]
opt-level = 0
debug = false

§Cargo features

Default features:

  • lapack: Include LAPACK bindgens.
  • x86_64: Use bindgen generated from x86_64 (not necessarily meaning arm64 could not use most functions in x86_64 bindgen, but arm64 will not able to use much lower-level ASM functions).

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.
  • flame: Include FLAME bindgens.

Mutually exclusive features:

  • flame and ilp64: We found that FLAME must be compiled with int of C, which is lp64 exclusive. Also use ilp64 carefully in BLIS and lapack.

§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.3

    • Enhancements: Updated panic information.

  • v0.1.2

    • Docs Update
    • Fix: Define BLIS_BLAS_INT_TYPE_SIZE in root level.

  • v0.1.1

    • API Breaking: Change CBLAS enum definition to crate rstsr-cblas-base.

Re-exports§

pub use blis_x86_64 as blis;
pub use blis as blas;
pub use blis as cblas;
pub use blis_types::*;

Modules§

blis_types
blis_x86_64
lapack