Merging upstream version 1.71.1+dfsg1.

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

10 files changed, 198 insertions, 10 deletions

diff --git a/src/doc/reference/src/SUMMARY.md b/src/doc/reference/src/SUMMARY.md
index 4d9cc1d76..2b17bf45d 100644
--- a/src/doc/reference/src/SUMMARY.md
+++ b/src/doc/reference/src/SUMMARY.md
@@ -44,6 +44,7 @@
     - [Code generation](attributes/codegen.md)
     - [Limits](attributes/limits.md)
     - [Type System](attributes/type_system.md)
+    - [Debugger](attributes/debugger.md)
 
 - [Statements and expressions](statements-and-expressions.md)
     - [Statements](statements.md)
diff --git a/src/doc/reference/src/attributes.md b/src/doc/reference/src/attributes.md
index 5d619c990..92ce1cd09 100644
--- a/src/doc/reference/src/attributes.md
+++ b/src/doc/reference/src/attributes.md
@@ -271,6 +271,8 @@ The following is an index of all built-in attributes.
 - Type System
   - [`non_exhaustive`] — Indicate that a type will have more fields/variants
     added in future.
+- Debugger
+  - [`debugger_visualizer`] — Embeds a file that specifies debugger output for a type.
 
 [Doc comments]: comments.md#doc-comments
 [ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm
@@ -291,6 +293,7 @@ The following is an index of all built-in attributes.
 [`cold`]: attributes/codegen.md#the-cold-attribute
 [`crate_name`]: crates-and-source-files.md#the-crate_name-attribute
 [`crate_type`]: linkage.md
+[`debugger_visualizer`]: attributes/debugger.md#the-debugger_visualizer-attribute
 [`deny`]: attributes/diagnostics.md#lint-check-attributes
 [`deprecated`]: attributes/diagnostics.md#the-deprecated-attribute
 [`derive`]: attributes/derive.md
diff --git a/src/doc/reference/src/attributes/codegen.md b/src/doc/reference/src/attributes/codegen.md
index ab59cd8e7..8629e835d 100644
--- a/src/doc/reference/src/attributes/codegen.md
+++ b/src/doc/reference/src/attributes/codegen.md
@@ -89,6 +89,7 @@ Feature     | Implicitly Enables | Description
 `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
+`f16c`      | `avx`    | [F16C] — 16-bit floating point conversion instructions
 `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
@@ -118,6 +119,7 @@ Feature     | Implicitly Enables | Description
 [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
+[F16C]: https://en.wikipedia.org/wiki/F16C
 [FMA3]: https://en.wikipedia.org/wiki/FMA_instruction_set
 [`fxsave`]: https://www.felixcloutier.com/x86/fxsave
 [`fxrstor`]: https://www.felixcloutier.com/x86/fxrstor
diff --git a/src/doc/reference/src/attributes/debugger.md b/src/doc/reference/src/attributes/debugger.md
new file mode 100644
index 000000000..6ea80221e
--- /dev/null
+++ b/src/doc/reference/src/attributes/debugger.md
@@ -0,0 +1,141 @@
+# Debugger attributes
+
+The following [attributes] are used for enhancing the debugging experience when using third-party debuggers like GDB or WinDbg.
+
+## The `debugger_visualizer` attribute
+
+The *`debugger_visualizer` attribute* can be used to embed a debugger visualizer file into the debug information.
+This enables an improved debugger experience for displaying values in the debugger.
+It uses the [_MetaListNameValueStr_] syntax to specify its inputs, and must be specified as a crate attribute.
+
+### Using `debugger_visualizer` with Natvis
+
+Natvis is an XML-based framework for Microsoft debuggers (such as Visual Studio and WinDbg) that uses declarative rules to customize the display of types.
+For detailed information on the Natvis format, refer to Microsoft's [Natvis documentation].
+
+This attribute only supports embedding Natvis files on `-windows-msvc` targets.
+
+The path to the Natvis file is specified with the `natvis_file` key, which is a path relative to the crate source file:
+
+<!-- ignore: requires external files, and msvc -->
+```rust ignore
+#![debugger_visualizer(natvis_file = "Rectangle.natvis")]
+
+struct FancyRect {
+    x: f32,
+    y: f32,
+    dx: f32,
+    dy: f32,
+}
+
+fn main() {
+    let fancy_rect = FancyRect { x: 10.0, y: 10.0, dx: 5.0, dy: 5.0 };
+    println!("set breakpoint here");
+}
+```
+
+and `Rectangle.natvis` contains:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
+    <Type Name="foo::FancyRect">
+      <DisplayString>({x},{y}) + ({dx}, {dy})</DisplayString>
+      <Expand>
+        <Synthetic Name="LowerLeft">
+          <DisplayString>({x}, {y})</DisplayString>
+        </Synthetic>
+        <Synthetic Name="UpperLeft">
+          <DisplayString>({x}, {y + dy})</DisplayString>
+        </Synthetic>
+        <Synthetic Name="UpperRight">
+          <DisplayString>({x + dx}, {y + dy})</DisplayString>
+        </Synthetic>
+        <Synthetic Name="LowerRight">
+          <DisplayString>({x + dx}, {y})</DisplayString>
+        </Synthetic>
+      </Expand>
+    </Type>
+</AutoVisualizer>
+```
+
+When viewed under WinDbg, the `fancy_rect` variable would be shown as follows:
+
+```text
+> Variables:
+  > fancy_rect: (10.0, 10.0) + (5.0, 5.0)
+    > LowerLeft: (10.0, 10.0)
+    > UpperLeft: (10.0, 15.0)
+    > UpperRight: (15.0, 15.0)
+    > LowerRight: (15.0, 10.0)
+```
+
+### Using `debugger_visualizer` with GDB
+
+GDB supports the use of a structured Python script, called a *pretty printer*, that describes how a type should be visualized in the debugger view.
+For detailed information on pretty printers, refer to GDB's [pretty printing documentation].
+
+Embedded pretty printers are not automatically loaded when debugging a binary under GDB.
+There are two ways to enable auto-loading embedded pretty printers:
+1. Launch GDB with extra arguments to explicitly add a directory or binary to the auto-load safe path: `gdb -iex "add-auto-load-safe-path safe-path path/to/binary" path/to/binary`
+ For more information, see GDB's [auto-loading documentation].
+1. Create a file named `gdbinit` under `$HOME/.config/gdb` (you may need to create the directory if it doesn't already exist). Add the following line to that file: `add-auto-load-safe-path path/to/binary`.
+
+These scripts are embedded using the `gdb_script_file` key, which is a path relative to the crate source file.
+
+<!-- ignore: requires external files -->
+```rust ignore
+#![debugger_visualizer(gdb_script_file = "printer.py")]
+
+struct Person {
+    name: String,
+    age: i32,
+}
+
+fn main() {
+    let bob = Person { name: String::from("Bob"), age: 10 };
+    println!("set breakpoint here");
+}
+```
+
+and `printer.py` contains:
+
+```python
+import gdb
+
+class PersonPrinter:
+    "Print a Person"
+
+    def __init__(self, val):
+        self.val = val
+        self.name = val["name"]
+        self.age = int(val["age"])
+
+    def to_string(self):
+        return "{} is {} years old.".format(self.name, self.age)
+
+def lookup(val):
+    lookup_tag = val.type.tag
+    if lookup_tag is None:
+        return None
+    if "foo::Person" == lookup_tag:
+        return PersonPrinter(val)
+
+    return None
+
+gdb.current_objfile().pretty_printers.append(lookup)
+```
+
+When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` will display:
+
+```text
+"Bob" is 10 years old.
+```
+
+[^rust-gdb]: Note: This assumes you are using the `rust-gdb` script which configures pretty-printers for standard library types like `String`.
+
+[auto-loading documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Auto_002dloading-safe-path.html
+[attributes]: ../attributes.md
+[Natvis documentation]: https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects
+[pretty printing documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html
+[_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
diff --git a/src/doc/reference/src/inline-assembly.md b/src/doc/reference/src/inline-assembly.md
index a12f495ff..6c23d592c 100644
--- a/src/doc/reference/src/inline-assembly.md
+++ b/src/doc/reference/src/inline-assembly.md
@@ -17,6 +17,7 @@ The compiler will emit an error if `asm!` is used on an unsupported target.
 ## Example
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 // Multiply x by 6 using shifts and adds
@@ -32,6 +33,7 @@ unsafe {
     );
 }
 assert_eq!(x, 4 * 6);
+# }
 ```
 
 ## Syntax
diff --git a/src/doc/reference/src/items/external-blocks.md b/src/doc/reference/src/items/external-blocks.md
index ce2190829..25ae37bc3 100644
--- a/src/doc/reference/src/items/external-blocks.md
+++ b/src/doc/reference/src/items/external-blocks.md
@@ -231,9 +231,38 @@ resolution logic to find that import library. Alternatively, specifying
 `kind = "raw-dylib"` instructs the compiler to generate an import library
 during compilation and provide that to the linker instead.
 
-`raw-dylib` is only supported on Windows and not supported on 32-bit x86
-(`target_arch="x86"`). Using it when targeting other platforms or
-x86 on Windows will result in a compiler error.
+`raw-dylib` is only supported on Windows. Using it when targeting other
+platforms will result in a compiler error.
+
+#### The `import_name_type` key
+
+On x86 Windows, names of functions are "decorated" (i.e., have a specific prefix
+and/or suffix added) to indicate their calling convention. For example, a
+`stdcall` calling convention function with the name `fn1` that has no arguments
+would be decorated as `_fn1@0`. However, the [PE Format] does also permit names
+to have no prefix or be undecorated. Additionally, the MSVC and GNU toolchains
+use different decorations for the same calling conventions which means, by
+default, some Win32 functions cannot be called using the `raw-dylib` link kind
+via the GNU toolchain.
+
+To allow for these differences, when using the `raw-dylib` link kind you may
+also specify the `import_name_type` key with one of the following values to
+change how functions are named in the generated import library:
+
+* `decorated`: The function name will be fully-decorated using the MSVC
+  toolchain format.
+* `noprefix`: The function name will be decorated using the MSVC toolchain
+  format, but skipping the leading `?`, `@`, or optionally `_`.
+* `undecorated`: The function name will not be decorated.
+
+If the `import_name_type` key is not specified, then the function name will be
+fully-decorated using the target toolchain's format.
+
+Variables are never decorated and so the `import_name_type` key has no effect on
+how they are named in the generated import library.
+
+The `import_name_type` key is only supported on x86 Windows. Using it when
+targeting other platforms will result in a compiler error.
 
 ### The `link_name` attribute
 
@@ -308,3 +337,4 @@ restrictions as [regular function parameters].
 [`whole-archive` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-whole-archive
 [`verbatim` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-verbatim
 [`dylib` versus `raw-dylib`]: #dylib-versus-raw-dylib
+[PE Format]: https://learn.microsoft.com/windows/win32/debug/pe-format#import-name-type
diff --git a/src/doc/reference/src/keywords.md b/src/doc/reference/src/keywords.md
index 67f1089d8..1855a35d0 100644
--- a/src/doc/reference/src/keywords.md
+++ b/src/doc/reference/src/keywords.md
@@ -111,6 +111,7 @@ is possible to declare a variable or method with the name `union`.
   Beginning in the 2018 edition, `dyn` has been promoted to a strict keyword.
 
 > **<sup>Lexer</sup>**\
+> KW_MACRO_RULES    : `macro_rules`\
 > KW_UNION          : `union`\
 > KW_STATICLIFETIME : `'static`
 >
diff --git a/src/doc/reference/src/macros-by-example.md b/src/doc/reference/src/macros-by-example.md
index cd9dc3402..51aa919fc 100644
--- a/src/doc/reference/src/macros-by-example.md
+++ b/src/doc/reference/src/macros-by-example.md
@@ -166,7 +166,7 @@ The repetition operators are:
 
 - `*` — indicates any number of repetitions.
 - `+` — indicates any number but at least one.
-- `?` — indicates an optional fragment with zero or one occurrences.
+- `?` — indicates an optional fragment with zero or one occurrence.
 
 Since `?` represents at most one occurrence, it cannot be used with a
 separator.
diff --git a/src/doc/reference/src/procedural-macros.md b/src/doc/reference/src/procedural-macros.md
index 31f029a63..7d69ab72d 100644
--- a/src/doc/reference/src/procedural-macros.md
+++ b/src/doc/reference/src/procedural-macros.md
@@ -251,7 +251,7 @@ use my_macro::show_streams;
 #[show_streams]
 fn invoke1() {}
 // out: attr: ""
-// out: item: "fn invoke1() { }"
+// out: item: "fn invoke1() {}"
 
 // Example: Attribute with input
 #[show_streams(bar)]
diff --git a/src/doc/reference/src/types/impl-trait.md b/src/doc/reference/src/types/impl-trait.md
index 413f999f8..af900408e 100644
--- a/src/doc/reference/src/types/impl-trait.md
+++ b/src/doc/reference/src/types/impl-trait.md
@@ -31,15 +31,15 @@ The caller must provide a type that satisfies the bounds declared by the anonymo
 
 For example, these two forms are almost equivalent:
 
-```rust,ignore
+```rust
 trait Trait {}
 
 // generic type parameter
-fn foo<T: Trait>(arg: T) {
+fn with_generic_type<T: Trait>(arg: T) {
 }
 
 // impl Trait in argument position
-fn foo(arg: impl Trait) {
+fn with_impl_trait(arg: impl Trait) {
 }
 ```
 
@@ -96,16 +96,24 @@ With `impl Trait`, unlike with a generic type parameter, the function chooses th
 
 The function:
 
-```rust,ignore
+```rust
+# trait Trait {}
 fn foo<T: Trait>() -> T {
+    // ...
+# panic!()
+}
 ```
 
 allows the caller to determine the return type, `T`, and the function returns that type.
 
 The function:
 
-```rust,ignore
+```rust
+# trait Trait {}
+# impl Trait for () {}
 fn foo() -> impl Trait {
+    // ...
+}
 ```
 
 doesn't allow the caller to determine the return type.