GCC's assembler syntax

Constraint strings bridge your C expressions to assembler operands. They are necessary because the compiler doesn't know what kind of operands are valid for what instructions. In fact, for all the compiler cares, operands aren't even required to be operands to any instructions: you could use them in comments or instruction names, or not use them at all, as long as the output string is valid to the assembler.

For a valid example, in "imul %0, %1, %2":

• the first operand has to be a register
• the second operand may be a register or a memory address
• the last operand has to be a constant integer value

The constraint string for each operand must communicate these requirements to GCC. For instance, it will ensure that the destination value lives in a register that can be used at the point of this statement.

GCC defines many types of constraints, but on 2019's desktop/mobile platforms, those are the constraints that are the most likely to be used:

• r specifies that the operand must be a general-purpose register
• m specifies that the operand must be a memory address
• i specifies that the operand must be an integer constant
• g specifies that the operand must be a general-purpose register, or a memory address, or an integer constant (effectively the same as "rmi")

As implied by the g constraint, it is possible to specify multiple constraints for each argument. By specifying multiple constraints, you allow the compiler to pick the operand kind that suits it best when the same instruction has multiple forms. This is useful on x86 and not so much on ARM, because x86 overloads mnemonics with many operand types.

For example, in this code:

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

This is one way the compiler could choose to satisfy the r constraint:

	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).
	    movl %edi, %eax 
	    
	    // `b` does not need to be moved anywhere, it is
	    // already in a register.
	    
	    // The compiler can emit the addition.
	    addl %esi, %eax
	    
	    // The result of the addition is returned.
	    ret

Note that when it comes to i, the satisfiability of the constraint may depend on your optimization levels. Passing an integer literal or an enum value always works, but when it comes to variables, it depends on the compiler's ability to fold constants. For instance, this will work at -O1 and above, but not -O0, because the compiler needs to establish that x has a constant value:

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

GCC documents the full list of platform-independent constraints, as well as the full list of platform-specific constraints.

Outputs specify lvalues where the result should be stored at the end of the operation. As a refresher, the concept of lvalue in C is nebulous, but something that is assignable is usually an lvalue (variables, dereferenced pointers, array subscripts, structure fields, etc). Most lvalues are accepted as operands, as long as the constraint can be respected: for instance, it's possible to pass a bitfield with r (register), but not with m (memory) as you cannot take the address of a bitfield. (The same applies to Clang's vector types).

In addition, the constraint string of an output must be prefixed with either = or +.

• + means that the output is actually a read-write value. The operand initially has the value contained by the expression. It's fine to read from this output operand at any point in the assembly string.
• =& means that the output is an early-clobber output. Its initial value is unspecified. It is not a bug to read from an =& operand once it has been assigned a value.
• = means that the output is write-only. The compiler can choose to give an = output the same location as an input: for that reason, it is usually a bug to write to it before the last instruction of your assembly snippet.
• =@ccCOND is a special case of = that allows you to query the result of a condition code at the end of your assembly statement. You cannot reference a condition output in your assembly template.

For instance, almost all x86 instructions read and write to their first operand: you need to use the + prefix to communicate that. A simple example would be:

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

The initial value of foo is important here, because it's what bar will be added to. (The whole constraint string additionally specifies that foo may be referenced in the assembler string as a register or a memory address, since x86 has instruction forms for both.)

On the other hand, almost no ARM instruction uses the initial value of its destination register. In those cases, you would use = to communicate that. The ARM equivalent to the above would be:

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

(ARM only supports computations on registers, so all the operands are register operands.)

When you use = for an output, the compiler may reuse a location that was used as an input. This can lead to incorrect code generation if you also read from that output. For instance, in this assembly code:

	asm("movl $123, %0 \n  "
	    "addl %1, %0"
	    : "=&r"(foo)
	    : "r"(bar));

The =& constraint is necessary: the mov that writes to %0 isn't the last instruction of the sequence, and this asm statement has inputs. If we used =, the compiler could have selected the same register for %1 and %0! Note that this works and it is safe if your statement has a single instruction, such as in the ARM case above. However, with our two-instruction example, instead of doing the equivalent of foo = bar + 123, this code could now be doing "movl $123, %eax; addl %eax, eax", which is just foo = 246. You solve this problem by using =&, which tells the compiler that it can't use the same location as it used for an input.

Condition code outputs

	// [godbolt]
	asm("subq %3, %2"
	    : "=@ccc"(*carry), "=@cco"(*overflow)
	    : "g"(left), "g"(right));

Inputs can be any value, as long as it makes sense for the constraint. For instance, to use the i constraint, the compiler must be able to find that the value is a constant. They are not prefixed with anything.

Instead of passing a constraint, you may pass the index of an output constraint (optionally prefixed with %). When you do so, you tell the compiler to use the same location for that input and that output. This is not valid for + outputs: the compiler will emit a diagnostic. In fact, you may think of a + output as a shorthand for "="(foo) as an output and "0"(foo) as an input. Using = or =& in that case makes no difference.

As such, these two examples have the same result:

	asm("xorq %0, %0" : "+r"(foo));
	asm("xorq %1, %0" : "=r"(foo)) : "0"(foo));

The use of volatile

	asm volatile("syscall" : "=a"(ret_val) :: "rcx", "r11");

This example left-rotates a 64-bit integer. The encoding of rol is tricky, requiring the count operand to either be an immediate value, or (very specifically) the cl register.

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

Using the ci constraint, the compiler is able to use a constant value when it is available, or else fall back on the cl register.

Multiply two 64-bit integers and return the 128-bit result (by address). Here we use the x86-specific a and d constraints, which specify "the rax register" and "the rdx register", respectively. The variant of the register is chosen by the compiler to be size-appropriate; 32-bit values get eax, for instance.

This example is interesting because it has implicitly-referenced outputs. Using the =d output constraint to bind *hi, we cause the compiler to move the value of rdx to *hi at the end of the assembly code, even though it is not explicitly used by the assembly string.

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

By binding inputs to registers using x86-specific constraints, we let the compiler do any necessary lifting to move argument values to the syscall argument registers. On x86_64 Linux, in the normal case, no moving at all is required for the first 4 arguments.

The operating system uses the value of rax to determine which system call is being invoked.

	// [godbolt]
	int do_write(int fp, void* ptr, size_t size) {
		int rax = SYS_write;
		asm volatile(
		    "syscall"
		    : "+a"(rax)
		    : "D" (fp), "S" (ptr), "d" (size)
		    : "rcx", "r11");
		return rax;
	}

Here, we use +a for rax, as syscall implicitly reads from it (through the operating system's behavior).