Yes, this is [inline assembly](https://en.wikipedia.org/wiki/Inline_assembler) or in other words assembler code which is integrated in a high level programming language. In my case this high level programming language is [C](https://en.wikipedia.org/wiki/C_%28programming_language%29). Yeah, the `C` programming language is not very high-level, but still.
Yes, this is [inline assembly](https://en.wikipedia.org/wiki/Inline_assembler) or in other words assembler code which is integrated in a high level programming language. In this case the high level programming language is [C](https://en.wikipedia.org/wiki/C_%28programming_language%29). Yes, the `C` programming language is not very high-level, but still.
If you are familiar with [assembly](https://en.wikipedia.org/wiki/Assembly_language) programming language, you may notice that `inline assembly` is not very different from the usual. Moreover, the special form of inline assembly which is called `basic form` is the same. For example:
If you are familiar with the [assembly](https://en.wikipedia.org/wiki/Assembly_language) programming language, you may notice that `inline assembly` is not very different from normal assembler. Moreover, the special form of inline assembly which is called `basic form` is exactly the same. For example:
```C
__asm__("movq %rax, %rsp");
@ -36,18 +36,18 @@ __asm__("movq $3, %rax\t\n"
"movq %rsi, %rdi");
```
The `asm` keyword may be used in place of `__asm__`, however `__asm__` is portable whereas `asm` is the `GNU`-specific [extension](https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html). Further I will use only `__asm__` variant in examples.
The `asm` keyword may be used in place of `__asm__`, however `__asm__` is portable whereas the `asm` keyword is a `GNU` [extension](https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html). In further examples I will only use the `__asm__` variant.
If you know assembly programming language this looks pretty easy. The main problem is in the second form of inline assembly statements:`extended`. This form allows us to pass parameters to an assembly statement, perform [jumps](https://en.wikipedia.org/wiki/Branch_%28computer_science%29), etc. Not so hard, but this leads to the need to know the additional extended rules as well as having knowledge of assembly language. Every time I see yet another piece of inline assembly code in the Linux kernel, I need to refer to the official [documentation](https://gcc.gnu.org/onlinedocs/) of `GCC` to remember how a particular `qualifier` behaves or what the meaning of the `=&r` is, for example.
If you know assembly programming language this looks pretty familiar. The main problem is in the second form of inline assembly statements -`extended`. This form allows us to pass parameters to an assembly statement, perform [jumps](https://en.wikipedia.org/wiki/Branch_%28computer_science%29) etc. Does not sound difficult, but requires knowledge of special rules in addition to knowledge of the assembly language. Every time I see yet another piece of inline assembly code in the Linux kernel, I need to refer to the official [documentation](https://gcc.gnu.org/onlinedocs/) of `GCC` to remember how a particular `qualifier` behaves or what the meaning of `=&r` is for example.
I've decided to write this to consolidate my knowledge related to inline assembly here. As inline assembly statements are quite common in the Linux kernel and we may see them in [linux-insides](https://0xax.gitbooks.io/linux-insides/content/) parts sometimes, I thought that it would be useful if we would have a special part which contains descriptions of the more important aspects of inline assembly. Of course you may find comprehensive information about inline assembly in the official [documentation](https://gcc.gnu.org/onlinedocs/gcc/Using-Assembly-Language-with-C.html#Using-Assembly-Language-with-C), but I like the rules all in one place.
I've decided to write this part to consolidate my knowledge related to the inline assembly, as inline assembly statements are quite common in the Linux kernel and we may see them in [linux-insides](https://0xax.gitbooks.io/linux-insides/content/) parts sometimes. I thought that it would be useful if we have a special part which contains information on more important aspects of the inline assembly. Of course you may find comprehensive information about inline assembly in the official [documentation](https://gcc.gnu.org/onlinedocs/gcc/Using-Assembly-Language-with-C.html#Using-Assembly-Language-with-C), but I like to put everything in one place.
** Note: This part will not provide a guide for assembly programming. It is not intended to teach you to write programs with assembler and to know what one or another assembler instruction means. Just a little memo for extended asm. **
** Note: This part will not provide guide for assembly programming. It is not intended to teach you to write programs with assembler or to know what one or another assembler instruction means. Just a little memo for extended asm. **
So, let's start. As I already wrote above, the `basic` assembly statement consists of the `asm` or `__asm__` keyword and a set of assembly instructions. If you are familiar with assembly programming language, there is no sense in writing something additional about it. The most interesting part of inline assembly are those statements in the extended syntax, or those with operands. An extended assembly statement looks a little more complicated and consists of these parts:
So, let's start. As I already mentioned above, the `basic` assembly statement consists of the `asm` or `__asm__` keyword and set of assembly instructions. This form is in no way different from "normal" assembly. The most interesting part is inline assembler with operands, or `extended` assembler. An extended assembly statement looks more complicated and consists of more than two parts:
All parameters which are marked with squared brackets are optional. You may notice that if we skip all the optional parameters and also the `volatile` and `goto` qualifiers, we get the `basic` form. Let's start to consider this in order. The first optional `qualifier` is `volatile`. This specifier tells the compiler that an assembly statement may produce `side effects`. In this case we need to prevent the compiler's optimization related to the given assembly statement. In simple words, the `volatile` specifier tells to compiler not to touch this statement and to put it in the same place where it was in the original code. For example let's look at the following function from the [Linux kernel](https://github.com/torvalds/linux/blob/master/arch/x86/include/asm/desc.h):
All parameters which are marked with squared brackets are optional. You may notice that if we skip the optional parameters and the modifiers `volatile` and `goto` we obtain the `basic` form.
Let's start to consider this in order. The first optional `qualifier` is `volatile`. This specifier tells the compiler that an assembly statement may produce `side effects`. In this case we need to prevent compiler optimizations related to the given assembly statement. In simple terms the `volatile` specifier instructs the compiler not to modify the statement and place it exactly where it was in the original code. As an example let's look at the following function from the [Linux kernel](https://github.com/torvalds/linux/blob/master/arch/x86/include/asm/desc.h):
Here we see the `native_load_gdt` function which loads the base address of the [Global Descriptor Table](https://en.wikipedia.org/wiki/Global_Descriptor_Table) to the `GDTR` register with the `lgdt` instruction. This assembly statement is marked with the `volatile` qualifier. It is very important that the compiler will not change the original place of this assembly statement in the resulting code, otherwise the `GDTR` register may contain an invalid address for the `Global Descriptor Table` or the address may be correct, but the structure isn't filled yet. In this way an exception will be generated and the kernel will not boot correctly.
Here we see the `native_load_gdt` function which loads a base address from the [Global Descriptor Table](https://en.wikipedia.org/wiki/Global_Descriptor_Table) to the `GDTR` register with the `lgdt` instruction. This assembly statement is marked with `volatile` qualifier. It is very important that the compiler does not change the original place of this assembly statement in the resulting code. Otherwise the `GDTR` register may contain wrong address for the `Global Descriptor Table` or the address may be correct, but the structure has not been filled yet. This can lead to an exception being generated, preventing the kernel from booting correctly.
The second optional `qualifier` is the `goto`. This qualifier tells to the compiler that the given assembly statement may perform a jump to one of the labels which are listed in the `GotoLabels`. For example:
The second optional `qualifier` is the `goto`. This qualifier tells the compiler that the given assembly statement may perform a jump to one of the labels which are listed in the `GotoLabels`. For example:
```C
__asm__ goto("jmp %l[label]" : : : label);
```
As we finish with these two qualifiers, let's consider the main part of an assembly statement body. As we can see, the main part of an assembly statement consists of the following four parts:
Since we finished with these two qualifiers, let's look at the main part of an assembly statement body. As we have seen above, the main part of an assembly statement consists of the following four parts:
* set of assembly instructions;
* output parameters;
* input parameters;
* clobbers.
The first represents a string which contains a set of valid assembly instructions which may be separated by the `\t\n` sequence. Names of processor [registers](https://en.wikipedia.org/wiki/Processor_register) must be prefixed with the `%%` sequence in `extended` form and other symbols like immediates must start from the `$` symbol. The `OutputOperands` and `InputOperands` are comma-separated lists of [C](https://en.wikipedia.org/wiki/C_%28programming_language%29) variables which may be provided with `constraints` and the `Clobbers` is a list of registers or other values which are changed by the assembler instructions from the `AssemblerTemplate` beyond those listed in the `OutputOperands`. But before we can consider the first example again we must also know about `constraints`. A constraint is a string which specifies placement of an operand. For example the value of an operand may be written to a processor register, can be read from memory, etc.
The first represents a string which contains a set of valid assembly instructions which may be separated by the `\t\n` sequence. Names of processor [registers](https://en.wikipedia.org/wiki/Processor_register) must be prefixed with the `%%` sequence in `extended` form and other symbols like immediates must start with the `$` symbol. The `OutputOperands` and `InputOperands` are comma-separated lists of [C](https://en.wikipedia.org/wiki/C_%28programming_language%29) variables which may be provided with "constraints" and the `Clobbers` is a list of registers or other values which are modified by the assembler instructions from the `AssemblerTemplate` beyond those listed in the `OutputOperands`. Before we dive into the examples we have to know a little bit about `constraints`. A constraint is a string which specifies placement of an operand. For example the value of an operand may be written to a processor register or read from memory etc.
Now let's consider the following simple example:
Consider the following simple example:
```C
#include<stdio.h>
@ -100,7 +102,7 @@ int main(void)
}
```
Before we consider this example, let's compile and run it to be sure that it works as expected:
Let's compile and run it to be sure that it works as expected:
```
$ gcc test.c -o test
@ -108,7 +110,7 @@ $ gcc test.c -o test
a + b = 15
```
Ok, great. It works. Now let's consider this example. Here we see a simple `C` program which calculates sum of two variables and puts the result into the `sum` variable. In the end we just print the result. This example consists of three parts: The first is an assembly statement with the [add](http://x86.renejeschke.de/html/file_module_x86_id_5.html) instruction which adds the value of the source operand to the value of the destination operand and stores the result in the destination operand. In our case:
Ok, great. It works. Now let's look at this example in detail. Here we see a simple `C` program which calculates the sum of two variables placing the result into the `sum` variable and in the end we print the result. This example consists of three parts. The first is the assembly statement with the [add](http://x86.renejeschke.de/html/file_module_x86_id_5.html) instruction. It adds the value of the source operand together with the value of the destination operand and stores the result in the destination operand. In our case:
```assembly
addl %1, %2
@ -120,25 +122,25 @@ will be expanded to the:
addl a, b
```
Variables and expressions which are listed in the `OutputOperands` and `InputOperands` may be matched in the `AssemblerTemplate`. An input/output operand is designated as `%N` where the `N` is the number of the operand from left to right starting at`zero`. The second part of the our assembly statement is located after the first `:` symbol and represents the definition of the output value:
Variables and expressions which are listed in the `OutputOperands` and `InputOperands` may be matched in the `AssemblerTemplate`. An input/output operand is designated as `%N` where the `N` is the number of operand from left to right beginning from`zero`. The second part of the our assembly statement is located after the first `:` symbol and contains the definition of the output value:
```assembly
"=r" (sum)
```
Notice that `sum` is marked with two special symbols: `=r`. This is the first constraint that we have encountered. Actually the constraint here is only `r`. The `=` symbol is a `modifier` which denotes the output value. This tells the compiler that the previous value will be discarded and replaced by the new data. Besides the `=` modifier, `GCC` provides support for the following three modifiers:
Notice that the `sum` is marked with two special symbols: `=r`. This is the first constraint that we have encountered. The actual constraint here is only `r` itself. The `=` symbol is `modifier` which denotes output value. This tells to compiler that the previous value will be discarded and replaced by the new data. Besides the `=` modifier, `GCC` provides support for following three modifiers:
* `+` - an operand is read and written by an instruction;
* `&` - output register shouldn't overlap an input register and should be used only for output;
* `%` - tells the compiler that operands may be [commutative](https://en.wikipedia.org/wiki/Commutative_property).
Now let's back to the `r` qualifier. As I already wrote above, a qualifier denotes placement of an operand. The `r` symbol means a value will be stored in one of the [general purpose register](https://en.wikipedia.org/wiki/Processor_register). The last part of our assembly statement:
Now let's go back to the `r` qualifier. As I mentioned above, a qualifier denotes the placement of an operand. The `r` symbol means a value will be stored in one of the [general purpose register](https://en.wikipedia.org/wiki/Processor_register). The last part of our assembly statement:
```assembly
"r" (a), "0" (b)
```
are input operands - `a` and `b` variables. We already know what the `r` qualifier mean. Now we may notice a new constraint before the `b` variable. A `0` or any other digit from `1` to `9` is called a `matching constraint`. With this the assembler may use only one a single operand that fills two roles. As you may guess, here the value of the constraint provides the number order of operands. In our case `0` will match `sum`. If we look at assembly output of our program:
These are input operands - variables `a` and `b`. We already know what the `r` qualifier does. Now we can have a look at the constraint for the variable `b`. The `0` or any other digit from `1` to `9` is called "matching constraint". With this a single operand can be used for multiple roles. The value of the constraint is the source operand index. In our case `0` will match `sum`. If we look at assembly output of our program
```C
0000000000400400 <main>:
@ -147,21 +149,21 @@ are input operands - `a` and `b` variables. We already know what the `r` qualifi
40040b: 01 d0 add %edx,%eax
```
we will see that only two general purpose registers are used: `%edx` and `%eax`. In this way the `%eax` register is used to store the value of the `b` variable as the result of calculation. We have considered input and output parameters of an inline assembly statement but before we meet other constraints supported by `gcc`, there is still another part of inline assembly statements we must consider:`clobbers`.
we see that only two general purpose registers are used: `%edx` and `%eax`. This way the `%eax` register is used for storing the value of `b` as well as storing the result of the calculation. We have looked at input and output parameters of an inline assembly statement. Before we move on to other constraints supported by `gcc`, there is one remaining part of the inline assembly statement we have not discussed yet -`clobbers`.
As I wrote above, the `clobbered` part should contain a comma-separated list of registers which will be changed in the `AssemblerTemplate`. This may be useful when our assembly expression needs an additional register for calculation and only the output parameter will be changed. If we add a clobbered register to the inline assembly statement, the compiler will take this into account and the register will not be reused in an incorrect manner.
As mentioned above, the "clobbered" part should contain a comma-separated list of registers whos content will be modified by the assembler code. This is useful if our assembly expression needs additional registers for calculation. If we add clobbered registers to the inline assembly statement, the compiler take this into account and the register in question will not simultaneously be used by the compiler.
Let's consider the same example, but let's add an additional simple assembler expression:
Consider the example from before, but we will add an additional, simple assembler instruction:
```C
__asm__("movq $100, %%rdx\t\n"
"addl %1,%2" : "=r" (sum) : "r" (a), "0" (b));
```
If we look at the assembly output:
If we look at the assembly output
```C
0000000000400400 <main>:
@ -171,14 +173,14 @@ If we look at the assembly output:
400411: 01 d0 add %edx,%eax
```
We will see that the `%edx` register will be overwritten with a value of`0x64` or `100` and the result will be `115` instead of `15`. Now if we add the `%rdx` register to the list of `clobbered` registers:
we see that the `%edx` register is overwritten with`0x64` or `100` and the result will be `115` instead of `15`. Now if we add the `%rdx` register to the list of "clobbered" register
@ -188,18 +190,18 @@ and look at the assembler output again:
400411: 01 c8 add %ecx,%eax
```
Now we see that the `%ecx` register will be used for the `sum` calculation. Besides general purpose registers, we may pass two special specifiers. They are:
the `%ecx` register will be used for `sum` calculation, preserving the intended semantics of the program. Besides general purpose registers, we may pass two special specifiers. They are:
* `cc`;
* `memory`.
The first - `cc` indicates that an assembler statement modifies the [flags](https://en.wikipedia.org/wiki/FLAGS_register) register. It is common to pass `cc` to clobbers list for arithmetic or logic instructions:
The first - `cc` indicates that an assembler code modifies [flags](https://en.wikipedia.org/wiki/FLAGS_register) register. This is typically used if the assembly within contains arithmetic or logic instructions.
```C
__asm__("incq %0" ::""(variable): "cc");
```
The second specifier, `memory`, tells the compiler that the given inline assembly statement executes arbitrary write or read operations in memory which is not pointed to by operands listed in output list. This allows the compiler to prevent values loaded from memory from being cached in registers. Let's take a look at the following example:
The second `memory` specifier tells the compiler that the given inline assembly statement executes read/write operations on memory not specified by operands in the output list. This prevents the compiler from keeping memory values loaded and cached in registers. Let's take a look at the following example:
```C
#include<stdio.h>
@ -215,7 +217,7 @@ int main(void)
}
```
Of course, this example may seem artificial... Ok, this is in fact the case, but it may help show us the main concept. Here we have an array of integer numbers and one integer variable. The example is pretty simple: We take the first element of the `a` array and increment its value. After this we subtract the value of the `b` variable from the just incremented value of the first element in the `a` array. In the end we just print the result. If we compile and run this simple example, the result may surprise us:
This example may be artificial, but it illustrates the main idea. Here we have an array of integers and one integer variable. The example is pretty simple, we take the first element of `a` and increment its value. After this we subtract the value of `b` from the first element of `a`. In the end we print the result. If we compile and run this simple example the result may surprise you.
```
~$ gcc -O3 test.c -o test
@ -223,7 +225,7 @@ Of course, this example may seem artificial... Ok, this is in fact the case, but
a[0] - b = 5
```
The result is `5` here, but why? We increased the value of the first element of the `a` array, so the result must be `6` here. Let's look at the assembler output of this example:
The result is `5` here, but why? We incremented `a[0]` and subtracted b, so the result should be `6` here. If we have a look at the assembler output for this example
```assembly
00000000004004f6 <main>:
@ -237,15 +239,15 @@ The result is `5` here, but why? We increased the value of the first element of
400512: b8 05 00 00 00 mov $0x5,%eax
```
At the first line we see that the first element of the `a` array contains `0xa` or `10` value. The last two lines of code are actual calculations. We increment value of the first item of our array with `incl` instruction and just put `5` into the `%eax` register. This looks strange. We have passed the `-O3` flag to `gcc`, so the compiler removed calculations. The problem here is that `GCC` has a copy of the array element in a register (`rsp` in our case) that was loaded from memory, but in the same way that `GCC` does not associate actual calculations with calculation in the assembly statement, it just puts the calculated result of `a[0] - b` directly into the `%eax` register.
we see that the first element of the `a` contains the value `0xa` (`10`). The last two lines of code are the actual calculations. We see our increment instruction with `incl` but then just a move of `5` to the `%eax` register. This looks strange. The problem is we have passed the `-O3` flag to `gcc`, so the compiler did some constant folding and propagation to determine the result of `a[0] - 5` at compile time and reduced it to a `mov` with a constant `5` at runtime.
Now the result is correct. If we look at the assembly output now:
Now the result is correct. If we look at the assembly output again
```assembly
00000000004004f6 <main>:
@ -269,19 +271,19 @@ Now the result is correct. If we look at the assembly output now:
400519: c3 retq
```
we will see one difference here. The difference is in the following piece of code:
we will see one difference here which is in the following piece code:
```assembly
400512: 8b 44 24 f0 mov -0x10(%rsp),%eax
400516: 83 e8 05 sub $0x5,%eax
```
Instead of direct calculation, `GCC` now associates calculation from the assembly statement and puts the value of `a[0]` into the `%eax` register after this. In the end it just subtracts the value of the `b` variable. Besides the `memory` specifier, we see a new constraint here - `m`. This constraint tells the compiler to deal with the address of the `a[0]`, instead of its value. So, now we have finished with `clobbers` and we may continue to consider other constraints supported by `GCC` besides `r` and `m`.
Instead of constant folding, `GCC` now preserves calculations in the assembly and places the value of `a[0]` in the `%eax` register afterwards. In the end it just subtracts the constant value of `b`. Besides the `memory` specifier, we also see a new constraint here - `m`. This constraint tells the compiler to use the address of `a[0]`, instead of its value. So, now we are finished with `clobbers` and we may continue by looking at other constraints supported by `GCC` besides `r` and `m` which we have already seen.
Now as we have finished with all three possible parts of an inline assembly statement, let's return to constraints. We already saw some constraints in this part, like the `r` constraint which represents a `register` operand, the `m` constraint represents a memory operand and `0-9` constraints which represent an operand that matches specified the operand number from an inline assembly statement. Besides these constraints, the `GCC` provides support for other constraints: The `i` constraint represents an `immediate` integer operand with known value:
Now that we are finished with all three parts of an inline assembly statement, let's return to constraints. We already saw some constraints in the previous parts, like `r` which represents a `register` operand, `m` which represents a memory operand and `0-9` which represent an reused, indexed operand. Besides these `GCC` provides support for other constraints. For example the `i` constraint represents an `immediate` integer operand with know value.
```C
#include<stdio.h>
@ -304,7 +306,7 @@ The result is:
a = 100
```
Or for example the `I` constraint which represents a `32-bit` integer. The difference between the `i` and `I` constraints is that `i` is more general, while `I` is for strictly `32-bit` integer data. For example if you try to compile the following example:
Or for example `I` which represents an immediate 32-bit integer. The difference between `i` and `I` is that `i` is general, whereas `I` is strictly specified to 32-bit integer data. For example if you try to compile the following
`GCC` also supports `J`, `K`, and `N` constraints for integer constants in the range `0...63` bits, signed `8-bit` integer constants and unsigned `8-bit` integer constants respectively. The `o` constraint represents a memory operand which represents an `offsetable` memory address. For example:
`GCC` also supports `J`, `K`, `N` constraints for integer constants in the range of 0-63 bits, signed 8-bit integer constants and unsigned 8-bit integer constants respectively. The `o` constraint represents a memory operand with an `offsetable` memory address. For example:
```C
#include<stdio.h>
@ -371,7 +373,7 @@ The result, as expected:
2
```
All of these constraints may be combined (of course actually not all of them). In this way the compiler will choose the best one for a given situation. For example:
All of these constraints may be combined (so long as they do not conflict). In this case the compiler will choose the best one for a certain situation. For example:
That's about all there is to commonly used constraints in inline assembly statements. You may find more in the [documentation](https://gcc.gnu.org/onlinedocs/gcc/Simple-Constraints.html#Simple-Constraints).
That's about all of the commonly used constraints in inline assembly statements. You can find more in the oficcial [documentation](https://gcc.gnu.org/onlinedocs/gcc/Simple-Constraints.html#Simple-Constraints).
Before this part is finished, let's look at the set of special constraints. These constrains are architecture specific and as this book is [x86_64](https://en.wikipedia.org/wiki/X86-64) architecture specific, we will consider constraints related to it. First of all the set of `a` ... `d` and also `S` and `D` constraints represent [generic purpose](https://en.wikipedia.org/wiki/Processor_register) registers. In this case the `a` constraint corresponds to the `%al`, `%ax`, `%eax` or `%rax` register depending on instruction size. The `S` and `D` constraints are the `%si` and `%di` registers respectively. Let's take another look at our previous example. We may see in its assembly output that the value of the `a` variable is stored in the `%eax` register. Now let's look at the assembly output of the same example, but with a different constraint:
Before we finish, let's look at the set of special constraints. These constrains are architecture specific and as this book is specific to the [x86_64](https://en.wikipedia.org/wiki/X86-64) architecture, we will look at constraints related to it. First of all the set of `a` ... `d` and also `S` and `D` constraints represent [generic purpose](https://en.wikipedia.org/wiki/Processor_register) registers. In this case the `a` constraint corresponds to `%al`, `%ax`, `%eax` or `%rax` register depending on instruction size. The `S` and `D` constraints are `%si` and `%di` registers respectively. For example let's take our previous example. We can see in its assembly output that value of the `a` variable is stored in the `%eax` register. Now let's look at the assembly output of the same assembly, but with other constraint:
```C
#include<stdio.h>
@ -422,7 +424,7 @@ Now we see that value of the `a` variable will be stored in the `%edx` register:
The `f` and `t` constraints represent any floating point stack register - `%st` and the top of the floating point stack respectively. The `u` constraint represents the second value from the top of the floating point stack.
That's all. You may find more details about [x86_64](https://en.wikipedia.org/wiki/X86-64) and constraints, including architecture specific ones, in the official [documentation](https://gcc.gnu.org/onlinedocs/gcc/Machine-Constraints.html#Machine-Constraints).
That's all. You may find more details about [x86_64](https://en.wikipedia.org/wiki/X86-64) and general constraints in the official [documentation](https://gcc.gnu.org/onlinedocs/gcc/Machine-Constraints.html#Machine-Constraints).
Justus Adam
8 years ago