Rollup merge of rust-lang#92611 - Amanieu:asm-reference, r=m-ou-se

Add links to the reference and rust by example for asm! docs and lints

These were previously removed in rust-lang#91728 due to broken links.

cc `@ehuss` since this updates the rust-by-example submodule

Author: matthiaskrgr

compiler/rustc_lint/src/builtin.rs

@@ -3158,7 +3158,10 @@ declare_lint! {
     /// of this, GNU assembler [local labels] *must* be used instead of labels
     /// with a name. Using named labels might cause assembler or linker errors.
     ///
+    /// See the explanation in [Rust By Example] for more details.
+    ///
     /// [local labels]: https://sourceware.org/binutils/docs/as/Symbol-Names.html#Local-Labels
+    /// [Rust By Example]: https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels
     pub NAMED_ASM_LABELS,
     Deny,
     "named labels in inline assembly",

compiler/rustc_lint/src/context.rs

@@ -762,6 +762,7 @@ pub trait LintContext: Sized {
                 }
                 BuiltinLintDiagnostics::NamedAsmLabel(help) => {
                     db.help(&help);
+                    db.note("see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information");
                 }
             }
             // Rewrap `db`, and pass control to the user.

compiler/rustc_lint_defs/src/builtin.rs

@@ -2456,6 +2456,10 @@ declare_lint! {
     /// register size, to alert you of possibly using the incorrect width. To
     /// fix this, add the suggested modifier to the template, or cast the
     /// value to the correct size.
+    ///
+    /// See [register template modifiers] in the reference for more details.
+    ///
+    /// [register template modifiers]: https://doc.rust-lang.org/nightly/reference/inline-assembly.html#template-modifiers
     pub ASM_SUB_REGISTER,
     Warn,
     "using only a subset of a register for inline asm inputs",

library/core/src/lib.rs

@@ -374,13 +374,25 @@ pub mod arch {
     pub use crate::core_arch::arch::*;
 
     /// Inline assembly.
+    ///
+    /// Refer to [rust by example] for a usage guide and the [reference] for
+    /// detailed information about the syntax and available options.
+    ///
+    /// [rust by example]: https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html
+    /// [reference]: https://doc.rust-lang.org/nightly/reference/inline-assembly.html
     #[stable(feature = "asm", since = "1.59.0")]
     #[rustc_builtin_macro]
     pub macro asm("assembly template", $(operands,)* $(options($(option),*))?) {
         /* compiler built-in */
     }
 
     /// Module-level inline assembly.
+    ///
+    /// Refer to [rust by example] for a usage guide and the [reference] for
+    /// detailed information about the syntax and available options.
+    ///
+    /// [rust by example]: https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html
+    /// [reference]: https://doc.rust-lang.org/nightly/reference/inline-assembly.html
     #[stable(feature = "global_asm", since = "1.59.0")]
     #[rustc_builtin_macro]
     pub macro global_asm("assembly template", $(operands,)* $(options($(option),*))?) {

src/doc/rust-by-example

@@ -6,6 +6,7 @@ LL |         asm!("bar: nop");
    |
    = note: `#[deny(named_asm_labels)]` on by default
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:27:15
@@ -14,6 +15,7 @@ LL |         asm!("abcd:");
    |               ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:30:15
@@ -22,6 +24,7 @@ LL |         asm!("foo: bar1: nop");
    |               ^^^  ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:34:15
@@ -30,6 +33,7 @@ LL |         asm!("foo1: nop", "nop");
    |               ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:35:15
@@ -38,6 +42,7 @@ LL |         asm!("foo2: foo3: nop", "nop");
    |               ^^^^  ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:37:22
@@ -46,6 +51,7 @@ LL |         asm!("nop", "foo4: nop");
    |                      ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:38:15
@@ -54,6 +60,7 @@ LL |         asm!("foo5: nop", "foo6: nop");
    |               ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:38:28
@@ -62,6 +69,7 @@ LL |         asm!("foo5: nop", "foo6: nop");
    |                            ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:43:15
@@ -70,6 +78,7 @@ LL |         asm!("foo7: nop; foo8: nop");
    |               ^^^^       ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:45:15
@@ -78,6 +87,7 @@ LL |         asm!("foo9: nop; nop");
    |               ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:46:20
@@ -86,6 +96,7 @@ LL |         asm!("nop; foo10: nop");
    |                    ^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:49:15
@@ -94,6 +105,7 @@ LL |         asm!("bar2: nop\n bar3: nop");
    |               ^^^^        ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:51:15
@@ -102,6 +114,7 @@ LL |         asm!("bar4: nop\n nop");
    |               ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:52:21
@@ -110,6 +123,7 @@ LL |         asm!("nop\n bar5: nop");
    |                     ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:53:21
@@ -118,6 +132,7 @@ LL |         asm!("nop\n bar6: bar7: nop");
    |                     ^^^^  ^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:59:13
@@ -128,6 +143,7 @@ LL |             blah3: nop
    |             ^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:68:19
@@ -136,6 +152,7 @@ LL |             nop ; blah4: nop
    |                   ^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:82:15
@@ -144,6 +161,7 @@ LL |         asm!("blah1: 2bar: nop");
    |               ^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:85:15
@@ -152,6 +170,7 @@ LL |         asm!("def: def: nop");
    |               ^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:86:15
@@ -160,6 +179,7 @@ LL |         asm!("def: nop\ndef: nop");
    |               ^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:87:15
@@ -168,6 +188,7 @@ LL |         asm!("def: nop; def: nop");
    |               ^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:95:15
@@ -176,6 +197,7 @@ LL |         asm!("fooo\u{003A} nop");
    |               ^^^^^^^^^^^^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:96:15
@@ -184,6 +206,7 @@ LL |         asm!("foooo\x3A nop");
    |               ^^^^^^^^^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:99:15
@@ -192,6 +215,7 @@ LL |         asm!("fooooo:\u{000A} nop");
    |               ^^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:100:15
@@ -200,6 +224,7 @@ LL |         asm!("foooooo:\x0A nop");
    |               ^^^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:104:14
@@ -208,6 +233,7 @@ LL |         asm!("\x41\x42\x43\x3A\x20\x6E\x6F\x70");
    |              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:112:13
@@ -216,6 +242,7 @@ LL |             ab: nop // ab: does foo
    |             ^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:124:14
@@ -224,6 +251,7 @@ LL |         asm!(include_str!("named-asm-labels.s"));
    |              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 warning: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:134:19
@@ -237,6 +265,7 @@ note: the lint level is defined here
 LL |         #[warn(named_asm_labels)]
    |                ^^^^^^^^^^^^^^^^
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:143:20
@@ -245,6 +274,7 @@ LL |     unsafe { asm!(".Lfoo: mov rax, {}; ret;", "nop", const 1, options(noret
    |                    ^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:149:20
@@ -253,6 +283,7 @@ LL |     unsafe { asm!(".Lbar: mov rax, {}; ret;", "nop", const 1, options(noret
    |                    ^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:157:20
@@ -261,6 +292,7 @@ LL |     unsafe { asm!(".Laaa: nop; ret;", options(noreturn)) }
    |                    ^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:167:24
@@ -269,6 +301,7 @@ LL |         unsafe { asm!(".Lbbb: nop; ret;", options(noreturn)) }
    |                        ^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:176:15
@@ -277,6 +310,7 @@ LL |         asm!("closure1: nop");
    |               ^^^^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:180:15
@@ -285,6 +319,7 @@ LL |         asm!("closure2: nop");
    |               ^^^^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: avoid using named labels in inline assembly
   --> $DIR/named-asm-labels.rs:190:19
@@ -293,6 +328,7 @@ LL |             asm!("closure3: nop");
    |                   ^^^^^^^^
    |
    = help: only local labels of the form `<number>:` should be used in inline asm
+   = note: see the asm section of Rust By Example <https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html#labels> for more information
 
 error: aborting due to 35 previous errors; 1 warning emitted