Skip to content

Commit 8a82158

Browse files
newpavlovnewpavlov
authored
cpufeatures: use #![doc = include_str!("../README.md")] (#1193)
List of supported features in README and crate docs was out of sync which was pretty confusing. Additionally, marks `sha512`, `sm3` and `sm4` features on `x86` as stable.
1 parent 6fd0e8d commit 8a82158

File tree

2 files changed

+56
-136
lines changed

2 files changed

+56
-136
lines changed

‎cpufeatures/README.md‎

Lines changed: 55 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,54 @@ Supports `no_std` as well as mobile targets including iOS and Android,
1414
providing an alternative to the `std`-dependent `is_x86_feature_detected!`
1515
macro.
1616

17-
[Documentation][docs-link]
18-
19-
# Supported target architectures
17+
This crate is intended as a stopgap until Rust [RFC 2725] adding first-class
18+
target feature detection macros to `libcore` is implemented.
19+
20+
## Example
21+
```
22+
#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
23+
pub mod x86_backend {
24+
// This macro creates `cpuid_aes_sha` module
25+
cpufeatures::new!(cpuid_aes_sha, "aes", "sha");
26+
27+
pub fn run() {
28+
// `token` is a Zero Sized Type (ZST) value, which guarantees
29+
// that underlying static storage got properly initialized,
30+
// which allows to omit initialization branch
31+
let token: cpuid_aes_sha::InitToken = cpuid_aes_sha::init();
32+
33+
if token.get() {
34+
println!("CPU supports both SHA and AES extensions");
35+
} else {
36+
println!("SHA and AES extensions are not supported");
37+
}
38+
39+
// If stored value needed only once you can get stored value
40+
// omitting the token
41+
let val = cpuid_aes_sha::get();
42+
assert_eq!(val, token.get());
43+
44+
// Additionally you can get both token and value
45+
let (token, val) = cpuid_aes_sha::init_get();
46+
assert_eq!(val, token.get());
47+
}
48+
}
49+
```
50+
51+
Note that if all tested target features are enabled via compiler options
52+
(e.g. by using `RUSTFLAGS`), the `get` method will always return `true`
53+
and `init` will not use CPUID instruction. Such behavior allows
54+
compiler to completely eliminate fallback code.
55+
56+
After first call macro caches result and returns it in subsequent
57+
calls, thus runtime overhead for them is minimal.
58+
59+
## Supported target architectures
2060

2161
*NOTE: target features with an asterisk are unstable (nightly-only) and subject
22-
to change to match upstream name changes in the Rust standard library.
62+
to change to match upstream name changes in the Rust standard library.*
2363

24-
## `aarch64`
64+
### `aarch64`
2565

2666
Linux, iOS, and macOS/ARM only (ARM64 does not support OS-independent feature detection)
2767

@@ -31,7 +71,7 @@ Target features:
3171
- `sha2`*
3272
- `sha3`*
3373

34-
## `loongarch64`
74+
### `loongarch64`
3575

3676
Linux only (LoongArch64 does not support OS-independent feature detection)
3777

@@ -51,7 +91,7 @@ Target features:
5191
- `lbt.mips`*
5292
- `ptw`*
5393

54-
## `x86`/`x86_64`
94+
### `x86`/`x86_64`
5595

5696
OS independent and `no_std`-friendly
5797

@@ -73,7 +113,7 @@ Target features:
73113
- `avx512vbmi2`*
74114
- `bmi1`
75115
- `bmi2`
76-
- `fma`,
116+
- `fma`
77117
- `mmx`
78118
- `pclmulqdq`
79119
- `popcnt`
@@ -87,12 +127,12 @@ Target features:
87127
- `sse4.1`
88128
- `sse4.2`
89129
- `ssse3`
90-
- `sha512`*
91-
- `sm3`*
92-
- `sm4`*
130+
- `sha512`
131+
- `sm3`
132+
- `sm4`
93133

94134
If you would like detection support for a target feature which is not on
95-
this list, please [open a GitHub issue].
135+
this list, please [open a GitHub issue][github-issue].
96136

97137
## License
98138

@@ -124,6 +164,7 @@ dual licensed as above, without any additional terms or conditions.
124164

125165
[//]: # (general links)
126166

127-
[RustCrypto]: https://github.com/rustcrypto
167+
[RustCrypto]: https://github.com/RustCrypto
128168
[RustCrypto/utils#378]: https://github.com/RustCrypto/utils/issues/378
129-
[open a GitHub issue]: https://github.com/RustCrypto/utils/issues/new?title=cpufeatures:%20requesting%20support%20for%20CHANGEME%20target%20feature
169+
[RFC 2725]: https://github.com/rust-lang/rfcs/pull/2725
170+
[github-issue]: https://github.com/RustCrypto/utils/issues/new?title=cpufeatures:%20requesting%20support%20for%20CHANGEME%20target%20feature

‎cpufeatures/src/lib.rs‎

Lines changed: 1 addition & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -1,126 +1,5 @@
1-
//! This crate provides macros for runtime CPU feature detection. It's intended
2-
//! as a stopgap until Rust [RFC 2725] adding first-class target feature detection
3-
//! macros to `libcore` is implemented.
4-
//!
5-
//! # Supported target architectures
6-
//!
7-
//! *NOTE: target features with an asterisk are unstable (nightly-only) and
8-
//! subject to change to match upstream name changes in the Rust standard
9-
//! library.
10-
//!
11-
//! ## `aarch64`
12-
//!
13-
//! Linux, iOS, and macOS/ARM only (ARM64 does not support OS-independent feature detection)
14-
//!
15-
//! Target features:
16-
//!
17-
//! - `aes`*
18-
//! - `sha2`*
19-
//! - `sha3`*
20-
//!
21-
//! Linux only
22-
//!
23-
//! - `sm4`*
24-
//!
25-
//! ## `loongarch64`
26-
//!
27-
//! Linux only (LoongArch64 does not support OS-independent feature detection)
28-
//!
29-
//! Target features:
30-
//!
31-
//! - `lam`*
32-
//! - `ual`*
33-
//! - `fpu`*
34-
//! - `lsx`*
35-
//! - `lasx`*
36-
//! - `crc32`*
37-
//! - `complex`*
38-
//! - `crypto`*
39-
//! - `lvz`*
40-
//! - `lbt.x86`*
41-
//! - `lbt.arm`*
42-
//! - `lbt.mips`*
43-
//! - `ptw`*
44-
//!
45-
//! ## `x86`/`x86_64`
46-
//!
47-
//! OS independent and `no_std`-friendly
48-
//!
49-
//! Target features:
50-
//!
51-
//! - `adx`
52-
//! - `aes`
53-
//! - `avx`
54-
//! - `avx2`
55-
//! - `avx512bw`*
56-
//! - `avx512cd`*
57-
//! - `avx512dq`*
58-
//! - `avx512er`*
59-
//! - `avx512f`*
60-
//! - `avx512ifma`*
61-
//! - `avx512pf`*
62-
//! - `avx512vl`*
63-
//! - `bmi1`
64-
//! - `bmi2`
65-
//! - `fma`,
66-
//! - `mmx`
67-
//! - `pclmulqdq`
68-
//! - `popcnt`
69-
//! - `rdrand`
70-
//! - `rdseed`
71-
//! - `sgx`
72-
//! - `sha`
73-
//! - `sse`
74-
//! - `sse2`
75-
//! - `sse3`
76-
//! - `sse4.1`
77-
//! - `sse4.2`
78-
//! - `ssse3`
79-
//!
80-
//! If you would like detection support for a target feature which is not on
81-
//! this list, please [open a GitHub issue][gh].
82-
//!
83-
//! # Example
84-
//! ```
85-
//! # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
86-
//! # {
87-
//! // This macro creates `cpuid_aes_sha` module
88-
//! cpufeatures::new!(cpuid_aes_sha, "aes", "sha");
89-
//!
90-
//! // `token` is a Zero Sized Type (ZST) value, which guarantees
91-
//! // that underlying static storage got properly initialized,
92-
//! // which allows to omit initialization branch
93-
//! let token: cpuid_aes_sha::InitToken = cpuid_aes_sha::init();
94-
//!
95-
//! if token.get() {
96-
//! println!("CPU supports both SHA and AES extensions");
97-
//! } else {
98-
//! println!("SHA and AES extensions are not supported");
99-
//! }
100-
//!
101-
//! // If stored value needed only once you can get stored value
102-
//! // omitting the token
103-
//! let val = cpuid_aes_sha::get();
104-
//! assert_eq!(val, token.get());
105-
//!
106-
//! // Additionally you can get both token and value
107-
//! let (token, val) = cpuid_aes_sha::init_get();
108-
//! assert_eq!(val, token.get());
109-
//! # }
110-
//! ```
111-
//!
112-
//! Note that if all tested target features are enabled via compiler options
113-
//! (e.g. by using `RUSTFLAGS`), the `get` method will always return `true`
114-
//! and `init` will not use CPUID instruction. Such behavior allows
115-
//! compiler to completely eliminate fallback code.
116-
//!
117-
//! After first call macro caches result and returns it in subsequent
118-
//! calls, thus runtime overhead for them is minimal.
119-
//!
120-
//! [RFC 2725]: https://github.com/rust-lang/rfcs/pull/2725
121-
//! [gh]: https://github.com/RustCrypto/utils/issues/new?title=cpufeatures:%20requesting%20support%20for%20CHANGEME%20target%20feature
122-
1231
#![no_std]
2+
#![doc = include_str!("../README.md")]
1243
#![doc(
1254
html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
1265
html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"

0 commit comments

Comments
 (0)