Skip to content

Commit 524c896

Browse files
alexcrichtonalexcrichton
authored
Beef up documentation of arch module (#331)
This commit reorganizes some documentation for inclusion into the standard library, moving the bulk of the docs to the `arch` module and away from the crate root which won't actually be the end-user interface.
1 parent bed25b2 commit 524c896

File tree

4 files changed

+400
-140
lines changed

4 files changed

+400
-140
lines changed

‎coresimd/mod.rs

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
/// Platform independent SIMD vector types and operations.
2+
///
3+
/// This is an **unstable** module for portable SIMD operations. This module has
4+
/// not yet gone through an RFC and is likely to change, but feedback is always
5+
/// welcome!
26
#[unstable(feature = "stdsimd", issue = "0")]
37
pub mod simd {
48
pub use coresimd::v128::*;
@@ -8,23 +12,55 @@ pub mod simd {
812
}
913

1014
/// Platform dependent vendor intrinsics.
15+
///
16+
/// This documentation is for the version of this module in the `coresimd`
17+
/// crate, but you probably want to use the [`stdsimd` crate][stdsimd] which
18+
/// should have more complete documentation.
19+
///
20+
/// [stdsimd]: https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/arch/index.html
21+
///
22+
/// Also note that while this module may appear to contains the intrinsics for
23+
/// only one platform it actually contains intrinsics for multiple platforms
24+
/// compiled in conditionally. For other platforms of stdsimd see:
25+
///
26+
/// * [x86]
27+
/// * [x86_64]
28+
/// * [arm]
29+
/// * [aarch64]
30+
///
31+
/// [x86]: https://rust-lang-nursery.github.io/stdsimd/x86/stdsimd/arch/index.html
32+
/// [x86_64]: https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/arch/index.html
33+
/// [arm]: https://rust-lang-nursery.github.io/stdsimd/arm/stdsimd/arch/index.html
34+
/// [aarch64]: https://rust-lang-nursery.github.io/stdsimd/aarch64/stdsimd/arch/index.html
1135
#[unstable(feature = "stdsimd", issue = "0")]
1236
pub mod arch {
37+
/// Platform-specific intrinsics for the `x86` platform.
38+
///
39+
/// See the [module documentation](../index.html) for more details.
1340
#[cfg(target_arch = "x86")]
1441
pub mod x86 {
1542
pub use coresimd::x86::*;
1643
}
1744

45+
/// Platform-specific intrinsics for the `x86_64` platform.
46+
///
47+
/// See the [module documentation](../index.html) for more details.
1848
#[cfg(target_arch = "x86_64")]
1949
pub mod x86_64 {
2050
pub use coresimd::x86::*;
2151
}
2252

53+
/// Platform-specific intrinsics for the `arm` platform.
54+
///
55+
/// See the [module documentation](../index.html) for more details.
2356
#[cfg(target_arch = "arm")]
2457
pub mod arm {
2558
pub use coresimd::arm::*;
2659
}
2760

61+
/// Platform-specific intrinsics for the `aarch64` platform.
62+
///
63+
/// See the [module documentation](../index.html) for more details.
2864
#[cfg(target_arch = "aarch64")]
2965
pub mod aarch64 {
3066
pub use coresimd::arm::*;

‎crates/coresimd/src/lib.rs

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,10 @@
11
//! SIMD and vendor intrinsics support library.
22
//!
3-
//! This documentation is only for one particular architecture, you can find
4-
//! others at:
3+
//! This documentation is for the `coresimd` crate, but you probably want to use
4+
//! the [`stdsimd` crate][stdsimd] which should have more complete
5+
//! documentation.
56
//!
6-
//! * [i686](https://rust-lang-nursery.github.io/stdsimd/i686/stdsimd/)
7-
//! * [`x86_64`](https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/)
8-
//! * [arm](https://rust-lang-nursery.github.io/stdsimd/arm/stdsimd/)
9-
//! * [aarch64](https://rust-lang-nursery.github.io/stdsimd/aarch64/stdsimd/)
7+
//! [stdsimd]: https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/
108
119
#![cfg_attr(feature = "strict", deny(warnings))]
1210
#![allow(dead_code)]

‎crates/stdsimd/src/lib.rs

Lines changed: 8 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -1,136 +1,11 @@
11
//! SIMD and vendor intrinsics support library.
22
//!
3-
//! This documentation is only for one particular architecture, you can find
4-
//! others at:
3+
//! This crate defines the vendor intrinsics and types primarily used for SIMD
4+
//! in Rust. The crate here will soon be available in the standard library, but
5+
//! for now you can also browse the documentation here, primarily in the `arch`
6+
//! submodule.
57
//!
6-
//! * [i686](https://rust-lang-nursery.github.io/stdsimd/i686/stdsimd/)
7-
//! * [`x86_64`](https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/)
8-
//! * [arm](https://rust-lang-nursery.github.io/stdsimd/arm/stdsimd/)
9-
//! * [aarch64](https://rust-lang-nursery.github.io/stdsimd/aarch64/stdsimd/)
10-
//! * [powerpc](https://rust-lang-nursery.github.io/stdsimd/powerpc/stdsimd/)
11-
//! * [powerpc64](https://rust-lang-nursery.github.io/stdsimd/powerpc64/stdsimd/)
12-
//!
13-
//! # Overview
14-
//!
15-
//! The `simd` module exposes *portable vector types*. These types work on all
16-
//! platforms, but their run-time performance may vary depending on hardware
17-
//! support.
18-
//!
19-
//! The `vendor` module exposes vendor-specific intrinsics that typically
20-
//! correspond to a single machine instruction. In general, these intrinsics
21-
//! are not portable: their availability is architecture-dependent, and not all
22-
//! machines of that architecture might provide the intrinsic.
23-
//!
24-
//! Two macros make it possible to write portable code:
25-
//!
26-
//! * `cfg!(target_feature = "feature")`: returns `true` if the `feature` is
27-
//! enabled in all CPUs that the binary will run on (at compile-time)
28-
//! * `is_target_feature_detected!("feature")`: returns `true` if the `feature` is
29-
//! enabled in the CPU in which the binary is currently running on (at
30-
//! run-time, unless the result is known at compile time)
31-
//!
32-
//! # Example
33-
//!
34-
//! ```rust
35-
//! #![feature(cfg_target_feature, target_feature, stdsimd)]
36-
//!
37-
//! #[macro_use]
38-
//! extern crate stdsimd;
39-
//! use stdsimd::simd::i32x4;
40-
//!
41-
//! fn main() {
42-
//! let a = i32x4::new(1, 2, 3, 4);
43-
//! let b = i32x4::splat(10);
44-
//! assert_eq!(b, i32x4::new(10, 10, 10, 10));
45-
//! let c = a + b;
46-
//! assert_eq!(c, i32x4::new(11, 12, 13, 14));
47-
//! assert_eq!(sum_portable(b), 40);
48-
//! assert_eq!(sum_ct(b), 40);
49-
//! assert_eq!(sum_rt(b), 40);
50-
//! }
51-
//!
52-
//! // Sums the elements of the vector.
53-
//! fn sum_portable(x: i32x4) -> i32 {
54-
//! let mut r = 0;
55-
//! for i in 0..4 {
56-
//! r += x.extract(i);
57-
//! }
58-
//! r
59-
//! }
60-
//!
61-
//! // Sums the elements of the vector using SSE2 instructions.
62-
//! // This function is only safe to call if the CPU where the
63-
//! // binary runs supports SSE2.
64-
//! #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
65-
//! #[target_feature(enable = "sse2")]
66-
//! unsafe fn sum_sse2(x: i32x4) -> i32 {
67-
//! #[cfg(target_arch = "x86")]
68-
//! use stdsimd::arch::x86::*;;
69-
//! #[cfg(target_arch = "x86_64")]
70-
//! use stdsimd::arch::x86_64::*;;
71-
//! use std::mem;
72-
//!
73-
//! let x: __m128i = mem::transmute(x);
74-
//! let x = _mm_add_epi32(x, _mm_srli_si128(x, 8));
75-
//! let x = _mm_add_epi32(x, _mm_srli_si128(x, 4));
76-
//! let ret = _mm_cvtsi128_si32(x);
77-
//! mem::transmute(ret)
78-
//! }
79-
//!
80-
//! // Uses the SSE2 version if SSE2 is enabled for all target
81-
//! // CPUs at compile-time (does not perform any run-time
82-
//! // feature detection).
83-
//! fn sum_ct(x: i32x4) -> i32 {
84-
//! #[cfg(all(any(target_arch = "x86_64", target_arch = "x86"),
85-
//! target_feature = "sse2"))]
86-
//! {
87-
//! // This function is only available for x86/x86_64 targets,
88-
//! // and is only safe to call it if the target supports SSE2
89-
//! unsafe { sum_sse2(x) }
90-
//! }
91-
//! #[cfg(not(all(any(target_arch = "x86_64", target_arch = "x86"),
92-
//! target_feature = "sse2")))]
93-
//! {
94-
//! sum_portable(x)
95-
//! }
96-
//! }
97-
//!
98-
//! // Detects SSE2 at run-time, and uses a SIMD intrinsic if enabled.
99-
//! fn sum_rt(x: i32x4) -> i32 {
100-
//! #[cfg(any(target_arch = "x86_64", target_arch = "x86"))]
101-
//! {
102-
//! // If SSE2 is not enabled at compile-time, this
103-
//! // detects whether SSE2 is available at run-time:
104-
//! if is_target_feature_detected!("sse2") {
105-
//! return unsafe { sum_sse2(x) };
106-
//! }
107-
//! }
108-
//! sum_portable(x)
109-
//! }
110-
//! ```
111-
//!
112-
//! # Status
113-
//!
114-
//! This crate is intended for eventual inclusion into the standard library,
115-
//! but some work and experimentation is needed to get there! First and
116-
//! foremost you can help out by kicking the tires on this crate and seeing if
117-
//! it works for your use case! Next up you can help us fill out the [vendor
118-
//! intrinsics][vendor] to ensure that we've got all the SIMD support
119-
//! necessary.
120-
//!
121-
//! The language support and status of SIMD is also still a little up in the
122-
//! air right now, you may be interested in a few issues along these lines:
123-
//!
124-
//! * [Overal tracking issue for SIMD support][simd_tracking_issue]
125-
//! * [`cfg_target_feature` tracking issue][cfg_target_feature_issue]
126-
//! * [SIMD types currently not sound][simd_soundness_bug]
127-
//! * [`#[target_feature]` improvements][target_feature_impr]
128-
//!
129-
//! [vendor]: https://github.com/rust-lang-nursery/stdsimd/issues/40
130-
//! [simd_tracking_issue]: https://github.com/rust-lang/rust/issues/27731
131-
//! [cfg_target_feature_issue]: https://github.com/rust-lang/rust/issues/29717
132-
//! [simd_soundness_bug]: https://github.com/rust-lang/rust/issues/44367
133-
//! [target_feature_impr]: https://github.com/rust-lang/rust/issues/44839
8+
//! [stdsimd]: https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/
1349
13510
#![feature(const_fn, integer_atomics, staged_api, stdsimd)]
13611
#![cfg_attr(target_os = "linux", feature(linkage))]
@@ -152,6 +27,6 @@ mod stdsimd;
15227

15328
pub use stdsimd::*;
15429

155-
pub use _std::prelude;
156-
pub use _std::fs;
157-
pub use _std::io;
30+
use _std::prelude;
31+
use _std::fs;
32+
use _std::io;

0 commit comments

Comments
 (0)