Document MaybeUninit bit validity

library/core/src/mem/maybe_uninit.rs

@@ -252,6 +252,46 @@ use crate::{fmt, intrinsics, ptr, slice};
 ///     std::process::exit(*code); // UB! Accessing uninitialized memory.
 /// }
 /// ```
+///
+/// # Validity
+///
+/// A `MaybeUninit<T>` has no validity requirement – any sequence of [bytes][reference-byte] of the
+/// appropriate length, initialized or uninitialized, are a valid representation of `MaybeUninit<T>`.
+///
+/// However, "round-tripping" via `MaybeUninit` does not always result in the original value.
+/// `MaybeUninit` can have padding, and the contents of that padding are not preserved.
+/// Concretely, given distinct `T` and `U` where `size_of::<T>() == size_of::<U>()`, the following
+/// code is not guaranteed to be sound:
+///
+/// ```rust,no_run
+/// # use core::mem::{MaybeUninit, transmute};
+/// # struct T; struct U;
+/// fn identity(t: T) -> T {
+///     unsafe {
+///         let u: MaybeUninit<U> = transmute(t);
+///         transmute(u)
+///     }
+/// }
+/// ```
+///
+/// If the representation of `t` contains initialized bytes at byte offsets where `U` contains padding bytes, these
+/// may not be preserved in `MaybeUninit<U>`. Transmuting `u` back to `T` (i.e., `transmute(u)` above) may thus
+/// be undefined behavior or yield a value different from `t` due to those bytes being lost. This is an active area of discussion, and this code
+/// may become sound in the future.
+///
+/// However, so long as no such byte offsets exist, then the preceding `identity` example *is* sound.
+/// In particular, since `[u8; N]` has no padding bytes, transmuting `t` to `MaybeUninit<[u8; size_of::<T>]>`
+/// and back will always produce the original value `t` again. This is true even if `t` contains [provenance]:
+/// the resulting value will have the same provenance as the original `t`.
+///
+/// Note a potential footgun: if `t` contains a reference, then there may be implicit reborrows of the reference
+/// any time it is copied, which may alter its provenance. In that case, the value returned by `identity` may
+/// not be exactly the same as its argument. However, even in this case, it remains true that `identity` behaves
+/// the same as a function that just returns `t` immediately (i.e., `fn identity<T>(t: T) -> T { t }`).
+///
+/// [provenance]: crate::ptr#provenance
+///
+/// [reference-byte]: ../../reference/memory-model.html#bytes
 #[stable(feature = "maybe_uninit", since = "1.36.0")]
 // Lang item so we can wrap other types in it. This is useful for coroutines.
 #[lang = "maybe_uninit"]