Skip to content

R
riscv-gcc-1
Commit d719aff9 by Sandra Loosemore Committed by Sandra Loosemore
Options

extend.texi (Function Attributes [naked]): Copy-edit. 

2015-02-07  Sandra Loosemore  <sandra@codesourcery.com>

	gcc/
	* doc/extend.texi (Function Attributes [naked]): Copy-edit.
	(Using Assembly Language with C): Expand introduction.
	(Basic Asm): Copy-edit.  Add more information about uses of
	basic asm.
	(Extended Asm): Copy-edit.  Document new escape syntax and
	%l[label] syntax.
	(Global Reg Vars): Copy-edit.
	(Local Reg Vars): Likewise.

From-SVN: r220506
parent 1060d940
Showing with 391 additions and 322 deletions
gcc/ChangeLog
2015-02-07 Sandra Loosemore <sandra@codesourcery.com>
* doc/extend.texi (Function Attributes [naked]): Copy-edit.
(Using Assembly Language with C): Expand introduction.
(Basic Asm): Copy-edit. Add more information about uses of
basic asm.
(Extended Asm): Copy-edit. Document new escape syntax and
%l[label] syntax.
(Global Reg Vars): Copy-edit.
(Local Reg Vars): Likewise.
2015-02-06 David Edelsohn <dje.gcc@gmail.com> 2015-02-06 David Edelsohn <dje.gcc@gmail.com>
PR debug/2714 PR debug/2714
......
gcc/doc/extend.texi
...@@ -3396,10 +3396,10 @@ This attribute is available on the ARM, AVR, MCORE, MSP430, NDS32, ...@@ -3396,10 +3396,10 @@ This attribute is available on the ARM, AVR, MCORE, MSP430, NDS32,
RL78, RX and SPU ports. It allows the compiler to construct the RL78, RX and SPU ports. It allows the compiler to construct the
requisite function declaration, while allowing the body of the requisite function declaration, while allowing the body of the
function to be assembly code. The specified function will not have function to be assembly code. The specified function will not have
prologue/epilogue sequences generated by the compiler. Only Basic prologue/epilogue sequences generated by the compiler. Only basic
@code{asm} statements can safely be included in naked functions @code{asm} statements can safely be included in naked functions
(@pxref{Basic Asm}). While using Extended @code{asm} or a mixture of (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
Basic @code{asm} and ``C'' code may appear to work, they cannot be basic @code{asm} and C code may appear to work, they cannot be
depended upon to work reliably and are not supported. depended upon to work reliably and are not supported.
@item near @item near
...@@ -6382,12 +6382,25 @@ access hardware. ...@@ -6382,12 +6382,25 @@ access hardware.
@node Using Assembly Language with C @node Using Assembly Language with C
@section How to Use Inline Assembly Language in C Code @section How to Use Inline Assembly Language in C Code
@cindex @code{asm} keyword
GCC provides various extensions that allow you to embed assembler within @cindex assembly language in C
C code. @cindex inline assembly language
@cindex mixing assembly language and C
The @code{asm} keyword allows you to embed assembler instructions
within C code. GCC provides two forms of inline @code{asm}
statements. A @dfn{basic @code{asm}} statement is one with no
operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}}
statement (@pxref{Extended Asm}) includes one or more operands.
The extended form is preferred for mixing C and assembly language
within a function, but to include assembly language at
top level you must use basic @code{asm}.
You can also use the @code{asm} keyword to override the assembler name
for a C symbol, or to place a C variable in a specific register.
@menu @menu
* Basic Asm:: Inline assembler with no operands. * Basic Asm:: Inline assembler without operands.
* Extended Asm:: Inline assembler with operands. * Extended Asm:: Inline assembler with operands.
* Constraints:: Constraints for @code{asm} operands * Constraints:: Constraints for @code{asm} operands
* Asm Labels:: Specifying the assembler name to use for a C symbol. * Asm Labels:: Specifying the assembler name to use for a C symbol.
...@@ -6396,92 +6409,105 @@ C code. ...@@ -6396,92 +6409,105 @@ C code.
@end menu @end menu
@node Basic Asm @node Basic Asm
@subsection Basic Asm --- Assembler Instructions with No Operands @subsection Basic Asm --- Assembler Instructions Without Operands
@cindex basic @code{asm} @cindex basic @code{asm}
@cindex assembly language in C, basic
The @code{asm} keyword allows you to embed assembler instructions within A basic @code{asm} statement has the following syntax:
C code.
@example @example
asm [ volatile ] ( AssemblerInstructions ) asm @r{[} volatile @r{]} ( @var{AssemblerInstructions} )
@end example @end example
To create headers compatible with ISO C, write @code{__asm__} instead of The @code{asm} keyword is a GNU extension.
When writing code that can be compiled with @option{-ansi} and the
various @option{-std} options, use @code{__asm__} instead of
@code{asm} (@pxref{Alternate Keywords}). @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 @subsubheading Qualifiers
@emph{volatile} @table @code
@* @item volatile
This optional qualifier has no effect. All Basic @code{asm} blocks are The optional @code{volatile} qualifier has no effect.
implicitly volatile. All basic @code{asm} blocks are implicitly volatile.
@end table
@subsubheading Parameters @subsubheading Parameters
@emph{AssemblerInstructions} @table @var
@*
@item AssemblerInstructions
This is a literal string that specifies the assembler code. The string can This is a literal string that specifies the assembler code. The string can
contain any instructions recognized by the assembler, including directives. contain any instructions recognized by the assembler, including directives.
GCC does not parse the assembler instructions themselves and GCC does not parse the assembler instructions themselves and
does not know what they mean or even whether they are valid assembler input. 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} You may place multiple assembler instructions together in a single @code{asm}
string, separated by the characters normally used in assembly code for the 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 system. A combination that works in most places is a newline to break the
line, plus a tab character (written as "\n\t"). line, plus a tab character (written as @samp{\n\t}).
Some assemblers allow semicolons as a line separator. However, Some assemblers allow semicolons as a line separator. However,
note that some assembler dialects use semicolons to start a comment. note that some assembler dialects use semicolons to start a comment.
@end table
@subsubheading Remarks
Using extended @code{asm} typically produces smaller, safer, and more
efficient code, and in most cases it is a better solution than basic
@code{asm}. However, there are two situations where only basic @code{asm}
can be used:
@itemize @bullet
@item
Extended @code{asm} statements have to be inside a C
function, so to write inline assembly language at file scope (``top-level''),
outside of C functions, you must use basic @code{asm}.
You can use this technique to emit assembler directives,
define assembly language macros that can be invoked elsewhere in the file,
or write entire functions in assembly language.
@item
Functions declared
with the @code{naked} attribute also require basic @code{asm}
(@pxref{Function Attributes}).
@end itemize
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}.
Do not expect a sequence of @code{asm} statements to remain perfectly Do not expect a sequence of @code{asm} statements to remain perfectly
consecutive after compilation. If certain instructions need to remain consecutive after compilation. If certain instructions need to remain
consecutive in the output, put them in a single multi-instruction asm consecutive in the output, put them in a single multi-instruction @code{asm}
statement. Note that GCC's optimizers can move @code{asm} statements statement. Note that GCC's optimizers can move @code{asm} statements
relative to other code, including across jumps. relative to other code, including across jumps.
@code{asm} statements may not perform jumps into other @code{asm} statements. @code{asm} statements may not perform jumps into other @code{asm} statements.
GCC does not know about these jumps, and therefore cannot take 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 account of them when deciding how to optimize. Jumps from @code{asm} to C
labels are only supported in Extended @code{asm}. 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.
Functions declared with the @code{naked} attribute also require Basic
@code{asm} (@pxref{Function Attributes}).
Under certain circumstances, GCC may duplicate (or remove duplicates of) your Under certain circumstances, GCC may duplicate (or remove duplicates of) your
assembly code when optimizing. This can lead to unexpected duplicate assembly code when optimizing. This can lead to unexpected duplicate
symbol errors during compilation if your assembly code defines symbols or symbol errors during compilation if your assembly code defines symbols or
labels. labels.
Safely accessing C data and calling functions from Basic @code{asm} is more Since GCC does not parse the @var{AssemblerInstructions}, it has no
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 visibility of any symbols it references. This may result in GCC discarding
those symbols as unreferenced. those symbols as unreferenced.
Unlike Extended @code{asm}, all Basic @code{asm} blocks are implicitly The compiler copies the assembler instructions in a basic @code{asm}
volatile. @xref{Volatile}. Similarly, Basic @code{asm} blocks are not treated verbatim to the assembly language output file, without
as though they used a "memory" clobber (@pxref{Clobbers}). processing dialects or any of the @samp{%} operators that are available with
extended @code{asm}. This results in minor differences between basic
All Basic @code{asm} blocks use the assembler dialect specified by the @code{asm} strings and extended @code{asm} templates. For example, to refer to
@option{-masm} command-line option. Basic @code{asm} provides no registers you might use @samp{%eax} in basic @code{asm} and
@samp{%%eax} in extended @code{asm}.
On targets such as x86 that support multiple assembler dialects,
all basic @code{asm} blocks use the assembler dialect specified by the
@option{-masm} command-line option (@pxref{x86 Options}).
Basic @code{asm} provides no
mechanism to provide different assembler strings for different dialects. mechanism to provide different assembler strings for different dialects.
Here is an example of Basic @code{asm} for i386: Here is an example of basic @code{asm} for i386:
@example @example
/* Note that this code will not compile with -masm=intel */ /* Note that this code will not compile with -masm=intel */
...@@ -6490,95 +6516,90 @@ Here is an example of Basic @code{asm} for i386: ...@@ -6490,95 +6516,90 @@ Here is an example of Basic @code{asm} for i386:
@node Extended Asm @node Extended Asm
@subsection Extended Asm - Assembler Instructions with C Expression Operands @subsection Extended Asm - Assembler Instructions with C Expression Operands
@cindex @code{asm} keyword
@cindex extended @code{asm} @cindex extended @code{asm}
@cindex assembler instructions @cindex assembly language in C, extended
The @code{asm} keyword allows you to embed assembler instructions within C With extended @code{asm} you can read and write C variables from
code. With Extended @code{asm} you can read and write C variables from assembler and perform jumps from assembler code to C labels.
assembler and perform jumps from assembler code to C labels. Extended @code{asm} syntax uses colons (@samp{:}) to delimit
the operand parameters after the assembler template:
@example @example
@ifhtml asm @r{[}volatile@r{]} ( @var{AssemblerTemplate}
asm [volatile] ( AssemblerTemplate : [OutputOperands] [ : [InputOperands] [ : [Clobbers] ] ] ) : @var{OutputOperands}
@r{[} : @var{InputOperands}
asm [volatile] goto ( AssemblerTemplate : : [InputOperands] : [Clobbers] : GotoLabels ) @r{[} : @var{Clobbers} @r{]} @r{]})
@end ifhtml
@ifnothtml asm @r{[}volatile@r{]} goto ( @var{AssemblerTemplate}
asm [volatile] ( AssemblerTemplate
: [OutputOperands]
[ : [InputOperands]
[ : [Clobbers] ] ])
asm [volatile] goto ( AssemblerTemplate
: :
: [InputOperands] : @var{InputOperands}
: [Clobbers] : @var{Clobbers}
: GotoLabels) : @var{GotoLabels})
@end ifnothtml
@end example @end example
To create headers compatible with ISO C, write @code{__asm__} instead of The @code{asm} keyword is a GNU extension.
@code{asm} and @code{__volatile__} instead of @code{volatile} When writing code that can be compiled with @option{-ansi} and the
(@pxref{Alternate Keywords}). There is no alternate for @code{goto}. various @option{-std} options, use @code{__asm__} instead of
@code{asm} (@pxref{Alternate Keywords}).
By definition, Extended @code{asm} is an @code{asm} statement that contains
operands. To separate the classes of operands, you use colons. Basic
@code{asm} statements contain no colons. (So, for example,
@code{asm("int $3")} is Basic @code{asm}, and @code{asm("int $3" : )} is
Extended @code{asm}. @pxref{Basic Asm}.)
@subsubheading Qualifiers @subsubheading Qualifiers
@emph{volatile} @table @code
@*
The typical use of Extended @code{asm} statements is to manipulate input @item volatile
The typical use of extended @code{asm} statements is to manipulate input
values to produce output values. However, your @code{asm} statements may 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} also produce side effects. If so, you may need to use the @code{volatile}
qualifier to disable certain optimizations. @xref{Volatile}. qualifier to disable certain optimizations. @xref{Volatile}.
@emph{goto} @item goto
@*
This qualifier informs the compiler that the @code{asm} statement may This qualifier informs the compiler that the @code{asm} statement may
perform a jump to one of the labels listed in the GotoLabels section. perform a jump to one of the labels listed in the @var{GotoLabels}.
@xref{GotoLabels}. @xref{GotoLabels}.
@end table
@subsubheading Parameters @subsubheading Parameters
@emph{AssemblerTemplate} @table @var
@* @item AssemblerTemplate
This is a literal string that contains the assembler code. It is a This is a literal string that is the template for the assembler code. It is a
combination of fixed text and tokens that refer to the input, output, combination of fixed text and tokens that refer to the input, output,
and goto parameters. @xref{AssemblerTemplate}. and goto parameters. @xref{AssemblerTemplate}.
@emph{OutputOperands} @item OutputOperands
@*
A comma-separated list of the C variables modified by the instructions in the A comma-separated list of the C variables modified by the instructions in the
AssemblerTemplate. @xref{OutputOperands}. @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
@emph{InputOperands} @item InputOperands
@*
A comma-separated list of C expressions read by the instructions in the A comma-separated list of C expressions read by the instructions in the
AssemblerTemplate. @xref{InputOperands}. @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
@emph{Clobbers} @item Clobbers
@*
A comma-separated list of registers or other values changed by the A comma-separated list of registers or other values changed by the
AssemblerTemplate, beyond those listed as outputs. @xref{Clobbers}. @var{AssemblerTemplate}, beyond those listed as outputs.
An empty list is permitted. @xref{Clobbers}.
@emph{GotoLabels} @item GotoLabels
@*
When you are using the @code{goto} form of @code{asm}, this section contains 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. the list of all C labels to which the code in the
@var{AssemblerTemplate} may jump.
@xref{GotoLabels}. @xref{GotoLabels}.
@code{asm} statements may not perform jumps into other @code{asm} statements,
only to the listed @var{GotoLabels}.
GCC's optimizers do not know about other jumps; therefore they cannot take
account of them when deciding how to optimize.
@end table
The total number of input + output + goto operands is limited to 30.
@subsubheading Remarks @subsubheading Remarks
The @code{asm} statement allows you to include assembly instructions directly The @code{asm} statement allows you to include assembly instructions directly
within C code. This may help you to maximize performance in time-sensitive 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 code or to access assembly instructions that are not readily available to C
programs. programs.
Note that Extended @code{asm} statements must be inside a function. Only Note that extended @code{asm} statements must be inside a function. Only
Basic @code{asm} may be outside functions (@pxref{Basic Asm}). basic @code{asm} may be outside functions (@pxref{Basic Asm}).
Functions declared with the @code{naked} attribute also require Basic Functions declared with the @code{naked} attribute also require basic
@code{asm} (@pxref{Function Attributes}). @code{asm} (@pxref{Function Attributes}).
While the uses of @code{asm} are many and varied, it may help to think of an While the uses of @code{asm} are many and varied, it may help to think of an
...@@ -6598,7 +6619,7 @@ asm ("mov %1, %0\n\t" ...@@ -6598,7 +6619,7 @@ asm ("mov %1, %0\n\t"
printf("%d\n", dst); printf("%d\n", dst);
@end example @end example
This code will copy @var{src} to @var{dst} and add 1 to @var{dst}. This code copies @code{src} to @code{dst} and add 1 to @code{dst}.
@anchor{Volatile} @anchor{Volatile}
@subsubsection Volatile @subsubsection Volatile
...@@ -6610,13 +6631,12 @@ there is no need for the output variables. Also, the optimizers may move ...@@ -6610,13 +6631,12 @@ 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 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 result (i.e. none of its input values change between calls). Using the
@code{volatile} qualifier disables these optimizations. @code{asm} statements @code{volatile} qualifier disables these optimizations. @code{asm} statements
that have no output operands are implicitly volatile. that have no output operands, including @code{asm goto} statements,
are implicitly volatile.
Examples:
This i386 code demonstrates a case that does not use (or require) the This i386 code demonstrates a case that does not use (or require) the
@code{volatile} qualifier. If it is performing assertion checking, this code @code{volatile} qualifier. If it is performing assertion checking, this code
uses @code{asm} to perform the validation. Otherwise, @var{dwRes} is uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is
unreferenced by any code. As a result, the optimizers can discard the 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{asm} statement, which in turn removes the need for the entire
@code{DoCheck} routine. By omitting the @code{volatile} qualifier when it @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
...@@ -6639,7 +6659,7 @@ void DoCheck(uint32_t dwSomeValue) ...@@ -6639,7 +6659,7 @@ void DoCheck(uint32_t dwSomeValue)
@end example @end example
The next example shows a case where the optimizers can recognize that 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 (@code{dwSomeValue}) never changes during the execution of the function and can
therefore move the @code{asm} outside the loop to produce more efficient code. therefore move the @code{asm} outside the loop to produce more efficient code.
Again, using @code{volatile} disables this type of optimization. Again, using @code{volatile} disables this type of optimization.
...@@ -6662,7 +6682,8 @@ void do_print(uint32_t dwSomeValue) ...@@ -6662,7 +6682,8 @@ void do_print(uint32_t dwSomeValue)
@end example @end example
The following example demonstrates a case where you need to use the The following example demonstrates a case where you need to use the
@code{volatile} qualifier. It uses the x86 RDTSC instruction, which reads @code{volatile} qualifier.
It uses the x86 @code{rdtsc} instruction, which reads
the computer's time-stamp counter. Without the @code{volatile} qualifier, the computer's time-stamp counter. Without the @code{volatile} qualifier,
the optimizers might assume that the @code{asm} block will always return the the optimizers might assume that the @code{asm} block will always return the
same value and therefore optimize away the second call. same value and therefore optimize away the second call.
...@@ -6692,7 +6713,7 @@ asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. ...@@ -6692,7 +6713,7 @@ asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
printf("msr: %llx\n", msr); printf("msr: %llx\n", msr);
@end example @end example
GCC's optimizers will not treat this code like the non-volatile code in the GCC's optimizers do 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 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. assumption that the result from a previous call is still valid.
...@@ -6700,7 +6721,7 @@ Note that the compiler can move even volatile @code{asm} instructions relative ...@@ -6700,7 +6721,7 @@ Note that the compiler can move even volatile @code{asm} instructions relative
to other code, including across jump instructions. For example, on many to other code, including across jump instructions. For example, on many
targets there is a system register that controls the rounding mode of 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 floating-point operations. Setting it with a volatile @code{asm}, as in the
following PowerPC example, will not work reliably. following PowerPC example, does not work reliably.
@example @example
asm volatile("mtfsf 255, %0" : : "f" (fpenv)); asm volatile("mtfsf 255, %0" : : "f" (fpenv));
...@@ -6718,16 +6739,18 @@ sum = x + y; ...@@ -6718,16 +6739,18 @@ sum = x + y;
Under certain circumstances, GCC may duplicate (or remove duplicates of) your Under certain circumstances, GCC may duplicate (or remove duplicates of) your
assembly code when optimizing. This can lead to unexpected duplicate symbol assembly code when optimizing. This can lead to unexpected duplicate symbol
errors during compilation if your asm code defines symbols or labels. Using %= errors during compilation if your asm code defines symbols or labels.
Using @samp{%=}
(@pxref{AssemblerTemplate}) may help resolve this problem. (@pxref{AssemblerTemplate}) may help resolve this problem.
@anchor{AssemblerTemplate} @anchor{AssemblerTemplate}
@subsubsection Assembler Template @subsubsection Assembler Template
@cindex @code{asm} assembler template @cindex @code{asm} assembler template
An assembler template is a literal string containing assembler instructions. An assembler template is a literal string containing assembler instructions.
The compiler will replace any references to inputs, outputs, and goto labels The compiler replaces tokens in the template that refer
in the template, and then output the resulting string to the assembler. The to inputs, outputs, and goto labels,
and then outputs the resulting string to the assembler. The
string can contain any instructions recognized by the assembler, including string can contain any instructions recognized by the assembler, including
directives. GCC does not parse the assembler instructions directives. GCC does not parse the assembler instructions
themselves and does not know what they mean or even whether they are valid themselves and does not know what they mean or even whether they are valid
...@@ -6738,7 +6761,8 @@ You may place multiple assembler instructions together in a single @code{asm} ...@@ -6738,7 +6761,8 @@ You may place multiple assembler instructions together in a single @code{asm}
string, separated by the characters normally used in assembly code for the 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 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 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 @samp{\n\t}).
Some assemblers allow semicolons as a line separator. However, note
that some assembler dialects use semicolons to start a comment. that some assembler dialects use semicolons to start a comment.
Do not expect a sequence of @code{asm} statements to remain perfectly Do not expect a sequence of @code{asm} statements to remain perfectly
...@@ -6751,20 +6775,44 @@ by using global symbols directly from the assembler template) may not work as ...@@ -6751,20 +6775,44 @@ by using global symbols directly from the assembler template) may not work as
expected. Similarly, calling functions directly from an assembler template expected. Similarly, calling functions directly from an assembler template
requires a detailed understanding of the target assembler and ABI. requires a detailed understanding of the target assembler and ABI.
Since GCC does not parse the AssemblerTemplate, it has no visibility of any Since GCC does not parse the assembler template,
it has no visibility of any
symbols it references. This may result in GCC discarding those symbols as symbols it references. This may result in GCC discarding those symbols as
unreferenced unless they are also listed as input, output, or goto operands. unreferenced unless they are also listed as input, output, or goto operands.
GCC can support multiple assembler dialects (for example, GCC for x86 @subsubheading Special format strings
supports "att" and "intel" dialects) for inline assembler. In builds that
support this capability, the @option{-masm} option controls which dialect In addition to the tokens described by the input, output, and goto operands,
GCC uses as its default. The hardware-specific documentation for the these tokens have special meanings in the assembler template:
@table @samp
@item %%
Outputs a single @samp{%} 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.
@item %@{
@itemx %|
@itemx %@}
Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively)
into the assembler code. When unescaped, these characters have special
meaning to indicate multiple assembler dialects, as described below.
@end table
@subsubheading Multiple assembler dialects in @code{asm} templates
On targets such as x86, GCC supports multiple assembler dialects.
The @option{-masm} option controls which dialect GCC uses as its
default for inline assembler. The target-specific documentation for the
@option{-masm} option contains the list of supported dialects, as well as 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 default dialect if the option is not specified. This information may be
important to understand, since assembler code that works correctly when important to understand, since assembler code that works correctly when
compiled using one dialect will likely fail if compiled using another. compiled using one dialect will likely fail if compiled using another.
@xref{x86 Options}.
@subsubheading Using braces in @code{asm} templates
If your code needs to support multiple assembler dialects (for example, if 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 you are writing public headers that need to support a variety of compilation
...@@ -6774,23 +6822,26 @@ options), use constructs of this form: ...@@ -6774,23 +6822,26 @@ options), use constructs of this form:
@{ dialect0 | dialect1 | dialect2... @} @{ dialect0 | dialect1 | dialect2... @}
@end example @end example
This construct outputs 'dialect0' when using dialect #0 to compile the code, This construct outputs @code{dialect0}
'dialect1' for dialect #1, etc. If there are fewer alternatives within the when using dialect #0 to compile the code,
@code{dialect1} for dialect #1, etc. If there are fewer alternatives within the
braces than the number of dialects the compiler supports, the construct braces than the number of dialects the compiler supports, the construct
outputs nothing. outputs nothing.
For example, if an x86 compiler supports two dialects (att, intel), an For example, if an x86 compiler supports two dialects
(@samp{att}, @samp{intel}), an
assembler template such as this: assembler template such as this:
@example @example
"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2" "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
@end example @end example
would produce the output: @noindent
is equivalent to one of
@example @example
For att: "btl %[Offset],%[Base] ; jc %l2" "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */}
For intel: "bt %[Base],%[Offset]; jc %l2" "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */}
@end example @end example
Using that same compiler, this code: Using that same compiler, this code:
...@@ -6799,33 +6850,15 @@ Using that same compiler, this code: ...@@ -6799,33 +6850,15 @@ Using that same compiler, this code:
"xchg@{l@}\t@{%%@}ebx, %1" "xchg@{l@}\t@{%%@}ebx, %1"
@end example @end example
would produce @noindent
corresponds to either
@example @example
For att: "xchgl\t%%ebx, %1" "xchgl\t%%ebx, %1" @r{/* att dialect */}
For intel: "xchg\tebx, %1" "xchg\tebx, %1" @r{/* intel dialect */}
@end example @end example
There is no support for nesting dialect alternatives. Also, there is no There is no support for nesting dialect alternatives.
``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} @anchor{OutputOperands}
@subsubsection Output Operands @subsubsection Output Operands
...@@ -6834,8 +6867,8 @@ generates multiple assembler instructions. ...@@ -6834,8 +6867,8 @@ generates multiple assembler instructions.
An @code{asm} statement has zero or more output operands indicating the names An @code{asm} statement has zero or more output operands indicating the names
of C variables modified by the assembler code. of C variables modified by the assembler code.
In this i386 example, @var{old} (referred to in the template string as In this i386 example, @code{old} (referred to in the template string as
@code{%0}) and @var{*Base} (as @code{%1}) are outputs and @var{Offset} @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset}
(@code{%2}) is an input: (@code{%2}) is an input:
@example @example
...@@ -6850,53 +6883,57 @@ __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base. ...@@ -6850,53 +6883,57 @@ __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
return old; return old;
@end example @end example
Operands use this format: Operands are separated by commas. Each operand has this format:
@example @example
[ [asmSymbolicName] ] "constraint" (cvariablename) @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename})
@end example @end example
@emph{asmSymbolicName} @table @var
@* @item asmSymbolicName
Specifies a symbolic name for the operand.
When not using asmSymbolicNames, use the (zero-based) position of the operand Reference the name in the assembler template
in the list of operands in the assembler template. For example if there are by enclosing it in square brackets
three output operands, use @code{%0} in the template to refer to the first, (i.e. @samp{%[Value]}). The scope of the name is the @code{asm} statement
@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, that contains the definition. Any valid C variable name is acceptable,
including names already defined in the surrounding code. No two operands including names already defined in the surrounding code. No two operands
within the same @code{asm} statement can use the same symbolic name. within the same @code{asm} statement can use the same symbolic name.
@emph{constraint} When not using an @var{asmSymbolicName}, use the (zero-based) position
@* of the operand
Output constraints must begin with either @code{"="} (a variable overwriting an in the list of operands in the assembler template. For example if there are
existing value) or @code{"+"} (when reading and writing). When using three output operands, use @samp{%0} in the template to refer to the first,
@code{"="}, do not assume the location will contain the existing value (except @samp{%1} for the second, and @samp{%2} for the third.
when tying the variable to an input; @pxref{InputOperands,,Input Operands}).
@item constraint
A string constant specifying constraints on the placement of the operand;
@xref{Constraints}, for details.
Output constraints must begin with either @samp{=} (a variable overwriting an
existing value) or @samp{+} (when reading and writing). When using
@samp{=}, do not assume the location contains the existing value
on entry to the @code{asm}, except
when the operand is tied to an input; @pxref{InputOperands,,Input Operands}.
After the prefix, there must be one or more additional constraints After the prefix, there must be one or more additional constraints
(@pxref{Constraints}) that describe where the value resides. Common (@pxref{Constraints}) that describe where the value resides. Common
constraints include @code{"r"} for register and @code{"m"} for memory. constraints include @samp{r} for register and @samp{m} for memory.
When you list more than one possible location (for example @code{"=rm"}), the When you list more than one possible location (for example, @code{"=rm"}),
compiler chooses the most efficient one based on the current context. If you the compiler chooses the most efficient one based on the current context.
list as many alternates as the @code{asm} statement allows, you will permit If you list as many alternates as the @code{asm} statement allows, you permit
the optimizers to produce the best possible code. If you must use a specific the optimizers to produce the best possible code.
register, but your Machine Constraints do not provide sufficient If you must use a specific register, but your Machine Constraints do not
control to select the specific register you want, Local Reg Vars may provide provide sufficient control to select the specific register you want,
a solution (@pxref{Local Reg Vars}). local register variables may provide a solution (@pxref{Local Reg Vars}).
@emph{cvariablename} @item cvariablename
@* Specifies a C lvalue expression to hold the output, typically a variable name.
Specifies the C variable name of the output (enclosed by parentheses). Accepts The enclosing parentheses are a required part of the syntax.
any (non-constant) variable within scope.
@end table
Remarks:
When the compiler selects the registers to use to
The total number of input + output + goto operands has a limit of 30. Commas represent the output operands, it does not use any of the clobbered registers
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}). (@pxref{Clobbers}).
Output operand expressions must be lvalues. The compiler cannot check whether Output operand expressions must be lvalues. The compiler cannot check whether
...@@ -6906,12 +6943,16 @@ example a bit-field), the constraint must allow a register. In that case, GCC ...@@ -6906,12 +6943,16 @@ 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 uses the register as the output of the @code{asm}, and then stores that
register into the output. register into the output.
Unless an output operand has the '@code{&}' constraint modifier Operands using the @samp{+} constraint modifier count as two operands
(@pxref{Modifiers}), GCC may allocate it in the same register as an unrelated (that is, both as input and output) towards the total maximum of 30 operands
input operand, on the assumption that the assembler code will consume its per @code{asm} statement.
Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output
operands that must not overlap an input. Otherwise,
GCC may allocate the output operand in the same register as an unrelated
input operand, on the assumption that the assembler code consumes its
inputs before producing outputs. This assumption may be false if the assembler 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 actually consists of more than one instruction.
'@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 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. constraint and another output parameter (@var{b}) allows a memory constraint.
...@@ -6920,13 +6961,13 @@ registers which @emph{might} be shared by @var{a}, and GCC considers those ...@@ -6920,13 +6961,13 @@ 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 to be inputs to the asm. As above, GCC assumes that such input
registers are consumed before any outputs are written. This assumption may registers are consumed before any outputs are written. This assumption may
result in incorrect behavior if the asm writes to @var{a} before using result in incorrect behavior if the asm writes to @var{a} before using
@var{b}. Combining the `@code{&}' constraint with the register constraint @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a}
ensures that modifying @var{a} will not affect what address is referenced by ensures that modifying @var{a} does not affect the address referenced by
@var{b}. Omitting the `@code{&}' constraint means that the location of @var{b} @var{b}. Otherwise, the location of @var{b}
will be undefined if @var{a} is modified before using @var{b}. is undefined if @var{a} is modified before using @var{b}.
@code{asm} supports operand modifiers on operands (for example @code{%k2} @code{asm} supports operand modifiers on operands (for example @samp{%k2}
instead of simply @code{%2}). Typically these qualifiers are hardware instead of simply @samp{%2}). Typically these qualifiers are hardware
dependent. The list of supported modifiers for x86 is found at dependent. The list of supported modifiers for x86 is found at
@ref{x86Operandmodifiers,x86 Operand modifiers}. @ref{x86Operandmodifiers,x86 Operand modifiers}.
...@@ -6935,13 +6976,11 @@ operands, use @code{volatile} for the @code{asm} statement to prevent the ...@@ -6935,13 +6976,11 @@ operands, use @code{volatile} for the @code{asm} statement to prevent the
optimizers from discarding the @code{asm} statement as unneeded optimizers from discarding the @code{asm} statement as unneeded
(see @ref{Volatile}). (see @ref{Volatile}).
Examples: This code makes no use of the optional @var{asmSymbolicName}. Therefore it
This code makes no use of the optional asmSymbolicName. Therefore it
references the first output operand as @code{%0} (were there a second, 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 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 than that of the last output operand. In this i386 example, that makes
@var{Mask} @code{%1}: @code{Mask} referenced as @code{%1}:
@example @example
uint32_t Mask = 1234; uint32_t Mask = 1234;
...@@ -6953,17 +6992,21 @@ uint32_t Index; ...@@ -6953,17 +6992,21 @@ uint32_t Index;
: "cc"); : "cc");
@end example @end example
That code overwrites the variable Index ("="), placing the value in a register That code overwrites the variable @code{Index} (@samp{=}),
("r"). The generic "r" constraint instead of a constraint for a specific placing the value in a register (@samp{r}).
Using the generic @samp{r} constraint instead of a constraint for a specific
register allows the compiler to pick the register to use, which can result 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 in more efficient code. This may not be possible if an assembler instruction
requires a specific register. requires a specific register.
The following i386 example uses the asmSymbolicName operand. It produces the The following i386 example uses the @var{asmSymbolicName} syntax.
It produces the
same result as the code above, but some may consider it more readable or more 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 maintainable since reordering index numbers is not necessary when adding or
removing operands. The names aIndex and aMask are only used to emphasize which removing operands. The names @code{aIndex} and @code{aMask}
names get used where. It is acceptable to reuse the names Index and Mask. are only used in this example to emphasize which
names get used where.
It is acceptable to reuse the names @code{Index} and @code{Mask}.
@example @example
uint32_t Mask = 1234; uint32_t Mask = 1234;
...@@ -6987,61 +7030,68 @@ asm ("mov %[e], %[d]" ...@@ -6987,61 +7030,68 @@ asm ("mov %[e], %[d]"
: [e] "rm" (*e)); : [e] "rm" (*e));
@end example @end example
Here, @var{d} may either be in a register or in memory. Since the compiler Here, @code{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} might already have the current value of the @code{uint32_t} location
pointed to by @code{e}
in a register, you can enable it to choose the best location in a register, you can enable it to choose the best location
for @var{d} by specifying both constraints. for @code{d} by specifying both constraints.
@anchor{InputOperands} @anchor{InputOperands}
@subsubsection Input Operands @subsubsection Input Operands
@cindex @code{asm} input operands @cindex @code{asm} input operands
@cindex @code{asm} expressions @cindex @code{asm} expressions
Input operands make inputs from C variables and expressions available to the Input operands make values from C variables and expressions available to the
assembly code. assembly code.
Specify input operands by using the format: Operands are separated by commas. Each operand has this format:
@example @example
[ [asmSymbolicName] ] "constraint" (cexpression) @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression})
@end example @end example
@emph{asmSymbolicName} @table @var
@* @item asmSymbolicName
When not using asmSymbolicNames, use the (zero-based) position of the operand Specifies a symbolic name for the operand.
in the list of operands, including outputs, in the assembler template. For Reference the name in the assembler template
example, if there are two output parameters and three inputs, @code{%2} refers by enclosing it in square brackets
to the first input, @code{%3} to the second, and @code{%4} to the third. (i.e. @samp{%[Value]}). The scope of the name is the @code{asm} statement
When using an asmSymbolicName, reference it by enclosing the name in square that contains the definition. Any valid C variable name is acceptable,
brackets (e.g. @code{%[Value]}). The scope of the name is the @code{asm} including names already defined in the surrounding code. No two operands
statement that contains the definition. Any valid C variable name is within the same @code{asm} statement can use the same symbolic name.
acceptable, including names already defined in the surrounding code. No two
operands within the same @code{asm} statement can use the same symbolic name. When not using an @var{asmSymbolicName}, use the (zero-based) position
of the operand
@emph{constraint} in the list of operands in the assembler template. For example if there are
@* two output opeerands and three inputs,
Input constraints must be a string containing one or more constraints use @samp{%2} in the template to refer to the first input operand,
(@pxref{Constraints}). When you give more than one possible constraint @samp{%3} for the second, and @samp{%4} for the third.
(for example, @code{"irm"}), the compiler will choose the most efficient
method based on the current context. Input constraints may not begin with @item constraint
either "=" or "+". If you must use a specific register, but your Machine A string constant specifying constraints on the placement of the operand;
Constraints do not provide sufficient control to select the specific @xref{Constraints}, for details.
register you want, Local Reg Vars may provide a solution
(@pxref{Local Reg Vars}). Input constraint strings may not begin with either @samp{=} or @samp{+}.
When you list more than one possible location (for example, @samp{"irm"}),
the compiler chooses the most efficient one based on the current context.
If you must use a specific register, but your Machine Constraints do not
provide sufficient control to select the specific register you want,
local register variables may provide a solution (@pxref{Local Reg Vars}).
Input constraints can also be digits (for example, @code{"0"}). This indicates 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 that the specified input must be in the same place as the output constraint
at the (zero-based) index in the output constraint list. When using at the (zero-based) index in the output constraint list.
asmSymbolicNames for the output operands, you may use these names (enclosed When using @var{asmSymbolicName} syntax for the output operands,
in brackets []) instead of digits. you may use these names (enclosed in brackets @samp{[]}) instead of digits.
@emph{cexpression} @item cexpression
@*
This is the C variable or expression being passed to the @code{asm} statement This is the C variable or expression being passed to the @code{asm} statement
as input. as input. The enclosing parentheses are a required part of the syntax.
@end table
When the compiler selects the registers to use to represent the 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}). operands, it does not use any of the clobbered registers (@pxref{Clobbers}).
If there are no output operands but there are input operands, place two If there are no output operands but there are input operands, place two
consecutive colons where the output operands would go: consecutive colons where the output operands would go:
...@@ -7054,8 +7104,9 @@ __asm__ ("some instructions" ...@@ -7054,8 +7104,9 @@ __asm__ ("some instructions"
@strong{Warning:} Do @emph{not} modify the contents of input-only operands @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 (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 the @code{asm} statement these operands contain the same values as they
had before executing the assembler. It is @emph{not} possible to use Clobbers had before executing the statement.
It is @emph{not} possible to use clobbers
to inform the compiler that the values in these inputs are changing. One 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 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 that never gets used. Note, however, that if the code that follows the
...@@ -7063,23 +7114,17 @@ that never gets used. Note, however, that if the code that follows the ...@@ -7063,23 +7114,17 @@ that never gets used. Note, however, that if the code that follows the
optimizers may discard the @code{asm} statement as unneeded optimizers may discard the @code{asm} statement as unneeded
(see @ref{Volatile}). (see @ref{Volatile}).
Remarks: @code{asm} supports operand modifiers on operands (for example @samp{%k2}
instead of simply @samp{%2}). Typically these qualifiers are hardware
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 x86 is found at dependent. The list of supported modifiers for x86 is found at
@ref{x86Operandmodifiers,x86 Operand modifiers}. @ref{x86Operandmodifiers,x86 Operand modifiers}.
Examples:
In this example using the fictitious @code{combine} instruction, the In this example using the fictitious @code{combine} instruction, the
constraint @code{"0"} for input operand 1 says that it must occupy the same 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 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 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 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 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 both operands is not enough to guarantee that they are in the same place in
the generated assembler code. the generated assembler code.
...@@ -7102,24 +7147,24 @@ asm ("cmoveq %1, %2, %[result]" ...@@ -7102,24 +7147,24 @@ asm ("cmoveq %1, %2, %[result]"
@cindex @code{asm} clobbers @cindex @code{asm} clobbers
While the compiler is aware of changes to entries listed in the output 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 operands, the inline @code{asm} code may modify more than just the outputs. For
example, calculations may require additional registers, or the processor may example, calculations may require additional registers, or the processor may
overwrite a register as a side effect of a particular assembler instruction. 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 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 list. Clobber list items are either register names or the special clobbers
(listed below). Each clobber list item is enclosed in double quotes and (listed below). Each clobber list item is a string constant
separated by commas. enclosed in double quotes and separated by commas.
Clobber descriptions may not in any way overlap with an input or output 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 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 with one member when listing that register in the clobber list. Variables
declared to live in specific registers (@pxref{Explicit Reg Vars}), and used 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 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 clobber description. In particular, there is no way to specify that input
operands get modified without also specifying them as output operands. operands get modified without also specifying them as output operands.
When the compiler selects which registers to use to represent input and output 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, operands, it does not use any of the clobbered registers. As a result,
clobbered registers are available for any use in the assembler code. clobbered registers are available for any use in the assembler code.
Here is a realistic example for the VAX showing the use of clobbered Here is a realistic example for the VAX showing the use of clobbered
...@@ -7134,68 +7179,78 @@ asm volatile ("movc3 %0, %1, %2" ...@@ -7134,68 +7179,78 @@ asm volatile ("movc3 %0, %1, %2"
Also, there are two special clobber arguments: Also, there are two special clobber arguments:
@enumerate @table @code
@item @item "cc"
The @code{"cc"} clobber indicates that the assembler code modifies the flags The @code{"cc"} clobber indicates that the assembler code modifies the flags
register. On some machines, GCC represents the condition codes as a specific register. On some machines, GCC represents the condition codes as a specific
hardware register; "cc" serves to name this register. On other machines, hardware register; @code{"cc"} serves to name this register.
condition code handling is different, and specifying "cc" has no effect. But On other machines, condition code handling is different,
it is valid no matter what the machine. and specifying @code{"cc"} has no effect. But
it is valid no matter what the target.
@item
The "memory" clobber tells the compiler that the assembly code performs memory @item "memory"
The @code{"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 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 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 parameters). To ensure memory contains correct values, GCC may need to flush
specific register values to memory before executing the @code{asm}. Further, specific register values to memory before executing the @code{asm}. Further,
the compiler will not assume that any values read from memory before an the compiler does not assume that any values read from memory before an
@code{asm} will remain unchanged after that @code{asm}; it will reload them as @code{asm} remain unchanged after that @code{asm}; it reloads them as
needed. This effectively forms a read/write memory barrier for the compiler. needed.
Using the @code{"memory"} clobber effectively forms a read/write
memory barrier for the compiler.
Note that this clobber does not prevent the @emph{processor} from doing Note that this clobber does not prevent the @emph{processor} from doing
speculative reads past the @code{asm} statement. To prevent that, you need speculative reads past the @code{asm} statement. To prevent that, you need
processor-specific fence instructions. processor-specific fence instructions.
Flushing registers to memory has performance implications and may be an issue 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 for time-sensitive code. You can use a trick to avoid this if the size of
the memory being accessed is known at compile time. For example, if accessing the memory being accessed is known at compile time. For example, if accessing
ten bytes of a string, use a memory input like: ten bytes of a string, use a memory input like:
@code{@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}}. @code{@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}}.
@end enumerate @end table
@anchor{GotoLabels} @anchor{GotoLabels}
@subsubsection Goto Labels @subsubsection Goto Labels
@cindex @code{asm} goto labels @cindex @code{asm} goto labels
@code{asm goto} allows assembly code to jump to one or more C labels. The @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 @var{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 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 @code{asm} execution falls through to the next statement (if this is not the
case, consider using the @code{__builtin_unreachable} intrinsic after the case, consider using the @code{__builtin_unreachable} intrinsic after the
@code{asm} statement). Optimization of @code{asm goto} may be improved by @code{asm} statement). Optimization of @code{asm goto} may be improved by
using the @code{hot} and @code{cold} label attributes (@pxref{Label using the @code{hot} and @code{cold} label attributes (@pxref{Label
Attributes}). The total number of input + output + goto operands has Attributes}).
a limit of 30.
An @code{asm goto} statement can not have outputs (which means that the An @code{asm goto} statement cannot have outputs.
statement is implicitly volatile). This is due to an internal restriction of This is due to an internal restriction of
the compiler: control transfer instructions cannot have outputs. If the the compiler: control transfer instructions cannot have outputs.
assembler code does modify anything, use the "memory" clobber to force the If the assembler code does modify anything, use the @code{"memory"} clobber
optimizers to flush all register values to memory, and reload them if to force the
necessary, after the @code{asm} statement. 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 Also note that an @code{asm goto} statement is always implicitly
by its (zero-based) position in GotoLabels plus the number of input considered volatile.
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. To reference a label in the assembler template,
GCC's optimizers do not know about these jumps; therefore they cannot take prefix it with @samp{%l} (lowercase @samp{L}) followed
account of them when deciding how to optimize. by its (zero-based) position in @var{GotoLabels} plus the number of input
operands. For example, if the @code{asm} has three inputs and references two
labels, refer to the first label as @samp{%l3} and the second as @samp{%l4}).
Alternately, you can reference labels using the actual C label name enclosed
in brackets. For example, to reference a label named @code{carry}, you can
use @samp{%l[carry]}. The label must still be listed in the @var{GotoLabels}
section when using this approach.
Example code for i386 might look like: Here is an example of @code{asm goto} for i386:
@example @example
asm goto ( asm goto (
...@@ -7212,7 +7267,7 @@ carry: ...@@ -7212,7 +7267,7 @@ carry:
return 1; return 1;
@end example @end example
The following example shows an @code{asm goto} that uses the memory clobber. The following example shows an @code{asm goto} that uses a memory clobber.
@example @example
int frob(int x) int frob(int x)
...@@ -7230,17 +7285,20 @@ error: ...@@ -7230,17 +7285,20 @@ error:
@end example @end example
@anchor{x86Operandmodifiers} @anchor{x86Operandmodifiers}
@subsubsection x86 Operand modifiers @subsubsection x86 Operand Modifiers
Input, output, and goto operands for extended @code{asm} statements can use References to input, output, and goto operands in the assembler template
modifiers to affect the code output to the assembler. For example, the of extended @code{asm} statements can use
following code uses the "h" and "b" modifiers for x86: modifiers to affect the way the operands are formatted in
the code output to the assembler. For example, the
following code uses the @samp{h} and @samp{b} modifiers for x86:
@example @example
uint16_t num; uint16_t num;
asm volatile ("xchg %h0, %b0" : "+a" (num) ); asm volatile ("xchg %h0, %b0" : "+a" (num) );
@end example @end example
@noindent
These modifiers generate this assembler code: These modifiers generate this assembler code:
@example @example
...@@ -7265,7 +7323,7 @@ top: ...@@ -7265,7 +7323,7 @@ top:
@end example @end example
With no modifiers, this is what the output from the operands would be for the With no modifiers, this is what the output from the operands would be for the
att and intel dialects of assembler: @samp{att} and @samp{intel} dialects of assembler:
@multitable {Operand} {masm=att} {OFFSET FLAT:.L2} @multitable {Operand} {masm=att} {OFFSET FLAT:.L2}
@headitem Operand @tab masm=att @tab masm=intel @headitem Operand @tab masm=att @tab masm=intel
...@@ -7327,7 +7385,7 @@ The table below shows the list of supported modifiers and their effects. ...@@ -7327,7 +7385,7 @@ The table below shows the list of supported modifiers and their effects.
@end multitable @end multitable
@anchor{x86floatingpointasmoperands} @anchor{x86floatingpointasmoperands}
@subsubsection x86 floating-point asm operands @subsubsection x86 Floating-Point @code{asm} Operands
On x86 targets, there are several rules on the usage of stack-like registers On x86 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 in the operands of an @code{asm}. These rules apply only to the operands
...@@ -7369,10 +7427,10 @@ reload may think that it can use the same register for both the input and ...@@ -7369,10 +7427,10 @@ reload may think that it can use the same register for both the input and
the output. the output.
To prevent this from happening, To prevent this from happening,
if any input operand uses the @code{f} constraint, all output register if any input operand uses the @samp{f} constraint, all output register
constraints must use the @code{&} early-clobber modifier. constraints must use the @samp{&} early-clobber modifier.
The example above would be correctly written as: The example above is correctly written as:
@smallexample @smallexample
asm ("foo" : "=&t" (a) : "f" (b)); asm ("foo" : "=&t" (a) : "f" (b));
...@@ -7385,7 +7443,7 @@ know which registers the outputs appear in unless you indicate ...@@ -7385,7 +7443,7 @@ know which registers the outputs appear in unless you indicate
this in the constraints. this in the constraints.
Output operands must specifically indicate which register an output Output operands must specifically indicate which register an output
appears in after an @code{asm}. @code{=f} is not allowed: the operand appears in after an @code{asm}. @samp{=f} is not allowed: the operand
constraints must select a class with a single register. constraints must select a class with a single register.
@item @item
...@@ -7404,8 +7462,7 @@ unrelated to the inputs and outputs. ...@@ -7404,8 +7462,7 @@ unrelated to the inputs and outputs.
@end enumerate @end enumerate
Here are a couple of reasonable @code{asm}s to want to write. This This @code{asm}
@code{asm}
takes one input, which is internally popped, and produces two outputs. takes one input, which is internally popped, and produces two outputs.
@smallexample @smallexample
...@@ -7529,8 +7586,8 @@ Here @code{a5} is the name of the register that should be used. Choose a ...@@ -7529,8 +7586,8 @@ Here @code{a5} is the name of the register that should be used. Choose a
register that is normally saved and restored by function calls on your register that is normally saved and restored by function calls on your
machine, so that library routines will not clobber it. machine, so that library routines will not clobber it.
Naturally the register name is cpu-dependent, so you need to Naturally the register name is CPU-dependent, so you need to
conditionalize your program according to cpu type. The register conditionalize your program according to CPU type. The register
@code{a5} is a good choice on a 68000 for a variable of pointer @code{a5} is a good choice on a 68000 for a variable of pointer
type. On machines with register windows, be sure to choose a ``global'' type. On machines with register windows, be sure to choose a ``global''
register that is not affected magically by the function call mechanism. register that is not affected magically by the function call mechanism.
...@@ -7628,13 +7685,13 @@ Here @code{a5} is the name of the register that should be used. Note ...@@ -7628,13 +7685,13 @@ Here @code{a5} is the name of the register that should be used. Note
that this is the same syntax used for defining global register that this is the same syntax used for defining global register
variables, but for a local variable it appears within a function. variables, but for a local variable it appears within a function.
Naturally the register name is cpu-dependent, but this is not a Naturally the register name is CPU-dependent, but this is not a
problem, since specific registers are most often useful with explicit problem, since specific registers are most often useful with explicit
assembler instructions (@pxref{Extended Asm}). Both of these things assembler instructions (@pxref{Extended Asm}). Both of these things
generally require that you conditionalize your program according to generally require that you conditionalize your program according to
cpu type. CPU type.
In addition, operating systems on one type of cpu may differ in how they In addition, operating systems on one type of CPU may differ in how they
name the registers; then you need additional conditionals. For name the registers; then you need additional conditionals. For
example, some 68000 operating systems call this register @code{%a5}. example, some 68000 operating systems call this register @code{%a5}.
...@@ -7644,11 +7701,12 @@ the variable's value is not live. ...@@ -7644,11 +7701,12 @@ the variable's value is not live.
This option does not guarantee that GCC generates code that has This option does not guarantee that GCC generates code that has
this variable in the register you specify at all times. You may not this variable in the register you specify at all times. You may not
code an explicit reference to this register in the @emph{assembler code an explicit reference to this register in the assembler
instruction template} part of an @code{asm} statement and assume it instruction template part of an @code{asm} statement and assume it
always refers to this variable. However, using the variable as an always refers to this variable.
@code{asm} @emph{operand} guarantees that the specified register is used However, using the variable as an input or output operand to the @code{asm}
for the operand. guarantees that the specified register is used for that operand.
@xref{Extended Asm}, for more information.
Stores into local register variables may be deleted when they appear to be dead Stores into local register variables may be deleted when they appear to be dead
according to dataflow analysis. References to local register variables may according to dataflow analysis. References to local register variables may
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment