GCC's Assembler Syntax

This documentation is better viewed on a desktop computer.

Right below is the index of this page. Beyond that, here is some useful notation:

• Non-trivial asm examples come with a [ godbolt ] link. Matt Godbolt's website hosts Compiler Explorer , a very useful resource to check out how compilers handle some given input.
• Instructions link to the x86 instruction documentation that is also hosted on this website.
• asm arguments are co lo red to be more easily identifiable.
• Constraint strings have their background highlighted and have a tooltip that explains the constraint.

asm is a statement , not an expression.

asm <optional stuff> (
	    "assembler template"
	    : outputs
	    : inputs
	    : clobbers
	    : labels)

Quick notes:

• the starting asm keyword is either asm or __asm__ , at your convenience
• <optional stuff> may be empty, or the keyword(s) volatile or goto (explained below)
• "assembler template" is a required string that encodes the instruction(s) that you want to run (explained below)
• there is a combined maximum of 30 inputs and outputs per asm statement
• outputs, inputs, clobbers, and labels are all optional. Colons are only required up to the parameter that you wish to use, and having nothing between colons is valid when you wish to skip a parameter. For instance, each of these (explained below) are valid:
  • asm volatile("lfence");
  • asm("movq %0, %0" : "+rm" (foo));
  • asm("addl %0, %1" : "+r" (foo) : "g" (bar));

The assembler template contains instructions and operand placeholders. You should think of it as a format string. This string will be "printed" to the assembly file that the compiler generates. Instructions must be separated by a newline (literally \n ), and it's popular to prefix them with a tab or spaces (although this is not necessary). The template is a good use case for C's string literal concatenation :

asm("<a href="/x86/NOP.html">nop</a>\n"
	    "<a href="/x86/NOP.html">nop</a>\n"
	    "<a href="/x86/NOP.html">nop</a>\n")

In this format string:

• you specify arguments using %N , where N refers to an argument by its zero-based number in order of appearance (outputs and inputs being in the same "namespace", outputs being first)
• you specify named arguments using %[Name] (see below for how to specify names)
• you specify a literal % by using %% , which you will need if you reference registers directly in x86 assembly with the AT&T syntax
• the GCC documentation additionally specifies %= , {= , %| and %} , which this page does not cover

Outputs and inputs are the parameters to your assembler template "format string". They are comma-separated. They both use either one of the two following patterns:

"constraint" (expression)
	[Name] "constraint" (expression)

Note that although this looks metasyntactic, these are in fact the literal spellings that you must use: [Name] (when used) needs to be enclosed in square brackets, "constraint" needs to be enclosed in double quotes, and (expression) needs to be enclosed in parentheses.

"constraints" , and the kind of (expression) s that are valid, are explained in the,andsections below.

When you specify the optional [Name] field, you become able to refer to that input or output using the %[Name] syntax in the assembler template. For instance:

int foo = 1;
	asm("inc %[IncrementMe]" : [IncrementMe] "+r" (foo));
	// foo == 2

Even when names are specified, you can still refer to operands using the numbered syntax. Corollary: named arguments contribute to the sequence of numbered arguments. The second argument of an asm statement is always available as %1 , regardless of whether the first argument has a name or not.

Constraints

int add(int a, int b) {
	    asm("addl %1, %0" : "+r" (a) : "rm" (b));
	    return a;
	}

add:
	    // Per x86_64 System V calling convention:
	    // * a is held in edi.
	    // * b is held in esi.
	    // The return value will be held in eax.
	    
	    // The compiler chooses to move `a` to eax before
	    // the add (it could arbitrarily do it after).
	    <a href="/x86/MOV.html">movl</a> %edi, %eax 
	    
	    // `b` does not need to be moved anywhere, it is
	    // already in a register.
	    
	    // The compiler can emit the addition.
	    <a href="/x86/ADD.html">addl</a> %esi, %eax
	    
	    // The result of the addition is returned.
	    <a href="/x86/RET.html">ret</a>

int x = 3;
	asm volatile("int %0" :: "i" (x) : "memory");
	// [godbolt] produces "int 3" at -O1 and above;
	// [godbolt] errors out at -O0

Outputs

=
+

asm("addl %1, %0" : "+rm" (foo) : "g" (bar))

asm("add %0, %1, %2" : "=r" (foo) : "r" (bar), "r" (baz))

Inputs

asm volatile("<a href="/x86/MFENCE.html">mfence</a>");

Clobbers are the list of writable locations that the assembly code might have modified, and which have not been specified in outputs. These can be:

• Register names (on x86, both register and %register are accepted, such as rax or %rax )
• The special name cc , which specifies that the assembly altered condition flags. On platforms that keep multiple sets of condition flags as separate registers, it's also possible to name indvidual registers: for instance, on PowerPC, you can specify that you clobber cr0 .
• The special name memory , which specifies that the assembly wrote to memory that is not directly visible to the compiler (for instance, by dereferencing a pointer input). A memory clobber forces the compiler to be pessimistic about memory operations.

The compiler will generate a diagnostic if you attempt to use an unknown clobber location.

Some architectures implicitly clobber some registers on any asm statement, with no way of opting out. One relevant example is that on x86, the flags register is always clobbered. (A previous version of this document recommended that all asm statements for x86 clobber cc .) The compiler will not emit a diagnostic if you explicitly clobber a register that is also implicitly clobbered. There does not appear to be a documented list of per-architecture adjustments to clobbers: the source informs that at the time of writing (October 2019), 7 architectures do it (CRIS, x86, MN103, NDS32, PDP11, IBM RS/6000, Visium), but this author is not familiar enough with most of them to tell what's going on.

As an example of clobbering, theimul instruction takes a single operand but modifies rax and rdx implicitly. You would have to specify them in the clobber list to ensure that the compiler doesn't keep anything it needs later in either of those registers.

// [godbolt]
	asm(
	    "movq  %[left], %%rax\n"
	    "imulq %[right]\n"
	    "movq  %%rax, %[low]\n"
	    "movq  %%rdx, %[high]\n"
	    : [low] "=rm" (low), [high] "=rm" (high)
	    : [left] "g" (left), [right] "rm" (right)
	    : "rax", "rdx")

It's always possible to branch within your asm code. With a little bit of extra effort, it's also possible to branch out of your asm statement, to labels that are available to your enclosing C function. To achieve this, you use asm goto .

When you use asm goto , it becomes impossible to specify outputs (this quirk is due to fairly fundamental decisions in the internal code representation of GCC), and you become able to specify labels as a fourth kind of parameter in your asm statement. Label arguments do not have constraints and cannot be named: they must be referred to by %N . For example:

// [godbolt]
	int add_overflows(long lhs, long rhs) {
	    asm goto(
	        "movq %%rax, %[left]\n  "
	        "addq %[right], %%rax\n  "
	        "jo %2"
	        : // can't have outputs
	        : [left] "g" (lhs), [right] "g" (rhs)
	        : "rax"
	        : on_overflow);
	    return 0; // no overflow
	    on_overflow: return 1; // had an overflow
	}

(This example's functionality can arguably be replicated with a flag output operand . Seeabove.)

Labels can only be C labels: they can't be other code addresses, such as functions or an indirect goto label variable.

Note that an asm goto statement is always implicitly volatile .

All examples are x86_64. Most x86 instructions clobber CPU flags, so almost all examples here have the cc clobber.

This section additionally uses x86-specific constraints that bind to named registers:

• a , b , c , d : the a , b , c , d registers, respectively (the " a " register being contextually al , ax , eax or rax , for example)
• D : the di register
• S : the si register

Rotate left

[godbolt]
	int rotate_left(unsigned long long value, unsigned char count) {
	    asm("rolq %[count], %0"
	        : "+a" (value)
	        : [count] "ci" (count));
	    return value;
	}

Do a two-word multiplication

// [godbolt]
	void imul128(
		int64_t left, int64_t right,
		int64_t* lo, int64_t* hi) {
	    asm(
	        "movq %[lhs], %0\n  "
	        "imulq %[rhs]"
	        : "=a" (*lo), "=d" (*hi)
	        : [lhs] "g" (left), [rhs] "rm" (right));
	}

Call the Linux write system call

// [godbolt]
	int do_write(int fp, void* ptr, size_t size) {
		int retval;
		asm volatile(
		    "movl %[read], %%eax\n  "
		    "syscall"
		    : "=a"(retval)
		    : "D" (fp), "S" (ptr), "d" (size),
		      [read] "i" (SYS_write)
		    : "rcx", "r11");
		return retval;
	}