Clarify the layout documentation for x86 SIMD types.

Author: veluca93

crates/core_arch/src/x86/mod.rs

@@ -28,8 +28,11 @@ 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding); however, the alignment is different and equal to
+    /// the size of the type. Note that the ABI for function calls may *not* be
+    /// the same.
     ///
     /// 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.
@@ -69,8 +72,11 @@ 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding); however, the alignment is different and equal to
+    /// the size of the type. Note that the ABI for function calls may *not* be
+    /// the same.
     ///
     /// Most intrinsics using `__m128` are prefixed with `_mm_` and are
     /// suffixed with "ps" (or otherwise contain "ps"). Not to be confused with
@@ -108,8 +114,11 @@ 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding); however, the alignment is different and equal to
+    /// the size of the type. Note that the ABI for function calls may *not* be
+    /// the same.
     ///
     /// Most intrinsics using `__m128d` are prefixed with `_mm_` and are
     /// suffixed with "pd" (or otherwise contain "pd"). Not to be confused with
@@ -152,8 +161,11 @@ 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding); however, the alignment is different and equal to
+    /// the size of the type. Note that the ABI for function calls may *not* be
+    /// the same.
     ///
     /// 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.
@@ -190,8 +202,11 @@ 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding  between two consecutive elements); however, the
+    /// alignment is different and equal to the size of the type. Note that the
+    /// ABI for function calls may *not* be the same.
     ///
     /// Most intrinsics using `__m256` are prefixed with `_mm256_` and are
     /// suffixed with "ps" (or otherwise contain "ps"). Not to be confused with
@@ -229,8 +244,11 @@ 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding); however, the alignment is different and equal to
+    /// the size of the type. Note that the ABI for function calls may *not* be
+    /// the same.
     ///
     /// Most intrinsics using `__m256d` are prefixed with `_mm256_` and are
     /// suffixed with "pd" (or otherwise contain "pd"). Not to be confused with
@@ -277,8 +295,11 @@ 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding); however, the alignment is different and equal to
+    /// the size of the type. Note that the ABI for function calls may *not* be
+    /// the same.
     ///
     /// 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.
@@ -296,8 +317,11 @@ 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding  between two consecutive elements); however, the
+    /// alignment is different and equal to the size of the type. Note that the
+    /// ABI for function calls may *not* be the same.
     ///
     /// Most intrinsics using `__m512` are prefixed with `_mm512_` and are
     /// suffixed with "ps" (or otherwise contain "ps"). Not to be confused with
@@ -316,8 +340,11 @@ 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding  between two consecutive elements); however, the
+    /// alignment is different and equal to the size of the type. Note that the
+    /// ABI for function calls may *not* be the same.
     ///
     /// Most intrinsics using `__m512d` are prefixed with `_mm512_` and are
     /// suffixed with "pd" (or otherwise contain "pd"). Not to be confused with
@@ -334,8 +361,11 @@ types! {
     /// 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding); however, the alignment is different and equal to
+    /// the size of the type. Note that the ABI for function calls may *not* be
+    /// the same.
     pub struct __m128bh(8 x u16);
 
     /// 256-bit wide set of 16 `u16` types, x86-specific
@@ -345,8 +375,11 @@ types! {
     /// 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding); however, the alignment is different and equal to
+    /// the size of the type. Note that the ABI for function calls may *not* be
+    /// the same.
     pub struct __m256bh(16 x u16);
 
     /// 512-bit wide set of 32 `u16` types, x86-specific
@@ -356,8 +389,11 @@ types! {
     /// 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding); however, the alignment is different and equal to
+    /// the size of the type. Note that the ABI for function calls may *not* be
+    /// the same.
     pub struct __m512bh(32 x u16);
 }
 
@@ -371,8 +407,11 @@ types! {
     /// 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding); however, the alignment is different and equal to
+    /// the size of the type. Note that the ABI for function calls may *not* be
+    /// the same.
     pub struct __m128h(8 x f16);
 
     /// 256-bit wide set of 16 `f16` types, x86-specific
@@ -382,8 +421,11 @@ types! {
     /// 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding); however, the alignment is different and equal to
+    /// the size of the type. Note that the ABI for function calls may *not* be
+    /// the same.
     pub struct __m256h(16 x f16);
 
     /// 512-bit wide set of 32 `f16` types, x86-specific
@@ -393,8 +435,11 @@ types! {
     /// 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).
+    /// The in-memory representation of this type is the same as the one of an
+    /// equivalent array (i.e. the in-memory order of elements is the same, and
+    /// there is no padding); however, the alignment is different and equal to
+    /// the size of the type. Note that the ABI for function calls may *not* be
+    /// the same.
     pub struct __m512h(32 x f16);
 }