Document the layout of x86 SIMD types.

Author: veluca93

crates/core_arch/src/x86/mod.rs

@@ -28,6 +28,9 @@ types! {
     /// internal bits differently, check the documentation of the intrinsic
     /// to see how it's being used.
     ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
+    ///
     /// Note that this means that an instance of `__m128i` typically just means
     /// a "bag of bits" which is left up to interpretation at the point of use.
     ///
@@ -66,6 +69,9 @@ types! {
     /// of `__m128` always corresponds to `f32x4`, or four `f32` types packed
     /// together.
     ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
+    ///
     /// Most intrinsics using `__m128` are prefixed with `_mm_` and are
     /// suffixed with "ps" (or otherwise contain "ps"). Not to be confused with
     /// "pd" which is used for `__m128d`.
@@ -102,6 +108,9 @@ types! {
     /// of `__m128d` always corresponds to `f64x2`, or two `f64` types packed
     /// together.
     ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
+    ///
     /// Most intrinsics using `__m128d` are prefixed with `_mm_` and are
     /// suffixed with "pd" (or otherwise contain "pd"). Not to be confused with
     /// "ps" which is used for `__m128`.
@@ -143,6 +152,9 @@ types! {
     /// internal bits differently, check the documentation of the intrinsic
     /// to see how it's being used.
     ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
+    ///
     /// Note that this means that an instance of `__m256i` typically just means
     /// a "bag of bits" which is left up to interpretation at the point of use.
     ///
@@ -178,6 +190,9 @@ types! {
     /// of `__m256` always corresponds to `f32x8`, or eight `f32` types packed
     /// together.
     ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
+    ///
     /// Most intrinsics using `__m256` are prefixed with `_mm256_` and are
     /// suffixed with "ps" (or otherwise contain "ps"). Not to be confused with
     /// "pd" which is used for `__m256d`.
@@ -214,6 +229,9 @@ types! {
     /// of `__m256d` always corresponds to `f64x4`, or four `f64` types packed
     /// together.
     ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
+    ///
     /// Most intrinsics using `__m256d` are prefixed with `_mm256_` and are
     /// suffixed with "pd" (or otherwise contain "pd"). Not to be confused with
     /// "ps" which is used for `__m256`.
@@ -259,6 +277,9 @@ types! {
     /// internal bits differently, check the documentation of the intrinsic
     /// to see how it's being used.
     ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
+    ///
     /// Note that this means that an instance of `__m512i` typically just means
     /// a "bag of bits" which is left up to interpretation at the point of use.
     pub struct __m512i(8 x i64);
@@ -275,6 +296,9 @@ types! {
     /// of `__m512` always corresponds to `f32x16`, or sixteen `f32` types
     /// packed together.
     ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
+    ///
     /// Most intrinsics using `__m512` are prefixed with `_mm512_` and are
     /// suffixed with "ps" (or otherwise contain "ps"). Not to be confused with
     /// "pd" which is used for `__m512d`.
@@ -292,6 +316,9 @@ types! {
     /// of `__m512d` always corresponds to `f64x4`, or eight `f64` types packed
     /// together.
     ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
+    ///
     /// Most intrinsics using `__m512d` are prefixed with `_mm512_` and are
     /// suffixed with "pd" (or otherwise contain "pd"). Not to be confused with
     /// "ps" which is used for `__m512`.
@@ -306,6 +333,9 @@ types! {
     /// This type is representing a 128-bit SIMD register which internally is consisted of
     /// eight packed `u16` instances. Its purpose is for bf16 related intrinsic
     /// implementations.
+    ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
     pub struct __m128bh(8 x u16);
 
     /// 256-bit wide set of 16 `u16` types, x86-specific
@@ -314,6 +344,9 @@ types! {
     /// representing a 256-bit SIMD register which internally is consisted of
     /// 16 packed `u16` instances. Its purpose is for bf16 related intrinsic
     /// implementations.
+    ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
     pub struct __m256bh(16 x u16);
 
     /// 512-bit wide set of 32 `u16` types, x86-specific
@@ -322,6 +355,9 @@ types! {
     /// representing a 512-bit SIMD register which internally is consisted of
     /// 32 packed `u16` instances. Its purpose is for bf16 related intrinsic
     /// implementations.
+    ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
     pub struct __m512bh(32 x u16);
 }
 
@@ -334,6 +370,9 @@ types! {
     /// representing a 128-bit SIMD register which internally is consisted of
     /// 8 packed `f16` instances. its purpose is for f16 related intrinsic
     /// implementations.
+    ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
     pub struct __m128h(8 x f16);
 
     /// 256-bit wide set of 16 `f16` types, x86-specific
@@ -342,6 +381,9 @@ types! {
     /// representing a 256-bit SIMD register which internally is consisted of
     /// 16 packed `f16` instances. its purpose is for f16 related intrinsic
     /// implementations.
+    ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
     pub struct __m256h(16 x f16);
 
     /// 512-bit wide set of 32 `f16` types, x86-specific
@@ -350,6 +392,9 @@ types! {
     /// representing a 512-bit SIMD register which internally is consisted of
     /// 32 packed `f16` instances. its purpose is for f16 related intrinsic
     /// implementations.
+    ///
+    /// The memory layout of this type (*not* the ABI!) is the same as the
+    /// layout of the corresponding array type(s).
     pub struct __m512h(32 x f16);
 }