Skip to content

[Headers][X86] Make brief descriptions briefer #82422

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 28, 2024
Merged

[Headers][X86] Make brief descriptions briefer #82422

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
121 changes: 62 additions & 59 deletions clang/lib/Headers/emmintrin.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2099,9 +2099,11 @@ static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_add_epi64(__m128i __a,
}

/// Adds, with saturation, the corresponding elements of two 128-bit
/// signed [16 x i8] vectors, saving each sum in the corresponding element of
/// a 128-bit result vector of [16 x i8]. Positive sums greater than 0x7F are
/// saturated to 0x7F. Negative sums less than 0x80 are saturated to 0x80.
/// signed [16 x i8] vectors, saving each sum in the corresponding element
/// of a 128-bit result vector of [16 x i8].
///
Copy link
Contributor

@phoebewang phoebewang Feb 21, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we remove the blank line to make it more compact?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description of brief says "A brief description ends when a blank line or another sectioning command is encountered." About the only command that would make sense here is \par which has to be on a line by itself, so the result would not be more compact.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's exactly the reason for my suggestion. By making it more compact, I actually mean we should make them one brief description instead of two. The second paragraph is not another \brief or \details. It's jsut supplement to the first paragraph.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding the blank line makes the brief section more compact, so I'm not clear what you want.

In our documentation, the first paragraph appears at the top of the documentation page for the function; both paragraphs will appear in the full description after the synopsis. No information is lost. I believe the detail about how saturation works is not needed in the brief description.

Are you saying the detail about saturation belongs in the brief description? Or something else?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you saying the detail about saturation belongs in the brief description?

Yes. I though otherwise the full description may turn into the second paragraph only. I'm not a doxygen user, so the explanation sounds good to me.

/// Positive sums greater than 0x7F are saturated to 0x7F. Negative sums
/// less than 0x80 are saturated to 0x80.
///
/// \headerfile <x86intrin.h>
///
Expand All @@ -2119,10 +2121,11 @@ static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_adds_epi8(__m128i __a,
}

/// Adds, with saturation, the corresponding elements of two 128-bit
/// signed [8 x i16] vectors, saving each sum in the corresponding element of
/// a 128-bit result vector of [8 x i16]. Positive sums greater than 0x7FFF
/// are saturated to 0x7FFF. Negative sums less than 0x8000 are saturated to
/// 0x8000.
/// signed [8 x i16] vectors, saving each sum in the corresponding element
/// of a 128-bit result vector of [8 x i16].
///
/// Positive sums greater than 0x7FFF are saturated to 0x7FFF. Negative sums
/// less than 0x8000 are saturated to 0x8000.
///
/// \headerfile <x86intrin.h>
///
Expand All @@ -2141,8 +2144,10 @@ static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_adds_epi16(__m128i __a,

/// Adds, with saturation, the corresponding elements of two 128-bit
/// unsigned [16 x i8] vectors, saving each sum in the corresponding element
/// of a 128-bit result vector of [16 x i8]. Positive sums greater than 0xFF
/// are saturated to 0xFF. Negative sums are saturated to 0x00.
/// of a 128-bit result vector of [16 x i8].
///
/// Positive sums greater than 0xFF are saturated to 0xFF. Negative sums are
/// saturated to 0x00.
///
/// \headerfile <x86intrin.h>
///
Expand All @@ -2161,8 +2166,10 @@ static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_adds_epu8(__m128i __a,

/// Adds, with saturation, the corresponding elements of two 128-bit
/// unsigned [8 x i16] vectors, saving each sum in the corresponding element
/// of a 128-bit result vector of [8 x i16]. Positive sums greater than
/// 0xFFFF are saturated to 0xFFFF. Negative sums are saturated to 0x0000.
/// of a 128-bit result vector of [8 x i16].
///
/// Positive sums greater than 0xFFFF are saturated to 0xFFFF. Negative sums
/// are saturated to 0x0000.
///
/// \headerfile <x86intrin.h>
///
Expand Down Expand Up @@ -2518,10 +2525,12 @@ static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_sub_epi64(__m128i __a,
return (__m128i)((__v2du)__a - (__v2du)__b);
}

/// Subtracts corresponding 8-bit signed integer values in the input and
/// returns the differences in the corresponding bytes in the destination.
/// Differences greater than 0x7F are saturated to 0x7F, and differences less
/// than 0x80 are saturated to 0x80.
/// Subtracts, with saturation, corresponding 8-bit signed integer values in
/// the input and returns the differences in the corresponding bytes in the
/// destination.
///
/// Differences greater than 0x7F are saturated to 0x7F, and differences
/// less than 0x80 are saturated to 0x80.
///
/// \headerfile <x86intrin.h>
///
Expand All @@ -2538,8 +2547,10 @@ static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_subs_epi8(__m128i __a,
return (__m128i)__builtin_elementwise_sub_sat((__v16qs)__a, (__v16qs)__b);
}

/// Subtracts corresponding 16-bit signed integer values in the input and
/// returns the differences in the corresponding bytes in the destination.
/// Subtracts, with saturation, corresponding 16-bit signed integer values in
/// the input and returns the differences in the corresponding bytes in the
/// destination.
///
/// Differences greater than 0x7FFF are saturated to 0x7FFF, and values less
/// than 0x8000 are saturated to 0x8000.
///
Expand All @@ -2558,9 +2569,11 @@ static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_subs_epi16(__m128i __a,
return (__m128i)__builtin_elementwise_sub_sat((__v8hi)__a, (__v8hi)__b);
}

/// Subtracts corresponding 8-bit unsigned integer values in the input
/// and returns the differences in the corresponding bytes in the
/// destination. Differences less than 0x00 are saturated to 0x00.
/// Subtracts, with saturation, corresponding 8-bit unsigned integer values in
/// the input and returns the differences in the corresponding bytes in the
/// destination.
///
/// Differences less than 0x00 are saturated to 0x00.
///
/// \headerfile <x86intrin.h>
///
Expand All @@ -2577,9 +2590,11 @@ static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_subs_epu8(__m128i __a,
return (__m128i)__builtin_elementwise_sub_sat((__v16qu)__a, (__v16qu)__b);
}

/// Subtracts corresponding 16-bit unsigned integer values in the input
/// and returns the differences in the corresponding bytes in the
/// destination. Differences less than 0x0000 are saturated to 0x0000.
/// Subtracts, with saturation, corresponding 16-bit unsigned integer values in
/// the input and returns the differences in the corresponding bytes in the
/// destination.
///
/// Differences less than 0x0000 are saturated to 0x0000.
///
/// \headerfile <x86intrin.h>
///
Expand Down Expand Up @@ -4050,80 +4065,68 @@ void _mm_mfence(void);
} // extern "C"
#endif

/// Converts 16-bit signed integers from both 128-bit integer vector
/// operands into 8-bit signed integers, and packs the results into the
/// destination. Positive values greater than 0x7F are saturated to 0x7F.
/// Negative values less than 0x80 are saturated to 0x80.
/// Converts, with saturation, 16-bit signed integers from both 128-bit integer
/// vector operands into 8-bit signed integers, and packs the results into
/// the destination.
///
/// Positive values greater than 0x7F are saturated to 0x7F. Negative values
/// less than 0x80 are saturated to 0x80.
///
/// \headerfile <x86intrin.h>
///
/// This intrinsic corresponds to the <c> VPACKSSWB / PACKSSWB </c> instruction.
///
/// \param __a
/// A 128-bit integer vector of [8 x i16]. Each 16-bit element is treated as
/// a signed integer and is converted to a 8-bit signed integer with
/// saturation. Values greater than 0x7F are saturated to 0x7F. Values less
/// than 0x80 are saturated to 0x80. The converted [8 x i8] values are
/// A 128-bit integer vector of [8 x i16]. The converted [8 x i8] values are
/// written to the lower 64 bits of the result.
/// \param __b
/// A 128-bit integer vector of [8 x i16]. Each 16-bit element is treated as
/// a signed integer and is converted to a 8-bit signed integer with
/// saturation. Values greater than 0x7F are saturated to 0x7F. Values less
/// than 0x80 are saturated to 0x80. The converted [8 x i8] values are
/// A 128-bit integer vector of [8 x i16]. The converted [8 x i8] values are
/// written to the higher 64 bits of the result.
/// \returns A 128-bit vector of [16 x i8] containing the converted values.
static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_packs_epi16(__m128i __a,
__m128i __b) {
return (__m128i)__builtin_ia32_packsswb128((__v8hi)__a, (__v8hi)__b);
}

/// Converts 32-bit signed integers from both 128-bit integer vector
/// operands into 16-bit signed integers, and packs the results into the
/// destination. Positive values greater than 0x7FFF are saturated to 0x7FFF.
/// Negative values less than 0x8000 are saturated to 0x8000.
/// Converts, with saturation, 32-bit signed integers from both 128-bit integer
/// vector operands into 16-bit signed integers, and packs the results into
/// the destination.
///
/// Positive values greater than 0x7FFF are saturated to 0x7FFF. Negative
/// values less than 0x8000 are saturated to 0x8000.
///
/// \headerfile <x86intrin.h>
///
/// This intrinsic corresponds to the <c> VPACKSSDW / PACKSSDW </c> instruction.
///
/// \param __a
/// A 128-bit integer vector of [4 x i32]. Each 32-bit element is treated as
/// a signed integer and is converted to a 16-bit signed integer with
/// saturation. Values greater than 0x7FFF are saturated to 0x7FFF. Values
/// less than 0x8000 are saturated to 0x8000. The converted [4 x i16] values
/// A 128-bit integer vector of [4 x i32]. The converted [4 x i16] values
/// are written to the lower 64 bits of the result.
/// \param __b
/// A 128-bit integer vector of [4 x i32]. Each 32-bit element is treated as
/// a signed integer and is converted to a 16-bit signed integer with
/// saturation. Values greater than 0x7FFF are saturated to 0x7FFF. Values
/// less than 0x8000 are saturated to 0x8000. The converted [4 x i16] values
/// A 128-bit integer vector of [4 x i32]. The converted [4 x i16] values
/// are written to the higher 64 bits of the result.
/// \returns A 128-bit vector of [8 x i16] containing the converted values.
static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_packs_epi32(__m128i __a,
__m128i __b) {
return (__m128i)__builtin_ia32_packssdw128((__v4si)__a, (__v4si)__b);
}

/// Converts 16-bit signed integers from both 128-bit integer vector
/// operands into 8-bit unsigned integers, and packs the results into the
/// destination. Values greater than 0xFF are saturated to 0xFF. Values less
/// than 0x00 are saturated to 0x00.
/// Converts, with saturation, 16-bit signed integers from both 128-bit integer
/// vector operands into 8-bit unsigned integers, and packs the results into
/// the destination.
///
/// Values greater than 0xFF are saturated to 0xFF. Values less than 0x00
/// are saturated to 0x00.
///
/// \headerfile <x86intrin.h>
///
/// This intrinsic corresponds to the <c> VPACKUSWB / PACKUSWB </c> instruction.
///
/// \param __a
/// A 128-bit integer vector of [8 x i16]. Each 16-bit element is treated as
/// a signed integer and is converted to an 8-bit unsigned integer with
/// saturation. Values greater than 0xFF are saturated to 0xFF. Values less
/// than 0x00 are saturated to 0x00. The converted [8 x i8] values are
/// A 128-bit integer vector of [8 x i16]. The converted [8 x i8] values are
/// written to the lower 64 bits of the result.
/// \param __b
/// A 128-bit integer vector of [8 x i16]. Each 16-bit element is treated as
/// a signed integer and is converted to an 8-bit unsigned integer with
/// saturation. Values greater than 0xFF are saturated to 0xFF. Values less
/// than 0x00 are saturated to 0x00. The converted [8 x i8] values are
/// A 128-bit integer vector of [8 x i16]. The converted [8 x i8] values are
/// written to the higher 64 bits of the result.
/// \returns A 128-bit vector of [16 x i8] containing the converted values.
static __inline__ __m128i __DEFAULT_FN_ATTRS _mm_packus_epi16(__m128i __a,
Expand Down
48 changes: 32 additions & 16 deletions clang/lib/Headers/fmaintrin.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,8 @@ _mm_fmadd_pd(__m128d __A, __m128d __B, __m128d __C)

/// Computes a scalar multiply-add of the single-precision values in the
/// low 32 bits of 128-bit vectors of [4 x float].
/// \code
///
/// \code{.operation}
/// result[31:0] = (__A[31:0] * __B[31:0]) + __C[31:0]
/// result[127:32] = __A[127:32]
/// \endcode
Expand Down Expand Up @@ -88,7 +89,8 @@ _mm_fmadd_ss(__m128 __A, __m128 __B, __m128 __C)

/// Computes a scalar multiply-add of the double-precision values in the
/// low 64 bits of 128-bit vectors of [2 x double].
/// \code
///
/// \code{.operation}
/// result[63:0] = (__A[63:0] * __B[63:0]) + __C[63:0]
/// result[127:64] = __A[127:64]
/// \endcode
Expand Down Expand Up @@ -156,7 +158,8 @@ _mm_fmsub_pd(__m128d __A, __m128d __B, __m128d __C)

/// Computes a scalar multiply-subtract of the single-precision values in
/// the low 32 bits of 128-bit vectors of [4 x float].
/// \code
///
/// \code{.operation}
/// result[31:0] = (__A[31:0] * __B[31:0]) - __C[31:0]
/// result[127:32] = __A[127:32]
/// \endcode
Expand Down Expand Up @@ -184,7 +187,8 @@ _mm_fmsub_ss(__m128 __A, __m128 __B, __m128 __C)

/// Computes a scalar multiply-subtract of the double-precision values in
/// the low 64 bits of 128-bit vectors of [2 x double].
/// \code
///
/// \code{.operation}
/// result[63:0] = (__A[63:0] * __B[63:0]) - __C[63:0]
/// result[127:64] = __A[127:64]
/// \endcode
Expand Down Expand Up @@ -252,7 +256,8 @@ _mm_fnmadd_pd(__m128d __A, __m128d __B, __m128d __C)

/// Computes a scalar negated multiply-add of the single-precision values in
/// the low 32 bits of 128-bit vectors of [4 x float].
/// \code
///
/// \code{.operation}
/// result[31:0] = -(__A[31:0] * __B[31:0]) + __C[31:0]
/// result[127:32] = __A[127:32]
/// \endcode
Expand Down Expand Up @@ -280,7 +285,8 @@ _mm_fnmadd_ss(__m128 __A, __m128 __B, __m128 __C)

/// Computes a scalar negated multiply-add of the double-precision values
/// in the low 64 bits of 128-bit vectors of [2 x double].
/// \code
///
/// \code{.operation}
/// result[63:0] = -(__A[63:0] * __B[63:0]) + __C[63:0]
/// result[127:64] = __A[127:64]
/// \endcode
Expand Down Expand Up @@ -348,7 +354,8 @@ _mm_fnmsub_pd(__m128d __A, __m128d __B, __m128d __C)

/// Computes a scalar negated multiply-subtract of the single-precision
/// values in the low 32 bits of 128-bit vectors of [4 x float].
/// \code
///
/// \code{.operation}
/// result[31:0] = -(__A[31:0] * __B[31:0]) - __C[31:0]
/// result[127:32] = __A[127:32]
/// \endcode
Expand Down Expand Up @@ -376,7 +383,8 @@ _mm_fnmsub_ss(__m128 __A, __m128 __B, __m128 __C)

/// Computes a scalar negated multiply-subtract of the double-precision
/// values in the low 64 bits of 128-bit vectors of [2 x double].
/// \code
///
/// \code{.operation}
/// result[63:0] = -(__A[63:0] * __B[63:0]) - __C[63:0]
/// result[127:64] = __A[127:64]
/// \endcode
Expand Down Expand Up @@ -404,7 +412,8 @@ _mm_fnmsub_sd(__m128d __A, __m128d __B, __m128d __C)

/// Computes a multiply with alternating add/subtract of 128-bit vectors of
/// [4 x float].
/// \code
///
/// \code{.operation}
/// result[31:0] = (__A[31:0] * __B[31:0]) - __C[31:0]
/// result[63:32] = (__A[63:32] * __B[63:32]) + __C[63:32]
/// result[95:64] = (__A[95:64] * __B[95:64]) - __C[95:64]
Expand All @@ -430,7 +439,8 @@ _mm_fmaddsub_ps(__m128 __A, __m128 __B, __m128 __C)

/// Computes a multiply with alternating add/subtract of 128-bit vectors of
/// [2 x double].
/// \code
///
/// \code{.operation}
/// result[63:0] = (__A[63:0] * __B[63:0]) - __C[63:0]
/// result[127:64] = (__A[127:64] * __B[127:64]) + __C[127:64]
/// \endcode
Expand All @@ -454,7 +464,8 @@ _mm_fmaddsub_pd(__m128d __A, __m128d __B, __m128d __C)

/// Computes a multiply with alternating add/subtract of 128-bit vectors of
/// [4 x float].
/// \code
///
/// \code{.operation}
/// result[31:0] = (__A[31:0] * __B[31:0]) + __C[31:0]
/// result[63:32] = (__A[63:32] * __B[63:32]) - __C[63:32]
/// result[95:64] = (__A[95:64] * __B[95:64]) + __C[95:64]
Expand All @@ -480,7 +491,8 @@ _mm_fmsubadd_ps(__m128 __A, __m128 __B, __m128 __C)

/// Computes a multiply with alternating add/subtract of 128-bit vectors of
/// [2 x double].
/// \code
///
/// \code{.operation}
/// result[63:0] = (__A[63:0] * __B[63:0]) + __C[63:0]
/// result[127:64] = (__A[127:64] * __B[127:64]) - __C[127:64]
/// \endcode
Expand Down Expand Up @@ -664,7 +676,8 @@ _mm256_fnmsub_pd(__m256d __A, __m256d __B, __m256d __C)

/// Computes a multiply with alternating add/subtract of 256-bit vectors of
/// [8 x float].
/// \code
///
/// \code{.operation}
/// result[31:0] = (__A[31:0] * __B[31:0]) - __C[31:0]
/// result[63:32] = (__A[63:32] * __B[63:32]) + __C[63:32]
/// result[95:64] = (__A[95:64] * __B[95:64]) - __C[95:64]
Expand Down Expand Up @@ -694,7 +707,8 @@ _mm256_fmaddsub_ps(__m256 __A, __m256 __B, __m256 __C)

/// Computes a multiply with alternating add/subtract of 256-bit vectors of
/// [4 x double].
/// \code
///
/// \code{.operation}
/// result[63:0] = (__A[63:0] * __B[63:0]) - __C[63:0]
/// result[127:64] = (__A[127:64] * __B[127:64]) + __C[127:64]
/// result[191:128] = (__A[191:128] * __B[191:128]) - __C[191:128]
Expand All @@ -720,7 +734,8 @@ _mm256_fmaddsub_pd(__m256d __A, __m256d __B, __m256d __C)

/// Computes a vector multiply with alternating add/subtract of 256-bit
/// vectors of [8 x float].
/// \code
///
/// \code{.operation}
/// result[31:0] = (__A[31:0] * __B[31:0]) + __C[31:0]
/// result[63:32] = (__A[63:32] * __B[63:32]) - __C[63:32]
/// result[95:64] = (__A[95:64] * __B[95:64]) + __C[95:64]
Expand Down Expand Up @@ -750,7 +765,8 @@ _mm256_fmsubadd_ps(__m256 __A, __m256 __B, __m256 __C)

/// Computes a vector multiply with alternating add/subtract of 256-bit
/// vectors of [4 x double].
/// \code
///
/// \code{.operation}
/// result[63:0] = (__A[63:0] * __B[63:0]) + __C[63:0]
/// result[127:64] = (__A[127:64] * __B[127:64]) - __C[127:64]
/// result[191:128] = (__A[191:128] * __B[191:128]) + __C[191:128]
Expand Down
Loading