[clang] Update ASM goto documentation to reflect how Clang differs from GCC

[shafik]

Thank you for updating the documents!

clang/docs/LanguageExtensions.rst

1570

It would be helpful to provide an example of what is not supported. If you can provide an example that actually results in undefined behavior that would be even better.

[void]

Update with example.

clang/docs/LanguageExtensions.rst

1570

I added an example, but it's hard to determine whether a given piece of code will have undefined behavior as it sometimes occurs only on a specific optimization level.

[nickdesaulniers]

clang/docs/LanguageExtensions.rst

1553

Consider adding a link to https://github.com/llvm/llvm-project/issues/53562?

Clang doesn't yet support... but support is planned.

or something.

1557

Do we need to keep the code block to retain formatting?

[shafik]

clang/docs/LanguageExtensions.rst

1570

Understood, I think what you have is good. Thank you.

[void]

clang/docs/LanguageExtensions.rst

1553

I'll add the link to the commit message. I don't know if it's very useful here, as it pertains mostly to compiler developers rather than end users.

clang/docs/LanguageExtensions.rst

 :doc:`BlockLanguageSpec<BlockLanguageSpec>`. Implementation and ABI details for
 the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`.
 
 Query for this feature with ``__has_extension(blocks)``.
 
 ASM Goto with Output Constraints
 ================================
 
-In addition to the functionality provided by `GCC's extended
-assembly <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_, clang
-supports output constraints with the `goto` form.
-
-The goto form of GCC's extended assembly allows the programmer to branch to a C
-label from within an inline assembly block. Clang extends this behavior by
-allowing the programmer to use output constraints:
+.. note::
+
+  Clang's implementation of ASM goto differs from `GCC's
+  implementation<https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_ in
+  that Clang doesn't yet support outputs on the indirect branch. Use of an
+  output on the indirect branch may result in undefined behavior and should be
+  avoided. E.g., in the following `z` isn't valid when used and may have
+  different values depending on optimization levels. (Clang may not warn about
+  such constructs.)
 
   .. code-block:: c++
 
     int foo(int x) {
-      int y;
-      asm goto("# %0 %1 %l2" : "=r"(y) : "r"(x) : : err);
+      int y, z;
+      asm goto(... : "=r"(y), "=r"(z): "r"(x) : : err);
       return y;
     err:
-      return -1;
+      return z;
     }
 
-It's important to note that outputs are valid only on the "fallthrough" branch.
-Using outputs on an indirect branch may result in undefined behavior. For
-example, in the function above, use of the value assigned to `y` in the `err`
-block is undefined behavior.
-
 When using tied-outputs (i.e. outputs that are inputs and outputs, not just
 outputs) with the `+r` constraint, there is a hidden input that's created
 before the label, so numeric references to operands must account for that.
 
 .. code-block:: c++
 
   int foo(int x) {
       // %0 and %1 both refer to x
       // %l2 refers to err
       asm goto("# %0 %1 %l2" : "+r"(x) : : : err);