GNU Assembler

Examples
GAS, the GNU Assembler, is the default assembler for the GNU Operating System. It works on many
different architectures and supports several assembly language syntaxes. These examples are only for
operating systems using the Linux kernel and an x86-64 processor, however.

Getting Started
Here is the traditional Hello World program that uses Linux System calls, for a 64-bit
installation:
hello.s
#
#
#
#
#
#
#
#
#
#

---------------------------------------------------------------------------------------Writes "Hello, World" to the console using only system calls. Runs on 64-bit Linux only.
To assemble and run:
gcc -c hello.s && ld hello.o && ./a.out
or
gcc -nostdlib hello.s && ./a.out
---------------------------------------------------------------------------------------.global _start
.text

_start:
# write(1, message, 13)
mov
$1, %rax
mov
$1, %rdi
mov
$message, %rsi
mov
$13, %rdx
syscall
# exit(0)
mov
$60, %rax
xor
%rdi, %rdi
syscall
message:
.ascii "Hello, world\n"

#
#
#
#
#

system call 1 is write

file handle 1 is stdout
address of string to output
number of bytes
invoke operating system to do the write

# system call 60 is exit

# we want return code 0
# invoke operating system to exit

$gccchello.s&&ldhello.o&&./a.out
Hello,World

If you are using a different operating system, such as OSX or Windows, the system call numbers
and the registers used will likely be different.

Working with the C Library

Generally you will want to use a C library. Here's Hello World again:
hola.s
#
#
#
#
#
#

---------------------------------------------------------------------------------------Writes "Hola, mundo" to the console using a C library. Runs on Linux or any other system
that does not use underscores for symbols in its C library. To assemble and run:
gcc hola.s && ./a.out
---------------------------------------------------------------------------------------.global main
.text

main:
mov
$message, %rdi
call
puts
ret
message:
.asciz "Hola, mundo"

#
#
#
#

This is called by C library's startup code

First integer (or pointer) parameter in %rdi
puts(message)
Return to C library code

# asciz puts a 0 byte at the end

$gcchola.s&&./a.out
Hola,mundo

Calling Conventions for 64-bit C Code

The 64-bit calling conventions are a bit more detailed, and they are explained fully in the
AMD64 ABI Reference. You can also get info on them at Wikipedia. The most important points
are (again, for 64-bit Linux, not Windows):
From left to right, pass as many parameters as will fit in registers. The order in which
registers are allocated, are:
For integers and pointers, rdi, rsi, rdx, rcx, r8, r9.
For floating-point (float, double), xmm0, xmm1, xmm2, xmm3, xmm4, xmm5, xmm6,
xmm7
Additional parameters are pushed on the stack, right to left, and are removed by the caller
after the call.
After the parameters are pushed, the call instruction is made, so when the called function
gets control, the return address is at (%rsp), the first memory parameter is at 8(%rsp),
etc.
THE STACK POINTER %RSP MUST BE ALIGNED TO A 16-BYTE
BOUNDARY BEFORE MAKING A CALL. Fine, but the process of making a call
pushes the return address (8 bytes) on the stack, so when a function gets control, %rsp is
not aligned. You have to make that extra space yourself, by pushing something or
subtracting 8 from %rsp.
The only registers that the called function is required to preserve (the calle-save registers)
are: rbp, rbx, r12, r13, r14, r15. All others are free to be changed by the called function.

The callee is also supposed to save the control bits of the XMCSR and the x87 control
word, but x87 instructions are rare in 64-bit code so you probably don't have to worry
about this.
Integers are returned in rax or rdx:rax, and floating point values are returned in xmm0 or
xmm1:xmm0.
This program prints the first few fibonacci numbers, illustrating how registers have to be saved
and restored:
fib.s
#
#
#
#
#
#
#

----------------------------------------------------------------------------A 64-bit Linux application that writes the first 90 Fibonacci numbers. It
needs to be linked with a C library.
Assemble and Link:
gcc fib.s
----------------------------------------------------------------------------.global main
.text

main:
push

%rbx

# we have to save this since we use it

mov
xor
xor
inc

$90, %ecx
%rax, %rax
%rbx, %rbx
%rbx

#
#
#
#

ecx
rax
rbx
rbx

will countdown to 0
will hold the current number
will hold the next number
is originally 1

print:
# We need to call printf, but we are using eax, ebx, and ecx. printf
# may destroy eax and ecx so we will save these before the call and
# restore them afterwards.
push
push

%rax
%rcx

# caller-save register
# caller-save register

mov
mov
xor

$format, %rdi
%rax, %rsi
%rax, %rax

# set 1st parameter (format)

# set 2nd parameter (current_number)
# because printf is varargs

# Stack is already aligned because we pushed three 8 byte registers

call
printf
# printf(format, current_number)
pop
pop

%rcx
%rax

# restore caller-save register

# restore caller-save register

mov
mov
add
dec
jnz

%rax, %rdx
%rbx, %rax
%rdx, %rbx
%ecx
print

#
#
#
#
#

pop
ret

%rbx

# restore rbx before returning

.asciz

"%20ld\n"

format:

$gccfib.s&&./a.out
0
1
1
2
3
...
420196140727489673
679891637638612258
1100087778366101931
1779979416004714189

save the current number

next number is now current
get the new next number
count down
if not done counting, do some more

Mixing C and Assembly Language

This 64-bit program is a very simple function that takes in three 64-bit integer parameters and
returns the maximum value. It shows how to extract integer parameters: They will have been
pushed on the stack so that on entry to the function, they will be in rdi, rsi, and rdx,
respectively. The return value is an integer so it gets returned in rax.
maxofthree.s
#
#
#
#
#
#
#
#
#

----------------------------------------------------------------------------A 64-bit function that returns the maximum value of its three 64-bit integer
arguments. The function has signature:
int64_t maxofthree(int64_t x, int64_t y, int64_t z)
Note that the parameters have already been passed in rdi, rsi, and rdx. We
just have to return the value in rax.
----------------------------------------------------------------------------.globl

.text
maxofthree:
mov
cmp
cmovl
cmp
cmovl
ret

maxofthree

%rdi,
%rsi,
%rsi,
%rdx,
%rdx,

%rax
%rax
%rax
%rax
%rax

#
#
#
#
#
#

result (rax) initially holds x

is x less than y?
if so, set result to y
is max(x,y) less than z?
if so, set result to z
the max will be in eax

Here is a C program that calls the assembly language function.

callmaxofthree.c
/*
* callmaxofthree.c
*
* A small program that illustrates how to call the maxofthree function we wrote in
* assembly language.
*/
#include <stdio.h>
#include <inttypes.h>
int64_t maxofthree(int64_t, int64_t, int64_t);
int main() {
printf("%ld\n",
printf("%ld\n",
printf("%ld\n",
printf("%ld\n",
printf("%ld\n",
printf("%ld\n",
return 0;
}

maxofthree(1, -4, -7));

maxofthree(2, -6, 1));
maxofthree(2, 3, 1));
maxofthree(-2, 4, 3));
maxofthree(2, -6, 5));
maxofthree(2, 4, 6));

To assemble, link and run this two-part program:

$gccstd=c99callmaxofthree.cmaxofthree.s&&./a.out
1
2
3
4
5
6

Command Line Arguments

You know that in C, main is just a plain old function, and it has a couple parameters of its own:
int main(int argc, char** argv)
Here is a program that uses this fact to simply echo the commandline arguments to a program,
one per line:
echo.s
#
#
#
#
#

----------------------------------------------------------------------------A 64-bit program that displays its commandline arguments, one per line.
On entry, %rdi will contain argc and %rsi will contain argv.
----------------------------------------------------------------------------.global main
.text

main:
push
push
sub

%rdi
%rsi
$8, %rsp

# save registers that puts uses

mov
call

(%rsi), %rdi
puts

# the argument string to display

# print it

add
pop
pop

$8, %rsp
%rsi
%rdi

# restore %rsp to pre-aligned value

# restore registers puts used

add
dec
jnz

$8, %rsi
%rdi
main

# point to next argument

# count down
# if not done counting keep going

# must align stack before call

ret
format:
.asciz

"%s\n"

$gccecho.s&&./a.out25782doghuh$$
./a.out
25782
dog
huh
9971
$gccecho.s&&./a.out25782doghuh'$$'
./a.out
25782
dog
huh
$$

Note that as far as the C Library is concerned, command line arguments are always strings. If
y

you want to treat them as integers, call atoi. Here's a little program to compute x . Another
feature of this example is that it shows how to restrict values to 32-bit ones.
power.s
#
#
#
#
#
#

----------------------------------------------------------------------------A 64-bit command line application to compute x^y.

Syntax: power x y
x and y are integers
-----------------------------------------------------------------------------

.global main
.text
main:
push
%r12
# save callee-save registers
push
%r13
push
%r14
# By pushing 3 registers our stack is already aligned for calls
cmp
jne

$3, %rdi
error1

# must have exactly two arguments

mov

%rsi, %r12

# argv

# We will use ecx to count down form the exponent to zero, esi to hold the
# value of the base, and eax to hold the running product.
mov
call
cmp
jl
mov

16(%r12), %rdi
atoi
$0, %eax
error2
%eax, %r13d

# argv[2]
# y in eax
# disallow negative exponents

mov
call
mov

8(%r12), %rdi
atoi
%eax, %r14d

# argv
# x in eax
# x in r14d

mov

$1, %eax

# start with answer = 1

test
jz
imul
dec
jmp

%r13d, %r13d
gotit
%r14d, %eax
%r13d
check

# we're counting y downto 0

# done
# multiply in another x

mov
movslq
xor
call
jmp

$answer, %rdi
%eax, %rsi
%rax, %rax
printf
done

mov
call
jmp

$badArgumentCount, %edi
puts
done

mov
call

$negativeExponent, %edi
puts

pop
pop
pop
ret

%r14
%r13
%r12

# y in r13d

check:

gotit:

# print report on success

error1:

# print error message

error2:

# print error message

done:

# restore saved registers

answer:
.asciz "%d\n"
badArgumentCount:
.asciz "Requires exactly two arguments\n"
negativeExponent:
.asciz "The exponent may not be negative\n"

$./power219
524288
$./power38
Theexponentmaynotbenegative
$./power1500
1

Exercise: Rewrite this example to use 64-bit numbers everywhere. You will also need to
switch from atoi to strtol.

Floating Point Instructions

Floating-point arguments go int the xmm registers. Here is a simple function for summing the
values in a double array:
sum.s
#
#
#
#
#
#

----------------------------------------------------------------------------A 64-bit function that returns the sum of the elements in a floating-point
array. The function has prototype:
double sum(double[] array, unsigned length)
----------------------------------------------------------------------------.global sum
.text

sum:
xorpd
cmp
je

%xmm0, %xmm0
$0, %rsi
done

# initialize the sum to 0

# special case for length = 0

addsd
add
dec
jnz

(%rdi), %xmm0
$8, %rdi
%rsi
next

#
#
#
#

next:
add in the current array element
move to next array element
count down
if not done counting, continue

done:
ret

# return value already in xmm0

A C program that calls it:

callsum.c
/*
* callsum.c
*
* Illustrates how to call the sum function we wrote in assembly language.
*/
#include <stdio.h>
double sum(double[], unsigned);
int main() {
double test[] = {
40.5, 26.7, 21.9, 1.5, -40.5, -23.4
};
printf("%20.7f\n", sum(test, 6));
printf("%20.7f\n", sum(test, 2));
printf("%20.7f\n", sum(test, 0));
printf("%20.7f\n", sum(test, 3));
return 0;
}

$gcccallsum.csum.s&&./a.out
26.7000000
67.2000000
0.0000000
89.1000000

Data Sections
The text section is read-only on most operating systems, so you might find the need for a data

section. On most operating systems, the data section is only for initialized data, and you have a
special .bss section for uninitialized data. Here is a program that averages the command line
arguments, expected to be integers, and displays the result as a floating point number.
average.s
#
#
#
#
#
#

----------------------------------------------------------------------------64-bit program that treats all its command line arguments as integers and
displays their average as a floating point number. This program uses a data
section to store intermediate results, not that it has to, but only to
illustrate how data sections are used.
----------------------------------------------------------------------------.globl

main

.text
main:
dec
%rdi
jz
nothingToAverage
mov
%rdi, count
accumulate:
push
%rdi
push
%rsi
mov
(%rsi,%rdi,8), %rdi
call
atoi
pop
%rsi
pop
%rdi
add
%rax, sum
dec
%rdi
jnz
accumulate
average:
cvtsi2sd sum, %xmm0
cvtsi2sd count, %xmm1
divsd
%xmm1, %xmm0
mov
$format, %rdi
mov
$1, %rax
sub
call
add

$8, %rsp
printf
$8, %rsp

# argc-1, since we don't count program name

# save number of real arguments
# save register across call to atoi
# argv[rdi]
# now rax has the int value of arg
# restore registers after atoi call
# accumulate sum as we go
# count down
# more arguments?

# xmm0 is sum/count
# 1st arg to printf
# printf is varargs, there is 1 non-int argument
# align stack pointer
# printf(format, sum/count)
# restore stack pointer

ret
nothingToAverage:
mov
$error, %rdi
xor
%rax, %rax
call
printf
ret

count:
sum:
format:
error:

.data
.quad
.quad
.asciz
.asciz

0
0
"%g\n"
"There are no command line arguments to average\n"

Recursion
Perhaps surprisingly, there's nothing out of the ordinary required to implement recursive
functions. You just have to be careful to save registers, as usual. Here's an example. In C:
uint64_t factorial(unsigned n) {
return (n <= 1) ? 1 : n * factorial(n-1);
}

factorial.s

#
#
#
#
#
#
#

---------------------------------------------------------------------------A 64-bit recursive implementation of the function

uint64_t factorial(unsigned n)
implemented recursively
---------------------------------------------------------------------------.globl

.text
factorial:
cmp
jnbe
mov
ret
L1:
push
dec
call
pop
imul
ret

factorial

$1, %rdi
L1
$1, %rax

# n <= 1?
# if not, go do a recursive call
# otherwise return 1

%rdi
%rdi
factorial
%rdi
%rdi, %rax

#
#
#
#
#

save n on stack (also aligns %rsp!)

n-1
factorial(n-1), result goes in %rax
restore n
n * factorial(n-1), stored in %rax

An example caller:
callfactorial.c
/*
* An application that illustrates calling the factorial function defined elsewhere.
*/
#include <stdio.h>
#include <inttypes.h>
uint64_t factorial(unsigned n);
int main() {
for (unsigned i = 0; i < 20; i++) {
printf("factorial(%2u) = %lu\n", i, factorial(i));
}
}

SIMD Parallelism
The XMM registers can do arithmetic on floating point values one opeation at a time or
multiple operations at a time. The operations have the form:
operation

xmmregister_or_memorylocation, xmmregister

For floating point addition, the instructions are:

addpd
addps
addsd
addss

do
do
do
do

2 double-precision additions
just one double-precision addition, using the low 64-bits of the register
4 single-precision additions
just one single-precision addition, using the low 32-bits of the register

TODO - show a function that processes an array of floats, 4 at a time.

Saturated Arithmetic
The XMM registers can also do arithmetic on integers. The instructions have the form:
operation

xmmregister_or_memorylocation, xmmregister

For integer addition, the instructions are:

paddb do 16 byte additions
paddw do 8 word additions
paddd do 4 dword additions
paddq do 2 qword additions
paddsb do 16 byte additions with signed saturation (80..7F)
paddsw do 8 word additions with unsigned saturation (8000..7FFF)
paddusb do 16 byte additions with unsigned saturation (00..FF)
paddusw do 8 word additions with unsigned saturation (00..FFFF)
TODO - SHOW AN EXAMPLE

Local Variables and Stack Frames

First, please read Eli Bendersky's article That overview is more complete than my brief notes.
When a function is called the caller will first put the parameters in the correct registers then
issue the call instruction. Additional parameters beyond those covered by the registers will be
pushed on the stack prior to the call. The call instruction puts the return address on the top of
stack. So if you have the function
long example(long x, long y) {
long a, b, c;
b = 7;
return x * b + y;
}

Then on entry to the function, x will be in %edi, y will be in %esi, and the return address will
be on the top of the stack. Where can we put the local variables? An easy choice is on the stack
itself, though if you have enough regsters, use those.
If you are running on a machine that respect the standard ABI, you can leave %rsp where it is
and access the "extra parameters" and the local variables directly from %rsp for example:
+----------+
rsp-24 |
a
|
+----------+
rsp-16 |
b
|
+----------+
rsp-8 |
c
|
+----------+

rsp
rsp+8

| retaddr |
+----------+
| caller's |
| stack
|
| frame
|
| ...
|
+----------+

So our function looks like this:

.text
.globl
example:
movl
mov
imul
add
ret

example
$7, -16(%rsp)
%rdi, %rax
8(%rsp), %rax
%rsi, %rax

If our function were to make another call, you would have to adjust %rsp to get out of the way
at that time.
On Windows you can't use this scheme because if an interrupt were to occur, everything above
the stack pointer gets plastered. This doesn't happen on most other operating systems because
there is a "red zone" of 128 bytes past the stack pointer which is safe from these things. In this
case, you can make room on the stack immediately:
example:
sub

$24, %rsp

so our stack looks like this:

+----------+
rsp
|
a
|
+----------+
rsp+8 |
b
|
+----------+
rsp+16 |
c
|
+----------+
rsp+24 | retaddr |
+----------+
rsp+32 | caller's |
| stack
|
| frame
|
| ...
|
+----------+
Here's the function now. Note that we have to remember to replace the stack pointer before
returning!
.text
.globl
example:
sub

example
$24, %rsp

movl
mov
imul
add
add
ret

$7, 8(%rsp)
%rdi, %rax
8(%rsp), %rax
%rsi, %rax
$24, %rsp