From 0df83f8e5e85268b0134f8c698e09b5c8d6b3ef6 Mon Sep 17 00:00:00 2001
From: Amanieu d'Antras <amanieu@gmail.com>
Date: Wed, 21 Apr 2021 15:21:33 +0100
Subject: [PATCH] Update global_asm! documentation

---
 .../src/library-features/global-asm.md        | 49 ++++++++++++++++---
 1 file changed, 41 insertions(+), 8 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 e241f5788b9..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
@@ -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);
+# }
+```
 
 ------------------------