gcc: Basic Asm

1 
1 6.45.1 Basic Asm -- Assembler Instructions Without Operands
1 -----------------------------------------------------------
1 
1 A basic 'asm' statement has the following syntax:
1 
1      asm ASM-QUALIFIERS ( ASSEMBLERINSTRUCTIONS )
1 
1  The 'asm' keyword is a GNU extension.  When writing code that can be
1 compiled with '-ansi' and the various '-std' options, use '__asm__'
1 instead of 'asm' (⇒Alternate Keywords).
1 
1 Qualifiers
1 ..........
1 
1 'volatile'
1      The optional 'volatile' qualifier has no effect.  All basic 'asm'
1      blocks are implicitly volatile.
1 
1 'inline'
1      If you use the 'inline' qualifier, then for inlining purposes the
11      size of the asm is taken as the smallest size possible (⇒Size
      of an asm).
1 
1 Parameters
1 ..........
1 
1 ASSEMBLERINSTRUCTIONS
1      This is a literal string that specifies the assembler code.  The
1      string can contain any instructions recognized by the assembler,
1      including directives.  GCC does not parse the assembler
1      instructions themselves and does not know what they mean or even
1      whether they are valid assembler input.
1 
1      You may place multiple assembler instructions together in a single
1      'asm' string, separated by the characters normally used in assembly
1      code for the system.  A combination that works in most places is a
1      newline to break the line, plus a tab character (written as
1      '\n\t').  Some assemblers allow semicolons as a line separator.
1      However, note that some assembler dialects use semicolons to start
1      a comment.
1 
1 Remarks
1 .......
1 
1 Using extended 'asm' (⇒Extended Asm) typically produces smaller,
1 safer, and more efficient code, and in most cases it is a better
1 solution than basic 'asm'.  However, there are two situations where only
1 basic 'asm' can be used:
1 
1    * Extended 'asm' statements have to be inside a C function, so to
1      write inline assembly language at file scope ("top-level"), outside
1      of C functions, you must use basic 'asm'.  You can use this
1      technique to emit assembler directives, define assembly language
1      macros that can be invoked elsewhere in the file, or write entire
1      functions in assembly language.
1 
1    * Functions declared with the 'naked' attribute also require basic
1      'asm' (⇒Function Attributes).
1 
1  Safely accessing C data and calling functions from basic 'asm' is more
1 complex than it may appear.  To access C data, it is better to use
1 extended 'asm'.
1 
1  Do not expect a sequence of 'asm' statements to remain perfectly
1 consecutive after compilation.  If certain instructions need to remain
1 consecutive in the output, put them in a single multi-instruction 'asm'
1 statement.  Note that GCC's optimizers can move 'asm' statements
1 relative to other code, including across jumps.
1 
1  'asm' statements may not perform jumps into other 'asm' statements.
1 GCC does not know about these jumps, and therefore cannot take account
1 of them when deciding how to optimize.  Jumps from 'asm' to C labels are
1 only supported in extended 'asm'.
1 
1  Under certain circumstances, GCC may duplicate (or remove duplicates
1 of) your assembly code when optimizing.  This can lead to unexpected
1 duplicate symbol errors during compilation if your assembly code defines
1 symbols or labels.
1 
1  *Warning:* The C standards do not specify semantics for 'asm', making
1 it a potential source of incompatibilities between compilers.  These
1 incompatibilities may not produce compiler warnings/errors.
1 
1  GCC does not parse basic 'asm''s ASSEMBLERINSTRUCTIONS, which means
1 there is no way to communicate to the compiler what is happening inside
1 them.  GCC has no visibility of symbols in the 'asm' and may discard
1 them as unreferenced.  It also does not know about side effects of the
1 assembler code, such as modifications to memory or registers.  Unlike
1 some compilers, GCC assumes that no changes to general purpose registers
1 occur.  This assumption may change in a future release.
1 
1  To avoid complications from future changes to the semantics and the
1 compatibility issues between compilers, consider replacing basic 'asm'
1 with extended 'asm'.  See How to convert from basic asm to extended asm
1 (https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended) for information
1 about how to perform this conversion.
1 
1  The compiler copies the assembler instructions in a basic 'asm'
1 verbatim to the assembly language output file, without processing
1 dialects or any of the '%' operators that are available with extended
1 'asm'.  This results in minor differences between basic 'asm' strings
1 and extended 'asm' templates.  For example, to refer to registers you
1 might use '%eax' in basic 'asm' and '%%eax' in extended 'asm'.
1 
1  On targets such as x86 that support multiple assembler dialects, all
1 basic 'asm' blocks use the assembler dialect specified by the '-masm'
1 command-line option (⇒x86 Options).  Basic 'asm' provides no
1 mechanism to provide different assembler strings for different dialects.
1 
1  For basic 'asm' with non-empty assembler string GCC assumes the
1 assembler block does not change any general purpose registers, but it
1 may read or write any globally accessible variable.
1 
1  Here is an example of basic 'asm' for i386:
1 
1      /* Note that this code will not compile with -masm=intel */
1      #define DebugBreak() asm("int $3")
1