Merging upstream version 1.74.1+dfsg1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

8 files changed, 47 insertions, 13 deletions

diff --git a/src/doc/reference/src/behavior-considered-undefined.md b/src/doc/reference/src/behavior-considered-undefined.md
index 9d1732d07..f140fb20c 100644
--- a/src/doc/reference/src/behavior-considered-undefined.md
+++ b/src/doc/reference/src/behavior-considered-undefined.md
@@ -14,11 +14,15 @@ undefined behavior, it is *unsound*.
 
 <div class="warning">
 
-***Warning:*** The following list is not exhaustive. There is no formal model of
-Rust's semantics for what is and is not allowed in unsafe code, so there may be
-more behavior considered unsafe. The following list is just what we know for
-sure is undefined behavior. Please read the [Rustonomicon] before writing unsafe
-code.
+***Warning:*** The following list is not exhaustive; it may grow or shrink.
+There is no formal model of Rust's semantics for what is and is not allowed in
+unsafe code, so there may be more behavior considered unsafe. We also reserve
+the right to make some of the behavior in that list defined in the future. In
+other words, this list does not say that anything will *definitely* always be
+undefined in all future Rust version (but we might make such commitments for
+some list items in the future).
+
+Please read the [Rustonomicon] before writing unsafe code.
 
 </div>
 
diff --git a/src/doc/reference/src/conditional-compilation.md b/src/doc/reference/src/conditional-compilation.md
index c3a36effe..e724b21e2 100644
--- a/src/doc/reference/src/conditional-compilation.md
+++ b/src/doc/reference/src/conditional-compilation.md
@@ -129,6 +129,7 @@ Example values:
 * `"dragonfly"`
 * `"openbsd"`
 * `"netbsd"`
+* `"none"` (typical for embedded targets)
 
 ### `target_family`
 
diff --git a/src/doc/reference/src/items/implementations.md b/src/doc/reference/src/items/implementations.md
index ee651cee5..37965569e 100644
--- a/src/doc/reference/src/items/implementations.md
+++ b/src/doc/reference/src/items/implementations.md
@@ -205,7 +205,7 @@ Examples of constraining situations:
 // T constrains by being an argument to GenericTrait.
 impl<T> GenericTrait<T> for i32 { /* ... */ }
 
-// T constrains by being an arguement to GenericStruct
+// T constrains by being an argument to GenericStruct
 impl<T> Trait for GenericStruct<T> { /* ... */ }
 
 // Likewise, N constrains by being an argument to ConstGenericStruct
diff --git a/src/doc/reference/src/type-layout.md b/src/doc/reference/src/type-layout.md
index 4c87954f3..aae3577f5 100644
--- a/src/doc/reference/src/type-layout.md
+++ b/src/doc/reference/src/type-layout.md
@@ -88,7 +88,7 @@ String slices are a UTF-8 representation of characters that have the same layout
 
 ## Tuple Layout
 
-Tuples are laid out according to the [default representation][Default].
+Tuples are laid out according to the [`Rust` representation][`Rust`].
 
 The exception to this is the unit tuple (`()`), which is guaranteed as a
 zero-sized type to have a size of 0 and an alignment of 1.
@@ -110,7 +110,7 @@ All user-defined composite types (`struct`s, `enum`s, and `union`s) have a
 *representation* that specifies what the layout is for the type. The possible
 representations for a type are:
 
-- [Default]
+- [`Rust`] (default)
 - [`C`]
 - The [primitive representations]
 - [`transparent`]
@@ -159,10 +159,12 @@ not change the layout of the fields themselves. For example, a struct with a
 `C` representation that contains a struct `Inner` with the default
 representation will not change the layout of `Inner`.
 
-### The Default Representation
+### <a id="the-default-representation"></a> The `Rust` Representation
 
-Nominal types without a `repr` attribute have the default representation.
-Informally, this representation is also called the `rust` representation.
+The `Rust` representation is the default representation for nominal types
+without a `repr` attribute. Using this representation explicitly through a
+`repr` attribute is guaranteed to be the same as omitting the attribute
+entirely.
 
 The only data layout guarantees made by this representation are those required
 for soundness. They are:
@@ -543,7 +545,7 @@ important consequence of these rules is that a type with `#[repr(packed(1))]`
 
 The `align` and `packed` modifiers cannot be applied on the same type and a
 `packed` type cannot transitively contain another `align`ed type. `align` and
-`packed` may only be applied to the [default] and [`C`] representations.
+`packed` may only be applied to the [`Rust`] and [`C`] representations.
 
 The `align` modifier can also be applied on an `enum`.
 When it is, the effect on the `enum`'s alignment is the same as if the `enum`
@@ -604,7 +606,7 @@ used with any other representation.
 [undefined behavior]: behavior-considered-undefined.md
 [55149]: https://github.com/rust-lang/rust/issues/55149
 [`PhantomData<T>`]: special-types-and-traits.md#phantomdatat
-[Default]: #the-default-representation
+[`Rust`]: #the-rust-representation
 [`C`]: #the-c-representation
 [primitive representations]: #primitive-representations
 [structs]: items/structs.md
diff --git a/src/doc/reference/src/types/boolean.md b/src/doc/reference/src/types/boolean.md
index d8984025f..7ea99d185 100644
--- a/src/doc/reference/src/types/boolean.md
+++ b/src/doc/reference/src/types/boolean.md
@@ -92,6 +92,12 @@ boolean type for its operands, they evaluate using the rules of [boolean logic].
 * `a < b` is the same as `!(a >= b)`
 * `a <= b` is the same as `a == b | a < b`
 
+## Bit validity
+
+The single byte of a `bool` is guaranteed to be initialized (in other words,
+`transmute::<bool, u8>(...)` is always sound -- but since some bit patterns
+are invalid `bool`s, the inverse is not always sound).
+
 [boolean logic]: https://en.wikipedia.org/wiki/Boolean_algebra
 [enumerated type]: enum.md
 [expressions]: ../expressions.md
diff --git a/src/doc/reference/src/types/numeric.md b/src/doc/reference/src/types/numeric.md
index 8ab53a792..bd59daa6b 100644
--- a/src/doc/reference/src/types/numeric.md
+++ b/src/doc/reference/src/types/numeric.md
@@ -45,3 +45,8 @@ within an object along with one byte past the end.
 > `isize` are either 32-bit or 64-bit. As a consequence, 16-bit
 > pointer support is limited and may require explicit care and acknowledgment
 > from a library to support.
+
+## Bit validity
+
+For every numeric type, `T`, the bit validity of `T` is equivalent to the bit
+validity of `[u8; size_of::<T>()]`. An uninitialized byte is not a valid `u8`.
diff --git a/src/doc/reference/src/types/pointer.md b/src/doc/reference/src/types/pointer.md
index 4a74370a5..cbbf356e8 100644
--- a/src/doc/reference/src/types/pointer.md
+++ b/src/doc/reference/src/types/pointer.md
@@ -50,6 +50,16 @@ Raw pointers can be created directly using [`core::ptr::addr_of!`] for `*const`
 
 The standard library contains additional 'smart pointer' types beyond references and raw pointers.
 
+## Bit validity
+
+Despite pointers and references being similar to `usize`s in the machine code emitted on most platforms,
+the semantics of transmuting a reference or pointer type to a non-pointer type is currently undecided.
+Thus, it may not be valid to transmute a pointer or reference type, `P`, to a `[u8; size_of::<P>()]`.
+
+For thin raw pointers (i.e., for `P = *const T` or `P = *mut T` for `T: Sized`),
+the inverse direction (transmuting from an integer or array of integers to `P`) is always valid.
+However, the pointer produced via such a transmutation may not be dereferenced (not even if `T` has size zero).
+
 [`core::ptr::addr_of!`]: ../../core/ptr/macro.addr_of.html
 [`core::ptr::addr_of_mut!`]: ../../core/ptr/macro.addr_of_mut.html
 [Interior mutability]: ../interior-mutability.md
diff --git a/src/doc/reference/src/types/textual.md b/src/doc/reference/src/types/textual.md
index 65d563312..41ed35ea1 100644
--- a/src/doc/reference/src/types/textual.md
+++ b/src/doc/reference/src/types/textual.md
@@ -17,6 +17,12 @@ is valid UTF-8. Calling a `str` method with a non-UTF-8 buffer can cause
 Since `str` is a [dynamically sized type], it can only be instantiated through a
 pointer type, such as `&str`.
 
+## Bit validity
+
+Every byte of a `char` is guaranteed to be initialized (in other words,
+`transmute::<char, [u8; size_of::<char>()]>(...)` is always sound -- but since
+some bit patterns are invalid `char`s, the inverse is not always sound).
+
 [Unicode scalar value]: http://www.unicode.org/glossary/#unicode_scalar_value
 [Undefined Behavior]: ../behavior-considered-undefined.md
 [dynamically sized type]: ../dynamically-sized-types.md