Merging upstream version 1.70.0+dfsg1.

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

8 files changed, 80 insertions, 21 deletions

diff --git a/src/doc/reference/src/attributes/codegen.md b/src/doc/reference/src/attributes/codegen.md
index 69ad341d1..ab59cd8e7 100644
--- a/src/doc/reference/src/attributes/codegen.md
+++ b/src/doc/reference/src/attributes/codegen.md
@@ -88,9 +88,11 @@ Feature     | Implicitly Enables | Description
 `avx2`      | `avx`    | [AVX2] — Advanced Vector Extensions 2
 `bmi1`      |          | [BMI1] — Bit Manipulation Instruction Sets
 `bmi2`      |          | [BMI2] — Bit Manipulation Instruction Sets 2
+`cmpxchg16b`|          | [`cmpxchg16b`] - Compares and exchange 16 bytes (128 bits) of data atomically
 `fma`       | `avx`    | [FMA3] — Three-operand fused multiply-add
 `fxsr`      |          | [`fxsave`] and [`fxrstor`] — Save and restore x87 FPU, MMX Technology, and SSE State
 `lzcnt`     |          | [`lzcnt`] — Leading zeros count
+`movbe`     |          | [`movbe`] - Move data after swapping bytes
 `pclmulqdq` | `sse2`   | [`pclmulqdq`] — Packed carry-less multiplication quadword
 `popcnt`    |          | [`popcnt`] — Count of bits set to 1
 `rdrand`    |          | [`rdrand`] — Read random number
@@ -115,10 +117,12 @@ Feature     | Implicitly Enables | Description
 [AVX2]: https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#AVX2
 [BMI1]: https://en.wikipedia.org/wiki/Bit_Manipulation_Instruction_Sets
 [BMI2]: https://en.wikipedia.org/wiki/Bit_Manipulation_Instruction_Sets#BMI2
+[`cmpxchg16b`]: https://www.felixcloutier.com/x86/cmpxchg8b:cmpxchg16b
 [FMA3]: https://en.wikipedia.org/wiki/FMA_instruction_set
 [`fxsave`]: https://www.felixcloutier.com/x86/fxsave
 [`fxrstor`]: https://www.felixcloutier.com/x86/fxrstor
 [`lzcnt`]: https://www.felixcloutier.com/x86/lzcnt
+[`movbe`]: https://www.felixcloutier.com/x86/movbe
 [`pclmulqdq`]: https://www.felixcloutier.com/x86/pclmulqdq
 [`popcnt`]: https://www.felixcloutier.com/x86/popcnt
 [`rdrand`]: https://en.wikipedia.org/wiki/RdRand
diff --git a/src/doc/reference/src/attributes/diagnostics.md b/src/doc/reference/src/attributes/diagnostics.md
index 45f9cc440..506e2848b 100644
--- a/src/doc/reference/src/attributes/diagnostics.md
+++ b/src/doc/reference/src/attributes/diagnostics.md
@@ -49,7 +49,7 @@ check on and off:
 
 ```rust
 #[warn(missing_docs)]
-pub mod m2{
+pub mod m2 {
     #[allow(missing_docs)]
     pub mod nested {
         // Missing documentation is ignored here
diff --git a/src/doc/reference/src/expressions/loop-expr.md b/src/doc/reference/src/expressions/loop-expr.md
index 204207ee0..c8b93ea39 100644
--- a/src/doc/reference/src/expressions/loop-expr.md
+++ b/src/doc/reference/src/expressions/loop-expr.md
@@ -249,8 +249,27 @@ A `break` expression is only permitted in the body of a loop, and has one of the
 >    [_BlockExpression_]
 
 Labelled block expressions are exactly like block expressions, except that they allow using `break` expressions within the block.
-Unlike other loops, `break` expressions within a label expression *must* have a label (i.e. the label is not optional).
-Unlike other loops, labelled block expressions *must* begin with a label.
+Unlike loops, `break` expressions within a labelled block expression *must* have a label (i.e. the label is not optional).
+Similarly, labelled block expressions *must* begin with a label.
+
+```rust
+# fn do_thing() {}
+# fn condition_not_met() -> bool { true }
+# fn do_next_thing() {}
+# fn do_last_thing() {}
+let result = 'block: {
+    do_thing();
+    if condition_not_met() {
+        break 'block 1;
+    }
+    do_next_thing();
+    if condition_not_met() {
+        break 'block 2;
+    }
+    do_last_thing();
+    3
+};
+```
 
 ## `continue` expressions
 
diff --git a/src/doc/reference/src/expressions/struct-expr.md b/src/doc/reference/src/expressions/struct-expr.md
index 8caeff200..8d9154789 100644
--- a/src/doc/reference/src/expressions/struct-expr.md
+++ b/src/doc/reference/src/expressions/struct-expr.md
@@ -73,7 +73,7 @@ drop(y_ref);
 ```
 
 Struct expressions with curly braces can't be used directly in a [loop] or [if] expression's head, or in the [scrutinee] of an [if let] or [match] expression.
-However, struct expressions can be in used in these situations if they are within another expression, for example inside [parentheses].
+However, struct expressions can be used in these situations if they are within another expression, for example inside [parentheses].
 
 The field names can be decimal integer values to specify indices for constructing tuple structs.
 This can be used with base structs to fill out the remaining indices not specified:
diff --git a/src/doc/reference/src/inline-assembly.md b/src/doc/reference/src/inline-assembly.md
index 996b157da..a12f495ff 100644
--- a/src/doc/reference/src/inline-assembly.md
+++ b/src/doc/reference/src/inline-assembly.md
@@ -43,16 +43,15 @@ format_string := STRING_LITERAL / RAW_STRING_LITERAL
 dir_spec := "in" / "out" / "lateout" / "inout" / "inlateout"
 reg_spec := <register class> / "\"" <explicit register> "\""
 operand_expr := expr / "_" / expr "=>" expr / expr "=>" "_"
-reg_operand := dir_spec "(" reg_spec ")" operand_expr
-operand := reg_operand
+reg_operand := [ident "="] dir_spec "(" reg_spec ")" operand_expr
 clobber_abi := "clobber_abi(" <abi> *("," <abi>) [","] ")"
 option := "pure" / "nomem" / "readonly" / "preserves_flags" / "noreturn" / "nostack" / "att_syntax" / "raw"
 options := "options(" option *("," option) [","] ")"
-asm := "asm!(" format_string *("," format_string) *("," [ident "="] operand) *("," clobber_abi) *("," options) [","] ")"
-global_asm := "global_asm!(" format_string *("," format_string) *("," [ident "="] operand) *("," options) [","] ")"
+operand := reg_operand / clobber_abi / options
+asm := "asm!(" format_string *("," format_string) *("," operand) [","] ")"
+global_asm := "global_asm!(" format_string *("," format_string) *("," operand) [","] ")"
 ```
 
-
 ## Scope
 
 Inline assembly can be used in one of two ways.
@@ -74,8 +73,7 @@ An `asm!` invocation may have one or more template string arguments; an `asm!` w
 The expected usage is for each template string argument to correspond to a line of assembly code.
 All template string arguments must appear before any other arguments.
 
-As with format strings, named arguments must appear after positional arguments.
-Explicit [register operands](#register-operands) must appear at the end of the operand list, after named arguments if any.
+As with format strings, positional arguments must appear before named arguments and explicit [register operands](#register-operands).
 
 Explicit register operands cannot be used by placeholders in the template string.
 All other named and positional operands must appear at least once in the template string, otherwise a compiler error is generated.
@@ -486,6 +484,29 @@ To avoid undefined behavior, these rules must be followed when using function-sc
 
 > **Note**: As a general rule, the flags covered by `preserves_flags` are those which are *not* preserved when performing a function call.
 
+### Correctness and Validity
+
+In addition to all of the previous rules, the string argument to `asm!` must ultimately become—
+after all other arguments are evaluated, formatting is performed, and operands are translated—
+assembly that is both syntactically correct and semantically valid for the target architecture.
+The formatting rules allow the compiler to generate assembly with correct syntax.
+Rules concerning operands permit valid translation of Rust operands into and out of `asm!`.
+Adherence to these rules is necessary, but not sufficient, for the final expanded assembly to be
+both correct and valid. For instance:
+
+- arguments may be placed in positions which are syntactically incorrect after formatting
+- an instruction may be correctly written, but given architecturally invalid operands
+- an architecturally unspecified instruction may be assembled into unspecified code
+- a set of instructions, each correct and valid, may cause undefined behavior if placed in immediate succession
+
+As a result, these rules are _non-exhaustive_. The compiler is not required to check the
+correctness and validity of the initial string nor the final assembly that is generated.
+The assembler may check for correctness and validity but is not required to do so.
+When using `asm!`, a typographical error may be sufficient to make a program unsound,
+and the rules for assembly may include thousands of pages of architectural reference manuals.
+Programmers should exercise appropriate care, as invoking this `unsafe` capability comes with
+assuming the responsibility of not violating rules of both the compiler or the architecture.
+
 ### Directives Support
 
 Inline assembly supports a subset of the directives supported by both GNU AS and LLVM's internal assembler, given as follows.
@@ -499,12 +520,9 @@ The following directives are guaranteed to be supported by the assembler:
 - `.4byte`
 - `.8byte`
 - `.align`
+- `.alt_entry`
 - `.ascii`
 - `.asciz`
-- `.alt_entry`
-- `.balign`
-- `.balignl`
-- `.balignw`
 - `.balign`
 - `.balignl`
 - `.balignw`
@@ -520,17 +538,17 @@ The following directives are guaranteed to be supported by the assembler:
 - `.eqv`
 - `.fill`
 - `.float`
-- `.globl`
 - `.global`
-- `.lcomm`
+- `.globl`
 - `.inst`
+- `.lcomm`
 - `.long`
 - `.octa`
 - `.option`
-- `.private_extern`
 - `.p2align`
-- `.pushsection`
 - `.popsection`
+- `.private_extern`
+- `.pushsection`
 - `.quad`
 - `.scl`
 - `.section`
diff --git a/src/doc/reference/src/items/constant-items.md b/src/doc/reference/src/items/constant-items.md
index bf315932f..85d3e015d 100644
--- a/src/doc/reference/src/items/constant-items.md
+++ b/src/doc/reference/src/items/constant-items.md
@@ -89,6 +89,22 @@ m!(const _: () = (););
 // const _: () = ();
 ```
 
+## Evaluation
+
+[Free][free] constants are always [evaluated][const_eval] at compile-time to surface
+panics. This happens even within an unused function:
+
+```rust,compile_fail
+// Compile-time panic
+const PANIC: () = std::unimplemented!();
+
+fn unused_generic_function<T>() {
+    // A failing compile-time assertion
+    const _: () = assert!(usize::BITS == 0);
+}
+```
+
+[const_eval]: ../const_eval.md
 [associated constant]: ../items/associated-items.md#associated-constants
 [constant value]: ../const_eval.md#constant-expressions
 [free]: ../glossary.md#free-item
diff --git a/src/doc/reference/src/items/unions.md b/src/doc/reference/src/items/unions.md
index 325b22717..3c6c83d50 100644
--- a/src/doc/reference/src/items/unions.md
+++ b/src/doc/reference/src/items/unions.md
@@ -55,13 +55,13 @@ let f = unsafe { u.f1 };
 ## Reading and writing union fields
 
 Unions have no notion of an "active field". Instead, every union access just
-interprets the storage at the type of the field used for the access. Reading a
+interprets the storage as the type of the field used for the access. Reading a
 union field reads the bits of the union at the field's type. Fields might have a
 non-zero offset (except when [the C representation] is used); in that case the
 bits starting at the offset of the fields are read. It is the programmer's
 responsibility to make sure that the data is valid at the field's type. Failing
 to do so results in [undefined behavior]. For example, reading the value `3`
-through of a field of the [boolean type] is undefined behavior. Effectively,
+from a field of the [boolean type] is undefined behavior. Effectively,
 writing to and then reading from a union with [the C representation] is
 analogous to a [`transmute`] from the type used for writing to the type used for
 reading.
diff --git a/src/doc/reference/src/names/namespaces.md b/src/doc/reference/src/names/namespaces.md
index 14811697c..bb4409b73 100644
--- a/src/doc/reference/src/names/namespaces.md
+++ b/src/doc/reference/src/names/namespaces.md
@@ -52,6 +52,7 @@ The following is a list of namespaces, with their corresponding entities:
     * [Generic lifetime parameters]
 * Label Namespace
     * [Loop labels]
+    * [Block labels]
 
 An example of how overlapping names in different namespaces can be used unambiguously:
 
@@ -132,6 +133,7 @@ It is still an error for a [`use` import] to shadow another macro, regardless of
 [Attribute macros]: ../procedural-macros.md#attribute-macros
 [attributes]: ../attributes.md
 [bang-style macros]: ../macros.md
+[Block labels]: ../expressions/loop-expr.md#labelled-block-expressions
 [boolean]: ../types/boolean.md
 [Built-in attributes]: ../attributes.md#built-in-attributes-index
 [closure parameters]: ../expressions/closure-expr.md