Skip to content

Beef up documentation of arch module #331

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 27, 2018
Merged

Beef up documentation of arch module #331

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions coresimd/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
/// Platform independent SIMD vector types and operations.
///
/// This is an **unstable** module for portable SIMD operations. This module has
/// not yet gone through an RFC and is likely to change, but feedback is always
/// welcome!
#[unstable(feature = "stdsimd", issue = "0")]
pub mod simd {
pub use coresimd::v128::*;
Expand All @@ -8,23 +12,55 @@ pub mod simd {
}

/// Platform dependent vendor intrinsics.
///
/// This documentation is for the version of this module in the `coresimd`
/// crate, but you probably want to use the [`stdsimd` crate][stdsimd] which
/// should have more complete documentation.
///
/// [stdsimd]: https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/arch/index.html
///
/// Also note that while this module may appear to contains the intrinsics for
/// only one platform it actually contains intrinsics for multiple platforms
/// compiled in conditionally. For other platforms of stdsimd see:
///
/// * [x86]
/// * [x86_64]
/// * [arm]
/// * [aarch64]
///
/// [x86]: https://rust-lang-nursery.github.io/stdsimd/x86/stdsimd/arch/index.html
/// [x86_64]: https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/arch/index.html
/// [arm]: https://rust-lang-nursery.github.io/stdsimd/arm/stdsimd/arch/index.html
/// [aarch64]: https://rust-lang-nursery.github.io/stdsimd/aarch64/stdsimd/arch/index.html
#[unstable(feature = "stdsimd", issue = "0")]
pub mod arch {
/// Platform-specific intrinsics for the `x86` platform.
///
/// See the [module documentation](../index.html) for more details.
#[cfg(target_arch = "x86")]
pub mod x86 {
pub use coresimd::x86::*;
}

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

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

/// Platform-specific intrinsics for the `aarch64` platform.
///
/// See the [module documentation](../index.html) for more details.
#[cfg(target_arch = "aarch64")]
pub mod aarch64 {
pub use coresimd::arm::*;
Expand Down
10 changes: 4 additions & 6 deletions crates/coresimd/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
//! SIMD and vendor intrinsics support library.
//!
//! This documentation is only for one particular architecture, you can find
//! others at:
//! This documentation is for the `coresimd` crate, but you probably want to use
//! the [`stdsimd` crate][stdsimd] which should have more complete
//! documentation.
//!
//! * [i686](https://rust-lang-nursery.github.io/stdsimd/i686/stdsimd/)
//! * [`x86_64`](https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/)
//! * [arm](https://rust-lang-nursery.github.io/stdsimd/arm/stdsimd/)
//! * [aarch64](https://rust-lang-nursery.github.io/stdsimd/aarch64/stdsimd/)
//! [stdsimd]: https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/

#![cfg_attr(feature = "strict", deny(warnings))]
#![allow(dead_code)]
Expand Down
141 changes: 8 additions & 133 deletions crates/stdsimd/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,136 +1,11 @@
//! SIMD and vendor intrinsics support library.
//!
//! This documentation is only for one particular architecture, you can find
//! others at:
//! This crate defines the vendor intrinsics and types primarily used for SIMD
//! in Rust. The crate here will soon be available in the standard library, but
//! for now you can also browse the documentation here, primarily in the `arch`
//! submodule.
//!
//! * [i686](https://rust-lang-nursery.github.io/stdsimd/i686/stdsimd/)
//! * [`x86_64`](https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/)
//! * [arm](https://rust-lang-nursery.github.io/stdsimd/arm/stdsimd/)
//! * [aarch64](https://rust-lang-nursery.github.io/stdsimd/aarch64/stdsimd/)
//! * [powerpc](https://rust-lang-nursery.github.io/stdsimd/powerpc/stdsimd/)
//! * [powerpc64](https://rust-lang-nursery.github.io/stdsimd/powerpc64/stdsimd/)
//!
//! # Overview
//!
//! The `simd` module exposes *portable vector types*. These types work on all
//! platforms, but their run-time performance may vary depending on hardware
//! support.
//!
//! The `vendor` module exposes vendor-specific intrinsics that typically
//! correspond to a single machine instruction. In general, these intrinsics
//! are not portable: their availability is architecture-dependent, and not all
//! machines of that architecture might provide the intrinsic.
//!
//! Two macros make it possible to write portable code:
//!
//! * `cfg!(target_feature = "feature")`: returns `true` if the `feature` is
//! enabled in all CPUs that the binary will run on (at compile-time)
//! * `is_target_feature_detected!("feature")`: returns `true` if the `feature` is
//! enabled in the CPU in which the binary is currently running on (at
//! run-time, unless the result is known at compile time)
//!
//! # Example
//!
//! ```rust
//! #![feature(cfg_target_feature, target_feature, stdsimd)]
//!
//! #[macro_use]
//! extern crate stdsimd;
//! use stdsimd::simd::i32x4;
//!
//! fn main() {
//! let a = i32x4::new(1, 2, 3, 4);
//! let b = i32x4::splat(10);
//! assert_eq!(b, i32x4::new(10, 10, 10, 10));
//! let c = a + b;
//! assert_eq!(c, i32x4::new(11, 12, 13, 14));
//! assert_eq!(sum_portable(b), 40);
//! assert_eq!(sum_ct(b), 40);
//! assert_eq!(sum_rt(b), 40);
//! }
//!
//! // Sums the elements of the vector.
//! fn sum_portable(x: i32x4) -> i32 {
//! let mut r = 0;
//! for i in 0..4 {
//! r += x.extract(i);
//! }
//! r
//! }
//!
//! // Sums the elements of the vector using SSE2 instructions.
//! // This function is only safe to call if the CPU where the
//! // binary runs supports SSE2.
//! #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
//! #[target_feature(enable = "sse2")]
//! unsafe fn sum_sse2(x: i32x4) -> i32 {
//! #[cfg(target_arch = "x86")]
//! use stdsimd::arch::x86::*;;
//! #[cfg(target_arch = "x86_64")]
//! use stdsimd::arch::x86_64::*;;
//! use std::mem;
//!
//! let x: __m128i = mem::transmute(x);
//! let x = _mm_add_epi32(x, _mm_srli_si128(x, 8));
//! let x = _mm_add_epi32(x, _mm_srli_si128(x, 4));
//! let ret = _mm_cvtsi128_si32(x);
//! mem::transmute(ret)
//! }
//!
//! // Uses the SSE2 version if SSE2 is enabled for all target
//! // CPUs at compile-time (does not perform any run-time
//! // feature detection).
//! fn sum_ct(x: i32x4) -> i32 {
//! #[cfg(all(any(target_arch = "x86_64", target_arch = "x86"),
//! target_feature = "sse2"))]
//! {
//! // This function is only available for x86/x86_64 targets,
//! // and is only safe to call it if the target supports SSE2
//! unsafe { sum_sse2(x) }
//! }
//! #[cfg(not(all(any(target_arch = "x86_64", target_arch = "x86"),
//! target_feature = "sse2")))]
//! {
//! sum_portable(x)
//! }
//! }
//!
//! // Detects SSE2 at run-time, and uses a SIMD intrinsic if enabled.
//! fn sum_rt(x: i32x4) -> i32 {
//! #[cfg(any(target_arch = "x86_64", target_arch = "x86"))]
//! {
//! // If SSE2 is not enabled at compile-time, this
//! // detects whether SSE2 is available at run-time:
//! if is_target_feature_detected!("sse2") {
//! return unsafe { sum_sse2(x) };
//! }
//! }
//! sum_portable(x)
//! }
//! ```
//!
//! # Status
//!
//! This crate is intended for eventual inclusion into the standard library,
//! but some work and experimentation is needed to get there! First and
//! foremost you can help out by kicking the tires on this crate and seeing if
//! it works for your use case! Next up you can help us fill out the [vendor
//! intrinsics][vendor] to ensure that we've got all the SIMD support
//! necessary.
//!
//! The language support and status of SIMD is also still a little up in the
//! air right now, you may be interested in a few issues along these lines:
//!
//! * [Overal tracking issue for SIMD support][simd_tracking_issue]
//! * [`cfg_target_feature` tracking issue][cfg_target_feature_issue]
//! * [SIMD types currently not sound][simd_soundness_bug]
//! * [`#[target_feature]` improvements][target_feature_impr]
//!
//! [vendor]: https://github.com/rust-lang-nursery/stdsimd/issues/40
//! [simd_tracking_issue]: https://github.com/rust-lang/rust/issues/27731
//! [cfg_target_feature_issue]: https://github.com/rust-lang/rust/issues/29717
//! [simd_soundness_bug]: https://github.com/rust-lang/rust/issues/44367
//! [target_feature_impr]: https://github.com/rust-lang/rust/issues/44839
//! [stdsimd]: https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/

#![feature(const_fn, integer_atomics, staged_api, stdsimd)]
#![cfg_attr(target_os = "linux", feature(linkage))]
Expand All @@ -152,6 +27,6 @@ mod stdsimd;

pub use stdsimd::*;

pub use _std::prelude;
pub use _std::fs;
pub use _std::io;
use _std::prelude;
use _std::fs;
use _std::io;
Loading