1//! This module implements run-time feature detection.
2//!
3//! The `is_{arch}_feature_detected!("feature-name")` macros take the name of a
4//! feature as a string-literal, and return a boolean indicating whether the
5//! feature is enabled at run-time or not.
6//!
7//! These macros do two things:
8//! * map the string-literal into an integer stored as a `Feature` enum,
9//! * call a `os::check_for(x: Feature)` function that returns `true` if the
10//! feature is enabled.
11//!
12//! The `Feature` enums are also implemented in the `arch/{target_arch}.rs`
13//! modules.
14//!
15//! The `check_for` functions are, in general, Operating System dependent. Most
16//! architectures do not allow user-space programs to query the feature bits
17//! due to security concerns (x86 is the big exception). These functions are
18//! implemented in the `os/{target_os}.rs` modules.
19
20use cfg_if::cfg_if;
21
22#[macro_use]
23mod macros;
24
25mod arch;
26
27// This module needs to be public because the `is_{arch}_feature_detected!`
28// macros expand calls to items within it in user crates.
29#[doc(hidden)]
30#[unstable(feature = "stdarch_internal", issue = "none")]
31pub use self::arch::__is_feature_detected;
32
33pub(crate) use self::arch::Feature;
34
35mod bit;
36mod cache;
37
38cfg_if! {
39 if #[cfg(miri)] {
40 // When running under miri all target-features that are not enabled at
41 // compile-time are reported as disabled at run-time.
42 //
43 // For features for which `cfg(target_feature)` returns true,
44 // this run-time detection logic is never called.
45 #[path = "os/other.rs"]
46 mod os;
47 } else if #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] {
48 // On x86/x86_64 no OS specific functionality is required.
49 #[path = "os/x86.rs"]
50 mod os;
51 } else if #[cfg(all(any(target_os = "linux", target_os = "android"), feature = "libc"))] {
52 #[cfg(any(target_arch = "riscv32", target_arch = "riscv64"))]
53 #[path = "os/riscv.rs"]
54 mod riscv;
55 #[path = "os/linux/mod.rs"]
56 mod os;
57 } else if #[cfg(all(target_os = "freebsd", feature = "libc"))] {
58 #[cfg(target_arch = "aarch64")]
59 #[path = "os/aarch64.rs"]
60 mod aarch64;
61 #[path = "os/freebsd/mod.rs"]
62 mod os;
63 } else if #[cfg(all(target_os = "openbsd", target_arch = "aarch64", feature = "libc"))] {
64 #[allow(dead_code)] // we don't use code that calls the mrs instruction.
65 #[path = "os/aarch64.rs"]
66 mod aarch64;
67 #[path = "os/openbsd/aarch64.rs"]
68 mod os;
69 } else if #[cfg(all(target_os = "windows", any(target_arch = "aarch64", target_arch = "arm64ec")))] {
70 #[path = "os/windows/aarch64.rs"]
71 mod os;
72 } else if #[cfg(all(target_vendor = "apple", target_arch = "aarch64", feature = "libc"))] {
73 #[path = "os/darwin/aarch64.rs"]
74 mod os;
75 } else {
76 #[path = "os/other.rs"]
77 mod os;
78 }
79}
80
81/// Performs run-time feature detection.
82#[inline]
83#[allow(dead_code)]
84fn check_for(x: Feature) -> bool {
85 cache::test(bit:x as u32)
86}
87
88/// Returns an `Iterator<Item=(&'static str, bool)>` where
89/// `Item.0` is the feature name, and `Item.1` is a `bool` which
90/// is `true` if the feature is supported by the host and `false` otherwise.
91#[unstable(feature = "stdarch_internal", issue = "none")]
92pub fn features() -> impl Iterator<Item = (&'static str, bool)> {
93 cfg_if! {
94 if #[cfg(any(
95 target_arch = "x86",
96 target_arch = "x86_64",
97 target_arch = "arm",
98 target_arch = "aarch64",
99 target_arch = "arm64ec",
100 target_arch = "riscv32",
101 target_arch = "riscv64",
102 target_arch = "powerpc",
103 target_arch = "powerpc64",
104 target_arch = "mips",
105 target_arch = "mips64",
106 target_arch = "loongarch64",
107 target_arch = "s390x",
108 ))] {
109 (0_u8..Feature::_last as u8).map(|discriminant: u8| {
110 #[allow(bindings_with_variant_name)] // RISC-V has Feature::f
111 let f: Feature = unsafe { core::mem::transmute(discriminant) };
112 let name: &'static str = f.to_str();
113 let enabled: bool = check_for(f);
114 (name, enabled)
115 })
116 } else {
117 None.into_iter()
118 }
119 }
120}
121