014-05-09 David Wohlferd <LimeGreenSocks@yahoo.com> Andrew Haley...

014-05-09  David Wohlferd <LimeGreenSocks@yahoo.com>
	Andrew Haley <aph@redhat.com>
	Richard Sandiford <rdsandiford@googlemail.com>

	* doc/extend.texi: Rewrite inline asm page / re-org asm-related
	pages.

From-SVN: r210273

1 files changed, 933 insertions, 440 deletions

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 9780d92..897c562 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -65,11 +65,7 @@ extensions, accepted by GCC in C90 mode and in C++.
 * Alignment::           Inquiring about the alignment of a type or variable.
 * Inline::              Defining inline functions (as fast as macros).
 * Volatiles::           What constitutes an access to a volatile object.
-* Extended Asm::        Assembler instructions with C expressions as operands.
-                        (With them you can define ``built-in'' functions.)
-* Constraints::         Constraints for asm operands
-* Asm Labels::          Specifying the assembler name to use for a C symbol.
-* Explicit Reg Vars::   Defining variables residing in specified registers.
+* Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
 * Alternate Keywords::  @code{__const__}, @code{__asm__}, etc., for header files.
 * Incomplete Enums::    @code{enum foo;}, with details to follow.
 * Function Names::      Printable strings which are the name of the current
@@ -6137,491 +6133,948 @@ bit-fields are only partially accessed, if they straddle a storage unit
 boundary.  For these reasons it is unwise to use volatile bit-fields to
 access hardware.
 
+@node Using Assembly Language with C
+@section How to Use Inline Assembly Language in C Code
+
+GCC provides various extensions that allow you to embed assembler within 
+C code.
+
+@menu
+* Basic Asm::          Inline assembler with no operands.
+* Extended Asm::       Inline assembler with operands.
+* Constraints::        Constraints for @code{asm} operands
+* Asm Labels::         Specifying the assembler name to use for a C symbol.
+* Explicit Reg Vars::  Defining variables residing in specified registers.
+* Size of an asm::     How GCC calculates the size of an @code{asm} block.
+@end menu
+
+@node Basic Asm
+@subsection Basic Asm --- Assembler Instructions with No Operands
+@cindex basic @code{asm}
+
+The @code{asm} keyword allows you to embed assembler instructions within 
+C code.
+
+@example
+asm [ volatile ] ( AssemblerInstructions )
+@end example
+
+To create headers compatible with ISO C, write @code{__asm__} instead of 
+@code{asm} (@pxref{Alternate Keywords}).
+
+By definition, a Basic @code{asm} statement is one with no operands. 
+@code{asm} statements that contain one or more colons (used to delineate 
+operands) are considered to be Extended (for example, @code{asm("int $3")} 
+is Basic, and @code{asm("int $3" : )} is Extended). @xref{Extended Asm}.
+
+@subsubheading Qualifiers
+@emph{volatile}
+@*
+This optional qualifier has no effect. All Basic @code{asm} blocks are 
+implicitly volatile.
+
+@subsubheading Parameters
+@emph{AssemblerInstructions}
+@*
+This is a literal string that specifies the assembler code. The string can 
+contain any instructions recognized by the assembler, including directives. 
+GCC does not parse the assembler instructions themselves and 
+does not know what they mean or even whether they are valid assembler input. 
+The compiler copies it verbatim to the assembly language output file, without 
+processing dialects or any of the "%" operators that are available with
+Extended @code{asm}. This results in minor differences between Basic 
+@code{asm} strings and Extended @code{asm} templates. For example, to refer to 
+registers you might use %%eax in Extended @code{asm} and %eax in Basic 
+@code{asm}.
+
+You may place multiple assembler instructions together in a single @code{asm} 
+string, separated by the characters normally used in assembly code for the 
+system. A combination that works in most places is a newline to break the 
+line, plus a tab character (written as "\n\t").
+Some assemblers allow semicolons as a line separator. However, 
+note that some assembler dialects use semicolons to start a comment. 
+
+Do not expect a sequence of @code{asm} statements to remain perfectly 
+consecutive after compilation. If certain instructions need to remain 
+consecutive in the output, put them in a single multi-instruction asm 
+statement. Note that GCC's optimizers can move @code{asm} statements 
+relative to other code, including across jumps.
+
+@code{asm} statements may not perform jumps into other @code{asm} statements. 
+GCC does not know about these jumps, and therefore cannot take 
+account of them when deciding how to optimize. Jumps from @code{asm} to C 
+labels are only supported in Extended @code{asm}.
+
+@subsubheading Remarks
+Using Extended @code{asm} will typically produce smaller, safer, and more 
+efficient code, and in most cases it is a better solution. When writing 
+inline assembly language outside of C functions, however, you must use Basic 
+@code{asm}. Extended @code{asm} statements have to be inside a C function.
+
+Under certain circumstances, GCC may duplicate (or remove duplicates of) your 
+assembly code when optimizing. This can lead to unexpected duplicate 
+symbol errors during compilation if your assembly code defines symbols or 
+labels.
+
+Safely accessing C data and calling functions from Basic @code{asm} is more 
+complex than it may appear. To access C data, it is better to use Extended 
+@code{asm}.
+
+Since GCC does not parse the AssemblerInstructions, it has no 
+visibility of any symbols it references. This may result in GCC discarding 
+those symbols as unreferenced.
+
+Unlike Extended @code{asm}, all Basic @code{asm} blocks are implicitly 
+volatile. @xref{Volatile}.  Similarly, Basic @code{asm} blocks are not treated 
+as though they used a "memory" clobber (@pxref{Clobbers}).
+
+All Basic @code{asm} blocks use the assembler dialect specified by the 
+@option{-masm} command-line option. Basic @code{asm} provides no
+mechanism to provide different assembler strings for different dialects.
+
+Here is an example of Basic @code{asm} for i386:
+
+@example
+/* Note that this code will not compile with -masm=intel */
+#define DebugBreak() asm("int $3")
+@end example
+
 @node Extended Asm
-@section Assembler Instructions with C Expression Operands
+@subsection Extended Asm - Assembler Instructions with C Expression Operands
+@cindex @code{asm} keyword
 @cindex extended @code{asm}
-@cindex @code{asm} expressions
 @cindex assembler instructions
-@cindex registers
 
-In an assembler instruction using @code{asm}, you can specify the
-operands of the instruction using C expressions.  This means you need not
-guess which registers or memory locations contain the data you want
-to use.
+The @code{asm} keyword allows you to embed assembler instructions within C 
+code. With Extended @code{asm} you can read and write C variables from 
+assembler and perform jumps from assembler code to C labels.
 
-You must specify an assembler instruction template much like what
-appears in a machine description, plus an operand constraint string for
-each operand.
+@example
+@ifhtml
+asm [volatile] ( AssemblerTemplate : [OutputOperands] [ : [InputOperands] [ : [Clobbers] ] ] )
+
+asm [volatile] goto ( AssemblerTemplate : : [InputOperands] : [Clobbers] : GotoLabels )
+@end ifhtml
+@ifnothtml
+asm [volatile] ( AssemblerTemplate 
+                 : [OutputOperands] 
+                 [ : [InputOperands] 
+                 [ : [Clobbers] ] ])
+
+asm [volatile] goto ( AssemblerTemplate 
+                      : 
+                      : [InputOperands] 
+                      : [Clobbers] 
+                      : GotoLabels)
+@end ifnothtml
+@end example
 
-For example, here is how to use the 68881's @code{fsinx} instruction:
+To create headers compatible with ISO C, write @code{__asm__} instead of 
+@code{asm} and @code{__volatile__} instead of @code{volatile} 
+(@pxref{Alternate Keywords}). There is no alternate for @code{goto}.
+
+By definition, Extended @code{asm} is an @code{asm} statement that contains 
+operands. To separate the classes of operands, you use colons. Basic 
+@code{asm} statements contain no colons. (So, for example, 
+@code{asm("int $3")} is Basic @code{asm}, and @code{asm("int $3" : )} is 
+Extended @code{asm}. @pxref{Basic Asm}.)
+
+@subsubheading Qualifiers
+@emph{volatile}
+@*
+The typical use of Extended @code{asm} statements is to manipulate input 
+values to produce output values. However, your @code{asm} statements may 
+also produce side effects. If so, you may need to use the @code{volatile} 
+qualifier to disable certain optimizations. @xref{Volatile}.
+
+@emph{goto}
+@*
+This qualifier informs the compiler that the @code{asm} statement may 
+perform a jump to one of the labels listed in the GotoLabels section. 
+@xref{GotoLabels}.
+
+@subsubheading Parameters
+@emph{AssemblerTemplate}
+@*
+This is a literal string that contains the assembler code. It is a 
+combination of fixed text and tokens that refer to the input, output, 
+and goto parameters. @xref{AssemblerTemplate}.
+
+@emph{OutputOperands}
+@*
+A comma-separated list of the C variables modified by the instructions in the 
+AssemblerTemplate. @xref{OutputOperands}.
+
+@emph{InputOperands}
+@*
+A comma-separated list of C expressions read by the instructions in the 
+AssemblerTemplate. @xref{InputOperands}.
+
+@emph{Clobbers}
+@*
+A comma-separated list of registers or other values changed by the 
+AssemblerTemplate, beyond those listed as outputs. @xref{Clobbers}.
+
+@emph{GotoLabels}
+@*
+When you are using the @code{goto} form of @code{asm}, this section contains 
+the list of all C labels to which the AssemblerTemplate may jump. 
+@xref{GotoLabels}.
+
+@subsubheading Remarks
+The @code{asm} statement allows you to include assembly instructions directly 
+within C code. This may help you to maximize performance in time-sensitive 
+code or to access assembly instructions that are not readily available to C 
+programs.
+
+Note that Extended @code{asm} statements must be inside a function. Only 
+Basic @code{asm} may be outside functions (@pxref{Basic Asm}).
+
+While the uses of @code{asm} are many and varied, it may help to think of an 
+@code{asm} statement as a series of low-level instructions that convert input 
+parameters to output parameters. So a simple (if not particularly useful) 
+example for i386 using @code{asm} might look like this:
 
-@smallexample
-asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
-@end smallexample
+@example
+int src = 1;
+int dst;   
 
-@noindent
-Here @code{angle} is the C expression for the input operand while
-@code{result} is that of the output operand.  Each has @samp{"f"} as its
-operand constraint, saying that a floating-point register is required.
-The @samp{=} in @samp{=f} indicates that the operand is an output; all
-output operands' constraints must use @samp{=}.  The constraints use the
-same language used in the machine description (@pxref{Constraints}).
-
-Each operand is described by an operand-constraint string followed by
-the C expression in parentheses.  A colon separates the assembler
-template from the first output operand and another separates the last
-output operand from the first input, if any.  Commas separate the
-operands within each group.  The total number of operands is currently
-limited to 30; this limitation may be lifted in some future version of
-GCC@.
-
-If there are no output operands but there are input operands, you must
-place two consecutive colons surrounding the place where the output
-operands would go.
-
-As of GCC version 3.1, it is also possible to specify input and output
-operands using symbolic names which can be referenced within the
-assembler code.  These names are specified inside square brackets
-preceding the constraint string, and can be referenced inside the
-assembler code using @code{%[@var{name}]} instead of a percentage sign
-followed by the operand number.  Using named operands the above example
-could look like:
-
-@smallexample
-asm ("fsinx %[angle],%[output]"
-     : [output] "=f" (result)
-     : [angle] "f" (angle));
-@end smallexample
+asm ("mov %1, %0\n\t"
+    "add $1, %0"
+    : "=r" (dst) 
+    : "r" (src));
 
-@noindent
-Note that the symbolic operand names have no relation whatsoever to
-other C identifiers.  You may use any name you like, even those of
-existing C symbols, but you must ensure that no two operands within the same
-assembler construct use the same symbolic name.
-
-Output operand expressions must be lvalues; the compiler can check this.
-The input operands need not be lvalues.  The compiler cannot check
-whether the operands have data types that are reasonable for the
-instruction being executed.  It does not parse the assembler instruction
-template and does not know what it means or even whether it is valid
-assembler input.  The extended @code{asm} feature is most often used for
-machine instructions the compiler itself does not know exist.  If
-the output expression cannot be directly addressed (for example, it is a
-bit-field), your constraint must allow a register.  In that case, GCC
-uses the register as the output of the @code{asm}, and then stores
-that register into the output.
-
-The ordinary output operands must be write-only; GCC assumes that
-the values in these operands before the instruction are dead and need
-not be generated.  Extended asm supports input-output or read-write
-operands.  Use the constraint character @samp{+} to indicate such an
-operand and list it with the output operands.
-
-You may, as an alternative, logically split its function into two
-separate operands, one input operand and one write-only output
-operand.  The connection between them is expressed by constraints
-that say they need to be in the same location when the instruction
-executes.  You can use the same C expression for both operands, or
-different expressions.  For example, here we write the (fictitious)
-@samp{combine} instruction with @code{bar} as its read-only source
-operand and @code{foo} as its read-write destination:
-
-@smallexample
-asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
-@end smallexample
+printf("%d\n", dst);
+@end example
 
-@noindent
-The constraint @samp{"0"} for operand 1 says that it must occupy the
-same location as operand 0.  A number in constraint is allowed only in
-an input operand and it must refer to an output operand.
+This code will copy @var{src} to @var{dst} and add 1 to @var{dst}.
 
-Only a number in the constraint can guarantee that one operand is in
-the same place as another.  The mere fact that @code{foo} is the value
-of both operands is not enough to guarantee that they are in the
-same place in the generated assembler code.  The following does not
-work reliably:
+@anchor{Volatile}
+@subsubsection Volatile
+@cindex volatile @code{asm}
+@cindex @code{asm} volatile
 
-@smallexample
-asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
-@end smallexample
+GCC's optimizers sometimes discard @code{asm} statements if they determine 
+there is no need for the output variables. Also, the optimizers may move 
+code out of loops if they believe that the code will always return the same 
+result (i.e. none of its input values change between calls). Using the 
+@code{volatile} qualifier disables these optimizations. @code{asm} statements 
+that have no output operands are implicitly volatile.
 
-Various optimizations or reloading could cause operands 0 and 1 to be in
-different registers; GCC knows no reason not to do so.  For example, the
-compiler might find a copy of the value of @code{foo} in one register and
-use it for operand 1, but generate the output operand 0 in a different
-register (copying it afterward to @code{foo}'s own address).  Of course,
-since the register for operand 1 is not even mentioned in the assembler
-code, the result will not work, but GCC can't tell that.
+Examples:
 
-As of GCC version 3.1, one may write @code{[@var{name}]} instead of
-the operand number for a matching constraint.  For example:
+This i386 code demonstrates a case that does not use (or require) the 
+@code{volatile} qualifier. If it is performing assertion checking, this code 
+uses @code{asm} to perform the validation. Otherwise, @var{dwRes} is 
+unreferenced by any code. As a result, the optimizers can discard the 
+@code{asm} statement, which in turn removes the need for the entire 
+@code{DoCheck} routine. By omitting the @code{volatile} qualifier when it 
+isn't needed you allow the optimizers to produce the most efficient code 
+possible.
 
-@smallexample
-asm ("cmoveq %1,%2,%[result]"
-     : [result] "=r"(result)
-     : "r" (test), "r"(new), "[result]"(old));
-@end smallexample
+@example
+void DoCheck(uint32_t dwSomeValue)
+@{
+   uint32_t dwRes;
 
-Sometimes you need to make an @code{asm} operand be a specific register,
-but there's no matching constraint letter for that register @emph{by
-itself}.  To force the operand into that register, use a local variable
-for the operand and specify the register in the variable declaration.
-@xref{Explicit Reg Vars}.  Then for the @code{asm} operand, use any
-register constraint letter that matches the register:
+   // Assumes dwSomeValue is not zero.
+   asm ("bsfl %1,%0"
+     : "=r" (dwRes)
+     : "r" (dwSomeValue)
+     : "cc");
 
-@smallexample
-register int *p1 asm ("r0") = @dots{};
-register int *p2 asm ("r1") = @dots{};
-register int *result asm ("r0");
-asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
-@end smallexample
+   assert(dwRes > 3);
+@}
+@end example
 
-@anchor{Example of asm with clobbered asm reg}
-In the above example, beware that a register that is call-clobbered by
-the target ABI will be overwritten by any function call in the
-assignment, including library calls for arithmetic operators.
-Also a register may be clobbered when generating some operations,
-like variable shift, memory copy or memory move on x86.
-Assuming it is a call-clobbered register, this may happen to @code{r0}
-above by the assignment to @code{p2}.  If you have to use such a
-register, use temporary variables for expressions between the register
-assignment and use:
+The next example shows a case where the optimizers can recognize that the input 
+(@var{dwSomeValue}) never changes during the execution of the function and can 
+therefore move the @code{asm} outside the loop to produce more efficient code. 
+Again, using @code{volatile} disables this type of optimization.
 
-@smallexample
-int t1 = @dots{};
-register int *p1 asm ("r0") = @dots{};
-register int *p2 asm ("r1") = t1;
-register int *result asm ("r0");
-asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
-@end smallexample
+@example
+void do_print(uint32_t dwSomeValue)
+@{
+   uint32_t dwRes;
+
+   for (uint32_t x=0; x < 5; x++)
+   @{
+      // Assumes dwSomeValue is not zero.
+      asm ("bsfl %1,%0"
+        : "=r" (dwRes)
+        : "r" (dwSomeValue)
+        : "cc");
+
+      printf("%u: %u %u\n", x, dwSomeValue, dwRes);
+   @}
+@}
+@end example
 
-Some instructions clobber specific hard registers.  To describe this,
-write a third colon after the input operands, followed by the names of
-the clobbered hard registers (given as strings).  Here is a realistic
-example for the VAX:
+The following example demonstrates a case where you need to use the 
+@code{volatile} qualifier. It uses the i386 RDTSC instruction, which reads 
+the computer's time-stamp counter. Without the @code{volatile} qualifier, 
+the optimizers might assume that the @code{asm} block will always return the 
+same value and therefore optimize away the second call.
 
-@smallexample
-asm volatile ("movc3 %0,%1,%2"
-              : /* @r{no outputs} */
-              : "g" (from), "g" (to), "g" (count)
-              : "r0", "r1", "r2", "r3", "r4", "r5");
-@end smallexample
+@example
+uint64_t msr;
 
-You may not write a clobber description in a way that overlaps with an
-input or output operand.  For example, you may not have an operand
-describing a register class with one member if you mention that register
-in the clobber list.  Variables declared to live in specific registers
-(@pxref{Explicit Reg Vars}), and used as asm input or output operands must
-have no part mentioned in the clobber description.
-There is no way for you to specify that an input
-operand is modified without also specifying it as an output
-operand.  Note that if all the output operands you specify are for this
-purpose (and hence unused), you then also need to specify
-@code{volatile} for the @code{asm} construct, as described below, to
-prevent GCC from deleting the @code{asm} statement as unused.
+asm volatile ( "rdtsc\n\t"    // Returns the time in EDX:EAX.
+        "shl $32, %%rdx\n\t"  // Shift the upper bits left.
+        "or %%rdx, %0"        // 'Or' in the lower bits.
+        : "=a" (msr)
+        : 
+        : "rdx");
 
-If you refer to a particular hardware register from the assembler code,
-you probably have to list the register after the third colon to
-tell the compiler the register's value is modified.  In some assemblers,
-the register names begin with @samp{%}; to produce one @samp{%} in the
-assembler code, you must write @samp{%%} in the input.
+printf("msr: %llx\n", msr);
 
-If your assembler instruction can alter the condition code register, add
-@samp{cc} to the list of clobbered registers.  GCC on some machines
-represents the condition codes as a specific hardware register;
-@samp{cc} serves to name this register.  On other machines, the
-condition code is handled differently, and specifying @samp{cc} has no
-effect.  But it is valid no matter what the machine.
+// Do other work...
 
-If your assembler instructions access memory in an unpredictable
-fashion, add @samp{memory} to the list of clobbered registers.  This
-causes GCC to not keep memory values cached in registers across the
-assembler instruction and not optimize stores or loads to that memory.
-You also should add the @code{volatile} keyword if the memory
-affected is not listed in the inputs or outputs of the @code{asm}, as
-the @samp{memory} clobber does not count as a side-effect of the
-@code{asm}.  If you know how large the accessed memory is, you can add
-it as input or output but if this is not known, you should add
-@samp{memory}.  As an example, if you access ten bytes of a string, you
-can use a memory input like:
+// Reprint the timestamp
+asm volatile ( "rdtsc\n\t"    // Returns the time in EDX:EAX.
+        "shl $32, %%rdx\n\t"  // Shift the upper bits left.
+        "or %%rdx, %0"        // 'Or' in the lower bits.
+        : "=a" (msr)
+        : 
+        : "rdx");
 
-@smallexample
-@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}.
-@end smallexample
+printf("msr: %llx\n", msr);
+@end example
 
-Note that in the following example the memory input is necessary,
-otherwise GCC might optimize the store to @code{x} away:
-@smallexample
-int foo ()
-@{
-  int x = 42;
-  int *y = &x;
-  int result;
-  asm ("magic stuff accessing an 'int' pointed to by '%1'"
-       : "=&d" (result) : "a" (y), "m" (*y));
-  return result;
-@}
-@end smallexample
+GCC's optimizers will not treat this code like the non-volatile code in the 
+earlier examples. They do not move it out of loops or omit it on the 
+assumption that the result from a previous call is still valid.
 
-You can put multiple assembler instructions together in a single
-@code{asm} template, separated by the characters normally used in assembly
-code for the system.  A combination that works in most places is a newline
-to break the line, plus a tab character to move to the instruction field
-(written as @samp{\n\t}).  Sometimes semicolons can be used, if the
-assembler allows semicolons as a line-breaking character.  Note that some
-assembler dialects use semicolons to start a comment.
-The input operands are guaranteed not to use any of the clobbered
-registers, and neither do the output operands' addresses, so you can
-read and write the clobbered registers as many times as you like.  Here
-is an example of multiple instructions in a template; it assumes the
-subroutine @code{_foo} accepts arguments in registers 9 and 10:
+Note that the compiler can move even volatile @code{asm} instructions relative 
+to other code, including across jump instructions. For example, on many 
+targets there is a system register that controls the rounding mode of 
+floating-point operations. Setting it with a volatile @code{asm}, as in the 
+following PowerPC example, will not work reliably.
 
-@smallexample
-asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo"
-     : /* no outputs */
-     : "g" (from), "g" (to)
-     : "r9", "r10");
-@end smallexample
+@example
+asm volatile("mtfsf 255, %0" : : "f" (fpenv));
+sum = x + y;
+@end example
 
-Unless an output operand has the @samp{&} constraint modifier, GCC
-may allocate it in the same register as an unrelated input operand, on
-the assumption the inputs are consumed before the outputs are produced.
-This assumption may be false if the assembler code actually consists of
-more than one instruction.  In such a case, use @samp{&} for each output
-operand that may not overlap an input.  @xref{Modifiers}.
+The compiler may move the addition back before the volatile @code{asm}. To 
+make it work as expected, add an artificial dependency to the @code{asm} by 
+referencing a variable in the subsequent code, for example: 
 
-If you want to test the condition code produced by an assembler
-instruction, you must include a branch and a label in the @code{asm}
-construct, as follows:
+@example
+asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
+sum = x + y;
+@end example
 
-@smallexample
-asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
-     : "g" (result)
-     : "g" (input));
-@end smallexample
+Under certain circumstances, GCC may duplicate (or remove duplicates of) your 
+assembly code when optimizing. This can lead to unexpected duplicate symbol 
+errors during compilation if your asm code defines symbols or labels. Using %= 
+(@pxref{AssemblerTemplate}) may help resolve this problem.
+
+@anchor{AssemblerTemplate}
+@subsubsection Assembler Template
+@cindex @code{asm} assembler template
+
+An assembler template is a literal string containing assembler instructions. 
+The compiler will replace any references to inputs, outputs, and goto labels 
+in the template, and then output the resulting string to the assembler. The 
+string can contain any instructions recognized by the assembler, including 
+directives. GCC does not parse the assembler instructions 
+themselves and does not know what they mean or even whether they are valid 
+assembler input. However, it does count the statements 
+(@pxref{Size of an asm}).
+
+You may place multiple assembler instructions together in a single @code{asm} 
+string, separated by the characters normally used in assembly code for the 
+system. A combination that works in most places is a newline to break the 
+line, plus a tab character to move to the instruction field (written as 
+"\n\t"). Some assemblers allow semicolons as a line separator. However, note 
+that some assembler dialects use semicolons to start a comment. 
+
+Do not expect a sequence of @code{asm} statements to remain perfectly 
+consecutive after compilation, even when you are using the @code{volatile} 
+qualifier. If certain instructions need to remain consecutive in the output, 
+put them in a single multi-instruction asm statement.
+
+Accessing data from C programs without using input/output operands (such as 
+by using global symbols directly from the assembler template) may not work as 
+expected. Similarly, calling functions directly from an assembler template 
+requires a detailed understanding of the target assembler and ABI.
+
+Since GCC does not parse the AssemblerTemplate, it has no visibility of any 
+symbols it references. This may result in GCC discarding those symbols as 
+unreferenced unless they are also listed as input, output, or goto operands.
+
+GCC can support multiple assembler dialects (for example, GCC for i386 
+supports "att" and "intel" dialects) for inline assembler. In builds that 
+support this capability, the @option{-masm} option controls which dialect 
+GCC uses as its default. The hardware-specific documentation for the 
+@option{-masm} option contains the list of supported dialects, as well as the 
+default dialect if the option is not specified. This information may be 
+important to understand, since assembler code that works correctly when 
+compiled using one dialect will likely fail if compiled using another.
+
+@subsubheading Using braces in @code{asm} templates
+
+If your code needs to support multiple assembler dialects (for example, if 
+you are writing public headers that need to support a variety of compilation 
+options), use constructs of this form:
 
-@noindent
-This assumes your assembler supports local labels, as the GNU assembler
-and most Unix assemblers do.
+@example
+@{ dialect0 | dialect1 | dialect2... @}
+@end example
 
-Speaking of labels, jumps from one @code{asm} to another are not
-supported.  The compiler's optimizers do not know about these jumps, and
-therefore they cannot take account of them when deciding how to
-optimize.  @xref{Extended asm with goto}.
+This construct outputs 'dialect0' when using dialect #0 to compile the code, 
+'dialect1' for dialect #1, etc. If there are fewer alternatives within the 
+braces than the number of dialects the compiler supports, the construct 
+outputs nothing.
 
-@cindex macros containing @code{asm}
-Usually the most convenient way to use these @code{asm} instructions is to
-encapsulate them in macros that look like functions.  For example,
+For example, if an i386 compiler supports two dialects (att, intel), an 
+assembler template such as this:
 
-@smallexample
-#define sin(x)       \
-(@{ double __value, __arg = (x);   \
-   asm ("fsinx %1,%0": "=f" (__value): "f" (__arg));  \
-   __value; @})
-@end smallexample
+@example
+"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
+@end example
 
-@noindent
-Here the variable @code{__arg} is used to make sure that the instruction
-operates on a proper @code{double} value, and to accept only those
-arguments @code{x} that can convert automatically to a @code{double}.
-
-Another way to make sure the instruction operates on the correct data
-type is to use a cast in the @code{asm}.  This is different from using a
-variable @code{__arg} in that it converts more different types.  For
-example, if the desired type is @code{int}, casting the argument to
-@code{int} accepts a pointer with no complaint, while assigning the
-argument to an @code{int} variable named @code{__arg} warns about
-using a pointer unless the caller explicitly casts it.
-
-If an @code{asm} has output operands, GCC assumes for optimization
-purposes the instruction has no side effects except to change the output
-operands.  This does not mean instructions with a side effect cannot be
-used, but you must be careful, because the compiler may eliminate them
-if the output operands aren't used, or move them out of loops, or
-replace two with one if they constitute a common subexpression.  Also,
-if your instruction does have a side effect on a variable that otherwise
-appears not to change, the old value of the variable may be reused later
-if it happens to be found in a register.
-
-You can prevent an @code{asm} instruction from being deleted
-by writing the keyword @code{volatile} after
-the @code{asm}.  For example:
-
-@smallexample
-#define get_and_set_priority(new)              \
-(@{ int __old;                                  \
-   asm volatile ("get_and_set_priority %0, %1" \
-                 : "=g" (__old) : "g" (new));  \
-   __old; @})
-@end smallexample
+would produce the output:
 
-@noindent
-The @code{volatile} keyword indicates that the instruction has
-important side-effects.  GCC does not delete a volatile @code{asm} if
-it is reachable.  (The instruction can still be deleted if GCC can
-prove that control flow never reaches the location of the
-instruction.)  Note that even a volatile @code{asm} instruction
-can be moved relative to other code, including across jump
-instructions.  For example, on many targets there is a system
-register that can be set to control the rounding mode of
-floating-point operations.  You might try
-setting it with a volatile @code{asm}, like this PowerPC example:
+@example
+For att: "btl %[Offset],%[Base] ; jc %l2"
+For intel: "bt %[Base],%[Offset]; jc %l2"
+@end example
 
-@smallexample
-       asm volatile("mtfsf 255,%0" : : "f" (fpenv));
-       sum = x + y;
-@end smallexample
+Using that same compiler, this code:
 
-@noindent
-This does not work reliably, as the compiler may move the addition back
-before the volatile @code{asm}.  To make it work you need to add an
-artificial dependency to the @code{asm} referencing a variable in the code
-you don't want moved, for example:
+@example
+"xchg@{l@}\t@{%%@}ebx, %1"
+@end example
 
-@smallexample
-    asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv));
-    sum = x + y;
-@end smallexample
+would produce 
 
-Similarly, you can't expect a
-sequence of volatile @code{asm} instructions to remain perfectly
-consecutive.  If you want consecutive output, use a single @code{asm}.
-Also, GCC performs some optimizations across a volatile @code{asm}
-instruction; GCC does not ``forget everything'' when it encounters
-a volatile @code{asm} instruction the way some other compilers do.
+@example
+For att: "xchgl\t%%ebx, %1"
+For intel: "xchg\tebx, %1"
+@end example
 
-An @code{asm} instruction without any output operands is treated
-identically to a volatile @code{asm} instruction.
+There is no support for nesting dialect alternatives. Also, there is no 
+``escape'' for an open brace (@{), so do not use open braces in an Extended 
+@code{asm} template other than as a dialect indicator.
 
-It is a natural idea to look for a way to give access to the condition
-code left by the assembler instruction.  However, when we attempted to
-implement this, we found no way to make it work reliably.  The problem
-is that output operands might need reloading, which result in
-additional following ``store'' instructions.  On most machines, these
-instructions alter the condition code before there is time to
-test it.  This problem doesn't arise for ordinary ``test'' and
-``compare'' instructions because they don't have any output operands.
+@subsubheading Other format strings
 
-For reasons similar to those described above, it is not possible to give
-an assembler instruction access to the condition code left by previous
-instructions.
+In addition to the tokens described by the input, output, and goto operands, 
+there are a few special cases:
 
-@anchor{Extended asm with goto}
-As of GCC version 4.5, @code{asm goto} may be used to have the assembly
-jump to one or more C labels.  In this form, a fifth section after the
-clobber list contains a list of all C labels to which the assembly may jump.
-Each label operand is implicitly self-named.  The @code{asm} is also assumed
-to fall through to the next statement.
+@itemize
+@item
+"%%" outputs a single "%" into the assembler code.
 
-This form of @code{asm} is restricted to not have outputs.  This is due
-to a internal restriction in the compiler that control transfer instructions
-cannot have outputs.  This restriction on @code{asm goto} may be lifted
-in some future version of the compiler.  In the meantime, @code{asm goto}
-may include a memory clobber, and so leave outputs in memory.
+@item
+"%=" outputs a number that is unique to each instance of the @code{asm} 
+statement in the entire compilation. This option is useful when creating local 
+labels and referring to them multiple times in a single template that 
+generates multiple assembler instructions. 
 
-@smallexample
+@end itemize
+
+@anchor{OutputOperands}
+@subsubsection Output Operands
+@cindex @code{asm} output operands
+
+An @code{asm} statement has zero or more output operands indicating the names
+of C variables modified by the assembler code.
+
+In this i386 example, @var{old} (referred to in the template string as 
+@code{%0}) and @var{*Base} (as @code{%1}) are outputs and @var{Offset} 
+(@code{%2}) is an input:
+
+@example
+bool old;
+
+__asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
+         "sbb %0,%0"      // Use the CF to calculate old.
+   : "=r" (old), "+rm" (*Base)
+   : "Ir" (Offset)
+   : "cc");
+
+return old;
+@end example
+
+Operands use this format:
+
+@example
+[ [asmSymbolicName] ] "constraint" (cvariablename)
+@end example
+
+@emph{asmSymbolicName}
+@*
+
+When not using asmSymbolicNames, use the (zero-based) position of the operand 
+in the list of operands in the assembler template. For example if there are 
+three output operands, use @code{%0} in the template to refer to the first, 
+@code{%1} for the second, and @code{%2} for the third. When using an 
+asmSymbolicName, reference it by enclosing the name in square brackets 
+(i.e. @code{%[Value]}). The scope of the name is the @code{asm} statement 
+that contains the definition. Any valid C variable name is acceptable, 
+including names already defined in the surrounding code. No two operands 
+within the same @code{asm} statement can use the same symbolic name.
+
+@emph{constraint}
+@*
+Output constraints must begin with either @code{"="} (a variable overwriting an 
+existing value) or @code{"+"} (when reading and writing). When using 
+@code{"="}, do not assume the location will contain the existing value (except 
+when tying the variable to an input; @pxref{InputOperands,,Input Operands}).
+
+After the prefix, there must be one or more additional constraints 
+(@pxref{Constraints}) that describe where the value resides. Common 
+constraints include @code{"r"} for register and @code{"m"} for memory. 
+When you list more than one possible location (for example @code{"=rm"}), the 
+compiler chooses the most efficient one based on the current context. If you 
+list as many alternates as the @code{asm} statement allows, you will permit 
+the optimizers to produce the best possible code. If you must use a specific
+register, but your Machine Constraints do not provide sufficient 
+control to select the specific register you want, Local Reg Vars may provide 
+a solution (@pxref{Local Reg Vars}).
+
+@emph{cvariablename}
+@*
+Specifies the C variable name of the output (enclosed by parentheses). Accepts 
+any (non-constant) variable within scope.
+
+Remarks:
+
+The total number of input + output + goto operands has a limit of 30. Commas 
+separate the operands. When the compiler selects the registers to use to 
+represent the output operands, it will not use any of the clobbered registers 
+(@pxref{Clobbers}).
+
+Output operand expressions must be lvalues. The compiler cannot check whether 
+the operands have data types that are reasonable for the instruction being 
+executed. For output expressions that are not directly addressable (for 
+example a bit-field), the constraint must allow a register. In that case, GCC 
+uses the register as the output of the @code{asm}, and then stores that 
+register into the output. 
+
+Unless an output operand has the '@code{&}' constraint modifier 
+(@pxref{Modifiers}), GCC may allocate it in the same register as an unrelated 
+input operand, on the assumption that the assembler code will consume its 
+inputs before producing outputs. This assumption may be false if the assembler 
+code actually consists of more than one instruction. In this case, use 
+'@code{&}' on each output operand that must not overlap an input.
+
+The same problem can occur if one output parameter (@var{a}) allows a register 
+constraint and another output parameter (@var{b}) allows a memory constraint.
+The code generated by GCC to access the memory address in @var{b} can contain
+registers which @emph{might} be shared by @var{a}, and GCC considers those 
+registers to be inputs to the asm. As above, GCC assumes that such input
+registers are consumed before any outputs are written. This assumption may 
+result in incorrect behavior if the asm writes to @var{a} before using 
+@var{b}. Combining the `@code{&}' constraint with the register constraint 
+ensures that modifying @var{a} will not affect what address is referenced by 
+@var{b}. Omitting the `@code{&}' constraint means that the location of @var{b} 
+will be undefined if @var{a} is modified before using @var{b}.
+
+@code{asm} supports operand modifiers on operands (for example @code{%k2} 
+instead of simply @code{%2}). Typically these qualifiers are hardware 
+dependent. The list of supported modifiers for i386 is found at 
+@ref{i386Operandmodifiers,i386 Operand modifiers}.
+
+If the C code that follows the @code{asm} makes no use of any of the output 
+operands, use @code{volatile} for the @code{asm} statement to prevent the 
+optimizers from discarding the @code{asm} statement as unneeded 
+(see @ref{Volatile}).
+
+Examples:
+
+This code makes no use of the optional asmSymbolicName. Therefore it 
+references the first output operand as @code{%0} (were there a second, it 
+would be @code{%1}, etc). The number of the first input operand is one greater 
+than that of the last output operand. In this i386 example, that makes 
+@var{Mask} @code{%1}:
+
+@example
+uint32_t Mask = 1234;
+uint32_t Index;
+
+  asm ("bsfl %1, %0"
+     : "=r" (Index)
+     : "r" (Mask)
+     : "cc");
+@end example
+
+That code overwrites the variable Index ("="), placing the value in a register 
+("r"). The generic "r" constraint instead of a constraint for a specific 
+register allows the compiler to pick the register to use, which can result 
+in more efficient code. This may not be possible if an assembler instruction 
+requires a specific register.
+
+The following i386 example uses the asmSymbolicName operand. It produces the 
+same result as the code above, but some may consider it more readable or more 
+maintainable since reordering index numbers is not necessary when adding or 
+removing operands. The names aIndex and aMask are only used to emphasize which 
+names get used where. It is acceptable to reuse the names Index and Mask.
+
+@example
+uint32_t Mask = 1234;
+uint32_t Index;
+
+  asm ("bsfl %[aMask], %[aIndex]"
+     : [aIndex] "=r" (Index)
+     : [aMask] "r" (Mask)
+     : "cc");
+@end example
+
+Here are some more examples of output operands.
+
+@example
+uint32_t c = 1;
+uint32_t d;
+uint32_t *e = &c;
+
+asm ("mov %[e], %[d]"
+   : [d] "=rm" (d)
+   : [e] "rm" (*e));
+@end example
+
+Here, @var{d} may either be in a register or in memory. Since the compiler 
+might already have the current value of the uint32_t pointed to by @var{e} 
+in a register, you can enable it to choose the best location
+for @var{d} by specifying both constraints.
+
+@anchor{InputOperands}
+@subsubsection Input Operands
+@cindex @code{asm} input operands
+@cindex @code{asm} expressions
+
+Input operands make inputs from C variables and expressions available to the 
+assembly code.
+
+Specify input operands by using the format:
+
+@example
+[ [asmSymbolicName] ] "constraint" (cexpression)
+@end example
+
+@emph{asmSymbolicName}
+@*
+When not using asmSymbolicNames, use the (zero-based) position of the operand 
+in the list of operands, including outputs, in the assembler template. For 
+example, if there are two output parameters and three inputs, @code{%2} refers 
+to the first input, @code{%3} to the second, and @code{%4} to the third.
+When using an asmSymbolicName, reference it by enclosing the name in square 
+brackets (e.g. @code{%[Value]}). The scope of the name is the @code{asm} 
+statement that contains the definition. Any valid C variable name is 
+acceptable, including names already defined in the surrounding code. No two 
+operands within the same @code{asm} statement can use the same symbolic name.
+
+@emph{constraint}
+@*
+Input constraints must be a string containing one or more constraints 
+(@pxref{Constraints}). When you give more than one possible constraint 
+(for example, @code{"irm"}), the compiler will choose the most efficient 
+method based on the current context. Input constraints may not begin with 
+either "=" or "+". If you must use a specific register, but your Machine
+Constraints do not provide sufficient control to select the specific 
+register you want, Local Reg Vars may provide a solution 
+(@pxref{Local Reg Vars}).
+
+Input constraints can also be digits (for example, @code{"0"}). This indicates 
+that the specified input will be in the same place as the output constraint 
+at the (zero-based) index in the output constraint list. When using 
+asmSymbolicNames for the output operands, you may use these names (enclosed 
+in brackets []) instead of digits.
+
+@emph{cexpression}
+@*
+This is the C variable or expression being passed to the @code{asm} statement 
+as input.
+
+When the compiler selects the registers to use to represent the input 
+operands, it will not use any of the clobbered registers (@pxref{Clobbers}).
+
+If there are no output operands but there are input operands, place two 
+consecutive colons where the output operands would go:
+
+@example
+__asm__ ("some instructions"
+   : /* No outputs. */
+   : "r" (Offset / 8);
+@end example
+
+@strong{Warning:} Do @emph{not} modify the contents of input-only operands 
+(except for inputs tied to outputs). The compiler assumes that on exit from 
+the @code{asm} statement these operands will contain the same values as they 
+had before executing the assembler. It is @emph{not} possible to use Clobbers 
+to inform the compiler that the values in these inputs are changing. One 
+common work-around is to tie the changing input variable to an output variable 
+that never gets used. Note, however, that if the code that follows the 
+@code{asm} statement makes no use of any of the output operands, the GCC 
+optimizers may discard the @code{asm} statement as unneeded 
+(see @ref{Volatile}).
+
+Remarks:
+
+The total number of input + output + goto operands has a limit of 30.
+
+@code{asm} supports operand modifiers on operands (for example @code{%k2} 
+instead of simply @code{%2}). Typically these qualifiers are hardware 
+dependent. The list of supported modifiers for i386 is found at 
+@ref{i386Operandmodifiers,i386 Operand modifiers}.
+
+Examples:
+
+In this example using the fictitious @code{combine} instruction, the 
+constraint @code{"0"} for input operand 1 says that it must occupy the same 
+location as output operand 0. Only input operands may use numbers in 
+constraints, and they must each refer to an output operand. Only a number (or 
+the symbolic assembler name) in the constraint can guarantee that one operand 
+is in the same place as another. The mere fact that @var{foo} is the value of 
+both operands is not enough to guarantee that they are in the same place in 
+the generated assembler code.
+
+@example
+asm ("combine %2, %0" 
+   : "=r" (foo) 
+   : "0" (foo), "g" (bar));
+@end example
+
+Here is an example using symbolic names.
+
+@example
+asm ("cmoveq %1, %2, %[result]" 
+   : [result] "=r"(result) 
+   : "r" (test), "r" (new), "[result]" (old));
+@end example
+
+@anchor{Clobbers}
+@subsubsection Clobbers
+@cindex @code{asm} clobbers
+
+While the compiler is aware of changes to entries listed in the output 
+operands, the assembler code may modify more than just the outputs. For 
+example, calculations may require additional registers, or the processor may 
+overwrite a register as a side effect of a particular assembler instruction. 
+In order to inform the compiler of these changes, list them in the clobber 
+list. Clobber list items are either register names or the special clobbers 
+(listed below). Each clobber list item is enclosed in double quotes and 
+separated by commas.
+
+Clobber descriptions may not in any way overlap with an input or output 
+operand. For example, you may not have an operand describing a register class 
+with one member when listing that register in the clobber list. Variables 
+declared to live in specific registers (@pxref{Explicit Reg Vars}), and used 
+as @code{asm} input or output operands, must have no part mentioned in the 
+clobber description. In particular, there is no way to specify that input 
+operands get modified without also specifying them as output operands.
+
+When the compiler selects which registers to use to represent input and output 
+operands, it will not use any of the clobbered registers. As a result, 
+clobbered registers are available for any use in the assembler code.
+
+Here is a realistic example for the VAX showing the use of clobbered 
+registers: 
+
+@example
+asm volatile ("movc3 %0, %1, %2"
+                   : /* No outputs. */
+                   : "g" (from), "g" (to), "g" (count)
+                   : "r0", "r1", "r2", "r3", "r4", "r5");
+@end example
+
+Also, there are two special clobber arguments:
+
+@enumerate
+@item
+The @code{"cc"} clobber indicates that the assembler code modifies the flags 
+register. On some machines, GCC represents the condition codes as a specific 
+hardware register; "cc" serves to name this register. On other machines, 
+condition code handling is different, and specifying "cc" has no effect. But 
+it is valid no matter what the machine.
+
+@item
+The "memory" clobber tells the compiler that the assembly code performs memory 
+reads or writes to items other than those listed in the input and output 
+operands (for example accessing the memory pointed to by one of the input 
+parameters). To ensure memory contains correct values, GCC may need to flush 
+specific register values to memory before executing the @code{asm}. Further, 
+the compiler will not assume that any values read from memory before an 
+@code{asm} will remain unchanged after that @code{asm}; it will reload them as 
+needed. This effectively forms a read/write memory barrier for the compiler.
+
+Note that this clobber does not prevent the @emph{processor} from doing 
+speculative reads past the @code{asm} statement. To prevent that, you need 
+processor-specific fence instructions.
+
+Flushing registers to memory has performance implications and may be an issue 
+for time-sensitive code. One trick to avoid this is available if the size of 
+the memory being accessed is known at compile time. For example, if accessing 
+ten bytes of a string, use a memory input like: 
+
+@code{@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}}.
+
+@end enumerate
+
+@anchor{GotoLabels}
+@subsubsection Goto Labels
+@cindex @code{asm} goto labels
+
+@code{asm goto} allows assembly code to jump to one or more C labels. The 
+GotoLabels section in an @code{asm goto} statement contains a comma-separated 
+list of all C labels to which the assembler code may jump. GCC assumes that 
+@code{asm} execution falls through to the next statement (if this is not the 
+case, consider using the @code{__builtin_unreachable} intrinsic after the 
+@code{asm} statement). The total number of input + output + goto operands has 
+a limit of 30.
+
+An @code{asm goto} statement can not have outputs (which means that the 
+statement is implicitly volatile). This is due to an internal restriction of 
+the compiler: control transfer instructions cannot have outputs. If the 
+assembler code does modify anything, use the "memory" clobber to force the 
+optimizers to flush all register values to memory, and reload them if 
+necessary, after the @code{asm} statement.
+
+To reference a label, prefix it with @code{%l} (that's a lowercase L) followed 
+by its (zero-based) position in GotoLabels plus the number of input 
+arguments.  For example, if the @code{asm} has three inputs and references two 
+labels, refer to the first label as @code{%l3} and the second as @code{%l4}).
+
+@code{asm} statements may not perform jumps into other @code{asm} statements. 
+GCC's optimizers do not know about these jumps; therefore they cannot take 
+account of them when deciding how to optimize.
+
+Example code for i386 might look like:
+
+@example
+asm goto (
+    "btl %1, %0\n\t"
+    "jc %l2"
+    : /* No outputs. */
+    : "r" (p1), "r" (p2) 
+    : "cc" 
+    : carry);
+
+return 0;
+
+carry:
+return 1;
+@end example
+
+The following example shows an @code{asm goto} that uses the memory clobber.
+
+@example
 int frob(int x)
 @{
   int y;
   asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
-            : : "r"(x), "r"(&y) : "r5", "memory" : error);
+            : /* No outputs. */
+            : "r"(x), "r"(&y)
+            : "r5", "memory" 
+            : error);
   return y;
- error:
+error:
   return -1;
 @}
-@end smallexample
+@end example
 
-@noindent
-In this (inefficient) example, the @code{frob} instruction sets the
-carry bit to indicate an error.  The @code{jc} instruction detects
-this and branches to the @code{error} label.  Finally, the output
-of the @code{frob} instruction (@code{%r5}) is stored into the memory
-for variable @code{y}, which is later read by the @code{return} statement.
+@anchor{i386Operandmodifiers}
+@subsubsection i386 Operand modifiers
 
-@smallexample
-void doit(void)
+Input, output, and goto operands for extended @code{asm} statements can use 
+modifiers to affect the code output to the assembler. For example, the 
+following code uses the "h" and "b" modifiers for i386:
+
+@example
+uint16_t  num;
+asm volatile ("xchg %h0, %b0" : "+a" (num) );
+@end example
+
+These modifiers generate this assembler code:
+
+@example
+xchg %ah, %al
+@end example
+
+The rest of this discussion uses the following code for illustrative purposes.
+
+@example
+int main()
 @{
-  int i = 0;
-  asm goto ("mfsr %%r1, 123; jmp %%r1;"
-            ".pushsection doit_table;"
-            ".long %l0, %l1, %l2, %l3;"
-            ".popsection"
-            : : : "r1" : label1, label2, label3, label4);
-  __builtin_unreachable ();
-
- label1:
-  f1();
-  return;
- label2:
-  f2();
-  return;
- label3:
-  i = 1;
- label4:
-  f3(i);
-@}
-@end smallexample
+   int iInt = 1;
 
-@noindent
-In this (also inefficient) example, the @code{mfsr} instruction reads
-an address from some out-of-band machine register, and the following
-@code{jmp} instruction branches to that address.  The address read by
-the @code{mfsr} instruction is assumed to have been previously set via
-some application-specific mechanism to be one of the four values stored
-in the @code{doit_table} section.  Finally, the @code{asm} is followed
-by a call to @code{__builtin_unreachable} to indicate that the @code{asm}
-does not in fact fall through.
-
-@smallexample
-#define TRACE1(NUM)                         \
-  do @{                                      \
-    asm goto ("0: nop;"                     \
-              ".pushsection trace_table;"   \
-              ".long 0b, %l0;"              \
-              ".popsection"                 \
-              : : : : trace#NUM);           \
-    if (0) @{ trace#NUM: trace(); @}          \
-  @} while (0)
-#define TRACE  TRACE1(__COUNTER__)
-@end smallexample
+top:
 
-@noindent
-In this example (which in fact inspired the @code{asm goto} feature)
-we want on rare occasions to call the @code{trace} function; on other
-occasions we'd like to keep the overhead to the absolute minimum.
-The normal code path consists of a single @code{nop} instruction.
-However, we record the address of this @code{nop} together with the
-address of a label that calls the @code{trace} function.  This allows
-the @code{nop} instruction to be patched at run time to be an
-unconditional branch to the stored label.  It is assumed that an
-optimizing compiler moves the labeled block out of line, to
-optimize the fall through path from the @code{asm}.
-
-If you are writing a header file that should be includable in ISO C
-programs, write @code{__asm__} instead of @code{asm}.  @xref{Alternate
-Keywords}.
+   asm volatile goto ("some assembler instructions here"
+   : /* No outputs. */
+   : "q" (iInt), "X" (sizeof(unsigned char) + 1)
+   : /* No clobbers. */
+   : top);
+@}
+@end example
 
-@subsection Size of an @code{asm}
+With no modifiers, this is what the output from the operands would be for the 
+att and intel dialects of assembler:
+
+@multitable {Operand} {masm=att} {OFFSET FLAT:.L2}
+@headitem Operand @tab masm=att @tab masm=intel
+@item @code{%0}
+@tab @code{%eax}
+@tab @code{eax}
+@item @code{%1}
+@tab @code{$2}
+@tab @code{2}
+@item @code{%2}
+@tab @code{$.L2}
+@tab @code{OFFSET FLAT:.L2}
+@end multitable
 
-Some targets require that GCC track the size of each instruction used in
-order to generate correct code.  Because the final length of an
-@code{asm} is only known by the assembler, GCC must make an estimate as
-to how big it will be.  The estimate is formed by counting the number of
-statements in the pattern of the @code{asm} and multiplying that by the
-length of the longest instruction on that processor.  Statements in the
-@code{asm} are identified by newline characters and whatever statement
-separator characters are supported by the assembler; on most processors
-this is the @samp{;} character.
-
-Normally, GCC's estimate is perfectly adequate to ensure that correct
-code is generated, but it is possible to confuse the compiler if you use
-pseudo instructions or assembler macros that expand into multiple real
-instructions or if you use assembler directives that expand to more
-space in the object file than is needed for a single instruction.
-If this happens then the assembler produces a diagnostic saying that
-a label is unreachable.
+The table below shows the list of supported modifiers and their effects.
+
+@multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {masm=att} {masm=intel}
+@headitem Modifier @tab Description @tab Operand @tab @option{masm=att} @tab @option{masm=intel}
+@item @code{z}
+@tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
+@tab @code{%z0}
+@tab @code{l}
+@tab 
+@item @code{b}
+@tab Print the QImode name of the register.
+@tab @code{%b0}
+@tab @code{%al}
+@tab @code{al}
+@item @code{h}
+@tab Print the QImode name for a ``high'' register.
+@tab @code{%h0}
+@tab @code{%ah}
+@tab @code{ah}
+@item @code{w}
+@tab Print the HImode name of the register.
+@tab @code{%w0}
+@tab @code{%ax}
+@tab @code{ax}
+@item @code{k}
+@tab Print the SImode name of the register.
+@tab @code{%k0}
+@tab @code{%eax}
+@tab @code{eax}
+@item @code{q}
+@tab Print the DImode name of the register.
+@tab @code{%q0}
+@tab @code{%rax}
+@tab @code{rax}
+@item @code{l}
+@tab Print the label name with no punctuation.
+@tab @code{%l2}
+@tab @code{.L2}
+@tab @code{.L2}
+@item @code{c}
+@tab Require a constant operand and print the constant expression with no punctuation.
+@tab @code{%c1}
+@tab @code{2}
+@tab @code{2}
+@end multitable
 
-@subsection i386 floating-point asm operands
+@anchor{i386floatingpointasmoperands}
+@subsubsection i386 floating-point asm operands
 
 On i386 targets, there are several rules on the usage of stack-like registers
 in the operands of an @code{asm}.  These rules apply only to the operands
@@ -6715,10 +7168,34 @@ for the compiler to know that @code{fyl2xp1} pops both inputs.
 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
 @end smallexample
 
+@lowersections
 @include md.texi
+@raisesections
+
+@node Size of an asm
+@subsection Size of an @code{asm}
+
+Some targets require that GCC track the size of each instruction used
+in order to generate correct code.  Because the final length of the
+code produced by an @code{asm} statement is only known by the
+assembler, GCC must make an estimate as to how big it will be.  It
+does this by counting the number of instructions in the pattern of the
+@code{asm} and multiplying that by the length of the longest
+instruction supported by that processor.  (When working out the number
+of instructions, it assumes that any occurrence of a newline or of
+whatever statement separator character is supported by the assembler --
+typically @samp{;} --- indicates the end of an instruction.)
+
+Normally, GCC's estimate is adequate to ensure that correct
+code is generated, but it is possible to confuse the compiler if you use
+pseudo instructions or assembler macros that expand into multiple real
+instructions, or if you use assembler directives that expand to more
+space in the object file than is needed for a single instruction.
+If this happens then the assembler may produce a diagnostic saying that
+a label is unreachable.
 
 @node Asm Labels
-@section Controlling Names Used in Assembler Code
+@subsection Controlling Names Used in Assembler Code
 @cindex assembler names for identifiers
 @cindex names used in assembler code
 @cindex identifiers, names in assembler code
@@ -6766,7 +7243,7 @@ does not as yet have the ability to store static variables in registers.
 Perhaps that will be added.
 
 @node Explicit Reg Vars
-@section Variables in Specified Registers
+@subsection Variables in Specified Registers
 @cindex explicit register variables
 @cindex variables in specified registers
 @cindex specified registers
@@ -6806,7 +7283,7 @@ specified for that operand in the @code{asm}.)
 @end menu
 
 @node Global Reg Vars
-@subsection Defining Global Register Variables
+@subsubsection Defining Global Register Variables
 @cindex global register variables
 @cindex registers, global variables in
 
@@ -6903,7 +7380,7 @@ On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7.
 Of course, it does not do to use more than a few of those.
 
 @node Local Reg Vars
-@subsection Specifying Registers for Local Variables
+@subsubsection Specifying Registers for Local Variables
 @cindex local variables, specifying registers
 @cindex specifying registers for local variables
 @cindex registers for local variables
@@ -6946,21 +7423,37 @@ Stores into local register variables may be deleted when they appear to be dead
 according to dataflow analysis.  References to local register variables may
 be deleted or moved or simplified.
 
-As for global register variables, it's recommended that you choose a
+As with global register variables, it is recommended that you choose a
 register that is normally saved and restored by function calls on
-your machine, so that library routines will not clobber it.  A common
-pitfall is to initialize multiple call-clobbered registers with
-arbitrary expressions, where a function call or library call for an
-arithmetic operator overwrites a register value from a previous
-assignment, for example @code{r0} below:
+your machine, so that library routines will not clobber it.  
+
+Sometimes when writing inline @code{asm} code, you need to make an operand be a 
+specific register, but there's no matching constraint letter for that 
+register. To force the operand into that register, create a local variable 
+and specify the register in the variable's declaration. Then use the local 
+variable for the asm operand and specify any constraint letter that matches 
+the register:
+
 @smallexample
 register int *p1 asm ("r0") = @dots{};
 register int *p2 asm ("r1") = @dots{};
+register int *result asm ("r0");
+asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
 @end smallexample
 
-@noindent
-In those cases, a solution is to use a temporary variable for
-each arbitrary expression.   @xref{Example of asm with clobbered asm reg}.
+@emph{Warning:} In the above example, be aware that a register (for example r0) can be 
+call-clobbered by subsequent code, including function calls and library calls 
+for arithmetic operators on other variables (for example the initialization 
+of p2). In this case, use temporary variables for expressions between the 
+register assignments:
+
+@smallexample
+int t1 = @dots{};
+register int *p1 asm ("r0") = @dots{};
+register int *p2 asm ("r1") = t1;
+register int *result asm ("r0");
+asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
+@end smallexample
 
 @node Alternate Keywords
 @section Alternate Keywords