* [DOC PATCH] Rewrite docs for inline asm
@ 2014-04-04 19:48 dw
2014-04-08 23:17 ` Hans-Peter Nilsson
2016-06-17 14:54 ` Andrew Haley
0 siblings, 2 replies; 30+ messages in thread
From: dw @ 2014-04-04 19:48 UTC (permalink / raw)
To: gcc-patches; +Cc: Andrew Haley, rdsandiford
[-- Attachment #1: Type: text/plain, Size: 839 bytes --]
I do not have write permissions to check this patch in.
Problem description:
The existing documentation does an inadequate job of describing gcc's
implementation of the "asm" keyword. This has led to a great deal of
confusion as people struggle to understand how it works. This entire
section requires a rewrite that provides a structured layout and
detailed descriptions of each of the parameters along with examples.
ChangeLog:
2014-04-03 David Wohlferd (LimeGreenSocks@yahoo.com)
Andrew Haley (aph@redhat.com)
Richard Sandiford (rdsandiford@googlemail.com)
* extend.texi: Completely rewrite inline asm section / minor
reorg of asm-related sections
Bootstrapping and testing:
I have tested "make html" to produce html files, but my configuration
doesn't allow for the "make dvi" test.
dw
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: extend.texi.patch --]
[-- Type: text/x-patch; name="extend.texi.patch", Size: 60883 bytes --]
Index: extend.texi
===================================================================
--- extend.texi (revision 208978)
+++ extend.texi (working copy)
@@ -65,11 +65,8 @@
* 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.)
+* Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
* 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.
* 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
@@ -5967,7 +5964,7 @@
@}
@end smallexample
-If you are writing a header file to be included in ISO C90 programs, write
+If you are writing a header file that may be included in ISO C90 programs, write
@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
The three types of inlining behave similarly in two important cases:
@@ -6137,492 +6134,818 @@
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.
+* 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 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. The GCC compiler 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 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. If certain instructions
+need to remain consecutive in the output, put them in a single multi-instruction asm statement. Note that GCC's optimizer
+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's optimizer 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 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 asm code as part of optimization. This can lead to
+unexpected duplicate symbol errors during compilation if symbols or labels are being used.
+
+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 those symbols
+getting discarded by GCC as unreferenced.
+
+While Basic @code{asm} blocks are implicitly volatile, they 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 include 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
+asm [volatile] ( AssemblerTemplate : [OutputOperands] : [InputOperands] : [Clobbers])
-For example, here is how to use the 68881's @code{fsinx} instruction:
+asm [volatile] goto ( AssemblerTemplate : : [InputOperands] : [Clobbers] : GotoLabels)
+@end example
-@smallexample
-asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
-@end smallexample
+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}.
-@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}).
+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}.)
-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@.
+@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}.
-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.
+@emph{goto}
+@*
+This qualifier informs the compiler that the @code{asm} statement may include a jump to one of the labels listed
+in the GotoLabels section. @xref{GotoLabels}.
-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:
+@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}.
-@smallexample
-asm ("fsinx %[angle],%[output]"
- : [output] "=f" (result)
- : [angle] "f" (angle));
-@end smallexample
+@emph{OutputOperands}
+@*
+A comma-separated list of the C variables modified by the instructions in the AssemblerTemplate. @xref{OutputOperands}.
-@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.
+@emph{InputOperands}
+@*
+A comma-separated list of C expressions read by the instructions in the AssemblerTemplate. @xref{InputOperands}.
-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.
+@emph{Clobbers}
+@*
+A comma-separated list of registers or other values changed by the AssemblerTemplate, beyond those
+listed as outputs. @xref{Clobbers}.
-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.
+@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}.
-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:
+@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.
-@smallexample
-asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
-@end smallexample
+Note that Extended @code{asm} statements must be inside a function. Only Basic @code{asm} may be outside
+functions (@pxref{Basic Asm}).
-@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.
+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:
-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:
+@example
+int src = 1;
+int dst;
-@smallexample
-asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
-@end smallexample
+asm ("mov %1, %0\n\t"
+ "add $1, %0"
+ : "=r" (dst)
+ : "r" (src));
-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.
+printf("%d\n", dst);
+@end example
-As of GCC version 3.1, one may write @code{[@var{name}]} instead of
-the operand number for a matching constraint. For example:
+This code will copy @var{src} to @var{dst} and add 1 to @var{dst}.
-@smallexample
-asm ("cmoveq %1,%2,%[result]"
- : [result] "=r"(result)
- : "r" (test), "r"(new), "[result]"(old));
-@end smallexample
+@anchor{Volatile}
+@subsubsection Volatile
+@cindex volatile @code{asm}
+@cindex @code{asm} volatile
-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:
+GCC's optimizer sometimes discards @code{asm} statements if it determines that it has no need for the output
+variables. Also, the optimizer may move code out of loops if it believes 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.
-@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
+Examples:
-@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:
+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 optimizer 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 optimizer to produce the most efficient code possible.
-@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 DoCheck(uint32_t dwSomeValue)
+@{
+ uint32_t dwRes;
-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:
+ // Assumes dwSomeValue is not zero
+ asm ("bsfl %1,%0"
+ : "=r" (dwRes)
+ : "r" (dwSomeValue)
+ : "cc");
-@smallexample
-asm volatile ("movc3 %0,%1,%2"
- : /* @r{no outputs} */
- : "g" (from), "g" (to), "g" (count)
- : "r0", "r1", "r2", "r3", "r4", "r5");
-@end smallexample
+ assert(dwRes > 3);
+@}
+@end example
-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.
+The next example shows a case where the optimizer 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.
-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.
+@example
+void do_print(uint32_t dwSomeValue)
+@{
+ uint32_t dwRes;
-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.
+ for (uint32_t x=0; x < 5; x++)
+ @{
+ // Assumes dwSomeValue is not zero
+ asm ("bsfl %1,%0"
+ : "=r" (dwRes)
+ : "r" (dwSomeValue)
+ : "cc");
-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:
+ printf("%u: %u %u\n", x, dwSomeValue, dwRes);
+ @}
+@}
+@end example
-@smallexample
-@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}.
-@end smallexample
+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 optimizer
+might assume that the @code{asm} block will always return the same value and therefore
+optimize away the second call.
-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
+@example
+uint64_t msr;
-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:
+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
-asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo"
- : /* no outputs */
- : "g" (from), "g" (to)
- : "r9", "r10");
-@end smallexample
+printf("msr: %llx\n", msr);
-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}.
+// Do other work...
-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:
+// 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
-asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
- : "g" (result)
- : "g" (input));
-@end smallexample
+printf("msr: %llx\n", msr);
+@end example
-@noindent
-This assumes your assembler supports local labels, as the GNU assembler
-and most Unix assemblers do.
+GCC's optimizer will not treat this code like the non-volatile code in the earlier examples.
+It does not move it out of loops or omit it on the assumption that
+the result from a previous call is still valid.
-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}.
+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.
-@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,
+@example
+asm volatile("mtfsf 255, %0" : : "f" (fpenv));
+sum = x + y;
+@end example
-@smallexample
-#define sin(x) \
-(@{ double __value, __arg = (x); \
- asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
- __value; @})
-@end smallexample
+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:
-@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}.
+@example
+asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
+sum = x + y;
+@end example
-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.
+Under certain circumstances, GCC may duplicate (or remove duplicates of) your asm code as part of optimization. This
+can lead to unexpected duplicate symbol errors during compilation if symbols or labels are being used. Using %=
+(@pxref{AssemblerTemplate}) may help resolve this problem.
-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.
+@anchor{AssemblerTemplate}
+@subsubsection Assembler Template
+@cindex @code{asm} assembler template
-You can prevent an @code{asm} instruction from being deleted
-by writing the keyword @code{volatile} after
-the @code{asm}. For example:
+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.
+The GCC compiler does not parse the assembler instructions themselves
+and does not know what they mean or even whether they are valid assembler input.
-@smallexample
-#define get_and_set_priority(new) \
-(@{ int __old; \
- asm volatile ("get_and_set_priority %0, %1" \
- : "=g" (__old) : "g" (new)); \
- __old; @})
-@end smallexample
+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.
-@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:
+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.
-@smallexample
- asm volatile("mtfsf 255,%0" : : "f" (fpenv));
- sum = x + y;
-@end smallexample
+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.
-@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:
+Since GCC does not parse the AssemblerTemplate, it has no visibility of any symbols it references. This may result in those symbols
+getting discarded by GCC as unreferenced unless they are also listed as input, output, or goto operands.
-@smallexample
- asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv));
- sum = x + y;
-@end smallexample
+GCC may support multiple assembler dialects (such as "att" or "intel") for inline assembler. The list of supported dialects
+depends on the implementation details of the specific build of the compiler. When writing assembler,
+be aware of which dialect is the compiler's default. Assembler code that works correctly when compiled using
+one dialect will likely fail if compiled using another. The @option{-masm} option changes the dialect that GCC uses in builds that support
+multiple dialects.
-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.
+@subsubheading Using braces in @code{asm} templates
-An @code{asm} instruction without any output operands is treated
-identically to a volatile @code{asm} instruction.
+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:
-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.
+@example
+'@{dialect0|dialect1|dialect2...@}'
+@end example
-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.
+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.
-@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.
+For example, if an i386 compiler supports two dialects (att, intel), an assembler template such as this:
-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.
+@example
+"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
+@end example
-@smallexample
+would produce the output:
+
+@example
+For att: "btl %[Offset],%[Base] ; jc %l2"
+For intel: "bt %[Base],%[Offset]; jc %l2"
+@end example
+
+Using that same compiler, this code:
+
+@example
+"xchg@{l@}\t@{%%@}ebx, %1"
+@end example
+
+would produce
+
+@example
+For att: "xchgl\t%%ebx, %1"
+For intel: "xchg\tebx, %1"
+@end example
+
+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.
+
+@subsubheading Other format strings
+
+In addition to the tokens described by the input, output, and goto operands, there are a few special cases:
+
+@itemize
+@item
+'%%' outputs a '%' into the assembler code.
+
+@item
+'%=' outputs a number that is unique to each instance of the 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.
+
+@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 assembler statement
+may use the same symbolic name.
+
+@emph{constraint}
+@*
+Output constraints must begin with either "=" (a variable overwriting an existing value) or "+" (when reading and
+writing). When using "=",
+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 "r" for register, "m" for memory, and "i" for immediate.
+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 optimizer to produce the best possible code.
+
+@emph{cvariablename}
+@*
+Specifies the C variable name of the output (enclosed by parenthesis). 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 optimizer 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.
+
+@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 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 "+".
+
+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 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 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 optimizer 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 "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 asm. Further, the compiler will not assume that any values read from memory before the
+@code{asm} will remain unchanged after the @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 stop 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 may not have outputs (which means that the statement is implicitly volatile). This is due to
+an internal restriction in the compiler: that control transfer instructions cannot have outputs. If the
+assembler code does modify anything, use the "memory" clobber to force the optimizer 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} followed by a number. This number is zero-based and includes
+any 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)
-@{
- 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 ();
+Input, output, and goto operands for extended @code{asm} can use modifiers to affect the
+code output to the assembler. For example, the following code uses the 'h' and 'b' modifiers for i386:
- label1:
- f1();
- return;
- label2:
- f2();
- return;
- label3:
- i = 1;
- label4:
- f3(i);
-@}
-@end smallexample
+@example
+uint16_t num;
+asm volatile ("xchg %h0, %b0" : "+a" (num) );
+@end example
-@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.
+These modifiers generate this assembler code:
-@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
+@example
+xchg %ah, %al
+@end example
-@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}.
+The rest of this discussion uses the following code for illustrative purposes.
-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}.
+@example
+int main()
+@{
+ int iInt = 1;
-@subsection Size of an @code{asm}
+top:
-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.
+ asm volatile goto ("some assembler instructions here"
+ : /* no outputs */
+ : "q" (iInt), "X" (sizeof(unsigned char) + 1)
+ : /* no clobbers */
+ : top);
+@}
+@end example
-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.
+With no modifiers, this is what the output from the operands would be for the att and intel dialects of assembler:
-@subsection i386 floating-point asm operands
+@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
+The table below shows the list of supported modifiers and their effects.
+
+@multitable {Modifier} {Print the opcode suffix for the size of the current integer operand (one of b/w/l/q).} {Operand} {masm=att} {masm=intel}
+@headitem Modifier @tab Description @tab Operand @tab masm=att @tab masm=intel
+@item @code{z}
+@tab Print the opcode suffix for the size of the current integer operand (one of b/w/l/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
+
+@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
that are stack-like registers:
@@ -6715,10 +7038,30 @@
asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
@end smallexample
-@include md.texi
+@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 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.
+
@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 +7109,7 @@
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 +7149,7 @@
@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 +7246,7 @@
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
@@ -6960,8 +7303,10 @@
@noindent
In those cases, a solution is to use a temporary variable for
-each arbitrary expression. @xref{Example of asm with clobbered asm reg}.
+each arbitrary expression.
+@include md.texi
+
@node Alternate Keywords
@section Alternate Keywords
@cindex alternate keywords
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-04 19:48 [DOC PATCH] Rewrite docs for inline asm dw
@ 2014-04-08 23:17 ` Hans-Peter Nilsson
2014-04-09 5:02 ` Michael Matz
2014-04-09 5:29 ` dw
2016-06-17 14:54 ` Andrew Haley
1 sibling, 2 replies; 30+ messages in thread
From: Hans-Peter Nilsson @ 2014-04-08 23:17 UTC (permalink / raw)
To: dw; +Cc: gcc-patches
On Fri, 4 Apr 2014, dw wrote:
> Problem description:
> The existing documentation does an inadequate job of describing gcc's
> implementation of the "asm" keyword. This has led to a great deal of
> confusion as people struggle to understand how it works. This entire section
> requires a rewrite that provides a structured layout and detailed descriptions
> of each of the parameters along with examples.
>
> ChangeLog:
> 2014-04-03 David Wohlferd (LimeGreenSocks@yahoo.com)
> Andrew Haley (aph@redhat.com)
> Richard Sandiford (rdsandiford@googlemail.com)
>
> * extend.texi: Completely rewrite inline asm section / minor reorg
> of asm-related sections
(No other feedback since friday?)
Thanks for doing this!
There are some *minor* issues, like two-spaces-after-"." which
(IIRC) makes a semantic difference in texinfo, and missing use
of texinfo markup like @emph{not} instead of NOT. Also, in the
ChangeLog is the first of many overly long lines. Please keep
lines shorter than 80 chars like the rest of extend.texi,
somewhere between 70-79 chars? Also, code snippets in texinfo
should use GNU formatting, including comments (full sentences
with capitalization and full stop).
Also,
+ : [d] "=rm" (d)
+ : [e] "rm" (*e)
+ : );
That last bit, the ": )" (empty last operand part) shouldn't be
in the documentation. I'm not even sure it *should* work
(apparently it does, perhaps by accident).
The general bits seems like a big improvement, but what worries
me is the deleted text. For example, the aspects of "Explicit
Reg Vars" when *directly feeding an asm* and how to write them
to avoid the named registers being call-clobbered between
assignment and the asm. (Don't confuse this with the
asm-clobber operands which I think you covered fine.) Those
details are maybe not thoughtfully described, but they can't be
just plainly removed as they also serve as gcc specification;
definitions as to what works and doesn't work! (I don't know if
that was the only occurrence.)
Also, do we really want to document the trick in
"m" ((@{ struct @{ char x[10]; @} *p = (void *) ptr ; *p; @}))
(note: reformatted GNU-style and confusing @{ @} dropped)
IIRC this is from Linux, but I don't think GCC ever promised the
described semantics, and I don't think we should document
something that works just by accident. Do we want to make that
promise now?
> Bootstrapping and testing:
> I have tested "make html" to produce html files, but my configuration doesn't
> allow for the "make dvi" test.
That requirement is somewhat arcane but maybe "make pdf" would
work for you? (Though may or may not use dvi as an intermediate
step.) The point is to verify the layout; what goes into the
info files is often different to what goes into the printable
format.
brgds, H-P
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-08 23:17 ` Hans-Peter Nilsson
@ 2014-04-09 5:02 ` Michael Matz
2014-04-09 5:29 ` dw
1 sibling, 0 replies; 30+ messages in thread
From: Michael Matz @ 2014-04-09 5:02 UTC (permalink / raw)
To: Hans-Peter Nilsson; +Cc: dw, gcc-patches
Hi,
On Tue, 8 Apr 2014, Hans-Peter Nilsson wrote:
> Also, do we really want to document the trick in
> "m" ((@{ struct @{ char x[10]; @} *p = (void *) ptr ; *p; @}))
> (note: reformatted GNU-style and confusing @{ @} dropped)
We already document this since quite some time, and yes, it's indeed
supposed to work, and not by accident :)
Ciao,
Michael.
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-08 23:17 ` Hans-Peter Nilsson
2014-04-09 5:02 ` Michael Matz
@ 2014-04-09 5:29 ` dw
2014-04-10 21:44 ` dw
2014-04-13 1:47 ` Hans-Peter Nilsson
1 sibling, 2 replies; 30+ messages in thread
From: dw @ 2014-04-09 5:29 UTC (permalink / raw)
To: Hans-Peter Nilsson; +Cc: gcc-patches
[-- Attachment #1: Type: text/plain, Size: 5438 bytes --]
On 4/8/2014 4:17 PM, Hans-Peter Nilsson wrote:
> On Fri, 4 Apr 2014, dw wrote:
>> Problem description:
>> The existing documentation does an inadequate job of describing gcc's
>> implementation of the "asm" keyword. This has led to a great deal of
>> confusion as people struggle to understand how it works. This entire section
>> requires a rewrite that provides a structured layout and detailed descriptions
>> of each of the parameters along with examples.
>>
>> ChangeLog:
>> 2014-04-03 David Wohlferd (LimeGreenSocks@yahoo.com)
>> Andrew Haley (aph@redhat.com)
>> Richard Sandiford (rdsandiford@googlemail.com)
>>
>> * extend.texi: Completely rewrite inline asm section / minor reorg
>> of asm-related sections
> (No other feedback since friday?)
Most people who had input probably responded in the RFD on the GCC list
(http://gcc.gnu.org/ml/gcc/2014-02/msg00511.html).
I haven't heard from the doc maintainers yet, but I understand that at
least one of them is out of town.
> Thanks for doing this!
Thank you for the response and the feedback.
> There are some *minor* issues, like two-spaces-after-"." which
> (IIRC) makes a semantic difference in texinfo,
I wasn't aware this was a thing. All those years of typing classes make
this habit hard to break. Doing a search, it appears my changes aren't
the only place in extend.texi that does this. I've fixed mine.
> and missing use
> of texinfo markup like @emph{not} instead of NOT.
Hmm. If this is a standards thing, I suppose I should. Looks like I
only did it twice (and both in the same paragraph). Fixed.
> Also, in the
> ChangeLog is the first of many overly long lines. Please keep
> lines shorter than 80 chars like the rest of extend.texi,
> somewhere between 70-79 chars?
Sorry. Again, I didn't know this was a thing. texinfo doesn't seem to
mind, and the html pages I was generating didn't seem to care either.
I've fixed most of this. There are a couple of places I need someone
who is better at texinfo/formatting to help me out.
> Also, code snippets in texinfo
> should use GNU formatting, including comments (full sentences
> with capitalization and full stop).
I've fixed up the things I can see, but I'm no expert in GNU
formatting. If there's more, I'll need someone to tell me what is needed.
> Also,
>
> + : [d] "=rm" (d)
> + : [e] "rm" (*e)
> + : );
>
> That last bit, the ": )" (empty last operand part) shouldn't be
> in the documentation. I'm not even sure it *should* work
> (apparently it does, perhaps by accident).
I'd be tempted to debate this one, but I think I'm just going to change
it instead. Worms, cans, fixed.
> The general bits seems like a big improvement, but what worries
> me is the deleted text. For example, the aspects of "Explicit
> Reg Vars" when *directly feeding an asm* and how to write them
> to avoid the named registers being call-clobbered between
> assignment and the asm. (Don't confuse this with the
> asm-clobber operands which I think you covered fine.) Those
> details are maybe not thoughtfully described, but they can't be
> just plainly removed as they also serve as gcc specification;
> definitions as to what works and doesn't work! (I don't know if
> that was the only occurrence.)
I don't believe that section you are talking about was actually deleted,
but has instead been moved (along with "Asm Labels" and "Size of an
asm"). Looking at the new docs, instead of those sections being buried
with the ~60 other items like in the old docs
(http://gcc.gnu.org/onlinedocs/gcc-4.8.0/gcc/C-Extensions.html),
(nearly) all the asm-related subjects got moved here
(http://www.LimeGreenSocks.com/gcc/Using-Assembly-Language-with-C.html).
That's what the "minor reorg of asm-related sections" was about.
> Also, do we really want to document the trick in
> "m" ((@{ struct @{ char x[10]; @} *p = (void *) ptr ; *p; @}))
> (note: reformatted GNU-style and confusing @{ @} dropped)
> IIRC this is from Linux, but I don't think GCC ever promised the
> described semantics, and I don't think we should document
> something that works just by accident. Do we want to make that
> promise now?
I got that trick (formatting and all) from the existing docs. Such
being the case, the question is do we want to @emph{stop} promising
something that we used to? I have no preference here, other than the
general desire to maintain backward compatibility. I have not yet made
any change here.
>
>> Bootstrapping and testing:
>> I have tested "make html" to produce html files, but my configuration doesn't
>> allow for the "make dvi" test.
> That requirement is somewhat arcane
I got it off the contrib page
(http://gcc.gnu.org/contribute.html#docchanges) when I was trying to
figure out the "proper" way to submit this. If this is no longer a
requirement, perhaps this should be updated.
> but maybe "make pdf" would
> work for you? (Though may or may not use dvi as an intermediate
> step.) The point is to verify the layout; what goes into the
> info files is often different to what goes into the printable
> format.
I can try again to get this working. I was hoping "make html" would
cover most of it. With luck, "make dvi" would have shown nothing new.
I was focusing on the text since I figured there were likely plenty of
people with correctly functioning build environments to give this bit a
test.
dw
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: extend.texi.patch --]
[-- Type: text/x-patch; name="extend.texi.patch", Size: 61006 bytes --]
Index: extend.texi
===================================================================
--- extend.texi (revision 209222)
+++ extend.texi (working copy)
@@ -65,11 +65,8 @@
* 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.)
+* Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
* 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.
* 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
@@ -5967,7 +5964,7 @@
@}
@end smallexample
-If you are writing a header file to be included in ISO C90 programs, write
+If you are writing a header file that may be included in ISO C90 programs, write
@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
The three types of inlining behave similarly in two important cases:
@@ -6137,492 +6134,925 @@
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.
+* 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 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.
+The GCC compiler 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 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. If certain instructions need to remain
+consecutive in the output, put them in a single multi-instruction asm
+statement. Note that GCC's optimizer 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's optimizer 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 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
+asm code as part of optimization. This can lead to unexpected duplicate
+symbol errors during compilation if your asm 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 those symbols getting discarded
+by GCC as unreferenced.
+
+While Basic @code{asm} blocks are implicitly volatile, they 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 include 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
+asm [volatile] ( AssemblerTemplate : [OutputOperands] : [InputOperands] : [Clobbers])
-For example, here is how to use the 68881's @code{fsinx} instruction:
+asm [volatile] goto ( AssemblerTemplate : : [InputOperands] : [Clobbers] : GotoLabels)
+@end example
-@smallexample
-asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
-@end smallexample
+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}.
-@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}).
+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}.)
-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@.
+@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}.
-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.
+@emph{goto}
+@*
+This qualifier informs the compiler that the @code{asm} statement may
+include a jump to one of the labels listed in the GotoLabels section.
+@xref{GotoLabels}.
-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:
+@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}.
-@smallexample
-asm ("fsinx %[angle],%[output]"
- : [output] "=f" (result)
- : [angle] "f" (angle));
-@end smallexample
+@emph{OutputOperands}
+@*
+A comma-separated list of the C variables modified by the instructions in the
+AssemblerTemplate. @xref{OutputOperands}.
-@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.
+@emph{InputOperands}
+@*
+A comma-separated list of C expressions read by the instructions in the
+AssemblerTemplate. @xref{InputOperands}.
-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.
+@emph{Clobbers}
+@*
+A comma-separated list of registers or other values changed by the
+AssemblerTemplate, beyond those listed as outputs. @xref{Clobbers}.
-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.
+@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}.
-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:
+@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.
-@smallexample
-asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
-@end smallexample
+Note that Extended @code{asm} statements must be inside a function. Only
+Basic @code{asm} may be outside functions (@pxref{Basic Asm}).
-@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.
+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:
-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:
+@example
+int src = 1;
+int dst;
-@smallexample
-asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
-@end smallexample
+asm ("mov %1, %0\n\t"
+ "add $1, %0"
+ : "=r" (dst)
+ : "r" (src));
-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.
+printf("%d\n", dst);
+@end example
-As of GCC version 3.1, one may write @code{[@var{name}]} instead of
-the operand number for a matching constraint. For example:
+This code will copy @var{src} to @var{dst} and add 1 to @var{dst}.
-@smallexample
-asm ("cmoveq %1,%2,%[result]"
- : [result] "=r"(result)
- : "r" (test), "r"(new), "[result]"(old));
-@end smallexample
+@anchor{Volatile}
+@subsubsection Volatile
+@cindex volatile @code{asm}
+@cindex @code{asm} volatile
-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:
+GCC's optimizer sometimes discards @code{asm} statements if it determines
+that it has no need for the output variables. Also, the optimizer may move
+code out of loops if it believes 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.
-@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
+Examples:
-@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:
+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 optimizer 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 optimizer to produce the most efficient code
+possible.
-@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 DoCheck(uint32_t dwSomeValue)
+@{
+ uint32_t dwRes;
-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:
+ // Assumes dwSomeValue is not zero.
+ asm ("bsfl %1,%0"
+ : "=r" (dwRes)
+ : "r" (dwSomeValue)
+ : "cc");
-@smallexample
-asm volatile ("movc3 %0,%1,%2"
- : /* @r{no outputs} */
- : "g" (from), "g" (to), "g" (count)
- : "r0", "r1", "r2", "r3", "r4", "r5");
-@end smallexample
+ assert(dwRes > 3);
+@}
+@end example
-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.
+The next example shows a case where the optimizer 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.
-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.
+@example
+void do_print(uint32_t dwSomeValue)
+@{
+ uint32_t dwRes;
-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.
+ for (uint32_t x=0; x < 5; x++)
+ @{
+ // Assumes dwSomeValue is not zero.
+ asm ("bsfl %1,%0"
+ : "=r" (dwRes)
+ : "r" (dwSomeValue)
+ : "cc");
-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:
+ printf("%u: %u %u\n", x, dwSomeValue, dwRes);
+ @}
+@}
+@end example
-@smallexample
-@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}.
-@end smallexample
+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 optimizer might assume that the @code{asm} block will always return the
+same value and therefore optimize away the second call.
-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
+@example
+uint64_t msr;
-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:
+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
-asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo"
- : /* no outputs */
- : "g" (from), "g" (to)
- : "r9", "r10");
-@end smallexample
+printf("msr: %llx\n", msr);
-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}.
+// Do other work...
-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:
+// 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
-asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
- : "g" (result)
- : "g" (input));
-@end smallexample
+printf("msr: %llx\n", msr);
+@end example
-@noindent
-This assumes your assembler supports local labels, as the GNU assembler
-and most Unix assemblers do.
+GCC's optimizer will not treat this code like the non-volatile code in the
+earlier examples. It does not move it out of loops or omit it on the
+assumption that the result from a previous call is still valid.
-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}.
+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.
-@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,
+@example
+asm volatile("mtfsf 255, %0" : : "f" (fpenv));
+sum = x + y;
+@end example
-@smallexample
-#define sin(x) \
-(@{ double __value, __arg = (x); \
- asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
- __value; @})
-@end smallexample
+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:
-@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}.
+@example
+asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
+sum = x + y;
+@end example
-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.
+Under certain circumstances, GCC may duplicate (or remove duplicates of) your
+asm code as part of optimization. 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.
-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.
+@anchor{AssemblerTemplate}
+@subsubsection Assembler Template
+@cindex @code{asm} assembler template
-You can prevent an @code{asm} instruction from being deleted
-by writing the keyword @code{volatile} after
-the @code{asm}. For example:
+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. The GCC compiler does not parse the assembler instructions
+themselves and does not know what they mean or even whether they are valid
+assembler input.
-@smallexample
-#define get_and_set_priority(new) \
-(@{ int __old; \
- asm volatile ("get_and_set_priority %0, %1" \
- : "=g" (__old) : "g" (new)); \
- __old; @})
-@end smallexample
+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.
-@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:
+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.
-@smallexample
- asm volatile("mtfsf 255,%0" : : "f" (fpenv));
- sum = x + y;
-@end smallexample
+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.
-@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:
+Since GCC does not parse the AssemblerTemplate, it has no visibility of any
+symbols it references. This may result in those symbols getting discarded by
+GCC as unreferenced unless they are also listed as input, output, or goto
+operands.
-@smallexample
- asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv));
- sum = x + y;
-@end smallexample
+GCC may support multiple assembler dialects (such as "att" or "intel") for
+inline assembler. The list of supported dialects depends on the implementation
+details of the specific build of the compiler. When writing assembler, be
+aware of which dialect is the compiler's default. Assembler code that works
+correctly when compiled using one dialect will likely fail if compiled using
+another. The @option{-masm} option changes the dialect that GCC uses in builds
+that support multiple dialects.
-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.
+@subsubheading Using braces in @code{asm} templates
-An @code{asm} instruction without any output operands is treated
-identically to a volatile @code{asm} instruction.
+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:
-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.
+@example
+@{ dialect0 | dialect1 | dialect2... @}
+@end example
-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.
+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.
-@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.
+For example, if an i386 compiler supports two dialects (att, intel), an
+assembler template such as this:
-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.
+@example
+"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
+@end example
-@smallexample
+would produce the output:
+
+@example
+For att: "btl %[Offset],%[Base] ; jc %l2"
+For intel: "bt %[Base],%[Offset]; jc %l2"
+@end example
+
+Using that same compiler, this code:
+
+@example
+"xchg@{l@}\t@{%%@}ebx, %1"
+@end example
+
+would produce
+
+@example
+For att: "xchgl\t%%ebx, %1"
+For intel: "xchg\tebx, %1"
+@end example
+
+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.
+
+@subsubheading Other format strings
+
+In addition to the tokens described by the input, output, and goto operands,
+there are a few special cases:
+
+@itemize
+@item
+'%%' outputs a single '%' into the assembler code.
+
+@item
+'%=' outputs a number that is unique to each instance of the 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.
+
+@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 assembler statement may use the same symbolic name.
+
+@emph{constraint}
+@*
+Output constraints must begin with either "=" (a variable overwriting an
+existing value) or "+" (when reading and writing). When using "=", 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 "r" for register, "m" for memory, and "i" for immediate.
+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 optimizer to produce the best possible code.
+
+@emph{cvariablename}
+@*
+Specifies the C variable name of the output (enclosed by parenthesis). 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
+optimizer 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.
+
+@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 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
+"+".
+
+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
+optimizer 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 "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 asm. Further, the
+compiler will not assume that any values read from memory before the
+@code{asm} will remain unchanged after the @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 stop 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 may not have outputs (which means that the
+statement is implicitly volatile). This is due to an internal restriction in
+the compiler: that control transfer instructions cannot have outputs. If the
+assembler code does modify anything, use the "memory" clobber to force the
+optimizer 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} followed by a number. This
+number is zero-based and includes any 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)
-@{
- 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 ();
+Input, output, and goto operands for extended @code{asm} can use modifiers to
+affect the code output to the assembler. For example, the following code uses
+the 'h' and 'b' modifiers for i386:
- label1:
- f1();
- return;
- label2:
- f2();
- return;
- label3:
- i = 1;
- label4:
- f3(i);
-@}
-@end smallexample
+@example
+uint16_t num;
+asm volatile ("xchg %h0, %b0" : "+a" (num) );
+@end example
-@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.
+These modifiers generate this assembler code:
-@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
+@example
+xchg %ah, %al
+@end example
-@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}.
+The rest of this discussion uses the following code for illustrative purposes.
-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}.
+@example
+int main()
+@{
+ int iInt = 1;
-@subsection Size of an @code{asm}
+top:
-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.
+ asm volatile goto ("some assembler instructions here"
+ : /* No outputs. */
+ : "q" (iInt), "X" (sizeof(unsigned char) + 1)
+ : /* No clobbers. */
+ : top);
+@}
+@end example
-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.
+With no modifiers, this is what the output from the operands would be for the
+att and intel dialects of assembler:
-@subsection i386 floating-point asm operands
+@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
+The table below shows the list of supported modifiers and their effects.
+
+@multitable {Modifier} {Print the opcode suffix for the size of the current integer operand (one of b/w/l/q).} {Operand} {masm=att} {masm=intel}
+@headitem Modifier @tab Description @tab Operand @tab masm=att @tab masm=intel
+@item @code{z}
+@tab Print the opcode suffix for the size of the current integer operand (one of b/w/l/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
+
+@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
that are stack-like registers:
@@ -6715,10 +7145,30 @@
asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
@end smallexample
-@include md.texi
+@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 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.
+
@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 +7216,7 @@
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 +7256,7 @@
@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 +7353,7 @@
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
@@ -6960,8 +7410,10 @@
@noindent
In those cases, a solution is to use a temporary variable for
-each arbitrary expression. @xref{Example of asm with clobbered asm reg}.
+each arbitrary expression.
+@include md.texi
+
@node Alternate Keywords
@section Alternate Keywords
@cindex alternate keywords
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-09 5:29 ` dw
@ 2014-04-10 21:44 ` dw
2014-04-13 1:47 ` Hans-Peter Nilsson
1 sibling, 0 replies; 30+ messages in thread
From: dw @ 2014-04-10 21:44 UTC (permalink / raw)
To: Hans-Peter Nilsson; +Cc: gcc-patches
Hans-Peter Nilsson: Did you have any follow up here? Or did this
response (below) address all your concerns?
I have made some minor corrections since this post:
- "make dvi" now builds my text without errors (can't say this for the
rest of extend.texi).
- All (instead of nearly all) the asm-related subjects are now in the
same menu.
- Minor cleanup of asm prototype for Extended Asm.
Before re-posting this ~60k patch, I thought I'd wait to see if you (or
anyone else) had any final comments. If you want to see a
human-readable version with all the current updates, it's at:
http://www.LimeGreenSocks.com/gcc/Using-Assembly-Language-with-C.html
The first two sections on this menu ("Basic Asm" & "Extended Asm")
contain all the new text. The last four sections were just moved from
elsewhere to this menu to group all asm-related items together.
If there are no more comments by this time tomorrow, I'll re-post the
"final" patch.
Thanks,
dw
On 4/8/2014 10:29 PM, dw wrote:
>
> On 4/8/2014 4:17 PM, Hans-Peter Nilsson wrote:
>> On Fri, 4 Apr 2014, dw wrote:
>>> Problem description:
>>> The existing documentation does an inadequate job of describing gcc's
>>> implementation of the "asm" keyword. This has led to a great deal of
>>> confusion as people struggle to understand how it works. This entire
>>> section
>>> requires a rewrite that provides a structured layout and detailed
>>> descriptions
>>> of each of the parameters along with examples.
>>>
>>> ChangeLog:
>>> 2014-04-03 David Wohlferd (LimeGreenSocks@yahoo.com)
>>> Andrew Haley (aph@redhat.com)
>>> Richard Sandiford (rdsandiford@googlemail.com)
>>>
>>> * extend.texi: Completely rewrite inline asm section /
>>> minor reorg
>>> of asm-related sections
>> (No other feedback since friday?)
>
> Most people who had input probably responded in the RFD on the GCC
> list (http://gcc.gnu.org/ml/gcc/2014-02/msg00511.html).
>
> I haven't heard from the doc maintainers yet, but I understand that at
> least one of them is out of town.
>
>> Thanks for doing this!
>
> Thank you for the response and the feedback.
>
>> There are some *minor* issues, like two-spaces-after-"." which
>> (IIRC) makes a semantic difference in texinfo,
>
> I wasn't aware this was a thing. All those years of typing classes
> make this habit hard to break. Doing a search, it appears my changes
> aren't the only place in extend.texi that does this. I've fixed mine.
>
>> and missing use
>> of texinfo markup like @emph{not} instead of NOT.
>
> Hmm. If this is a standards thing, I suppose I should. Looks like I
> only did it twice (and both in the same paragraph). Fixed.
>
>> Also, in the
>> ChangeLog is the first of many overly long lines. Please keep
>> lines shorter than 80 chars like the rest of extend.texi,
>> somewhere between 70-79 chars?
>
> Sorry. Again, I didn't know this was a thing. texinfo doesn't seem
> to mind, and the html pages I was generating didn't seem to care either.
>
> I've fixed most of this. There are a couple of places I need someone
> who is better at texinfo/formatting to help me out.
>
>> Also, code snippets in texinfo
>> should use GNU formatting, including comments (full sentences
>> with capitalization and full stop).
>
> I've fixed up the things I can see, but I'm no expert in GNU
> formatting. If there's more, I'll need someone to tell me what is
> needed.
>
>> Also,
>>
>> + : [d] "=rm" (d)
>> + : [e] "rm" (*e)
>> + : );
>>
>> That last bit, the ": )" (empty last operand part) shouldn't be
>> in the documentation. I'm not even sure it *should* work
>> (apparently it does, perhaps by accident).
>
> I'd be tempted to debate this one, but I think I'm just going to
> change it instead. Worms, cans, fixed.
>
>> The general bits seems like a big improvement, but what worries
>> me is the deleted text. For example, the aspects of "Explicit
>> Reg Vars" when *directly feeding an asm* and how to write them
>> to avoid the named registers being call-clobbered between
>> assignment and the asm. (Don't confuse this with the
>> asm-clobber operands which I think you covered fine.) Those
>> details are maybe not thoughtfully described, but they can't be
>> just plainly removed as they also serve as gcc specification;
>> definitions as to what works and doesn't work! (I don't know if
>> that was the only occurrence.)
>
> I don't believe that section you are talking about was actually
> deleted, but has instead been moved (along with "Asm Labels" and "Size
> of an asm"). Looking at the new docs, instead of those sections being
> buried with the ~60 other items like in the old docs
> (http://gcc.gnu.org/onlinedocs/gcc-4.8.0/gcc/C-Extensions.html),
> (nearly) all the asm-related subjects got moved here
> (http://www.LimeGreenSocks.com/gcc/Using-Assembly-Language-with-C.html).
> That's what the "minor reorg of asm-related sections" was about.
>
>> Also, do we really want to document the trick in
>> "m" ((@{ struct @{ char x[10]; @} *p = (void *) ptr ; *p; @}))
>> (note: reformatted GNU-style and confusing @{ @} dropped)
>> IIRC this is from Linux, but I don't think GCC ever promised the
>> described semantics, and I don't think we should document
>> something that works just by accident. Do we want to make that
>> promise now?
>
> I got that trick (formatting and all) from the existing docs. Such
> being the case, the question is do we want to @emph{stop} promising
> something that we used to? I have no preference here, other than the
> general desire to maintain backward compatibility. I have not yet made
> any change here.
>
>>
>>> Bootstrapping and testing:
>>> I have tested "make html" to produce html files, but my
>>> configuration doesn't
>>> allow for the "make dvi" test.
>> That requirement is somewhat arcane
>
> I got it off the contrib page
> (http://gcc.gnu.org/contribute.html#docchanges) when I was trying to
> figure out the "proper" way to submit this. If this is no longer a
> requirement, perhaps this should be updated.
>
>> but maybe "make pdf" would
>> work for you? (Though may or may not use dvi as an intermediate
>> step.) The point is to verify the layout; what goes into the
>> info files is often different to what goes into the printable
>> format.
>
> I can try again to get this working. I was hoping "make html" would
> cover most of it. With luck, "make dvi" would have shown nothing
> new. I was focusing on the text since I figured there were likely
> plenty of people with correctly functioning build environments to give
> this bit a test.
>
> dw
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-09 5:29 ` dw
2014-04-10 21:44 ` dw
@ 2014-04-13 1:47 ` Hans-Peter Nilsson
2014-04-13 9:42 ` dw
1 sibling, 1 reply; 30+ messages in thread
From: Hans-Peter Nilsson @ 2014-04-13 1:47 UTC (permalink / raw)
To: dw; +Cc: gcc-patches
On Tue, 8 Apr 2014, dw wrote:
> > The general bits seems like a big improvement, but what worries
> > me is the deleted text. For example, the aspects of "Explicit
> > Reg Vars" when *directly feeding an asm* and how to write them
> > to avoid the named registers being call-clobbered between
> > assignment and the asm. (Don't confuse this with the
> > asm-clobber operands which I think you covered fine.) Those
> > details are maybe not thoughtfully described, but they can't be
> > just plainly removed as they also serve as gcc specification;
> > definitions as to what works and doesn't work! (I don't know if
> > that was the only occurrence.)
>
> I don't believe that section you are talking about was actually deleted, but
> has instead been moved (along with "Asm Labels" and "Size of an asm").
No, it does seem deleted, I can't find it. I can only find its
deletion in the patch, not any re-insert or rewrite and I can't
find this information in the web-pages at limegreensocks. To
wit: where's the corresponding information; the replacement for
the section which started with "Sometimes you need to make an
@code{asm} operand be a specific register, but there's no
matching constraint letter for that register" and had the two
"sysint" examples? Maybe best placed in a separate subsection
cross-referenced from the "top" Extended-Asm Remarks section or
when first discussing constraints, in the "Output Operands"
subsection.
> Looking at the new docs, instead of those sections being buried with the ~60
> other items like in the old docs
> (http://gcc.gnu.org/onlinedocs/gcc-4.8.0/gcc/C-Extensions.html), (nearly) all
> the asm-related subjects got moved here
> (http://www.LimeGreenSocks.com/gcc/Using-Assembly-Language-with-C.html).
> That's what the "minor reorg of asm-related sections" was about.
I did get this, I read the thread. But, speaking of that, I
can't find anyone mentioning the copyright issue. Maybe people
didn't want to scare you away... Someone has said that FSF were
moving towards it sometimes wouldn't be required anymore, but
that comment was made about a year ago and I don't know if
anything has actually changed, so: assuming this is "still"
required, are copyright assignment papers in place with the FSF
for these changes? I can't find any "dw" (or maybe too many) in
the canonical copyright.list just refreshed so I can't tell.
> > Also, do we really want to document the trick in
> > "m" ((@{ struct @{ char x[10]; @} *p = (void *) ptr ; *p; @}))
> > (note: reformatted GNU-style and confusing @{ @} dropped)
> > IIRC this is from Linux, but I don't think GCC ever promised the
> > described semantics, and I don't think we should document
> > something that works just by accident. Do we want to make that
> > promise now?
>
> I got that trick (formatting and all) from the existing docs. Such being the
> case, the question is do we want to @emph{stop} promising something that we
> used to?
No, absolutely not. This is the joy of reorganising things
(code as well as docs): you get blamed for old warts and errors
as well! :-)
> > > Bootstrapping and testing:
> > > I have tested "make html" to produce html files, but my configuration
> > > doesn't
> > > allow for the "make dvi" test.
> > That requirement is somewhat arcane
>
> I got it off the contrib page (http://gcc.gnu.org/contribute.html#docchanges)
> when I was trying to figure out the "proper" way to submit this. If this is
> no longer a requirement, perhaps this should be updated.
(I know you later got this, so just for the record here): I
wrote "arcane" here, not "obsolete" as I meant that perhaps dvi
should be replaced by pdf, but maybe not. The point is to check
that the layout works for the printable version which has
stricter formatting requirements than the html version. I know
it spews lots of warnings; changes are supposed to not make this
worse. If it errors out due to formatting changes before your
changes: no, you don't have to fix it.
brgds, H-P
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-13 1:47 ` Hans-Peter Nilsson
@ 2014-04-13 9:42 ` dw
2014-04-14 0:46 ` Hans-Peter Nilsson
0 siblings, 1 reply; 30+ messages in thread
From: dw @ 2014-04-13 9:42 UTC (permalink / raw)
To: Hans-Peter Nilsson; +Cc: gcc-patches
> No, it does seem deleted, I can't find it. I can only find its
> deletion in the patch, not any re-insert or rewrite and I can't
> find this information in the web-pages at limegreensocks. To
> wit: where's the corresponding information; the replacement for
> the section which started with "Sometimes you need to make an
> @code{asm} operand be a specific register, but there's no
> matching constraint letter for that register" and had the two
> "sysint" examples? Maybe best placed in a separate subsection
> cross-referenced from the "top" Extended-Asm Remarks section or
> when first discussing constraints, in the "Output Operands"
> subsection.
You are correct, I should not have removed this information. After
re-reading the original text several times to try to puzzle out exactly
what it was trying to say, I did feel the need to rephrase it however.
Then there's the question of where this text goes. Like you, I looked
at the idea of a new section, but it doesn't seem like it really merits
its own section. Putting it in the Output section sounds good, but it's
pretty big for that and kinda off-topic. And it would really have to be
repeated in the Inputs section as well. Yuck.
So, how about this:
1) I put the (rephrased) text and examples at the end of "Local Reg
Vars" page (starts with "Sometimes"):
http://www.LimeGreenSocks.com/gcc/Local-Reg-Vars.html
2) In the constraint paragraph for both Input and Output, I added this:
"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})."
Acceptable? To see the changes in patch form, check out
http://www.LimeGreenSocks.com/gcc/extend06.zip
Anything else? Or time to re-post the patch to the list?
> But, speaking of that, I
> can't find anyone mentioning the copyright issue. Maybe people
> didn't want to scare you away... Someone has said that FSF were
> moving towards it sometimes wouldn't be required anymore, but
> that comment was made about a year ago and I don't know if
> anything has actually changed, so: assuming this is "still"
> required, are copyright assignment papers in place with the FSF
> for these changes? I can't find any "dw" (or maybe too many) in
> the canonical copyright.list just refreshed so I can't tell.
It would be a bummer to just find out about this now, but fortunately
Jonathan Wakely and Ian Lance Taylor already helped walk me thru all
this copyright stuff.
I can't see the copyright.list to which you are referring, but the email
I received from Donald Robertson at FSF on August 7, 2013 stated "Your
assignment/disclaimer process with the FSF is currently complete."
My name is David Wohlferd (it was in the changelog). If I'm not on the
official list, please let me know how to proceed.
Thanks again for your time,
dw
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-13 9:42 ` dw
@ 2014-04-14 0:46 ` Hans-Peter Nilsson
2014-04-14 6:25 ` dw
0 siblings, 1 reply; 30+ messages in thread
From: Hans-Peter Nilsson @ 2014-04-14 0:46 UTC (permalink / raw)
To: dw; +Cc: gcc-patches
On Sun, 13 Apr 2014, dw wrote:
> So, how about this:
>
> 1) I put the (rephrased) text and examples at the end of "Local Reg Vars" page
> (starts with "Sometimes"):
> http://www.LimeGreenSocks.com/gcc/Local-Reg-Vars.html
> 2) In the constraint paragraph for both Input and Output, I added this: "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})."
>
> Acceptable?
Yes, nice, thank you!
> Anything else? Or time to re-post the patch to the list?
Better re-post the updated patch.
> > But, speaking of that, I
> > can't find anyone mentioning the copyright issue.
> It would be a bummer to just find out about this now, but fortunately Jonathan
> Wakely and Ian Lance Taylor already helped walk me thru all this copyright
> stuff.
Congratulations for having been through that!
> I can't see the copyright.list to which you are referring, but the email I
> received from Donald Robertson at FSF on August 7, 2013 stated "Your
> assignment/disclaimer process with the FSF is currently complete."
>
> My name is David Wohlferd (it was in the changelog). If I'm not on the
> official list, please let me know how to proceed.
No worries, you are there.
brgds, H-P
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-14 0:46 ` Hans-Peter Nilsson
@ 2014-04-14 6:25 ` dw
2014-04-23 3:44 ` Chung-Ju Wu
` (2 more replies)
0 siblings, 3 replies; 30+ messages in thread
From: dw @ 2014-04-14 6:25 UTC (permalink / raw)
To: gcc-patches, Gerald Pfeifer, Joseph Myers
Cc: Hans-Peter Nilsson, Andrew Haley, rdsandiford
[-- Attachment #1: Type: text/plain, Size: 799 bytes --]
Having resolved the objections, I'm posting the updated patch. I don't
have permissions to commit this patch, but I do have a release on file
with the FSF.
Problem description:
The existing documentation does an inadequate job of describing gcc's
implementation of the "asm" keyword. This has led to a great deal of
confusion as people struggle to understand how it works. This entire
section requires a rewrite that provides a structured layout and
detailed descriptions of each of the parameters along with examples.
ChangeLog:
2014-04-03 David Wohlferd (LimeGreenSocks@yahoo.com)
Andrew Haley (aph@redhat.com)
Richard Sandiford (rdsandiford@googlemail.com)
* extend.texi: Completely rewrite inline asm section / reorg
asm-related sections
David Wohlferd
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: extend.texi.patch --]
[-- Type: text/x-patch; name="extend.texi.patch", Size: 63682 bytes --]
Index: extend.texi
===================================================================
--- extend.texi (revision 209222)
+++ extend.texi (working copy)
@@ -65,11 +65,7 @@
* 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
@@ -5967,7 +5963,7 @@
@}
@end smallexample
-If you are writing a header file to be included in ISO C90 programs, write
+If you are writing a header file that may be included in ISO C90 programs, write
@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
The three types of inlining behave similarly in two important cases:
@@ -6137,492 +6133,945 @@
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 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 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.
+The GCC compiler 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 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. If certain instructions need to remain
+consecutive in the output, put them in a single multi-instruction asm
+statement. Note that GCC's optimizer 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's optimizer 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 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
+asm code as part of optimization. This can lead to unexpected duplicate
+symbol errors during compilation if your asm 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 those symbols getting discarded
+by GCC as unreferenced.
+
+While Basic @code{asm} blocks are implicitly volatile, they 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 include 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] ] ] )
-For example, here is how to use the 68881's @code{fsinx} instruction:
+asm [volatile] goto ( AssemblerTemplate : : [InputOperands] : [Clobbers] : GotoLabels )
+@end ifhtml
+@ifnothtml
+asm [volatile] ( AssemblerTemplate
+ : [OutputOperands]
+ [ : [InputOperands]
+ [ : [Clobbers] ] ])
-@smallexample
-asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
-@end smallexample
+asm [volatile] goto ( AssemblerTemplate
+ :
+ : [InputOperands]
+ : [Clobbers]
+ : GotoLabels)
+@end ifnothtml
+@end example
-@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}).
+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}.
-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@.
+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}.)
-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.
+@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}.
-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:
+@emph{goto}
+@*
+This qualifier informs the compiler that the @code{asm} statement may
+include a jump to one of the labels listed in the GotoLabels section.
+@xref{GotoLabels}.
-@smallexample
-asm ("fsinx %[angle],%[output]"
- : [output] "=f" (result)
- : [angle] "f" (angle));
-@end smallexample
+@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}.
-@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.
+@emph{OutputOperands}
+@*
+A comma-separated list of the C variables modified by the instructions in the
+AssemblerTemplate. @xref{OutputOperands}.
-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.
+@emph{InputOperands}
+@*
+A comma-separated list of C expressions read by the instructions in the
+AssemblerTemplate. @xref{InputOperands}.
-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.
+@emph{Clobbers}
+@*
+A comma-separated list of registers or other values changed by the
+AssemblerTemplate, beyond those listed as outputs. @xref{Clobbers}.
-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:
+@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}.
-@smallexample
-asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
-@end smallexample
+@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.
-@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.
+Note that Extended @code{asm} statements must be inside a function. Only
+Basic @code{asm} may be outside functions (@pxref{Basic Asm}).
-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:
+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 ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
-@end smallexample
+@example
+int src = 1;
+int dst;
-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.
+asm ("mov %1, %0\n\t"
+ "add $1, %0"
+ : "=r" (dst)
+ : "r" (src));
-As of GCC version 3.1, one may write @code{[@var{name}]} instead of
-the operand number for a matching constraint. For example:
+printf("%d\n", dst);
+@end example
-@smallexample
-asm ("cmoveq %1,%2,%[result]"
- : [result] "=r"(result)
- : "r" (test), "r"(new), "[result]"(old));
-@end smallexample
+This code will copy @var{src} to @var{dst} and add 1 to @var{dst}.
-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:
+@anchor{Volatile}
+@subsubsection Volatile
+@cindex volatile @code{asm}
+@cindex @code{asm} volatile
-@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
+GCC's optimizer sometimes discards @code{asm} statements if it determines
+that it has no need for the output variables. Also, the optimizer may move
+code out of loops if it believes 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.
-@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:
+Examples:
-@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
+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 optimizer 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 optimizer to produce the most efficient code
+possible.
-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:
+@example
+void DoCheck(uint32_t dwSomeValue)
+@{
+ uint32_t dwRes;
-@smallexample
-asm volatile ("movc3 %0,%1,%2"
- : /* @r{no outputs} */
- : "g" (from), "g" (to), "g" (count)
- : "r0", "r1", "r2", "r3", "r4", "r5");
-@end smallexample
+ // Assumes dwSomeValue is not zero.
+ asm ("bsfl %1,%0"
+ : "=r" (dwRes)
+ : "r" (dwSomeValue)
+ : "cc");
-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.
+ assert(dwRes > 3);
+@}
+@end example
-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.
+The next example shows a case where the optimizer 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.
-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.
+@example
+void do_print(uint32_t dwSomeValue)
+@{
+ uint32_t dwRes;
-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:
+ for (uint32_t x=0; x < 5; x++)
+ @{
+ // Assumes dwSomeValue is not zero.
+ asm ("bsfl %1,%0"
+ : "=r" (dwRes)
+ : "r" (dwSomeValue)
+ : "cc");
-@smallexample
-@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}.
-@end smallexample
-
-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;
+ printf("%u: %u %u\n", x, dwSomeValue, dwRes);
+ @}
@}
-@end smallexample
+@end example
-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:
+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 optimizer might assume that the @code{asm} block will always return the
+same value and therefore optimize away the second call.
-@smallexample
-asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo"
- : /* no outputs */
- : "g" (from), "g" (to)
- : "r9", "r10");
-@end smallexample
+@example
+uint64_t msr;
-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}.
+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 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:
+printf("msr: %llx\n", msr);
-@smallexample
-asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
- : "g" (result)
- : "g" (input));
-@end smallexample
+// Do other work...
-@noindent
-This assumes your assembler supports local labels, as the GNU assembler
-and most Unix assemblers do.
+// 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");
-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}.
+printf("msr: %llx\n", msr);
+@end example
-@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,
+GCC's optimizer will not treat this code like the non-volatile code in the
+earlier examples. It does not move it out of loops or omit it on the
+assumption that the result from a previous call is still valid.
-@smallexample
-#define sin(x) \
-(@{ double __value, __arg = (x); \
- asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
- __value; @})
-@end smallexample
+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.
-@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}.
+@example
+asm volatile("mtfsf 255, %0" : : "f" (fpenv));
+sum = x + y;
+@end example
-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.
+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 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.
+@example
+asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
+sum = x + y;
+@end example
-You can prevent an @code{asm} instruction from being deleted
-by writing the keyword @code{volatile} after
-the @code{asm}. For example:
+Under certain circumstances, GCC may duplicate (or remove duplicates of) your
+asm code as part of optimization. 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.
-@smallexample
-#define get_and_set_priority(new) \
-(@{ int __old; \
- asm volatile ("get_and_set_priority %0, %1" \
- : "=g" (__old) : "g" (new)); \
- __old; @})
-@end smallexample
+@anchor{AssemblerTemplate}
+@subsubsection Assembler Template
+@cindex @code{asm} assembler template
-@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:
+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. The GCC compiler does not parse the assembler instructions
+themselves and does not know what they mean or even whether they are valid
+assembler input.
-@smallexample
- asm volatile("mtfsf 255,%0" : : "f" (fpenv));
- sum = x + y;
-@end smallexample
+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.
-@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:
+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.
-@smallexample
- asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv));
- sum = x + y;
-@end smallexample
+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.
-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.
+Since GCC does not parse the AssemblerTemplate, it has no visibility of any
+symbols it references. This may result in those symbols getting discarded by
+GCC as unreferenced unless they are also listed as input, output, or goto
+operands.
-An @code{asm} instruction without any output operands is treated
-identically to a volatile @code{asm} instruction.
+GCC may support multiple assembler dialects (such as "att" or "intel") for
+inline assembler. The list of supported dialects depends on the implementation
+details of the specific build of the compiler. When writing assembler, be
+aware of which dialect is the compiler's default. Assembler code that works
+correctly when compiled using one dialect will likely fail if compiled using
+another. The @option{-masm} option changes the dialect that GCC uses in builds
+that support multiple dialects.
-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 Using braces in @code{asm} templates
-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.
+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:
-@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.
+@example
+@{ dialect0 | dialect1 | dialect2... @}
+@end example
-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.
+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.
-@smallexample
+For example, if an i386 compiler supports two dialects (att, intel), an
+assembler template such as this:
+
+@example
+"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
+@end example
+
+would produce the output:
+
+@example
+For att: "btl %[Offset],%[Base] ; jc %l2"
+For intel: "bt %[Base],%[Offset]; jc %l2"
+@end example
+
+Using that same compiler, this code:
+
+@example
+"xchg@{l@}\t@{%%@}ebx, %1"
+@end example
+
+would produce
+
+@example
+For att: "xchgl\t%%ebx, %1"
+For intel: "xchg\tebx, %1"
+@end example
+
+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.
+
+@subsubheading Other format strings
+
+In addition to the tokens described by the input, output, and goto operands,
+there are a few special cases:
+
+@itemize
+@item
+'%%' outputs a single '%' into the assembler code.
+
+@item
+'%=' outputs a number that is unique to each instance of the 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.
+
+@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 assembler statement may use the same symbolic name.
+
+@emph{constraint}
+@*
+Output constraints must begin with either "=" (a variable overwriting an
+existing value) or "+" (when reading and writing). When using "=", 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 "r" for register, "m" for memory, and "i" for immediate.
+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 optimizer 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 parenthesis). 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
+optimizer 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.
+
+@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 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
+optimizer 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 "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 asm. Further, the
+compiler will not assume that any values read from memory before the
+@code{asm} will remain unchanged after the @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 stop 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 may not have outputs (which means that the
+statement is implicitly volatile). This is due to an internal restriction in
+the compiler: that control transfer instructions cannot have outputs. If the
+assembler code does modify anything, use the "memory" clobber to force the
+optimizer 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} followed by a number. This
+number is zero-based and includes any 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)
-@{
- 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 ();
+Input, output, and goto operands for extended @code{asm} can use modifiers to
+affect the code output to the assembler. For example, the following code uses
+the 'h' and 'b' modifiers for i386:
- label1:
- f1();
- return;
- label2:
- f2();
- return;
- label3:
- i = 1;
- label4:
- f3(i);
-@}
-@end smallexample
+@example
+uint16_t num;
+asm volatile ("xchg %h0, %b0" : "+a" (num) );
+@end example
-@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.
+These modifiers generate this assembler code:
-@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
+@example
+xchg %ah, %al
+@end example
-@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}.
+The rest of this discussion uses the following code for illustrative purposes.
-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}.
+@example
+int main()
+@{
+ int iInt = 1;
-@subsection Size of an @code{asm}
+top:
-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.
+ asm volatile goto ("some assembler instructions here"
+ : /* No outputs. */
+ : "q" (iInt), "X" (sizeof(unsigned char) + 1)
+ : /* No clobbers. */
+ : top);
+@}
+@end example
-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.
+With no modifiers, this is what the output from the operands would be for the
+att and intel dialects of assembler:
-@subsection i386 floating-point asm operands
+@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
+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 masm=att @tab masm=intel
+@item @code{z}
+@tab Print the opcode suffix for the size of the current integer operand (one of b/w/l/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
+
+@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
that are stack-like registers:
@@ -6715,10 +7164,34 @@
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 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.
+
@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 +7239,7 @@
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 +7279,7 @@
@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 +7376,7 @@
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,22 +7419,38 @@
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 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
@cindex alternate keywords
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-14 6:25 ` dw
@ 2014-04-23 3:44 ` Chung-Ju Wu
2014-04-23 5:52 ` Chung-Ju Wu
2014-04-25 15:45 ` James Greenhalgh
2 siblings, 0 replies; 30+ messages in thread
From: Chung-Ju Wu @ 2014-04-23 3:44 UTC (permalink / raw)
To: dw
Cc: gcc patches, Gerald Pfeifer, Joseph Myers, Hans-Peter Nilsson,
Andrew Haley, Richard Sandiford
2014-04-14 14:24 GMT+08:00 dw <limegreensocks@yahoo.com>:
> Having resolved the objections, I'm posting the updated patch. I don't have
> permissions to commit this patch, but I do have a release on file with the
> FSF.
>
>
> Problem description:
> The existing documentation does an inadequate job of describing gcc's
> implementation of the "asm" keyword. This has led to a great deal of
> confusion as people struggle to understand how it works. This entire section
> requires a rewrite that provides a structured layout and detailed
> descriptions of each of the parameters along with examples.
>
> ChangeLog:
> 2014-04-03 David Wohlferd (LimeGreenSocks@yahoo.com)
> Andrew Haley (aph@redhat.com)
> Richard Sandiford (rdsandiford@googlemail.com)
>
> * extend.texi: Completely rewrite inline asm section / reorg asm-related
> sections
>
> David Wohlferd
Hi, David,
A few nit picking about ChangeLog format:
1. The "extend.texi" is supposed to have "doc/" prefix.
2. 80-columns limit each line in the description.
3. Better have '.' at the end of a sentence.
So, the refine description is suggested using:
* doc/extend.texi: Completely rewrite inline asm section and reorg
asm-related sections.
Hope your patch can be approved soon. :)
Best regards,
jasonwucj
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-14 6:25 ` dw
2014-04-23 3:44 ` Chung-Ju Wu
@ 2014-04-23 5:52 ` Chung-Ju Wu
2014-04-25 15:45 ` James Greenhalgh
2 siblings, 0 replies; 30+ messages in thread
From: Chung-Ju Wu @ 2014-04-23 5:52 UTC (permalink / raw)
To: dw
Cc: gcc patches, Gerald Pfeifer, Joseph Myers, Hans-Peter Nilsson,
Andrew Haley, Richard Sandiford
2014-04-14 14:24 GMT+08:00 dw <limegreensocks@yahoo.com>:
> Having resolved the objections, I'm posting the updated patch. I don't have
> permissions to commit this patch, but I do have a release on file with the
> FSF.
>
>
> Problem description:
> The existing documentation does an inadequate job of describing gcc's
> implementation of the "asm" keyword. This has led to a great deal of
> confusion as people struggle to understand how it works. This entire section
> requires a rewrite that provides a structured layout and detailed
> descriptions of each of the parameters along with examples.
>
> ChangeLog:
> 2014-04-03 David Wohlferd (LimeGreenSocks@yahoo.com)
> Andrew Haley (aph@redhat.com)
> Richard Sandiford (rdsandiford@googlemail.com)
>
For the date, name, and email formatting, it should be:
2014-04-03 David Wohlferd <LimeGreenSocks@yahoo.com>
Andrew Haley <aph@redhat.com>
Richard Sandiford <rdsandiford@googlemail.com>
Note that there are two spaces between date and name.
Same as name and email.
Best regards,
jasonwucj
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-14 6:25 ` dw
2014-04-23 3:44 ` Chung-Ju Wu
2014-04-23 5:52 ` Chung-Ju Wu
@ 2014-04-25 15:45 ` James Greenhalgh
2014-04-25 15:59 ` Andrew Haley
2014-04-27 0:21 ` Gerald Pfeifer
2 siblings, 2 replies; 30+ messages in thread
From: James Greenhalgh @ 2014-04-25 15:45 UTC (permalink / raw)
To: dw
Cc: gcc-patches, Gerald Pfeifer, Joseph Myers, Hans-Peter Nilsson,
aph, rdsandiford
Beyond comments on ChangeLog formatting, the review for this patch seems
to have stalled again.
The patch has been in review for two months now, with broadly positive comments
and all suggestions made thus far have been incorporated. I'd therefore like
to
*ping*
this on David's behalf and try to get the review moving again.
Thanks,
James
On Mon, Apr 14, 2014 at 07:24:56AM +0100, dw wrote:
> Having resolved the objections, I'm posting the updated patch. I don't
> have permissions to commit this patch, but I do have a release on file
> with the FSF.
>
> Problem description:
> The existing documentation does an inadequate job of describing gcc's
> implementation of the "asm" keyword. This has led to a great deal of
> confusion as people struggle to understand how it works. This entire
> section requires a rewrite that provides a structured layout and
> detailed descriptions of each of the parameters along with examples.
>
> ChangeLog:
> 2014-04-03 David Wohlferd (LimeGreenSocks@yahoo.com)
> Andrew Haley (aph@redhat.com)
> Richard Sandiford (rdsandiford@googlemail.com)
>
> * extend.texi: Completely rewrite inline asm section / reorg
> asm-related sections
>
> David Wohlferd
> Index: extend.texi
> ===================================================================
> --- extend.texi (revision 209222)
> +++ extend.texi (working copy)
> @@ -65,11 +65,7 @@
> * 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
> @@ -5967,7 +5963,7 @@
> @}
> @end smallexample
>
> -If you are writing a header file to be included in ISO C90 programs, write
> +If you are writing a header file that may be included in ISO C90 programs, write
> @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
>
> The three types of inlining behave similarly in two important cases:
> @@ -6137,492 +6133,945 @@
> 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 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 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.
> +The GCC compiler 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 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. If certain instructions need to remain
> +consecutive in the output, put them in a single multi-instruction asm
> +statement. Note that GCC's optimizer 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's optimizer 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 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
> +asm code as part of optimization. This can lead to unexpected duplicate
> +symbol errors during compilation if your asm 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 those symbols getting discarded
> +by GCC as unreferenced.
> +
> +While Basic @code{asm} blocks are implicitly volatile, they 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 include 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] ] ] )
>
> -For example, here is how to use the 68881's @code{fsinx} instruction:
> +asm [volatile] goto ( AssemblerTemplate : : [InputOperands] : [Clobbers] : GotoLabels )
> +@end ifhtml
> +@ifnothtml
> +asm [volatile] ( AssemblerTemplate
> + : [OutputOperands]
> + [ : [InputOperands]
> + [ : [Clobbers] ] ])
>
> -@smallexample
> -asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
> -@end smallexample
> +asm [volatile] goto ( AssemblerTemplate
> + :
> + : [InputOperands]
> + : [Clobbers]
> + : GotoLabels)
> +@end ifnothtml
> +@end example
>
> -@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}).
> +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}.
>
> -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@.
> +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}.)
>
> -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.
> +@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}.
>
> -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:
> +@emph{goto}
> +@*
> +This qualifier informs the compiler that the @code{asm} statement may
> +include a jump to one of the labels listed in the GotoLabels section.
> +@xref{GotoLabels}.
>
> -@smallexample
> -asm ("fsinx %[angle],%[output]"
> - : [output] "=f" (result)
> - : [angle] "f" (angle));
> -@end smallexample
> +@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}.
>
> -@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.
> +@emph{OutputOperands}
> +@*
> +A comma-separated list of the C variables modified by the instructions in the
> +AssemblerTemplate. @xref{OutputOperands}.
>
> -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.
> +@emph{InputOperands}
> +@*
> +A comma-separated list of C expressions read by the instructions in the
> +AssemblerTemplate. @xref{InputOperands}.
>
> -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.
> +@emph{Clobbers}
> +@*
> +A comma-separated list of registers or other values changed by the
> +AssemblerTemplate, beyond those listed as outputs. @xref{Clobbers}.
>
> -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:
> +@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}.
>
> -@smallexample
> -asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
> -@end smallexample
> +@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.
>
> -@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.
> +Note that Extended @code{asm} statements must be inside a function. Only
> +Basic @code{asm} may be outside functions (@pxref{Basic Asm}).
>
> -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:
> +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 ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
> -@end smallexample
> +@example
> +int src = 1;
> +int dst;
>
> -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.
> +asm ("mov %1, %0\n\t"
> + "add $1, %0"
> + : "=r" (dst)
> + : "r" (src));
>
> -As of GCC version 3.1, one may write @code{[@var{name}]} instead of
> -the operand number for a matching constraint. For example:
> +printf("%d\n", dst);
> +@end example
>
> -@smallexample
> -asm ("cmoveq %1,%2,%[result]"
> - : [result] "=r"(result)
> - : "r" (test), "r"(new), "[result]"(old));
> -@end smallexample
> +This code will copy @var{src} to @var{dst} and add 1 to @var{dst}.
>
> -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:
> +@anchor{Volatile}
> +@subsubsection Volatile
> +@cindex volatile @code{asm}
> +@cindex @code{asm} volatile
>
> -@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
> +GCC's optimizer sometimes discards @code{asm} statements if it determines
> +that it has no need for the output variables. Also, the optimizer may move
> +code out of loops if it believes 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.
>
> -@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:
> +Examples:
>
> -@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
> +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 optimizer 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 optimizer to produce the most efficient code
> +possible.
>
> -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:
> +@example
> +void DoCheck(uint32_t dwSomeValue)
> +@{
> + uint32_t dwRes;
>
> -@smallexample
> -asm volatile ("movc3 %0,%1,%2"
> - : /* @r{no outputs} */
> - : "g" (from), "g" (to), "g" (count)
> - : "r0", "r1", "r2", "r3", "r4", "r5");
> -@end smallexample
> + // Assumes dwSomeValue is not zero.
> + asm ("bsfl %1,%0"
> + : "=r" (dwRes)
> + : "r" (dwSomeValue)
> + : "cc");
>
> -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.
> + assert(dwRes > 3);
> +@}
> +@end example
>
> -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.
> +The next example shows a case where the optimizer 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.
>
> -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.
> +@example
> +void do_print(uint32_t dwSomeValue)
> +@{
> + uint32_t dwRes;
>
> -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:
> + for (uint32_t x=0; x < 5; x++)
> + @{
> + // Assumes dwSomeValue is not zero.
> + asm ("bsfl %1,%0"
> + : "=r" (dwRes)
> + : "r" (dwSomeValue)
> + : "cc");
>
> -@smallexample
> -@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}.
> -@end smallexample
> -
> -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;
> + printf("%u: %u %u\n", x, dwSomeValue, dwRes);
> + @}
> @}
> -@end smallexample
> +@end example
>
> -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:
> +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 optimizer might assume that the @code{asm} block will always return the
> +same value and therefore optimize away the second call.
>
> -@smallexample
> -asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo"
> - : /* no outputs */
> - : "g" (from), "g" (to)
> - : "r9", "r10");
> -@end smallexample
> +@example
> +uint64_t msr;
>
> -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}.
> +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 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:
> +printf("msr: %llx\n", msr);
>
> -@smallexample
> -asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
> - : "g" (result)
> - : "g" (input));
> -@end smallexample
> +// Do other work...
>
> -@noindent
> -This assumes your assembler supports local labels, as the GNU assembler
> -and most Unix assemblers do.
> +// 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");
>
> -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}.
> +printf("msr: %llx\n", msr);
> +@end example
>
> -@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,
> +GCC's optimizer will not treat this code like the non-volatile code in the
> +earlier examples. It does not move it out of loops or omit it on the
> +assumption that the result from a previous call is still valid.
>
> -@smallexample
> -#define sin(x) \
> -(@{ double __value, __arg = (x); \
> - asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
> - __value; @})
> -@end smallexample
> +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.
>
> -@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}.
> +@example
> +asm volatile("mtfsf 255, %0" : : "f" (fpenv));
> +sum = x + y;
> +@end example
>
> -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.
> +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 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.
> +@example
> +asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
> +sum = x + y;
> +@end example
>
> -You can prevent an @code{asm} instruction from being deleted
> -by writing the keyword @code{volatile} after
> -the @code{asm}. For example:
> +Under certain circumstances, GCC may duplicate (or remove duplicates of) your
> +asm code as part of optimization. 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.
>
> -@smallexample
> -#define get_and_set_priority(new) \
> -(@{ int __old; \
> - asm volatile ("get_and_set_priority %0, %1" \
> - : "=g" (__old) : "g" (new)); \
> - __old; @})
> -@end smallexample
> +@anchor{AssemblerTemplate}
> +@subsubsection Assembler Template
> +@cindex @code{asm} assembler template
>
> -@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:
> +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. The GCC compiler does not parse the assembler instructions
> +themselves and does not know what they mean or even whether they are valid
> +assembler input.
>
> -@smallexample
> - asm volatile("mtfsf 255,%0" : : "f" (fpenv));
> - sum = x + y;
> -@end smallexample
> +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.
>
> -@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:
> +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.
>
> -@smallexample
> - asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv));
> - sum = x + y;
> -@end smallexample
> +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.
>
> -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.
> +Since GCC does not parse the AssemblerTemplate, it has no visibility of any
> +symbols it references. This may result in those symbols getting discarded by
> +GCC as unreferenced unless they are also listed as input, output, or goto
> +operands.
>
> -An @code{asm} instruction without any output operands is treated
> -identically to a volatile @code{asm} instruction.
> +GCC may support multiple assembler dialects (such as "att" or "intel") for
> +inline assembler. The list of supported dialects depends on the implementation
> +details of the specific build of the compiler. When writing assembler, be
> +aware of which dialect is the compiler's default. Assembler code that works
> +correctly when compiled using one dialect will likely fail if compiled using
> +another. The @option{-masm} option changes the dialect that GCC uses in builds
> +that support multiple dialects.
>
> -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 Using braces in @code{asm} templates
>
> -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.
> +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:
>
> -@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.
> +@example
> +@{ dialect0 | dialect1 | dialect2... @}
> +@end example
>
> -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.
> +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.
>
> -@smallexample
> +For example, if an i386 compiler supports two dialects (att, intel), an
> +assembler template such as this:
> +
> +@example
> +"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
> +@end example
> +
> +would produce the output:
> +
> +@example
> +For att: "btl %[Offset],%[Base] ; jc %l2"
> +For intel: "bt %[Base],%[Offset]; jc %l2"
> +@end example
> +
> +Using that same compiler, this code:
> +
> +@example
> +"xchg@{l@}\t@{%%@}ebx, %1"
> +@end example
> +
> +would produce
> +
> +@example
> +For att: "xchgl\t%%ebx, %1"
> +For intel: "xchg\tebx, %1"
> +@end example
> +
> +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.
> +
> +@subsubheading Other format strings
> +
> +In addition to the tokens described by the input, output, and goto operands,
> +there are a few special cases:
> +
> +@itemize
> +@item
> +'%%' outputs a single '%' into the assembler code.
> +
> +@item
> +'%=' outputs a number that is unique to each instance of the 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.
> +
> +@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 assembler statement may use the same symbolic name.
> +
> +@emph{constraint}
> +@*
> +Output constraints must begin with either "=" (a variable overwriting an
> +existing value) or "+" (when reading and writing). When using "=", 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 "r" for register, "m" for memory, and "i" for immediate.
> +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 optimizer 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 parenthesis). 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
> +optimizer 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.
> +
> +@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 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
> +optimizer 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 "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 asm. Further, the
> +compiler will not assume that any values read from memory before the
> +@code{asm} will remain unchanged after the @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 stop 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 may not have outputs (which means that the
> +statement is implicitly volatile). This is due to an internal restriction in
> +the compiler: that control transfer instructions cannot have outputs. If the
> +assembler code does modify anything, use the "memory" clobber to force the
> +optimizer 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} followed by a number. This
> +number is zero-based and includes any 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)
> -@{
> - 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 ();
> +Input, output, and goto operands for extended @code{asm} can use modifiers to
> +affect the code output to the assembler. For example, the following code uses
> +the 'h' and 'b' modifiers for i386:
>
> - label1:
> - f1();
> - return;
> - label2:
> - f2();
> - return;
> - label3:
> - i = 1;
> - label4:
> - f3(i);
> -@}
> -@end smallexample
> +@example
> +uint16_t num;
> +asm volatile ("xchg %h0, %b0" : "+a" (num) );
> +@end example
>
> -@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.
> +These modifiers generate this assembler code:
>
> -@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
> +@example
> +xchg %ah, %al
> +@end example
>
> -@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}.
> +The rest of this discussion uses the following code for illustrative purposes.
>
> -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}.
> +@example
> +int main()
> +@{
> + int iInt = 1;
>
> -@subsection Size of an @code{asm}
> +top:
>
> -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.
> + asm volatile goto ("some assembler instructions here"
> + : /* No outputs. */
> + : "q" (iInt), "X" (sizeof(unsigned char) + 1)
> + : /* No clobbers. */
> + : top);
> +@}
> +@end example
>
> -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.
> +With no modifiers, this is what the output from the operands would be for the
> +att and intel dialects of assembler:
>
> -@subsection i386 floating-point asm operands
> +@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
>
> +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 masm=att @tab masm=intel
> +@item @code{z}
> +@tab Print the opcode suffix for the size of the current integer operand (one of b/w/l/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
> +
> +@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
> that are stack-like registers:
> @@ -6715,10 +7164,34 @@
> 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 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.
> +
> @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 +7239,7 @@
> 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 +7279,7 @@
> @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 +7376,7 @@
> 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,22 +7419,38 @@
> 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 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
> @cindex alternate keywords
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-25 15:45 ` James Greenhalgh
@ 2014-04-25 15:59 ` Andrew Haley
2014-04-27 0:21 ` Gerald Pfeifer
1 sibling, 0 replies; 30+ messages in thread
From: Andrew Haley @ 2014-04-25 15:59 UTC (permalink / raw)
To: James Greenhalgh, dw, Joseph Myers
Cc: gcc-patches, Gerald Pfeifer, Hans-Peter Nilsson, rdsandiford
On 04/25/2014 04:43 PM, James Greenhalgh wrote:
> Beyond comments on ChangeLog formatting, the review for this patch seems
> to have stalled again.
>
> The patch has been in review for two months now, with broadly positive comments
> and all suggestions made thus far have been incorporated. I'd therefore like
> to
>
> *ping*
>
> this on David's behalf and try to get the review moving again.
We're waiting for Joseph Myers or, at a pinch, a maintainer with global
write privs.
Andrew.
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-25 15:45 ` James Greenhalgh
2014-04-25 15:59 ` Andrew Haley
@ 2014-04-27 0:21 ` Gerald Pfeifer
2014-04-27 9:32 ` Andrew Haley
2014-04-27 23:07 ` dw
1 sibling, 2 replies; 30+ messages in thread
From: Gerald Pfeifer @ 2014-04-27 0:21 UTC (permalink / raw)
To: James Greenhalgh, limegreensocks
Cc: gcc-patches, Joseph Myers, Hans-Peter Nilsson, Andrew Haley,
Richard Sandiford
The perfect is the enemy of the good.
From all I have seen and heard, this rewrite is a clear improvement
over the status quo. So I am going to review and approve it wearing
my doc maintainer hat, deferring to and relying on Andrew and Richard
and their deep expertise on the technical side.
Please take my comments below into account for an updated patch, and
once Andrew and Richard have signed of, this is then good to commit.
(Patches of this size really are tough to review. That surely has
contributed to the delay getting this in the tree most significantly.
In fact, I fell asleep over my notebook thrice reviewing this last
evening, though traveling from US West coast to Central Europe without
sleep during the flight probably did not exactly help, either. :-)
On Fri, 25 Apr 2014, James Greenhalgh wrote:
>> +@menu
>> +* Basic Asm:: Inline assembler with no operands.
>> +* Extended Asm:: Inline assembler with operands.
>> +* Constraints:: Constraints for asm operands
Should this be "Asm operands" based on the other references here
or, better @code{asm} in all cases here?
>> +* Explicit Reg Vars:: Defining variables residing in specified registers.
Should this be "Register" instead of just "Reg"?
And "Variables" instead of just "Vars"?
>> +* Size of an asm:: How GCC calculates the size of an asm block.
@code{asm} ?
>> +@subsection Basic Asm - Assembler Instructions with No Operands
--- instead of -
>> +To create headers compatible with ISO C, write @code{__asm__} instead of
>> +@code{asm} (@pxref{Alternate Keywords}).
Here it's just ISO C, whereas in case of __inline__ you had ISO C90.
Would it make sense to just use ISO C throughout?
>> +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}.
At this point the reader does not yet know the concept of those
colons, does she? So that can be seen as a bit confusing.
>> +@subsubheading Parameters
>> +@emph{AssemblerInstructions}
>> +@*
>> +This is a literal string that specifies the assembler code. The string can
Just "assembler code", without "the", would be my take, but let's see
what native speakers so.
>> +The GCC compiler does not parse the assembler instructions themselves and
"GCC does". GCC stands for GNU Compiler Collection, and GNU Compiler
Collection Compiler may be a bit confusing. ;-)
>> +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.
Might "by the same characters normally...the target system" be more clear?
>> +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").
Will everyone know what an instruction field is? I'm not sure it's
that common of a term.
>> +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 optimizer can move @code{asm} statements
>> +relative to other code, including across jumps.
optimizers (plural)
>> +GCC's optimizer 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}.
How about just saying "GCC does not know..:"?
>> +@subsubheading Remarks
>> +Using Extended @code{asm} will typically produce smaller, safer, and more
>> +efficient code, and in most cases it is a better solution.
Why?
>> When writing inline assembly language outside C functions, however,
>> you must use Basic @code{asm}. Extended @code{asm} statements have to
>> be inside a C function.
Might that be "outside of C functions"? Native speakers?
The way this is phrased sounds a bit negative. Is this really a
drawback?
>> +Under certain circumstances, GCC may duplicate (or remove duplicates of) your
>> +asm code as part of optimization. This can lead to unexpected duplicate
>> +symbol errors during compilation if your asm code defines symbols or labels.
"as part of optimization" -> "when optimizing"
@code{asm}
>> +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}.
Here we are, this looks like (part of) the answer to my question
"Why?" above. :-)
>> +Since GCC does not parse the AssemblerInstructions, it has no visibility of
^^^^^^^^^^^^^^^^^^^^^
Something wrong here.
>> +any symbols it references. This may result in those symbols getting discarded
>> +by GCC as unreferenced.
We can omit "by GCC" here.
>> +While Basic @code{asm} blocks are implicitly volatile, they are not treated
>> +as though they used a "memory" clobber (@pxref{Clobbers}).
What does it mean for a block to be volatile, as opposed to a variable?
Should this be ``memory'' (note the quotes)?
>> -@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 include jumps from assembler code to C labels.
>> +@ifhtml
>> +asm [volatile] ( AssemblerTemplate : [OutputOperands] [ : [InputOperands] [ : [Clobbers] ] ] )
>>
>> -For example, here is how to use the 68881's @code{fsinx} instruction:
>> +asm [volatile] goto ( AssemblerTemplate : : [InputOperands] : [Clobbers] : GotoLabels )
>> +@end ifhtml
>> +@ifnothtml
>> +asm [volatile] ( AssemblerTemplate
>> + : [OutputOperands]
>> + [ : [InputOperands]
>> + [ : [Clobbers] ] ])
Why does the @ifhtml variant have a "goto" when the other does not?
>> +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}.)
What does "classes of operands refer to"? This does not seem to be
evident from the context.
>> +@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.
This feels like it comes rather late in the flow. Wouldn't that be
a comment pretty early on in this section?
>> +Note that Extended @code{asm} statements must be inside a function. Only
>> +Basic @code{asm} may be outside functions (@pxref{Basic Asm}).
We had a similary paragraph earlier on. Perhaps only keep this where
it relates to Extended statements? Not sure about this, though.
>> +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:
This, without the example possibly, would have been good earlier, when
all the different classes where described.
>> +GCC's optimizer sometimes discards @code{asm} statements if it determines
>> +that it has no need for the output variables.
How about just saying "GCC", not referring to the optimizer here?
>> +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.
>> +@code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
>> +isn't needed you allow the optimizer to produce the most efficient code
>> +possible.
How about "Only including ...when it is really necessary allows the
optimizer", that is, a more positive ("included" instead of "omitting")
approach?
>> +GCC's optimizer will not treat this code like the non-volatile code in the
>> +earlier examples. It does not move it out of loops or omit it on the
>> +assumption that the result from a previous call is still valid.
"GCC will..."
>> +Under certain circumstances, GCC may duplicate (or remove duplicates of) your
>> +asm code as part of optimization. This can lead to unexpected duplicate symbol
@code{asm}
And did we not have the same (or very similar) statement a bit earlier?
>> +directives. The GCC compiler does not parse the assembler instructions
Just "GCC".
>> +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.
This also looks quite familiar. Is there a way to build up and avoid
the redundancy?
>> +GCC may support multiple assembler dialects (such as "att" or "intel") for
>> +inline assembler. The list of supported dialects depends on the implementation
>> +details of the specific build of the compiler. When writing assembler, be
>> +aware of which dialect is the compiler's default. Assembler code that works
>> +correctly when compiled using one dialect will likely fail if compiled using
>> +another.
How about saying "When writing assembler code", since the term
assembler is a bit ambigous?
>> +@example
>> +@{ dialect0 | dialect1 | dialect2... @}
>> +@end example
:
>> +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.
How does the user know what is dialect #0? Same for the others?
>> +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.
``escape'' (note the quotes)
>> +In addition to the tokens described by the input, output, and goto
>> operands, there are a few special cases:
How about clobbers?
>> +@itemize
>> +@item
>> +'%%' outputs a single '%' into the assembler code.
>> +@item
>> +'%=' outputs a number that is unique to each instance of the 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.
@code{asm} statement
And again the quotes don't seem right (in a few cases here).
>> +Output constraints must begin with either "=" (a variable overwriting an
>> +existing value) or "+" (when reading and writing). When using "=", do not
>> +assume the location will contain the existing value (except when tying the
>> +variable to an input; @pxref{InputOperands,,Input Operands}).
@code{=}
@code{+}
Possibly under proper quotes as well?
>> +After the prefix, there must be one or more additional constraints
>> +(@pxref{Constraints}) that describe where the value resides. Common
>> +constraints include "r" for register, "m" for memory, and "i" for immediate.
Similarly here.
>> +control to select the specific register you want, Local Reg Vars may provide
>> +a solution (@pxref{Local Reg Vars}).
Local Reg Vars should be properly expanded, I assume.
>> +Specifies the C variable name of the output (enclosed by parenthesis).
"parentheses" (plural)
>> Accepts
>> +any (non-constant) variable within scope.
What's a non-constant variable? Or just a constant variable?
> > +@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}
If we use qoutes, they should read `...' in a couple of cases here.
>> +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
I don't think irm should be under quotes. The entire @code{...} I
could understand better.
>> +either "=" or "+". If you must use a specific register, but your Machine
Quotes.
>> +Constraints do not provide sufficient control to select the specific
>> +register you want, Local Reg Vars may provide a solution
>> +(@pxref{Local Reg Vars}).
Can we use a better term than Local Reg Vars? Or is that totally
entrenched?
>> +Input constraints can also be digits (for example, @code{"0"}). This indicates
Quotes inside of @code do not seem approriate here.
>> +Remarks:
>> +
>> +The total number of input + output + goto operands has a limit of 30.
We also had this data point earlier in the text of this patch already,
didn't we?
>> +constraint @code{"0"} for input operand 1 says that it must occupy the same
Mind the quotes.
>> +The "cc" clobber indicates that the assembler code modifies the flags
Quotes. And @code{cc} I guess.
>> +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.
Two more.
>> +The "memory" clobber tells the compiler that the assembly code performs memory
Same here.
>> +reads or writes to items other than those listed in the input and output > > +specific register values to memory before executing the asm. Further, the
@asm
>> +compiler will not assume that any values read from memory before the
>> +@code{asm} will remain unchanged after the @code{asm}; it will reload them as
>> +needed. This effectively forms a read/write memory barrier for the compiler.
"before an @code{asm}...after that @code{asm}"
>> +Note that this clobber does not prevent the @emph{processor} from doing
>> +speculative reads past the @code{asm} statement. To stop that, you need
>> +processor-specific fence instructions.
"prevent" instead of "stop" (since with "stop" it would have already
started).
>> +An @code{asm goto} statement may not have outputs (which means that the
>> +statement is implicitly volatile). This is due to an internal restriction in
>> +the compiler: that control transfer instructions cannot have outputs. If the
I'd say "of the compiler" and omit "that" in "that control transfer...".
>> +assembler code does modify anything, use the "memory" clobber to force the
``memory''
>> +To reference a label, prefix it with @code{%l} followed by a number. This
>> +number is zero-based and includes any 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}).
I understood this one, mostly based on the example, and am wondering
how we can improve it.
Something like "@code{%l} followed by its position in GotoLabels
(starting with zero) plus the number of input arguments."
And then "For example,..." as an independent sentence, not in
parentheses.
>> +Input, output, and goto operands for extended @code{asm} can use modifiers to
>> +affect the code output to the assembler. For example, the following code uses
>> +the 'h' and 'b' modifiers for i386:
extended @code{asm} statements
Mind the quotes.
>> +@multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {masm=att} {masm=intel}
WHere does th come from here?
Should this be @var{th}?
>> +@headitem Modifier @tab Description @tab Operand @tab masm=att @tab masm=intel
@code{masm...} ?
>> +@tab Print the opcode suffix for the size of the current integer
>> operand (one of b/w/l/q).
@code{b}/@code{w}/....
> > +@tab Print the QImode name for a "high" register.
``high''
>> +Some targets require that GCC track the size of each instruction used,
>> +in order to generate correct code.
I'd omit the comma here.
>> +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.)
--- instead of --
>> +Normally, GCC's estimate is perfectly adequate to ensure that correct
"adequate", without "perfectly". That'd be an odd combination. :-)
>> +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.
"produces" -> "may produce" ?
>> +Sometimes when writing inline asm code, you need to make an operand be a
@code{asm}
Hurray, and that's it for now.
If you send an updated patch, I'd appreciate if you could also just
send a diff between the file as it is now (after the current patch
applied) and after those updates so that we can see what just changed
in between the two reviews.
As I wrote above, I approve if you make these changes -- or reply
noting where and why you did not -- and Andrew and Richard ack.
Thank you for doing this in the first place, and being persistent
in getting this applied. This surely has been a lot, I means a _lot_,
of effort!
Gerald
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-27 0:21 ` Gerald Pfeifer
@ 2014-04-27 9:32 ` Andrew Haley
2014-04-27 11:57 ` Richard Kenner
2014-04-27 23:07 ` dw
1 sibling, 1 reply; 30+ messages in thread
From: Andrew Haley @ 2014-04-27 9:32 UTC (permalink / raw)
To: Gerald Pfeifer, James Greenhalgh, limegreensocks
Cc: gcc-patches, Joseph Myers, Hans-Peter Nilsson, Richard Sandiford
On 04/26/2014 10:33 PM, Gerald Pfeifer wrote:
>>> +any symbols it references. This may result in those symbols getting discarded
>>> >> +by GCC as unreferenced.
> We can omit "by GCC" here.
We can, but we should not. We should avoid the passive voice like the
plague in technical documentation, even if doing so leads to some
slight redundancy.
Andrew.
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-27 9:32 ` Andrew Haley
@ 2014-04-27 11:57 ` Richard Kenner
2014-04-28 8:57 ` Andrew Haley
0 siblings, 1 reply; 30+ messages in thread
From: Richard Kenner @ 2014-04-27 11:57 UTC (permalink / raw)
To: aph
Cc: gcc-patches, gerald, hp, james.greenhalgh, joseph,
limegreensocks, rdsandiford
> >>> any symbols it references. This may result in those symbols getting
> >>> discarded by GCC as unreferenced.
> >
> > We can omit "by GCC" here.
>
> We can, but we should not. We should avoid the passive voice like the
> plague in technical documentation, even if doing so leads to some
> slight redundancy.
I agree, but that's still passive voice (you need not omit the actor to be
using passive voice)! Active voice (which is indeed preferred) is "This
may result in GCC discarding those symbols as unreferenced." (For those
who don't know, a good test of whether something is the passive voice is that
you *could* remove the actor and the sentence would still be grammatically
correct. That's the case above.) Writing in the passive voice with the
actor present is indeed better than the passive voice with the actor removed,
but the active voice is still the preferred style.
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-27 0:21 ` Gerald Pfeifer
2014-04-27 9:32 ` Andrew Haley
@ 2014-04-27 23:07 ` dw
2014-04-29 11:07 ` dw
2014-05-05 20:23 ` Gerald Pfeifer
1 sibling, 2 replies; 30+ messages in thread
From: dw @ 2014-04-27 23:07 UTC (permalink / raw)
To: Gerald Pfeifer
Cc: James Greenhalgh, gcc-patches, Joseph Myers, Hans-Peter Nilsson,
Andrew Haley, Richard Sandiford, Richard Kenner
> Please take my comments below into account for an updated patch, and
> once Andrew and Richard have signed of, this is then good to commit.
You did raise a technical question I'd like to get Andrew, Richard or
someone to comment on:
How does the user know what is dialect #0? Same for the others?
When I originally wrote that section, I didn't know the answer (which is
why I left it vague). Now I think I do, but I'd like someone to
confirm. On my builds of gcc, the dialects are listed (in dialect
order) under "Known assembler dialects" in "gcc --target-help". Can I
rely on this enough to put it in the docs? Is there some better source?
> (Patches of this size really are tough to review. That surely has
> contributed to the delay getting this in the tree most significantly.
True enough.
The goal of this patch was to rewrite section 6.41. That's no simple
task, since 6.41 was ~10 very full pages. Unfortunately the current
text is so random, I couldn't think of any way to update it piecemeal.
Once I started, it became clear to me that I needed to split the text
into two sections (Basic & Extended), which meant I needed a sub-menu.
Once I had the sub-menu, it seemed logical to move the rest of the
asm-related topics here as well.
It was not (and is not) my intent to try to re-work all these
asm-related topics as part of this patch. Some changes have "leaked
in," but I actually have separate files where I have started work on new
patches for these related sections. So while the text in these related
sections may be "perfectly adequate" for the moment, I plan on taking
another shot at them.
> In fact, I fell asleep over my notebook thrice reviewing this
Dang, I knew I should have put more car chases and explosions in this
thing. Maybe a love interest?
On last point for Gerald:
A number of your concerns seem to stem from reviewing this text only by
looking at the patch. I think your questions might answered by looking
at the actual generated output. While I'm sure I don't need to teach
the doc maintainer how to generate the files, if you don't have your
build environment handy, you can see the output (with all the changes
below) at:
http://www.LimeGreenSocks.com/gcc/Using-Assembly-Language-with-C.html
>>> +@menu
>>> +* Basic Asm:: Inline assembler with no operands.
>>> +* Extended Asm:: Inline assembler with operands.
>>> +* Constraints:: Constraints for asm operands
> Should this be "Asm operands" based on the other references here
> or, better @code{asm} in all cases here?
Changed to "Constraints for @code{asm} operands".
>>> +* Explicit Reg Vars:: Defining variables residing in specified registers.
> Should this be "Register" instead of just "Reg"?
> And "Variables" instead of just "Vars"?
Since reg vars wasn't really the focus of this patch, I mostly left the
existing text. It may look new in the patch because it got moved into
this new menu. I don't know why this was originally written this way
(sounds like laziness). "Register" and "Variables" make more sense to
me. That said, unless you feel strongly, I'd suggest doing this in my
upcoming RegVars patch.
>>> +* Size of an asm:: How GCC calculates the size of an asm block.
> @code{asm} ?
Changed to: Size of an asm:: How GCC calculates the size of an
@code{asm} block.
>>> +@subsection Basic Asm - Assembler Instructions with No Operands
> --- instead of -
Changed.
>>> +To create headers compatible with ISO C, write @code{__asm__} instead of
>>> +@code{asm} (@pxref{Alternate Keywords}).
> Here it's just ISO C, whereas in case of __inline__ you had ISO C90.
> Would it make sense to just use ISO C throughout?
Wow, good catch. The change to __inline__ was a mistake. I must have
modified this bit in "Inline" while searching for similar text in the
asm section. I have undone this change to inline.
As for the larger issue of "ISO C" vs "ISO C90", that's a tougher
question. Now that I've undone this change, all the inline asm stuff
says "ISO C," which is what the original text used. "ISO C90" and "ISO
C99" are sprinkled throughout the other sections in extend.texi, and I'm
reluctant to make wholesale changes to the rest of the file as part of
this patch.
>>> +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}.
> At this point the reader does not yet know the concept of those
> colons, does she? So that can be seen as a bit confusing.
I understand what you mean, however I don't see a practical solution
here. Describing the use of colons in Basic asm, only to follow it by
saying "now that you understand all that, none of it applies here" seems
like it would be even more confusing.
Saying that colons are part of Extended asm, and providing a link to
Extended asm which does describe them seems to me the best compromise.
What's more, while a sequential reading of the docs might experience the
problem you describe, does anyone actually read the docs from beginning
to end? "At this point" is an undefined term.
Is this still confusing if you look at the output?
>>> +@subsubheading Parameters
>>> +@emph{AssemblerInstructions}
>>> +@*
>>> +This is a literal string that specifies the assembler code. The string can
> Just "assembler code", without "the", would be my take, but let's see
> what native speakers so.
"The" sounds right to me. Alternate might be "thine?" Maybe not.
>>> +The GCC compiler does not parse the assembler instructions themselves and
> "GCC does". GCC stands for GNU Compiler Collection, and GNU Compiler
> Collection Compiler may be a bit confusing. ;-)
<sigh> Ok. "GCC does" it is. Changed.
>>> +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.
> Might "by the same characters normally...the target system" be more clear?
Hmm. Not to me. I'm not sure what "same" would mean in this context.
The same as what?
I'm guessing that way back at the beginning of time, this text was
originally written as:
"You may place multiple assembler instructions together in a single
@code{asm}
string, separated by semicolons."
However, not all assemblers use semicolons to separate statements. This
new text was a compromise.
I have made no change here.
>>> +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").
> Will everyone know what an instruction field is? I'm not sure it's
> that common of a term.
Hmm. I brought that text across unchanged from the original text. I
know what it means, but only because I've programmed in languages that
require it. I haven't seen an assembler that cares, but my cross
platform experience is weak.
I don't want to get into the business of describing how to format and
write assembler code. That's (well) beyond the scope of this doc. What
would you say to:
A combination that works in most places is a newline to break the
line, plus a tab character (written as "\n\t").
For people who do have to deal with instruction fields, it will just
work (and since that's their environment, they'll understand why the tab
is needed). It will also work for people who don't, while keeping the
formatting of their asm output pretty.
>>> +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 optimizer can move @code{asm} statements
>>> +relative to other code, including across jumps.
> optimizers (plural)
Changed.
>>> +GCC's optimizer 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}.
> How about just saying "GCC does not know..:"?
Changed.
>>> +@subsubheading Remarks
>>> +Using Extended @code{asm} will typically produce smaller, safer, and more
>>> +efficient code, and in most cases it is a better solution.
> Why?
As below.
>>> When writing inline assembly language outside C functions, however,
>>> you must use Basic @code{asm}. Extended @code{asm} statements have to
>>> be inside a C function.
> Might that be "outside of C functions"? Native speakers?
Could go either way. Since it bothers you: Changed.
> The way this is phrased sounds a bit negative. Is this really a
> drawback?
If it seems to you I am trying to make Basic asm sound bad, I am. There
are so many things that "look right" when written in Basic asm that just
won't work, I'm trying my best to discourage its use. There are times
when you have no choice but to use Basic, but (IMO) if possible, you
shouldn't.
>>> +Under certain circumstances, GCC may duplicate (or remove duplicates of) your
>>> +asm code as part of optimization. This can lead to unexpected duplicate
>>> +symbol errors during compilation if your asm code defines symbols or labels.
> "as part of optimization" -> "when optimizing"
I don't really see the problem here, but since it bothers you: Changed.
> @code{asm}
Changed to "if your assembly code defines"
>>> +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}.
> Here we are, this looks like (part of) the answer to my question
> "Why?" above. :-)
Exactly. It is fantastically easy to write code that looks like it
should work, only to have it not. Or worse, it might partially work and
cause weird problems downstream. While that can happen in Extended asm
too, Basic is particularly bad.
>>> +Since GCC does not parse the AssemblerInstructions, it has no visibility of
> ^^^^^^^^^^^^^^^^^^^^^
> Something wrong here.
AssemblerInstructions is the first parameter to the Basic asm.
>>> +any symbols it references. This may result in those symbols getting discarded
>>> +by GCC as unreferenced.
> We can omit "by GCC" here.
Per discussion elsewhere, changed to: This may result in GCC discarding
those symbols as unreferenced.
>>> +While Basic @code{asm} blocks are implicitly volatile, they are not treated
>>> +as though they used a "memory" clobber (@pxref{Clobbers}).
> What does it mean for a block to be volatile, as opposed to a variable?
Changed to:
Unlike Extended @code{asm}, 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}).
> Should this be ``memory'' (note the quotes)?
There's a reason I did it this way. As an example, a common use for asm is:
asm ("" : : : "memory");
Since the memory clobber actually gets enclosed in quotes when used, I
used that format when discussing it. I suppose an argument could be
made for any of:
memory
"memory"
@emph{memory}
``memory''
but I like "memory". If you have a strong feeling for one of these
alternatives, I'll change it. My recommendation is to leave it.
>>> -@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 include jumps from assembler code to C labels.
Was there a question here?
>>> +@ifhtml
>>> +asm [volatile] ( AssemblerTemplate : [OutputOperands] [ : [InputOperands] [ : [Clobbers] ] ] )
>>>
>>> -For example, here is how to use the 68881's @code{fsinx} instruction:
>>> +asm [volatile] goto ( AssemblerTemplate : : [InputOperands] : [Clobbers] : GotoLabels )
>>> +@end ifhtml
>>> +@ifnothtml
>>> +asm [volatile] ( AssemblerTemplate
>>> + : [OutputOperands]
>>> + [ : [InputOperands]
>>> + [ : [Clobbers] ] ])
> Why does the @ifhtml variant have a "goto" when the other does not?
They both have goto. Look again.
>>> +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}.)
> What does "classes of operands refer to"? This does not seem to be
> evident from the context.
Looking at it in context:
asm [volatile] ( AssemblerTemplate : [OutputOperands] [ :
[InputOperands] [ : [Clobbers] ] ] )
Looking at where the colons fall, they separate OutputOperands from
InputOperands and InputOperands from Clobbers. Observation suggests
that makes "OutputOperands", "InputOperands" and "Clobbers" the classes
in question.
On the other hand, I already knew what I meant. If this is unclear,
what would you suggest?
>>> +@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.
> This feels like it comes rather late in the flow. Wouldn't that be
> a comment pretty early on in this section?
The very first line on the Extended asm page reads:
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.
Plus, this is the very first point after listing the parameters with a
short description. I'm not sure where "up" would be? Have you looked
at this in a non-patch format (pdf, html, etc)?
>>> +Note that Extended @code{asm} statements must be inside a function. Only
>>> +Basic @code{asm} may be outside functions (@pxref{Basic Asm}).
> We had a similary paragraph earlier on. Perhaps only keep this where
> it relates to Extended statements? Not sure about this, though.
The similar text was on the Basic Asm page. It referenced the Extended
page. This text is on the Extended page, referencing back to Basic.
Since we can't know where in the docs the reader "started," each section
should acknowledge the other.
>>> +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:
> This, without the example possibly, would have been good earlier, when
> all the different classes where described.
I'm not sure where you think this would go. The syntax section followed
by the "Qualifiers" section, the "Parameters" section and the "Remarks"
section seems like a very clean approach. Perhaps this isn't as clear
when reading a patch file?
>>> +GCC's optimizer sometimes discards @code{asm} statements if it determines
>>> +that it has no need for the output variables.
> How about just saying "GCC", not referring to the optimizer here?
I'm pretty sure it only happens when running the optimizer.
>>> +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.
Is there a question here?
>>> +@code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
>>> +isn't needed you allow the optimizer to produce the most efficient code
>>> +possible.
> How about "Only including ...when it is really necessary allows the
> optimizer", that is, a more positive ("included" instead of "omitting")
> approach?
Hmm. How strongly do you feel about this one? I'm ok with the current
text.
>>> +GCC's optimizer will not treat this code like the non-volatile code in the
>>> +earlier examples. It does not move it out of loops or omit it on the
>>> +assumption that the result from a previous call is still valid.
> "GCC will..."
Again, I believe this behavior comes from the optimizer.
>>> +Under certain circumstances, GCC may duplicate (or remove duplicates of) your
>>> +asm code as part of optimization. This can lead to unexpected duplicate symbol
> @code{asm}
Changed to "assembly code".
> And did we not have the same (or very similar) statement a bit earlier?
Yes we did, but it was in a different section (Basic asm).
>>> +directives. The GCC compiler does not parse the assembler instructions
> Just "GCC".
Yes, ok. Changed.
>>> +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.
> This also looks quite familiar. Is there a way to build up and avoid
> the redundancy?
When viewed in context, I believe this is appropriate. Basic asm and
Extended asm are completely separate sections. Among other things, they
end up on separate html pages.
>>> +GCC may support multiple assembler dialects (such as "att" or "intel") for
>>> +inline assembler. The list of supported dialects depends on the implementation
>>> +details of the specific build of the compiler. When writing assembler, be
>>> +aware of which dialect is the compiler's default. Assembler code that works
>>> +correctly when compiled using one dialect will likely fail if compiled using
>>> +another.
> How about saying "When writing assembler code", since the term
> assembler is a bit ambigous?
Changed.
>>> +@example
>>> +@{ dialect0 | dialect1 | dialect2... @}
>>> +@end example
> :
?
Are you saying there is supposed to be a colon here somewhere?
>>> +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.
> How does the user know what is dialect #0? Same for the others?
When I wrote this, I didn't know the answer. Looking now, I see (at
least on my platform) they are listed in "gcc --target-help" under
"Known assembler dialects."
What I don't know is if that will be true on all supported platforms.
>>> +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.
> ``escape'' (note the quotes)
Changed. Looks freaky, but changed.
>>> +In addition to the tokens described by the input, output, and goto
>>> operands, there are a few special cases:
> How about clobbers?
Nope.
>>> +@itemize
>>> +@item
>>> +'%%' outputs a single '%' into the assembler code.
> +@item
> +'%=' outputs a number that is unique to each instance of the 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.
> @code{asm} statement
Done.
> And again the quotes don't seem right (in a few cases here).
Not sure what I was thinking here. All ' changed to ".
>>> +Output constraints must begin with either "=" (a variable overwriting an
>>> +existing value) or "+" (when reading and writing). When using "=", do not
>>> +assume the location will contain the existing value (except when tying the
>>> +variable to an input; @pxref{InputOperands,,Input Operands}).
> @code{=}
>
> @code{+}
>
> Possibly under proper quotes as well?
I tried it without quotes (@code{=}), and it looked really odd to my
eyes. The effect of the new font doesn't really show up for just a
single character like this.
I've changed this to @code{"="}. Is that what you meant?
>>> +After the prefix, there must be one or more additional constraints
>>> +(@pxref{Constraints}) that describe where the value resides. Common
>>> +constraints include "r" for register, "m" for memory, and "i" for immediate.
> Similarly here.
Not sure about this one, but I'll defer to your judgement. "r" and "m"
changed to @code{"r"} and @code{"m"}.
>>> +control to select the specific register you want, Local Reg Vars may provide
>>> +a solution (@pxref{Local Reg Vars}).
> Local Reg Vars should be properly expanded, I assume.
Well, the current title of this section really is Local Reg Vars. Unless
we want to expand this patch to start updating even more things...
>>> +Specifies the C variable name of the output (enclosed by parenthesis).
> "parentheses" (plural)
Huh. Who knew? Changed.
>>> Accepts
>>> +any (non-constant) variable within scope.
> What's a non-constant variable? Or just a constant variable?
const int a = 4; /* A constant variable */
int b = 5; /* A non-constant variable */
In summary, anything that isn't marked as "const" is not const (aka
non-constant).
>>> +@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}
> If we use qoutes, they should read `...' in a couple of cases here.
That always looks weird to me. But since you say so, I've changed it.
>>> +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
> I don't think irm should be under quotes. The entire @code{...} I
> could understand better.
Well, if I had an input parameter that accepted Immediate, Register and
Memory, it might look like this:
asm("asm goes here" : : "irm" (a));
Since the irm would actually be enclosed in quotes, that's what I used.
Let me know if you still think I should change it.
>>> +either "=" or "+". If you must use a specific register, but your Machine
> Quotes.
Not sure I'm understand here. The quotes seem appropriate. I could add
@code, but I'm not sure that's needed.
>>> +Constraints do not provide sufficient control to select the specific
>>> +register you want, Local Reg Vars may provide a solution
>>> +(@pxref{Local Reg Vars}).
> Can we use a better term than Local Reg Vars? Or is that totally
> entrenched?
Wouldn't break my heart to see it changed. As before, I'm reluctant to
do that as part of this patch. "Local Reg Vars" is what the section is
called in the existing docs. Since I'm (mostly) just moving it, I
(mostly) left it alone. Now my *next* patch...
>>> +Input constraints can also be digits (for example, @code{"0"}). This indicates
> Quotes inside of @code do not seem approriate here.
As I mentioned above, applying @code to a single character isn't
visually distinctive. Though if you feel strongly, I'll change it.
>>> +Remarks:
>>> +
>>> +The total number of input + output + goto operands has a limit of 30.
> We also had this data point earlier in the text of this patch already,
> didn't we?
It is mentioned in each of input, output and goto. If someone is
working with input parameters, assuming they saw this back in output
parameters seems a stretch.
>>> +constraint @code{"0"} for input operand 1 says that it must occupy the same
> Mind the quotes.
As I mentioned above, applying @code to a single character isn't
visually distinctive. Though if you feel strongly, I'll change it.
>>> +The "cc" clobber indicates that the assembler code modifies the flags
> Quotes. And @code{cc} I guess.
@code is correct. I've changed that.
As for the quotes around cc, my reasoning here is the same as for
"memory" (way back near the top). If we change that, we should change
this. At present, I have changed neither.
>>> +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.
> Two more.
As before.
>>> +The "memory" clobber tells the compiler that the assembly code performs memory
> Same here.
As before.
>>> +reads or writes to items other than those listed in the input and output > > +specific register values to memory before executing the asm. Further, the
> @asm
Changed.
>>> +compiler will not assume that any values read from memory before the
>>> +@code{asm} will remain unchanged after the @code{asm}; it will reload them as
>>> +needed. This effectively forms a read/write memory barrier for the compiler.
> "before an @code{asm}...after that @code{asm}"
Changed.
>>> +Note that this clobber does not prevent the @emph{processor} from doing
>>> +speculative reads past the @code{asm} statement. To stop that, you need
>>> +processor-specific fence instructions.
> "prevent" instead of "stop" (since with "stop" it would have already
> started).
Changed.
>>> +An @code{asm goto} statement may not have outputs (which means that the
>>> +statement is implicitly volatile). This is due to an internal restriction in
>>> +the compiler: that control transfer instructions cannot have outputs. If the
> I'd say "of the compiler" and omit "that" in "that control transfer...".
Changed.
>>> +assembler code does modify anything, use the "memory" clobber to force the
> ``memory''
"Memory" clobber is discussed elsewhere.
>>> +To reference a label, prefix it with @code{%l} followed by a number. This
>>> +number is zero-based and includes any 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}).
> I understood this one, mostly based on the example, and am wondering
> how we can improve it.
>
> Something like "@code{%l} followed by its position in GotoLabels
> (starting with zero) plus the number of input arguments."
>
> And then "For example,..." as an independent sentence, not in
> parentheses.
Here's what I changed this to:
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}).
>>> +Input, output, and goto operands for extended @code{asm} can use modifiers to
>>> +affect the code output to the assembler. For example, the following code uses
>>> +the 'h' and 'b' modifiers for i386:
> extended @code{asm} statements
Changed.
> Mind the quotes.
s/'/"
>>> +@multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {masm=att} {masm=intel}
> WHere does th come from here?
>
> Should this be @var{th}?
Ahh. I know a texi trick you don't?
These parameters to multitable aren't actually output into the text.
They are only used to provide a column width. And if I put the entire
sentence here (from the table below), texi won't wrap the text in that
column. Without wrapping, the text is too long for a single line when
output to pdf. By truncating where I did, it uses a sensible column
width and wraps the text nicely.
>>> +@headitem Modifier @tab Description @tab Operand @tab masm=att @tab masm=intel
> @code{masm...} ?
You think? It's not really code. How about @option?
>>> +@tab Print the opcode suffix for the size of the current integer
>>> operand (one of b/w/l/q).
> @code{b}/@code{w}/....
Hmm. Ok. Changed.
>>> +@tab Print the QImode name for a "high" register.
> ``high''
Yuck, but changed.
>>> +Some targets require that GCC track the size of each instruction used,
>>> +in order to generate correct code.
> I'd omit the comma here.
Changed.
>>> +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.)
> --- instead of --
Changed.
>>> +Normally, GCC's estimate is perfectly adequate to ensure that correct
> "adequate", without "perfectly". That'd be an odd combination. :-)
Changed.
>>> +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.
> "produces" -> "may produce" ?
Changed.
>>> +Sometimes when writing inline asm code, you need to make an operand be a
> @code{asm}
Changed.
> Hurray, and that's it for now.
Whew.
> If you send an updated patch, I'd appreciate if you could also just
> send a diff between the file as it is now (after the current patch
> applied) and after those updates so that we can see what just changed
> in between the two reviews.
I haven't attached a diff yet. Rather than fill everyone's inbox with
partial updates, I'll wait until we've agreed on the questions above.
If someone just can't wait, the web pages mentioned above have all the
items I marked as Changed.
BTW, do you want the standard "diff" output? Or diff -u?
> As I wrote above, I approve if you make these changes -- or reply
> noting where and why you did not -- and Andrew and Richard ack.
I've tried to make it clear when I made a change, and when I disagreed
with your proposed change. If my explanations as to why I didn't make a
change aren't clear or if you still disagree, let me know. There are
several points where I'm looking for your opinion or clarification
before proceeding.
I'd also like to make one last plug for having you at least page thru
one of the output formats (such as the html I linked to at the top).
While looking at the actual .texi lets you catch things like @ifhtml and
@cindex errors, I believe structure and formatting are clearer in html.
What's more, I feel confident saying more people will view the html text
than the texi, so a little extra effort to make sure the html is correct
is merited.
Thanks for your feedback,
dw
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-27 11:57 ` Richard Kenner
@ 2014-04-28 8:57 ` Andrew Haley
0 siblings, 0 replies; 30+ messages in thread
From: Andrew Haley @ 2014-04-28 8:57 UTC (permalink / raw)
To: Richard Kenner
Cc: gcc-patches, gerald, hp, james.greenhalgh, joseph,
limegreensocks, rdsandiford
On 04/27/2014 11:56 AM, Richard Kenner wrote:
>>>>> any symbols it references. This may result in those symbols getting
>>>>> discarded by GCC as unreferenced.
>>>
>>> We can omit "by GCC" here.
>>
>> We can, but we should not. We should avoid the passive voice like the
>> plague in technical documentation, even if doing so leads to some
>> slight redundancy.
>
> I agree, but that's still passive voice (you need not omit the actor to be
> using passive voice)! Active voice (which is indeed preferred) is "This
> may result in GCC discarding those symbols as unreferenced."
Indeed. That's definitely better.
Andrew.
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-27 23:07 ` dw
@ 2014-04-29 11:07 ` dw
2014-04-29 12:55 ` Richard Earnshaw
2014-05-05 20:23 ` Gerald Pfeifer
1 sibling, 1 reply; 30+ messages in thread
From: dw @ 2014-04-29 11:07 UTC (permalink / raw)
To: Gerald Pfeifer
Cc: James Greenhalgh, gcc-patches, Joseph Myers, Hans-Peter Nilsson,
Andrew Haley, Richard Sandiford, Richard Kenner
While I'm waiting to hear back from Gerald about my responses to his
other corrections, I have answered one question:
> How does the user know what is dialect #0? Same for the others?
>
> When I originally wrote that section, I didn't know the answer (which
> is why I left it vague). Now I think I do, but I'd like someone to
> confirm. On my builds of gcc, the dialects are listed (in dialect
> order) under "Known assembler dialects" in "gcc --target-help". Can I
> rely on this enough to put it in the docs? Is there some better source?
First of all, -masm is (currently) only supported on i386:
http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html
Second, i386 -masm only supports two options:
http://gcc.gnu.org/onlinedocs/gcc/i386-and-x86-64-Options.html
So, the inline asm docs could just say "att" and "intel." However,
there's a difference between using "intel" and "att" as examples of how
dialects work, and "hard coding" these names into this section as the
list of available options. I'm not keen on putting machine-specific
info like this into an otherwise machine-neutral section.
Such being the case, I replaced the previously vague paragraph with:
GCC may support multiple assembler dialects (such as "att" or "intel") 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.
This keeps the machine-specific details with the already
machine-specific compile options. While this option only applies to
i386 currently, this text leaves the option open should some other
platform make use of it in the future.
Unless someone says otherwise, I'm calling this question resolved.
dw
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-29 11:07 ` dw
@ 2014-04-29 12:55 ` Richard Earnshaw
2014-04-30 2:38 ` dw
0 siblings, 1 reply; 30+ messages in thread
From: Richard Earnshaw @ 2014-04-29 12:55 UTC (permalink / raw)
To: dw
Cc: Gerald Pfeifer, James Greenhalgh, gcc-patches, Joseph Myers,
Hans-Peter Nilsson, aph, Richard Sandiford, Richard Kenner
On 29/04/14 11:47, dw wrote:
> While I'm waiting to hear back from Gerald about my responses to his
> other corrections, I have answered one question:
>
>> How does the user know what is dialect #0? Same for the others?
>>
>> When I originally wrote that section, I didn't know the answer (which
>> is why I left it vague). Now I think I do, but I'd like someone to
>> confirm. On my builds of gcc, the dialects are listed (in dialect
>> order) under "Known assembler dialects" in "gcc --target-help". Can I
>> rely on this enough to put it in the docs? Is there some better source?
>
> First of all, -masm is (currently) only supported on i386:
> http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html
>
> Second, i386 -masm only supports two options:
> http://gcc.gnu.org/onlinedocs/gcc/i386-and-x86-64-Options.html
>
> So, the inline asm docs could just say "att" and "intel." However,
> there's a difference between using "intel" and "att" as examples of how
> dialects work, and "hard coding" these names into this section as the
> list of available options. I'm not keen on putting machine-specific
> info like this into an otherwise machine-neutral section.
>
> Such being the case, I replaced the previously vague paragraph with:
>
> GCC may support multiple assembler dialects (such as "att" or "intel") for
It's generally wise to avoid 'may' in documentation; in this case I
think 'can' is acceptable.
Also, you should be clear at the time you introduce att and intel that
you are referring to the i386 compiler. Something like: "(for example,
GCC for i386 supports "att" and "intel" dialects)".
R.
> 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.
>
> This keeps the machine-specific details with the already
> machine-specific compile options. While this option only applies to
> i386 currently, this text leaves the option open should some other
> platform make use of it in the future.
>
> Unless someone says otherwise, I'm calling this question resolved.
>
> dw
>
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-29 12:55 ` Richard Earnshaw
@ 2014-04-30 2:38 ` dw
0 siblings, 0 replies; 30+ messages in thread
From: dw @ 2014-04-30 2:38 UTC (permalink / raw)
To: Richard Earnshaw
Cc: Gerald Pfeifer, James Greenhalgh, gcc-patches, Joseph Myers,
Hans-Peter Nilsson, aph, Richard Sandiford, Richard Kenner
On 4/29/2014 5:48 AM, Richard Earnshaw wrote:
> On 29/04/14 11:47, dw wrote:
>> While I'm waiting to hear back from Gerald about my responses to his
>> other corrections, I have answered one question:
>>
>>> How does the user know what is dialect #0? Same for the others?
>>>
>>> When I originally wrote that section, I didn't know the answer (which
>>> is why I left it vague). Now I think I do, but I'd like someone to
>>> confirm. On my builds of gcc, the dialects are listed (in dialect
>>> order) under "Known assembler dialects" in "gcc --target-help". Can I
>>> rely on this enough to put it in the docs? Is there some better source?
>> First of all, -masm is (currently) only supported on i386:
>> http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html
>>
>> Second, i386 -masm only supports two options:
>> http://gcc.gnu.org/onlinedocs/gcc/i386-and-x86-64-Options.html
>>
>> So, the inline asm docs could just say "att" and "intel." However,
>> there's a difference between using "intel" and "att" as examples of how
>> dialects work, and "hard coding" these names into this section as the
>> list of available options. I'm not keen on putting machine-specific
>> info like this into an otherwise machine-neutral section.
>>
>> Such being the case, I replaced the previously vague paragraph with:
>>
>> GCC may support multiple assembler dialects (such as "att" or "intel") for
> It's generally wise to avoid 'may' in documentation; in this case I
> think 'can' is acceptable.
I understand what you mean. This very patch once had a problem where
the context didn't make it clear whether "may" meant "might" or "is
permitted." Tricky thing this English.
I think the other "may" in this paragraph is appropriate.
> Also, you should be clear at the time you introduce att and intel that
> you are referring to the i386 compiler. Something like: "(for example,
> GCC for i386 supports "att" and "intel" dialects)".
Text updated to:
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.
Thanks for the feedback,
dw
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-27 23:07 ` dw
2014-04-29 11:07 ` dw
@ 2014-05-05 20:23 ` Gerald Pfeifer
2014-05-06 5:12 ` dw
` (2 more replies)
1 sibling, 3 replies; 30+ messages in thread
From: Gerald Pfeifer @ 2014-05-05 20:23 UTC (permalink / raw)
To: dw
Cc: James Greenhalgh, gcc-patches, Joseph Myers, Hans-Peter Nilsson,
Andrew Haley, Richard Sandiford, Richard Kenner
[ Oh no! I wrote this on a plane two days ago and now it got stuck
in my outbox. Let's get this patch in before any further delays
happen. ]
On Sun, 27 Apr 2014, dw wrote:
> The goal of this patch was to rewrite section 6.41. That's no simple
> task, since 6.41 was ~10 very full pages. Unfortunately the current
> text is so random, I couldn't think of any way to update it piecemeal.
Understood. Let's see that we can get an update committed soon.
We can always improve on it further later on, which then will be
a lot easier to do, review, and get pushed.
> A number of your concerns seem to stem from reviewing this text only by
> looking at the patch. I think your questions might answered by looking
> at the actual generated output.
Right, I just did not want to delay this any further.
> Since reg vars wasn't really the focus of this patch, I mostly left the
> existing text. It may look new in the patch because it got moved into
> this new menu. I don't know why this was originally written this way
> (sounds like laziness). "Register" and "Variables" make more sense to
> me. That said, unless you feel strongly, I'd suggest doing this in my
> upcoming RegVars patch.
Okay.
> As for the larger issue of "ISO C" vs "ISO C90", that's a tougher
> question. Now that I've undone this change, all the inline asm stuff
> says "ISO C," which is what the original text used. "ISO C90" and "ISO
> C99" are sprinkled throughout the other sections in extend.texi, and I'm
> reluctant to make wholesale changes to the rest of the file as part of
> this patch.
Let's leave the asm stuff at "ISO C" unless anyone has concerns
about this.
>>>> +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}.
>> At this point the reader does not yet know the concept of those
>> colons, does she? So that can be seen as a bit confusing.
> I understand what you mean, however I don't see a practical solution
> here. Describing the use of colons in Basic asm, only to follow it by
> saying "now that you understand all that, none of it applies here" seems
> like it would be even more confusing.
>
> Saying that colons are part of Extended asm, and providing a link to
> Extended asm which does describe them seems to me the best compromise.
That'd work for me.
> What's more, while a sequential reading of the docs might experience the
> problem you describe, does anyone actually read the docs from beginning
> to end? "At this point" is an undefined term.
I've seen both uses of our documentation. This is not a biggie, I
am fine keeping it as is (or going with the compromise you suggest
above).
>>>> +This is a literal string that specifies the assembler code. The string
>>>> can
>> Just "assembler code", without "the", would be my take, but let's see
>> what native speakers so.
> "The" sounds right to me. Alternate might be "thine?" Maybe not.
Let's keep it as is, then.
>>>> +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.
>> Might "by the same characters normally...the target system" be more
>> clear?
> Hmm. Not to me. I'm not sure what "same" would mean in this context.
> The same as what?
Actually, reading this again after a couple of days, I'm not sure
what triggered my comment. Now this works just fine.
>>>> +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").
>> Will everyone know what an instruction field is? I'm not sure it's
>> that common of a term.
> Hmm. I brought that text across unchanged from the original text. I
> know what it means, but only because I've programmed in languages that
> require it. I haven't seen an assembler that cares, but my cross
> platform experience is weak.
>
> I don't want to get into the business of describing how to format and
> write assembler code. That's (well) beyond the scope of this doc.
> What would you say to:
>
> A combination that works in most places is a newline to break the
> line, plus a tab character (written as "\n\t").
Yep, that sounds good.
> If it seems to you I am trying to make Basic asm sound bad, I am. There
> are so many things that "look right" when written in Basic asm that just
> won't work, I'm trying my best to discourage its use.
Fair enough. :-)
>>>> +Since GCC does not parse the AssemblerInstructions, it has no
>>>> visibility of
>> ^^^^^^^^^^^^^^^^^^^^^
>> Something wrong here.
> AssemblerInstructions is the first parameter to the Basic asm.
Right. I think I was expecting this to be in @var{...}, but no
need to change this for now. This could be part of a general
patch doing that consistently later on.
>> Should this be ``memory'' (note the quotes)?
> There's a reason I did it this way. As an example, a common use for asm is:
>
> asm ("" : : : "memory");
>
> Since the memory clobber actually gets enclosed in quotes when used, I used
> that format when discussing it. I suppose an argument could be made for any
> of:
>
> memory
> "memory"
> @emph{memory}
> ``memory''
>
> but I like "memory". If you have a strong feeling for one of these
> alternatives, I'll change it. My recommendation is to leave it.
Or @code{memory} or code{"memory"}. ;-) What do you think? No need
to change if you prefer not to.
> Was there a question here?
No, just an extensive (excessive) quote.
>>>> +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}.)
>> What does "classes of operands refer to"? This does not seem to be
>> evident from the context.
> Looking at it in context:
>
> asm [volatile] ( AssemblerTemplate : [OutputOperands] [ : [InputOperands] [ :
> [Clobbers] ] ] )
>
> Looking at where the colons fall, they separate OutputOperands from
> InputOperands and InputOperands from Clobbers. Observation suggests that
> makes "OutputOperands", "InputOperands" and "Clobbers" the classes in
> question.
>
> On the other hand, I already knew what I meant. If this is unclear,
> what would you suggest?
I also guessed what this meant, still I am wondering whether there
might be a better term for this than classes.
>> We had a similary paragraph earlier on. Perhaps only keep this where
>> it relates to Extended statements? Not sure about this, though.
> The similar text was on the Basic Asm page. It referenced the Extended
> page. This text is on the Extended page, referencing back to Basic.
> Since we can't know where in the docs the reader "started," each
> section should acknowledge the other.
Absolutely, I am a big fan of cross-references. I was wondering
whether we might be able to abstract things into a common part, but
that then makes things harder to read with a more tricky flow, so I
am fine leaving it as is.
>>>> +GCC's optimizer sometimes discards @code{asm} statements if it
>>>> determines
>>>> +that it has no need for the output variables.
>> How about just saying "GCC", not referring to the optimizer here?
> I'm pretty sure it only happens when running the optimizer.
There is just no such thing as "the GCC optimizer". There are many
optimizations that occur at different phases of translation, and
individual passes, just not one clearly demarked and defined optimizer.
That was behind my comment.
>>> +@code{DoCheck} routine. By omitting the @code{volatile} qualifier when
>>> it
>>> +isn't needed you allow the optimizer to produce the most efficient code
>>> +possible.
>> How about "Only including ...when it is really necessary allows the
>> optimizer", that is, a more positive ("included" instead of "omitting")
>> approach?
> Hmm. How strongly do you feel about this one? I'm ok with the current
> text.
The current one text is okay, I just think making this more "active"
and defaulting to _not_ using it as oppoed to assume usage and omitting
in case is a bit better.
>>>> +GCC's optimizer will not treat this code like the non-volatile code in
>>>> the
>>>> +earlier examples. It does not move it out of loops or omit it on the
>>>> +assumption that the result from a previous call is still valid.
>> "GCC will..."
> Again, I believe this behavior comes from the optimizer.
See above.
>>>> +@example
>>>> +@{ dialect0 | dialect1 | dialect2... @}
>>>> +@end example
>> :
> ?
>
> Are you saying there is supposed to be a colon here somewhere?
No, that was just a contracted form of quoting I sometimes use as
opposed to the more correct
> [...]
or similar.
>> @code{=}
>>
>> @code{+}
>>
>> Possibly under proper quotes as well?
> I tried it without quotes (@code{=}), and it looked really odd to my
> eyes. The effect of the new font doesn't really show up for just a
> single character like this.
>
> I've changed this to @code{"="}. Is that what you meant?
This is a question for Joseph. I see how a single character
under @code{} won't work, yet @code{"="} doesn't feel right,
either. Perhaps ``@code{=}''?
Let's defer this and raise with Joseph separately, unless he
responds here.
>> Local Reg Vars should be properly expanded, I assume.
> Well, the current title of this section really is Local Reg Vars. Unless
> we want to expand this patch to start updating even more things...
I agree to get this patch in with minimal changes now and rather
follow up with other changes later on.
>>>> Accepts
>>>> +any (non-constant) variable within scope.
>> What's a non-constant variable? Or just a constant variable?
> const int a = 4; /* A constant variable */
> int b = 5; /* A non-constant variable */
>
> In summary, anything that isn't marked as "const" is not const (aka
> non-constant).
Yeah, it's just a bit unintuitive to combine constant and variable
to describe one and the same entity. If the language standards use
that, so be it.
>>>> + Either "=" or "+". If you must use a specific register, but your
>>>> Machine
>> Quotes.
> Not sure I'm understand here. The quotes seem appropriate. I could add
> @code, but I'm not sure that's needed.
That's just another instance of the "Let's see what Joseph thinks"
item above.
>>>> +Input constraints can also be digits (for example, @code{"0"}). This
>>>> indicates
>> Quotes inside of @code do not seem approriate here.
> As I mentioned above, applying @code to a single character isn't
> visually distinctive. Though if you feel strongly, I'll change it.
Let's queue this with the other "Joseph" changes.
>>>> +constraint @code{"0"} for input operand 1 says that it must occupy the
>>>> same
>> Mind the quotes.
> As I mentioned above, applying @code to a single character isn't
> visually distinctive. Though if you feel strongly, I'll change it.
And this.
> 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}).
Sounds good.
>>>> +@multitable {Modifier} {Print the opcode suffix for the size of th}
>>>> {Operand} {masm=att} {masm=intel}
>> WHere does th come from here?
> Ahh. I know a texi trick you don't?
That's not super hard. :-)
> These parameters to multitable aren't actually output into the text.
> They are only used to provide a column width. And if I put the entire
> sentence here (from the table below), texi won't wrap the text in that
> column. Without wrapping, the text is too long for a single line when
> output to pdf. By truncating where I did, it uses a sensible column
> width and wraps the text nicely.
Makes sense. Thanks for the explanation!
>>>> +@headitem Modifier @tab Description @tab Operand @tab masm=att @tab
>>>> masm=intel
>> @code{masm...} ?
> You think? It's not really code. How about @option?
Yes! That was me being stuck with too much web page work, where
we only have <code>.
> BTW, do you want the standard "diff" output? Or diff -u?
Usually diff -u, though I can grok both. Either way, in a number
of cases diff was not too helpful with this patch. Not your fault
at all, and diff behaved as designed, as a human we would have made
some different choices.
Where I did not comment in this reply of mine, I was good or there
was nothing I felt was open.
> I'd also like to make one last plug for having you at least page thru
> one of the output formats (such as the html I linked to at the top).
> While looking at the actual .texi lets you catch things like @ifhtml and
> @cindex errors, I believe structure and formatting are clearer in html.
> What's more, I feel confident saying more people will view the html text
> than the texi, so a little extra effort to make sure the html is correct
> is merited.
I'll try to do that at a later point in time. Let's not delay the
patch over this.
Given their involvement from the technical side, I'd suggest that
Andrew or Richard commit the patch after the last final tweaks from
your side.
Thanks for your push to fix this up and your persistence!
Gerald
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-05-05 20:23 ` Gerald Pfeifer
@ 2014-05-06 5:12 ` dw
2014-05-07 5:47 ` dw
2014-05-06 7:58 ` Andrew Haley
2014-05-07 16:55 ` Joseph S. Myers
2 siblings, 1 reply; 30+ messages in thread
From: dw @ 2014-05-06 5:12 UTC (permalink / raw)
To: Gerald Pfeifer
Cc: James Greenhalgh, gcc-patches, Joseph Myers, Hans-Peter Nilsson,
Andrew Haley, Richard Sandiford, Richard Kenner
>>>>> +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").
>>> Will everyone know what an instruction field is? I'm not sure it's
>>> that common of a term.
>> Hmm. I brought that text across unchanged from the original text. I
>> know what it means, but only because I've programmed in languages that
>> require it. I haven't seen an assembler that cares, but my cross
>> platform experience is weak.
>>
>> I don't want to get into the business of describing how to format and
>> write assembler code. That's (well) beyond the scope of this doc.
>> What would you say to:
>>
>> A combination that works in most places is a newline to break the
>> line, plus a tab character (written as "\n\t").
> Yep, that sounds good.
Changed.
>>>>> +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}.)
>>> What does "classes of operands refer to"? This does not seem to be
>>> evident from the context.
>> Looking at it in context:
>>
>> asm [volatile] ( AssemblerTemplate : [OutputOperands] [ : [InputOperands] [ :
>> [Clobbers] ] ] )
>>
>> Looking at where the colons fall, they separate OutputOperands from
>> InputOperands and InputOperands from Clobbers. Observation suggests that
>> makes "OutputOperands", "InputOperands" and "Clobbers" the classes in
>> question.
>>
>> On the other hand, I already knew what I meant. If this is unclear,
>> what would you suggest?
> I also guessed what this meant, still I am wondering whether there
> might be a better term for this than classes.
While I can think of some alternatives ("groupings?"), none of them seem
any clearer than "classes." asm is doing something unusual here, so
none of the familiar terms apply.
>>>>> +GCC's optimizer sometimes discards @code{asm} statements if it
>>>>> determines
>>>>> +that it has no need for the output variables.
>>> How about just saying "GCC", not referring to the optimizer here?
>> I'm pretty sure it only happens when running the optimizer.
> There is just no such thing as "the GCC optimizer". There are many
> optimizations that occur at different phases of translation, and
> individual passes, just not one clearly demarked and defined optimizer.
> That was behind my comment.
I have modified this (and all other occurrences) to be plural. That
seems to be consistent with the surrounding text when it uses this term.
>>>> +@code{DoCheck} routine. By omitting the @code{volatile} qualifier when
>>>> it
>>>> +isn't needed you allow the optimizer to produce the most efficient code
>>>> +possible.
>>> How about "Only including ...when it is really necessary allows the
>>> optimizer", that is, a more positive ("included" instead of "omitting")
>>> approach?
>> Hmm. How strongly do you feel about this one? I'm ok with the current
>> text.
> The current one text is okay, I just think making this more "active"
> and defaulting to _not_ using it as oppoed to assume usage and omitting
> in case is a bit better.
The problem is, I'm not convinced that's the way *users* approach it.
In my (still limited) experience, people use volatile simply because
they aren't quite sure what it does. They used it "just to be safe."
And that's true: At worst, including it when it isn't needed produces
inefficient code. Omitting it when it is needed produces incorrect
code. So it -is- safer.
But I want to break people from that mindset. They should understand
what it does and use it appropriately. That's why this 'volatile'
section is so long. I'm hoping that explaining and exampling and subtle
phrasing will move people in the right direction.
> Let's queue this with the other "Joseph" changes.
I'm sorry if I'm leaving a mess for you guys to clean up. But even with
these bits unchanged, it's WAY better than it was.
>>>>> +@headitem Modifier @tab Description @tab Operand @tab masm=att @tab
>>>>> masm=intel
>>> @code{masm...} ?
>> You think? It's not really code. How about @option?
> Yes! That was me being stuck with too much web page work, where
> we only have <code>.
Changed.
> Given their involvement from the technical side, I'd suggest that
> Andrew or Richard commit the patch after the last final tweaks from
> your side.
So, at this point I have:
- Made the modifications described above.
- Updated the web pages on LGS.
- Produced the diff you requested of the changes since the last patch:
http://www.LimeGreenSocks/gcc/g02.zip
- Produced a new .patch file: http://www.LimeGreenSocks/gcc/extend08.zip
Unless I hear otherwise, I will post the updated patch (with a corrected
changelog) on this thread ~24 hours from this post.
It can then be committed as per usual.
dw
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-05-05 20:23 ` Gerald Pfeifer
2014-05-06 5:12 ` dw
@ 2014-05-06 7:58 ` Andrew Haley
2014-05-29 10:24 ` Eric Botcazou
2014-05-07 16:55 ` Joseph S. Myers
2 siblings, 1 reply; 30+ messages in thread
From: Andrew Haley @ 2014-05-06 7:58 UTC (permalink / raw)
To: Gerald Pfeifer, dw
Cc: James Greenhalgh, gcc-patches, Joseph Myers, Hans-Peter Nilsson,
Richard Sandiford, Richard Kenner
On 05/05/2014 09:23 PM, Gerald Pfeifer wrote:
> Understood. Let's see that we can get an update committed soon.
> We can always improve on it further later on, which then will be
> a lot easier to do, review, and get pushed.
Yes. We already know that this is better than the current docs.
Let's check it in.
Andrew.
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-05-06 5:12 ` dw
@ 2014-05-07 5:47 ` dw
0 siblings, 0 replies; 30+ messages in thread
From: dw @ 2014-05-07 5:47 UTC (permalink / raw)
To: Andrew Haley, Gerald Pfeifer
Cc: James Greenhalgh, gcc-patches, Joseph Myers, Hans-Peter Nilsson,
Richard Sandiford, Richard Kenner
[-- Attachment #1: Type: text/plain, Size: 1007 bytes --]
> Given their involvement from the technical side, I'd suggest that
> Andrew or Richard commit the patch after the last final tweaks from
> your side.
So Andrew:
- "Last final tweaks" have been made and a day has passed for final
comments.
- changelog uses 2 spaces before and after names, text < 80 chars, has
'doc/' prefix.
As near as I know, I'm done. Looks like you're up.
Problem description:
The existing documentation does an inadequate job of describing gcc's
implementation of the "asm" keyword. This has led to a great deal of
confusion as people struggle to understand how it works. This entire
section requires a rewrite that provides a structured layout and
detailed descriptions of each of the parameters along with examples.
ChangeLog:
2014-04-03 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.
dw
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: extend.texi.patch --]
[-- Type: text/x-patch; name="extend.texi.patch", Size: 63764 bytes --]
Index: extend.texi
===================================================================
--- extend.texi (revision 210031)
+++ extend.texi (working copy)
@@ -65,11 +65,7 @@
* 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,492 +6133,949 @@
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] ] ] )
-For example, here is how to use the 68881's @code{fsinx} instruction:
+asm [volatile] goto ( AssemblerTemplate : : [InputOperands] : [Clobbers] : GotoLabels )
+@end ifhtml
+@ifnothtml
+asm [volatile] ( AssemblerTemplate
+ : [OutputOperands]
+ [ : [InputOperands]
+ [ : [Clobbers] ] ])
-@smallexample
-asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
-@end smallexample
+asm [volatile] goto ( AssemblerTemplate
+ :
+ : [InputOperands]
+ : [Clobbers]
+ : GotoLabels)
+@end ifnothtml
+@end example
-@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}).
+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}.
-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@.
+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}.)
-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.
+@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}.
-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:
+@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}.
-@smallexample
-asm ("fsinx %[angle],%[output]"
- : [output] "=f" (result)
- : [angle] "f" (angle));
-@end smallexample
+@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}.
-@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.
+@emph{OutputOperands}
+@*
+A comma-separated list of the C variables modified by the instructions in the
+AssemblerTemplate. @xref{OutputOperands}.
-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.
+@emph{InputOperands}
+@*
+A comma-separated list of C expressions read by the instructions in the
+AssemblerTemplate. @xref{InputOperands}.
-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.
+@emph{Clobbers}
+@*
+A comma-separated list of registers or other values changed by the
+AssemblerTemplate, beyond those listed as outputs. @xref{Clobbers}.
-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:
+@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}.
-@smallexample
-asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
-@end smallexample
+@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.
-@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.
+Note that Extended @code{asm} statements must be inside a function. Only
+Basic @code{asm} may be outside functions (@pxref{Basic Asm}).
-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:
+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 ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
-@end smallexample
+@example
+int src = 1;
+int dst;
-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.
+asm ("mov %1, %0\n\t"
+ "add $1, %0"
+ : "=r" (dst)
+ : "r" (src));
-As of GCC version 3.1, one may write @code{[@var{name}]} instead of
-the operand number for a matching constraint. For example:
+printf("%d\n", dst);
+@end example
-@smallexample
-asm ("cmoveq %1,%2,%[result]"
- : [result] "=r"(result)
- : "r" (test), "r"(new), "[result]"(old));
-@end smallexample
+This code will copy @var{src} to @var{dst} and add 1 to @var{dst}.
-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:
+@anchor{Volatile}
+@subsubsection Volatile
+@cindex volatile @code{asm}
+@cindex @code{asm} volatile
-@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
+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.
-@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:
+Examples:
-@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
+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.
-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:
+@example
+void DoCheck(uint32_t dwSomeValue)
+@{
+ uint32_t dwRes;
-@smallexample
-asm volatile ("movc3 %0,%1,%2"
- : /* @r{no outputs} */
- : "g" (from), "g" (to), "g" (count)
- : "r0", "r1", "r2", "r3", "r4", "r5");
-@end smallexample
+ // Assumes dwSomeValue is not zero.
+ asm ("bsfl %1,%0"
+ : "=r" (dwRes)
+ : "r" (dwSomeValue)
+ : "cc");
-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.
+ assert(dwRes > 3);
+@}
+@end example
-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.
+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.
-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.
+@example
+void do_print(uint32_t dwSomeValue)
+@{
+ uint32_t dwRes;
-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:
+ for (uint32_t x=0; x < 5; x++)
+ @{
+ // Assumes dwSomeValue is not zero.
+ asm ("bsfl %1,%0"
+ : "=r" (dwRes)
+ : "r" (dwSomeValue)
+ : "cc");
-@smallexample
-@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}.
-@end smallexample
-
-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;
+ printf("%u: %u %u\n", x, dwSomeValue, dwRes);
+ @}
@}
-@end smallexample
+@end example
-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:
+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 ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo"
- : /* no outputs */
- : "g" (from), "g" (to)
- : "r9", "r10");
-@end smallexample
+@example
+uint64_t msr;
-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}.
+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 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:
+printf("msr: %llx\n", msr);
-@smallexample
-asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
- : "g" (result)
- : "g" (input));
-@end smallexample
+// Do other work...
-@noindent
-This assumes your assembler supports local labels, as the GNU assembler
-and most Unix assemblers do.
+// 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");
-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}.
+printf("msr: %llx\n", msr);
+@end example
-@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,
+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.
-@smallexample
-#define sin(x) \
-(@{ double __value, __arg = (x); \
- asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
- __value; @})
-@end smallexample
+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.
-@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}.
+@example
+asm volatile("mtfsf 255, %0" : : "f" (fpenv));
+sum = x + y;
+@end example
-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.
+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 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.
+@example
+asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
+sum = x + y;
+@end example
-You can prevent an @code{asm} instruction from being deleted
-by writing the keyword @code{volatile} after
-the @code{asm}. For example:
+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.
-@smallexample
-#define get_and_set_priority(new) \
-(@{ int __old; \
- asm volatile ("get_and_set_priority %0, %1" \
- : "=g" (__old) : "g" (new)); \
- __old; @})
-@end smallexample
+@anchor{AssemblerTemplate}
+@subsubsection Assembler Template
+@cindex @code{asm} assembler template
-@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:
+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}).
-@smallexample
- asm volatile("mtfsf 255,%0" : : "f" (fpenv));
- sum = x + y;
-@end smallexample
+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.
-@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:
+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.
-@smallexample
- asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv));
- sum = x + y;
-@end smallexample
+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.
-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.
+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.
-An @code{asm} instruction without any output operands is treated
-identically to a volatile @code{asm} instruction.
+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.
-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 Using braces in @code{asm} templates
-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.
+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:
-@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.
+@example
+@{ dialect0 | dialect1 | dialect2... @}
+@end example
-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.
+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.
-@smallexample
+For example, if an i386 compiler supports two dialects (att, intel), an
+assembler template such as this:
+
+@example
+"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
+@end example
+
+would produce the output:
+
+@example
+For att: "btl %[Offset],%[Base] ; jc %l2"
+For intel: "bt %[Base],%[Offset]; jc %l2"
+@end example
+
+Using that same compiler, this code:
+
+@example
+"xchg@{l@}\t@{%%@}ebx, %1"
+@end example
+
+would produce
+
+@example
+For att: "xchgl\t%%ebx, %1"
+For intel: "xchg\tebx, %1"
+@end example
+
+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.
+
+@subsubheading Other format strings
+
+In addition to the tokens described by the input, output, and goto operands,
+there are a few special cases:
+
+@itemize
+@item
+"%%" outputs a single "%" into the assembler code.
+
+@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.
+
+@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)
-@{
- 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 ();
+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:
- label1:
- f1();
- return;
- label2:
- f2();
- return;
- label3:
- i = 1;
- label4:
- f3(i);
-@}
-@end smallexample
+@example
+uint16_t num;
+asm volatile ("xchg %h0, %b0" : "+a" (num) );
+@end example
-@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.
+These modifiers generate this assembler code:
-@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
+@example
+xchg %ah, %al
+@end example
-@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}.
+The rest of this discussion uses the following code for illustrative purposes.
-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}.
+@example
+int main()
+@{
+ int iInt = 1;
-@subsection Size of an @code{asm}
+top:
-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.
+ asm volatile goto ("some assembler instructions here"
+ : /* No outputs. */
+ : "q" (iInt), "X" (sizeof(unsigned char) + 1)
+ : /* No clobbers. */
+ : top);
+@}
+@end example
-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.
+With no modifiers, this is what the output from the operands would be for the
+att and intel dialects of assembler:
-@subsection i386 floating-point asm operands
+@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
+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
+
+@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
that are stack-like registers:
@@ -6715,10 +7168,34 @@
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 @@
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 @@
@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 @@
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,22 +7423,38 @@
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
@cindex alternate keywords
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-05-05 20:23 ` Gerald Pfeifer
2014-05-06 5:12 ` dw
2014-05-06 7:58 ` Andrew Haley
@ 2014-05-07 16:55 ` Joseph S. Myers
2 siblings, 0 replies; 30+ messages in thread
From: Joseph S. Myers @ 2014-05-07 16:55 UTC (permalink / raw)
To: Gerald Pfeifer
Cc: dw, James Greenhalgh, gcc-patches, Hans-Peter Nilsson,
Andrew Haley, Richard Sandiford, Richard Kenner
On Mon, 5 May 2014, Gerald Pfeifer wrote:
> > I've changed this to @code{"="}. Is that what you meant?
>
> This is a question for Joseph. I see how a single character
> under @code{} won't work, yet @code{"="} doesn't feel right,
> either. Perhaps ``@code{=}''?
If you are referring to an actual string constant
"="
in the user's source code, then @code{"="} is correct. If you are
referring just to the single character
=
in the user's source code, whether as a token on its own or as part of a
larger token, then @samp{=} is the way to get it quoted (with the
character being in a fixed-width font, but the quotes around it not being
in such a font).
--
Joseph S. Myers
joseph@codesourcery.com
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-05-06 7:58 ` Andrew Haley
@ 2014-05-29 10:24 ` Eric Botcazou
2014-05-29 11:51 ` Andrew Haley
0 siblings, 1 reply; 30+ messages in thread
From: Eric Botcazou @ 2014-05-29 10:24 UTC (permalink / raw)
To: Andrew Haley
Cc: dw, gcc-patches, Gerald Pfeifer, James Greenhalgh, Joseph Myers,
Hans-Peter Nilsson, Richard Sandiford, Richard Kenner
> Yes. We already know that this is better than the current docs.
> Let's check it in.
As far as I can see you did it, but didn't add a ChangeLog entry (so David
isn't properly credited with the rewrite)?
--
Eric Botcazou
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-05-29 10:24 ` Eric Botcazou
@ 2014-05-29 11:51 ` Andrew Haley
2014-05-29 21:18 ` Eric Botcazou
0 siblings, 1 reply; 30+ messages in thread
From: Andrew Haley @ 2014-05-29 11:51 UTC (permalink / raw)
To: Eric Botcazou
Cc: dw, gcc-patches, Gerald Pfeifer, James Greenhalgh, Joseph Myers,
Hans-Peter Nilsson, Richard Sandiford, Richard Kenner
On 05/29/2014 11:22 AM, Eric Botcazou wrote:
>> Yes. We already know that this is better than the current docs.
>> Let's check it in.
>
> As far as I can see you did it, but didn't add a ChangeLog entry (so David
> isn't properly credited with the rewrite)?
Fixed.
Thanks,
Andrew.
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-05-29 11:51 ` Andrew Haley
@ 2014-05-29 21:18 ` Eric Botcazou
0 siblings, 0 replies; 30+ messages in thread
From: Eric Botcazou @ 2014-05-29 21:18 UTC (permalink / raw)
To: Andrew Haley
Cc: gcc-patches, dw, Gerald Pfeifer, James Greenhalgh, Joseph Myers,
Hans-Peter Nilsson, Richard Sandiford, Richard Kenner
> Fixed.
Thanks!
--
Eric Botcazou
^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: [DOC PATCH] Rewrite docs for inline asm
2014-04-04 19:48 [DOC PATCH] Rewrite docs for inline asm dw
2014-04-08 23:17 ` Hans-Peter Nilsson
@ 2016-06-17 14:54 ` Andrew Haley
1 sibling, 0 replies; 30+ messages in thread
From: Andrew Haley @ 2016-06-17 14:54 UTC (permalink / raw)
To: dw, gcc-patches; +Cc: rdsandiford
On 04/04/14 20:48, dw wrote:
> I do not have write permissions to check this patch in.
We must fix that.
Andrew.
^ permalink raw reply [flat|nested] 30+ messages in thread
end of thread, other threads:[~2016-06-17 14:54 UTC | newest]
Thread overview: 30+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-04-04 19:48 [DOC PATCH] Rewrite docs for inline asm dw
2014-04-08 23:17 ` Hans-Peter Nilsson
2014-04-09 5:02 ` Michael Matz
2014-04-09 5:29 ` dw
2014-04-10 21:44 ` dw
2014-04-13 1:47 ` Hans-Peter Nilsson
2014-04-13 9:42 ` dw
2014-04-14 0:46 ` Hans-Peter Nilsson
2014-04-14 6:25 ` dw
2014-04-23 3:44 ` Chung-Ju Wu
2014-04-23 5:52 ` Chung-Ju Wu
2014-04-25 15:45 ` James Greenhalgh
2014-04-25 15:59 ` Andrew Haley
2014-04-27 0:21 ` Gerald Pfeifer
2014-04-27 9:32 ` Andrew Haley
2014-04-27 11:57 ` Richard Kenner
2014-04-28 8:57 ` Andrew Haley
2014-04-27 23:07 ` dw
2014-04-29 11:07 ` dw
2014-04-29 12:55 ` Richard Earnshaw
2014-04-30 2:38 ` dw
2014-05-05 20:23 ` Gerald Pfeifer
2014-05-06 5:12 ` dw
2014-05-07 5:47 ` dw
2014-05-06 7:58 ` Andrew Haley
2014-05-29 10:24 ` Eric Botcazou
2014-05-29 11:51 ` Andrew Haley
2014-05-29 21:18 ` Eric Botcazou
2014-05-07 16:55 ` Joseph S. Myers
2016-06-17 14:54 ` Andrew Haley
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).