Skip to content

Commit 2939ca4

Browse files
gnzlbggnzlbg
committed
documents arithmetic reduction semantics
1 parent 8b5843e commit 2939ca4

File tree

3 files changed

+503
-17
lines changed

3 files changed

+503
-17
lines changed

‎coresimd/ppsv/api/arithmetic_reductions.rs

+56-12
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,20 @@ macro_rules! impl_arithmetic_reductions {
66
impl $id {
77
/// Lane-wise addition of the vector elements.
88
///
9-
/// FIXME: document guarantees with respect to:
10-
/// * integers: overflow behavior
11-
/// * floats: order and NaNs
9+
/// The intrinsic performs a tree-reduction of the vector elements.
10+
/// That is, for an 8 element vector:
11+
///
12+
/// > ((x0 + x1) + (x2 + x3)) + ((x4 + x5) + (x6 + x7))
13+
///
14+
/// # Integer vectors
15+
///
16+
/// If an operation overflows it returns the mathematical result
17+
/// modulo `2^n` where `n` is the number of times it overflows.
18+
///
19+
/// # Floating-point vectors
20+
///
21+
/// If one of the vector element is `NaN` the reduction returns
22+
/// `NaN`.
1223
#[cfg(not(target_arch = "aarch64"))]
1324
#[inline]
1425
pub fn sum(self) -> $elem_ty {
@@ -19,9 +30,20 @@ macro_rules! impl_arithmetic_reductions {
1930
}
2031
/// Lane-wise addition of the vector elements.
2132
///
22-
/// FIXME: document guarantees with respect to:
23-
/// * integers: overflow behavior
24-
/// * floats: order and NaNs
33+
/// The intrinsic performs a tree-reduction of the vector elements.
34+
/// That is, for an 8 element vector:
35+
///
36+
/// > ((x0 + x1) + (x2 + x3)) + ((x4 + x5) + (x6 + x7))
37+
///
38+
/// # Integer vectors
39+
///
40+
/// If an operation overflows it returns the mathematical result
41+
/// modulo `2^n` where `n` is the number of times it overflows.
42+
///
43+
/// # Floating-point vectors
44+
///
45+
/// If one of the vector element is `NaN` the reduction returns
46+
/// `NaN`.
2547
#[cfg(target_arch = "aarch64")]
2648
#[inline]
2749
pub fn sum(self) -> $elem_ty {
@@ -36,9 +58,20 @@ macro_rules! impl_arithmetic_reductions {
3658

3759
/// Lane-wise multiplication of the vector elements.
3860
///
39-
/// FIXME: document guarantees with respect to:
40-
/// * integers: overflow behavior
41-
/// * floats: order and NaNs
61+
/// The intrinsic performs a tree-reduction of the vector elements.
62+
/// That is, for an 8 element vector:
63+
///
64+
/// > ((x0 * x1) * (x2 * x3)) * ((x4 * x5) * (x6 * x7))
65+
///
66+
/// # Integer vectors
67+
///
68+
/// If an operation overflows it returns the mathematical result
69+
/// modulo `2^n` where `n` is the number of times it overflows.
70+
///
71+
/// # Floating-point vectors
72+
///
73+
/// If one of the vector element is `NaN` the reduction returns
74+
/// `NaN`.
4275
#[cfg(not(target_arch = "aarch64"))]
4376
#[inline]
4477
pub fn product(self) -> $elem_ty {
@@ -49,9 +82,20 @@ macro_rules! impl_arithmetic_reductions {
4982
}
5083
/// Lane-wise multiplication of the vector elements.
5184
///
52-
/// FIXME: document guarantees with respect to:
53-
/// * integers: overflow behavior
54-
/// * floats: order and NaNs
85+
/// The intrinsic performs a tree-reduction of the vector elements.
86+
/// That is, for an 8 element vector:
87+
///
88+
/// > ((x0 * x1) * (x2 * x3)) * ((x4 * x5) * (x6 * x7))
89+
///
90+
/// # Integer vectors
91+
///
92+
/// If an operation overflows it returns the mathematical result
93+
/// modulo `2^n` where `n` is the number of times it overflows.
94+
///
95+
/// # Floating-point vectors
96+
///
97+
/// If one of the vector element is `NaN` the reduction returns
98+
/// `NaN`.
5599
#[cfg(target_arch = "aarch64")]
56100
#[inline]
57101
pub fn product(self) -> $elem_ty {

‎coresimd/ppsv/api/minmax_reductions.rs

+29-5
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,13 @@ macro_rules! impl_minmax_reductions {
66
impl $id {
77
/// Largest vector value.
88
///
9-
/// FIXME: document behavior for float vectors with NaNs.
9+
/// # Floating-point behvior
10+
///
11+
/// If the vector contains only `NaN` values,
12+
/// the result is a `NaN`.
13+
///
14+
/// Otherwise, if the vector contains `NaN` values, either the
15+
/// largest element of the vector or a `NaN` is returned.
1016
#[cfg(not(target_arch = "aarch64"))]
1117
#[inline]
1218
pub fn max(self) -> $elem_ty {
@@ -15,9 +21,16 @@ macro_rules! impl_minmax_reductions {
1521
simd_reduce_max(self)
1622
}
1723
}
24+
1825
/// Largest vector value.
1926
///
20-
/// FIXME: document behavior for float vectors with NaNs.
27+
/// # Floating-point behvior
28+
///
29+
/// If the vector contains only `NaN` values,
30+
/// the result is a `NaN`.
31+
///
32+
/// Otherwise, if the vector contains `NaN` values, either the
33+
/// largest element of the vector or a `NaN` is returned.
2134
#[cfg(target_arch = "aarch64")]
2235
#[allow(unused_imports)]
2336
#[inline]
@@ -35,7 +48,13 @@ macro_rules! impl_minmax_reductions {
3548

3649
/// Smallest vector value.
3750
///
38-
/// FIXME: document behavior for float vectors with NaNs.
51+
/// # Floating-point behvior
52+
///
53+
/// If the vector contains only `NaN` values,
54+
/// the result is a `NaN`.
55+
///
56+
/// Otherwise, if the vector contains `NaN` values, either the
57+
/// smallest element of the vector or a `NaN` is returned.
3958
#[cfg(not(target_arch = "aarch64"))]
4059
#[inline]
4160
pub fn min(self) -> $elem_ty {
@@ -44,9 +63,14 @@ macro_rules! impl_minmax_reductions {
4463
simd_reduce_min(self)
4564
}
4665
}
47-
/// Smallest vector value.
66+
67+
/// # Floating-point behvior
68+
///
69+
/// If the vector contains only `NaN` values,
70+
/// the result is a `NaN`.
4871
///
49-
/// FIXME: document behavior for float vectors with NaNs.
72+
/// Otherwise, if the vector contains `NaN` values, either the
73+
/// smallest element of the vector or a `NaN` is returned.
5074
#[cfg(target_arch = "aarch64")]
5175
#[allow(unused_imports)]
5276
#[inline]

0 commit comments

Comments
 (0)