Auto merge of #84107 - Amanieu:global_asm2, r=nagisa

Add support for const operands and options to global_asm!

On x86, the default syntax is also switched to Intel to match asm!.

Currently `global_asm!` only supports `const` operands and the `att_syntax` option. In the future, `sym` operands will also be supported. However there is no plan to support any of the other operand types or options since they don't make sense in the context of `global_asm!`.

r? `@nagisa`

1 files changed, 51 insertions, 18 deletions

diff --git a/src/doc/unstable-book/src/library-features/global-asm.md b/src/doc/unstable-book/src/library-features/global-asm.md
index ce1155a977c..146d17b4638 100644
--- a/src/doc/unstable-book/src/library-features/global-asm.md
+++ b/src/doc/unstable-book/src/library-features/global-asm.md
@@ -8,12 +8,9 @@ The tracking issue for this feature is: [#35119]
 
 The `global_asm!` macro allows the programmer to write arbitrary
 assembly outside the scope of a function body, passing it through
-`rustc` and `llvm` to the assembler. The macro is a no-frills
-interface to LLVM's concept of [module-level inline assembly]. That is,
-all caveats applicable to LLVM's module-level inline assembly apply
-to `global_asm!`.
-
-[module-level inline assembly]: http://llvm.org/docs/LangRef.html#module-level-inline-assembly
+`rustc` and `llvm` to the assembler. That is to say, `global_asm!` is
+equivalent to assembling the asm with an external assembler and then
+linking the resulting object file with the current crate.
 
 `global_asm!` fills a role not currently satisfied by either `asm!`
 or `#[naked]` functions. The programmer has _all_ features of the
@@ -38,11 +35,11 @@ And a more complicated usage looks like this:
 # mod x86 {
 
 pub mod sally {
-    global_asm!(r#"
-        .global foo
-      foo:
-        jmp baz
-    "#);
+    global_asm!(
+        ".global foo",
+        "foo:",
+        "jmp baz",
+    );
 
     #[no_mangle]
     pub unsafe extern "C" fn baz() {}
@@ -56,11 +53,11 @@ extern "C" {
 }
 
 pub mod harry {
-    global_asm!(r#"
-        .global bar
-      bar:
-        jmp quux
-    "#);
+    global_asm!(
+        ".global bar",
+        "bar:",
+        "jmp quux",
+    );
 
     #[no_mangle]
     pub unsafe extern "C" fn quux() {}
@@ -69,8 +66,44 @@ pub mod harry {
 ```
 
 You may use `global_asm!` multiple times, anywhere in your crate, in
-whatever way suits you. The effect is as if you concatenated all
-usages and placed the larger, single usage in the crate root.
+whatever way suits you. However, you should not rely on assembler state
+(e.g. assembler macros) defined in one `global_asm!` to be available in
+another one. It is implementation-defined whether the multiple usages
+are concatenated into one or assembled separately.
+
+`global_asm!` also supports `const` operands like `asm!`, which allows
+constants defined in Rust to be used in assembly code:
+
+```rust,no_run
+#![feature(global_asm)]
+# #[cfg(any(target_arch="x86", target_arch="x86_64"))]
+# mod x86 {
+const C: i32 = 1234;
+global_asm!(
+    ".global bar",
+    "bar: .word {c}",
+    c = const C,
+);
+# }
+```
+
+The syntax for passing operands is the same as `asm!` except that only
+`const` operands are allowed. Refer to the [asm](asm.md) documentation
+for more details.
+
+On x86, the assembly code will use intel syntax by default. You can
+override this by adding `options(att_syntax)` at the end of the macro
+arguments list:
+
+```rust,no_run
+#![feature(global_asm)]
+# #[cfg(any(target_arch="x86", target_arch="x86_64"))]
+# mod x86 {
+global_asm!("movl ${}, %ecx", const 5, options(att_syntax));
+// is equivalent to
+global_asm!("mov ecx, {}", const 5);
+# }
+```
 
 ------------------------