|
1 | | -//! SIMD support |
2 | | -//! |
3 | | -//! This crate provides the fundamentals of supporting SIMD in Rust. This crate |
4 | | -//! should compile on all platforms and provide `simd` and `vendor` modules at |
5 | | -//! the top-level. The `simd` module contains *portable vector types* which |
6 | | -//! should work across all platforms and be implemented in the most efficient |
7 | | -//! manner possible for the platform at hand. The `vendor` module contains |
8 | | -//! vendor intrinsics that operate over these SIMD types, typically |
9 | | -//! corresponding to a particular CPU instruction |
10 | | -//! |
11 | | -//! ```rust |
12 | | -//! extern crate coresimd as stdsimd; |
13 | | -//! use stdsimd::simd::u32x4; |
14 | | -//! |
15 | | -//! fn main() { |
16 | | -//! let a = u32x4::new(1, 2, 3, 4); |
17 | | -//! let b = u32x4::splat(10); |
18 | | -//! assert_eq!(a + b, u32x4::new(11, 12, 13, 14)); |
19 | | -//! } |
20 | | -//! ``` |
21 | | -//! |
22 | | -//! > **Note**: This crate is *nightly only* at the moment, and requires a |
23 | | -//! > nightly rust toolchain to compile. |
| 1 | +//! SIMD and vendor intrinsics support library. |
24 | 2 | //! |
25 | 3 | //! This documentation is only for one particular architecture, you can find |
26 | 4 | //! others at: |
|
29 | 7 | //! * [`x86_64`](https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/) |
30 | 8 | //! * [arm](https://rust-lang-nursery.github.io/stdsimd/arm/stdsimd/) |
31 | 9 | //! * [aarch64](https://rust-lang-nursery.github.io/stdsimd/aarch64/stdsimd/) |
32 | | -//! |
33 | | -//! ## Portability |
34 | | -//! |
35 | | -//! The `simd` module and its types should be portable to all platforms. The |
36 | | -//! runtime characteristics of these types may vary per platform and per CPU |
37 | | -//! feature enabled, but they should always have the most optimized |
38 | | -//! implementation for the target at hand. |
39 | | -//! |
40 | | -//! The `vendor` module provides no portability guarantees. The `vendor` module |
41 | | -//! is per CPU architecture currently and provides intrinsics corresponding to |
42 | | -//! functions for that particular CPU architecture. Note that the functions |
43 | | -//! provided in this module are intended to correspond to CPU instructions and |
44 | | -//! have no runtime support for whether you CPU actually supports the |
45 | | -//! instruction. |
46 | | -//! |
47 | | -//! CPU target feature detection is done via the `cfg_feature_enabled!` macro |
48 | | -//! at runtime. This macro will detect at runtime whether the specified feature |
49 | | -//! is available or not, returning true or false depending on the current CPU. |
50 | | -//! |
51 | | -//! ``` |
52 | | -//! #![feature(cfg_target_feature)] |
53 | | -//! |
54 | | -//! #[macro_use] |
55 | | -//! extern crate coresimd as stdsimd; |
56 | | -//! |
57 | | -//! fn main() { |
58 | | -//! if cfg_feature_enabled!("avx2") { |
59 | | -//! println!("avx2 intrinsics will work"); |
60 | | -//! } else { |
61 | | -//! println!("avx2 intrinsics will not work"); |
62 | | -//! // undefined behavior: may generate a `SIGILL`. |
63 | | -//! } |
64 | | -//! } |
65 | | -//! ``` |
66 | | -//! |
67 | | -//! After verifying that a specified feature is available, use `target_feature` |
68 | | -//! to enable a given feature and use the desired intrinsic. |
69 | | -//! |
70 | | -//! ```ignore |
71 | | -//! # #![feature(cfg_target_feature)] |
72 | | -//! # #![feature(target_feature)] |
73 | | -//! # #[macro_use] |
74 | | -//! # extern crate coresimd as stdsimd; |
75 | | -//! # fn main() { |
76 | | -//! # if cfg_feature_enabled!("avx2") { |
77 | | -//! // avx2 specific code may be used in this function |
78 | | -//! #[target_feature = "+avx2"] |
79 | | -//! fn and_256() { |
80 | | -//! // avx2 feature specific intrinsics will work here! |
81 | | -//! use stdsimd::vendor::{__m256i, _mm256_and_si256}; |
82 | | -//! |
83 | | -//! let a = __m256i::splat(5); |
84 | | -//! let b = __m256i::splat(3); |
85 | | -//! |
86 | | -//! let got = unsafe { _mm256_and_si256(a, b) }; |
87 | | -//! |
88 | | -//! assert_eq!(got, __m256i::splat(1)); |
89 | | -//! } |
90 | | -//! # and_256(); |
91 | | -//! # } |
92 | | -//! # } |
93 | | -//! ``` |
94 | | -//! |
95 | | -//! # Status |
96 | | -//! |
97 | | -//! This crate is intended for eventual inclusion into the standard library, |
98 | | -//! but some work and experimentation is needed to get there! First and |
99 | | -//! foremost you can help out by kicking the tires on this crate and seeing if |
100 | | -//! it works for your use case! Next up you can help us fill out the [vendor |
101 | | -//! intrinsics][vendor] to ensure that we've got all the SIMD support |
102 | | -//! necessary. |
103 | | -//! |
104 | | -//! The language support and status of SIMD is also still a little up in the |
105 | | -//! air right now, you may be interested in a few issues along these lines: |
106 | | -//! |
107 | | -//! * [Overal tracking issue for SIMD support][simd_tracking_issue] |
108 | | -//! * [`cfg_target_feature` tracking issue][cfg_target_feature_issue] |
109 | | -//! * [SIMD types currently not sound][simd_soundness_bug] |
110 | | -//! * [`#[target_feature]` improvements][target_feature_impr] |
111 | | -//! |
112 | | -//! [vendor]: https://github.com/rust-lang-nursery/stdsimd/issues/40 |
113 | | -//! [simd_tracking_issue]: https://github.com/rust-lang/rust/issues/27731 |
114 | | -//! [cfg_target_feature_issue]: https://github.com/rust-lang/rust/issues/29717 |
115 | | -//! [simd_soundness_bug]: https://github.com/rust-lang/rust/issues/44367 |
116 | | -//! [target_feature_impr]: https://github.com/rust-lang/rust/issues/44839 |
117 | 10 |
|
118 | 11 | #![cfg_attr(feature = "strict", deny(warnings))] |
119 | 12 | #![allow(dead_code)] |
|
0 commit comments