src/stdsimd/crates/std_detect/README.md

   1 `std::detect` - Rust's standard library run-time CPU feature detection
   2 =======
   3
   4 [![Travis-CI Status]][travis] [![Appveyor Status]][appveyor] [![std_detect_crate_badge]][std_detect_crate_link] [![std_detect_docs_badge]][std_detect_docs_link]
   5
   6
   7 The private `std::detect` module implements run-time feature detection in Rust's
   8 standard library. This allows detecting whether the CPU the binary runs on
   9 supports certain features, like SIMD instructions.
  10
  11 # Usage
  12
  13 `std::detect` APIs are available as part of `libstd`. Prefer using it via the
  14 standard library than through this crate. Unstable features of `std::detect` are
  15 available on nightly Rust behind the `feature(stdsimd)` feature-gate.
  16
  17 If you need run-time feature detection in `#[no_std]` environments, Rust `core`
  18 library cannot help you. By design, Rust `core` is platform independent, but
  19 performing run-time feature detection requires a certain level of cooperation
  20 from the platform.
  21
  22 You can then manually include `std_detect` as a dependency to get similar
  23 run-time feature detection support than the one offered by Rust's standard
  24 library. We intend to make `std_detect` more flexible and configurable in this
  25 regard to better serve the needs of `#[no_std]` targets.
  26
  27 # Features
  28
  29 * `std_detect_dlsym_getauxval` (enabled by default, requires `libc`): Enable to
  30 use `libc::dlsym` to query whether [`getauxval`] is linked into the binary. When
  31 this is not the case, this feature allows other fallback methods to perform
  32 run-time feature detection. When this feature is disabled, `std_detect` assumes
  33 that [`getauxval`] is linked to the binary. If that is not the case the behavior
  34 is undefined.
  35
  36 * `std_detect_file_io` (enabled by default, requires `std`): Enable to perform run-time feature
  37 detection using file APIs (e.g. `/proc/cpuinfo`, etc.) if other more performant
  38 methods fail. This feature requires `libstd` as a dependency, preventing the
  39 crate from working on applications in which `std` is not available.
  40
  41 [`getauxval`]: http://man7.org/linux/man-pages/man3/getauxval.3.html
  42
  43 # Platform support
  44
  45 * All `x86`/`x86_64` targets are supported on all platforms by querying the
  46   `cpuid` instruction directly for the features supported by the hardware and
  47   the operating system. `std_detect` assumes that the binary is an user-space
  48   application. If you need raw support for querying `cpuid`, consider using the
  49   [`cupid`](https://crates.io/crates/cupid) crate.
  50
  51 * Linux:
  52   * `arm{32, 64}`, `mips{32,64}{,el}`, `powerpc{32,64}{,le}`: `std_detect`
  53     supports these on Linux by querying ELF auxiliary vectors (using `getauxval`
  54     when available), and if that fails, by querying `/proc/cpuinfo`.
  55   * `arm64`: partial support for doing run-time feature detection by directly
  56     querying `mrs` is implemented for Linux >= 4.11, but not enabled by default.
  57
  58 * FreeBSD:
  59   * `arm64`: run-time feature detection is implemented by directly querying `mrs`.
  60
  61 # License
  62
  63 This project is licensed under either of
  64
  65  * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
  66    http://www.apache.org/licenses/LICENSE-2.0)
  67  * MIT license ([LICENSE-MIT](LICENSE-MIT) or
  68    http://opensource.org/licenses/MIT)
  69
  70 at your option.
  71
  72 # Contribution
  73
  74 Unless you explicitly state otherwise, any contribution intentionally submitted
  75 for inclusion in `std_detect` by you, as defined in the Apache-2.0 license,
  76 shall be dual licensed as above, without any additional terms or conditions.
  77
  78 [travis]: https://travis-ci.com/rust-lang-nursery/stdsimd
  79 [Travis-CI Status]: https://travis-ci.com/rust-lang-nursery/stdsimd.svg?branch=master
  80 [appveyor]: https://ci.appveyor.com/project/rust-lang-libs/stdsimd/branch/master
  81 [Appveyor Status]: https://ci.appveyor.com/api/projects/status/ix74qhmilpibn00x/branch/master?svg=true
  82 [std_detect_crate_badge]: https://img.shields.io/crates/v/std_detect.svg
  83 [std_detect_crate_link]: https://crates.io/crates/std_detect
  84 [std_detect_docs_badge]: https://docs.rs/std_detect/badge.svg
  85 [std_detect_docs_link]: https://docs.rs/std_detect/