An absolute beginner to x64 ASM on Linux

[ker2x]

Hello hello !
I always wanted to write a tutorial.

i choose this topic :
- because it's hard to find that kind of tutorial and most of them are really old (Old tools, 32bits, ...).
- On linux because there is tons of free tools and the system is heavily documented
- because you may have tried ASM on 32bits and, seriously, it's a pain. x64 is really easier (thx to the xmm registers!)
- because i still need to learn a lot about this topic, and writing a tutorial is a good way to learn more  
- because ASM is FUN !

It will be written over many days/weeks/month(?).
Feel free to correct me if i'm wrong/inaccurate, or to ask question (we'll see if i can answer it, or if someone else can).

I'll assume basic knowledge about linux, some kind of programming skill (any language, as long as you know what's a variable, a loop, stuff like that), and basic knowledge about computer architecture (what's a CPU, memory, binary, hexadecimal, ...).

you'll need gcc (any version should be ok, i guess), yasm (it probably exist in every common linux distro), and a cool text editor (eg : nano, emacs, vi, vim, ...).
the yasm homepage (for the documentation) : http://yasm.tortall.net/

PS : It will be written over many post.

[ker2x]

Hey, you'll need a x64 CPU too  
A VM is ok.

If you want to know more about your CPU.
Type :

Code:

cat /proc/cpuinfo

Here is how it looks on the computer i use. if you have many core, the output can be many page (25 lines per cores including HyperThreading), i paste only the info from the last core (N° 23), they are all the sames.

Code:

processor       : 23
vendor_id       : GenuineIntel
cpu family      : 6
model           : 44
model name      : Intel(R) Xeon(R) CPU           X5670  @ 2.93GHz
stepping        : 2
cpu MHz         : 2926.330
cache size      : 12288 KB
physical id     : 11
siblings        : 2
core id         : 1
cpu cores       : 2
apicid          : 23
initial apicid  : 23
fpu             : yes
fpu_exception   : yes
cpuid level     : 11
wp              : yes
flags           : fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush dts acpi mmx fxsr sse sse2 ss ht syscall nx rdtscp lm constant_tsc arch_perfmon pebs bts rep_good xtopology tsc_reliable nonstop_tsc aperfmperf pni ssse3 cx16 sse4_1 sse4_2 popcnt hypervisor lahf_lm ida arat
bogomips        : 5852.66
clflush size    : 64
cache_alignment : 64
address sizes   : 40 bits physical, 48 bits virtual
power management:

most interesing line are self explanatory.
The last core is numbered "23", so i have 24 core (the first core is 0) and it's a Xeon X5670 @2.93Ghz.
(This computer have 2 CPU with 6 core per cpu and HyperThreading enabled : 2*6*2 = 24)
(Well, actually, according to Intel i should say 12 cores / 24 threads)

The most interesting line is the "flags" line.
I don't know all flags (feel free to search on google about them) but the flags i really want to know are thoses about SSE.
I can see that this CPU support SSE, SSE2, SSSE3, SSE4.1, SSE4.2 aaaaaaand.... no AVX support  

SSSE3 is not a typo, it exists : http://en.wikipedia.org/wiki/SSSE3
I suppose it also include the SSE3 instruction too. (i can't see the flags "sse3, only "ssse3").

The "hypervisor" flags means i'm running on a VM.

next post : Do nothing  

[marius]

Hello hello !
I always wanted to write a tutorial.

i choose this topic :
- because it's hard to find that kind of tutorial and most of them are really old (Old tools, 32bits, ...).
- On linux because there is tons of free tools and the system is heavily documented
- because you may have tried ASM on 32bits and, seriously, it's a pain. x64 is really easier (thx to the xmm registers!)
- because i still need to learn a lot about this topic, and writing a tutorial is a good way to learn more  
- because ASM is FUN !

It will be written over many days/weeks/month(?).
Feel free to correct me if i'm wrong/inaccurate, or to ask question (we'll see if i can answer it, or if someone else can).

I'll assume basic knowledge about linux, some kind of programming skill (any language, as long as you know what's a variable, a loop, stuff like that), and basic knowledge about computer architecture (what's a CPU, memory, binary, hexadecimal, ...).

you'll need gcc (any version should be ok, i guess), yasm (it probably exist in every common linux distro), and a cool text editor (eg : nano, emacs, vi, vim, ...).
the yasm homepage (for the documentation) : http://yasm.tortall.net/

PS : It will be written over many post.

Not to ding asm, but
you're aware of stuff like http://gcc.gnu.org/onlinedocs/gcc/Vector-Extensions.html and friends, I assume?

These days, I'd try hard writing using that layer of abstraction as much as possible and keep leveraging the ever increasing smarts of the compiler. And its excellent ability of dealing with all the tedious bits, bookkeeping and calling convention cruft.

If not good enough, I'd take the compiler asm output and tweak the bits the compiler is confused about.

[ker2x]

time to open your favorite text editor, write some ASM and run it !

The syntax of yasm is very simple :

Each source line contains (unless it is a macro, a preprocessor directive or an assembler directive) some combination of the four fields :

Code:

label:  instruction operands        ; comment

As usual, most of these fields are optional; the presence or absence of any combination of a label, an instruction and a comment is allowed.
Of course, the operand field is either required or forbidden by the presence and nature of the instruction field.

more info here : http://www.tortall.net/projects/yasm/manual/html/nasm-language.html#nasm-syntax  (note : yasm use the nasm syntax).

exit.asm :

Code:

; do nothing and exit with status code 42

segment .text
global main

main:
        nop             ; do nothing
        mov eax, 1   ; The "exit" syscall number
        mov ebx, 42  ; have an exit code of 42
        int 0x80        ; the thing that pokes the kernel and says, "Yo, do this"

there is already a lot to say about this but... later !

now in your shell type :

Code:

yasm -f elf64 -g dwarf2 -l exit.lst exit.asm

it will produce an exist.lst (it will show in a human readable version the generated hexadecimal code) and an exit.o (the binary stuff).

now you'll need to make it an executable code :

Code:

gcc -o exit exit.o

You can run it doing

Code:

./exit

(don't forget the ./ or you'll run the "exit" shell command and will... close your shell session )

If everything worked correctly, you shouldn't see anything (no warning, error, output).
To see the exit code (and be sure that our code worked correctly), type in your shell :

Code:

echo $?

$? print the exit code of the last command you executed.

Here is how it look on my computer :

Code:

ker2x@mandelbrot:~/asm$ vim exit.asm
ker2x@mandelbrot:~/asm$ yasm -f elf64 -g dwarf2 -l exit.lst exit.asm
ker2x@mandelbrot:~/asm$ gcc -o exit exit.o
ker2x@mandelbrot:~/asm$ ./exit
ker2x@mandelbrot:~/asm$ echo $?
42
ker2x@mandelbrot:~/asm$

next post : more about exit.asm

[cKleinhuis]

ehrm @ker2x if you really want to make this tutorial ... and you want it to really help someone, do you really think using a forum thread is the best solution for this ?

... i mean ... it is crumpled up right from the start ... i could offer you a subdomain of fractalforums running a wiki, like i did for
http://ultrafractalwiki.fractalforums.com/

[ker2x]

(i include my reply to marius : Yes, i know. You probably noticed that i never wrote that the goal was to write faster code than compiler generated code   . I just said it was FUN!
)

Now, more about exit.asm

Another version could be :
exit2.asm

Code:

segment .text
global _start

_start:
        nop
        mov eax, 1
        mov ebx, 42
        int 0x80

If you do that, you shouldn't call gcc to create the executable, you just need to link the .o

Code:

ker2x@mandelbrot:~/asm$ yasm -f elf64 -g dwarf2 -l exit2.lst exit2.asm
ker2x@mandelbrot:~/asm$ ld -o exit2 exit2.o
ker2x@mandelbrot:~/asm$ ./exit2
ker2x@mandelbrot:~/asm$ echo $?
42

it will also produce much much smaller code (on my computer ~1.6KB instead of ~7KB).

Actually, the real entry point of a linux executable is not "main" but "_start".
By using "main", you have to create your executable with gcc so gcc can  incorporate its own version of "_start" (and the gcc's "_start" will call "main" after doing tons of nasty stuff i don't know about. My guess is that it add stuff like signal handling, stdin/stdout/sterr, and so on... ).

there is probably a lot of inaccuracy about what i just wrote but i hope you got the point, isn't ?

Just as a side experiment, you can try to use ld instead of gcc on exit.o (the version that use "main")

Code:

ker2x@mandelbrot:~/asm$ ld -o exit exit.o
ld: warning: cannot find entry symbol _start; defaulting to 00000000004000b0

it complain about the executable entry point and ... it works! because... ho no please don't make me write about memory mapping. but ld tried its best to make it works despite the lack of _start entry point and it worked in this case.

Just to be on the safe side, i'll always use "main" and gcc unless i have a very good reason to not do it (which is unlikely).

Now let's go back to exit.asm :

Code:

; do nothing and exit with status code 42

segment .text
global main

main:
        nop             ; do nothing
        mov eax, 1      ; The "exit" syscall number
        mov ebx, 42     ; have an exit code of 42
        int 0x80        ; the thing that pokes the kernel and says, "Yo, do this"

The first is obviously a comment ignored by yasm.

segment .text is not an ASM instruction but a directive to tell that we're in the "text" segment. On linux the text segment is where the executable code live.
a very quick introduction to different segment can be found here :
http://en.wikipedia.org/wiki/Code_segment (segment .text)
http://en.wikipedia.org/wiki/Data_segment (segment .data)
http://en.wikipedia.org/wiki/.bss (segment .bss)


global main is another assembler directive. we tell yasm that the "main" label need to be made known to the linker (or gcc in our case).

main: i guess it is self-explanatory. this is the "main" label, just a location. (remember "GOTO a_label" in basic ? pretty much the same thing).

now follow real ASM code ! yay \o/

Our first instruction is the "nop" asm instruction it take no operand and do nothing.
we can remove it, but i wrote that our first program do nothing and exit with status code 42. so i did nothing.
(side note : the fact that this instruction exist is interesting, i suggest wikipedia and google : http://en.wikipedia.org/wiki/Nop )

Next, we'll exit.
Exiting is a system call. to do a system call on linux the asm code is "int 0x80".
Before doing the system call we want to define which system call we want to do with which parameter (if any)
The best reference i know about system call on linux is : http://syscalls.kernelgrok.com/

the row #1 is the one we want : sys_exit.
it is the system call "0x01" and it take 1 argument (the exit code) in the register ebx.

To write something somewhere, we'll use the "MOV" instruction. it take 2 operands : the destination, followed by the src.
Remember, not "MOV src, dest" but "MOV dest,src". don't ask me why we write the destination first. (but feel free to read about "Intel vs AT&T Syntax", eg : http://www.imada.sdu.dk/Courses/DM18/Litteratur/IntelnATT.htm )

Like many instruction, MOV can have different kind of operand. For now, let's just say that we want to write the immediate value "0x01" to the register "eax".
"0x01" mean that it's written in hexadecimal which is also 1 in decimal, that's why i just wrote "1" instead of "0x01".
We need to write our exit code (42) into the ebx register. (i wrote 42 in decimal too, i could also use 0x2A (42 write in hexadecimal).

Code:

        mov eax, 1      ; The "exit" syscall number
        mov ebx, 42     ; have an exit code of 42

Now that our register are setted correctly to call sys_exit with code 42, we can call the system by doing

Code:

        int 0x80

job done !

Question ?

next : the data segment

[ker2x]

ehrm @ker2x if you really want to make this tutorial ... and you want it to really help someone, do you really think using a forum thread is the best solution for this ?

... i mean ... it is crumpled up right from the start ... i could offer you a subdomain of fractalforums running a wiki, like i did for
http://ultrafractalwiki.fractalforums.com/

As you wish  

Edit : well, if you think it's a bad idea i can stop here and write this tutorial in french (my french is better than my english  ) on my blog. The goal of this tutorial is, of course, to write a mandelbrot renderer in 100% asm

[cKleinhuis]

@ker2x dont feel interrupted if you already have it sorted on your blog seems fine
crazy project btw

[ker2x]

Hello Fractalforums!

So far, our only way to communicate with the world is the exit code, which is annoying because the exit code is just an int.
We'll print a friendly "Hello Fractalforums!".

There is many way to write something on the standard output, we'll see that later, the main problem right now is to find a way to store the string.
There is, also, different way to store data. The goal for now is to use the "data" segment.

The data segment is where we put our global static data initialized by the programmer inside the exectuable itself.
Let's take another a new look at wikipedia http://en.wikipedia.org/wiki/Data_segment

A data segment is a portion of virtual address space of a program, which contains the global variables and static variables that are initialized by the programmer. This size of this segment is determined by the values placed there by the programmer before the program was compiled or assembled, and does not change at run-time.

Please note the existence of :
- the BSS segment that can store uninitialized data
- the HEAP area, managed by malloc
- the stack, used by the asm insutrction PUSH, POP, CALL and RET.


Well... back to our data.
According to the YASM documentation :

DB, DW, DD, DQ, DT, DDQ, and DO are used to declare initialized data in the output file.
DT does not accept numeric constants as operands, and DDQ does not accept float constants as operands. Any size larger than DD does not accept strings as operands.

RESB, RESW, RESD, RESQ, REST, RESDQ, and RESO are designed to be used in the BSS section of a module: they declare uninitialised storage space.

to use in data segment :
    db      0x55                ; just the byte 0x55
    db      0x55,0x56,0x57      ; three bytes in succession
    db      'a',0x55            ; character constants are OK
    db      'hello',13,10,'$'   ; so are string constants
    dw      0x1234              ; 0x34 0x12
    dw      'a'                 ; 0x41 0x00 (it's just a number)
    dw      'ab'                ; 0x41 0x42 (character constant)
    dw      'abc'               ; 0x41 0x42 0x43 0x00 (string)
    dd      0x12345678          ; 0x78 0x56 0x34 0x12
    dq      0x1122334455667788  ; 0x88 0x77 0x66 0x55 0x44 0x33 0x22 0x11
    ddq     0x112233445566778899aabbccddeeff00
    ; 0x00 0xff 0xee 0xdd 0xcc 0xbb 0xaa 0x99
    ; 0x88 0x77 0x66 0x55 0x44 0x33 0x22 0x11
    do     0x112233445566778899aabbccddeeff00 ; same as previous
    dd      1.234567e20         ; floating-point constant
    dq      1.234567e20         ; double-precision float
    dt      1.234567e20         ; extended-precision float

to use in bss segment :
    buffer:         resb    64      ; reserve 64 bytes
    wordvar:        resw    1       ; reserve a word
    realarray       resq    10      ; array of ten reals
    ...

db = 8 bit = 1 byte  (mnemonic : Data Byte)
dw = 16 bits = 2 bytes (Data Word)
dd = 32 bits = 4 bytes (Data Double-word)
dq = 64 bits = 8 bytes (Data Quad-word)
not sure about do and dt, never seen them before.

Please note that YASM recognize a 'string' and also add the null terminator at the end of the string. So we don't need to do something like

Code:

db    'h','e','l','l','o',0

We also want to add a cariage return (\n), the ASCII hexadecimal code for \n is 0x0a, and we need a label to refered to this string (we'll call it "hello)

Let's store our string in the data segment.

Code:

section .data
    hello:   db  'Hello Fractalforums!',0x0a

Yes... very easy


We're not printing anything yet. we just stored the string we want to print.
As said earlier, there is many way to do that.
The obvious (if you coded a hello world in C) is to use printf, which is too overkill for us. We don't need any formating or fancy stuff.
We could use fputs which is simplier.

the problem with this solution is that they are not ASM instruction.
We can call an external function from asm code and we'll learn to do that later.

We know how to do a ssytem call, and there is a system call to write stuff \o/

Back to http://syscalls.kernelgrok.com/ row #4 :
sys_write
eax : 0x04
ebx : unsigned int fd
ecx : const char __user *buf
edx : size_t count

fd is the file descriptor number. the standard output is "1"
*buf is our string
count is the string size

hello.asm :

Code:

; Hello fractalforums !

section .data
    hello:   db  'Hello Fractalforums!',0x0a

section .text
global main

main:
    ; Call sys_write(1, "hello world\n", 21)
    mov eax, 4
    mov ebx, 1
    mov ecx, hello
    mov edx, 21
    int 0x80
    ; Call sys_exit(0)
    mov eax, 1
    xor ebx, ebx    ; same as mov ebx, 0 (but more efficient)
    int 0x80

note that i exit with code 0, which is the usual code for a normal program termination without error.

Code:

ker2x@arthurus:~/asm/hello$ yasm -f elf64 hello.asm
ker2x@arthurus:~/asm/hello$ gcc -o hello hello.o
ker2x@arthurus:~/asm/hello$ ./hello
Hello Fractalforums!
ker2x@arthurus:~/asm/hello$

There is a way to let YASM count the size of the hello string.
Please take a look at the YASM documentation about "EQU" (a pseudo-instruction) and "$-label" (an expression)

hello.asm:

Code:

; Hello fractalforums !

section .data
    hello:   db  'Hello Fractalforums!',0x0a
    msglen:    equ $-hello

section .text
global main

main:
    ; Call sys_write(1, "hello world\n", 21)
    mov eax, 4
    mov ebx, 1
    mov ecx, hello
    mov edx, msglen
    int 0x80
    ; Call sys_exit(0)
    mov eax, 1
    xor ebx, ebx    ; same as mov ebx, 0 (but more efficient)
    int 0x80

Pfew... question ?

PS @cKleinhuis : no, i didn't wrote anything on my blog. the main goal was to write an asm tutorial on fractalforums to create fractals using ASM.
It's not as big as you might think. Just 1 or 2 more post to learn to call external function, pass/retrieve parameters and the x64 ABI.
Then everything else will be about fractal code, optimisation and SSE* instruction. 

[ker2x]

I have a question.
i'm not sure which solution is best :
- Writing the fractal image to a file (a .ppm, easiest image format to use and very portable).
- Open a graphical output using the good old Xlib
- Open a graphical output using the SDL lib.
- something else ?

Any thought ?

PS : By replacing "main" with "_start", using ld instead of gcc, and using sstrip on the generated executable, the executable size is reduced to 229 bytes instead of ~8.5 KB 
good way to start a 4k intro 

[ker2x]

i found a super cool image format that is understood on a standard linux distro and super easy to write in asm :
http://people.sc.fsu.edu/~jburkardt/data/ppmb/ppmb.html

there is nothing new in this ASM code, i'm not calling external function as i initially planed :

Code:

; create a ppmb file
; http://people.sc.fsu.edu/~jburkardt/data/ppmb/ppmb.html

segment .data
    header:     db  'P6 4 4 255', 0x0a
    headerlen:  equ $-header
    image:      db  255,0,0, 0,255,0, 0,0,255, 255,255,255
    imagelen:   equ $-image

segment .text
global main

main:
    mov eax, 4
    mov ebx, 1
    mov ecx, header
    mov edx, headerlen
    int 0x80
    mov eax, 4
    mov ebx, 1
    mov ecx, image
    mov edx, imagelen
    int 0x80
    mov eax, 4
    int 0x80
    mov eax, 4
    int 0x80
    mov eax, 4
    int 0x80
    ; Call sys_exit(0)
    mov eax, 1
    xor ebx, ebx
    int 0x80

step one :
write "P6 4 4 255" + '\n' : P6 is the magic number for the file format, 4 is the wdith in pixel, 4 is the height, 255 is the maximum pixel value in this file (255 being the maximum allowed in the 'binary format'.

step two :
write 4 RGB pixels fort the 1st line :
255,0,0 : Red
0,255,0 : Green
0,0,255 : Blue
255,255,255 : White

step three : repeat for the 2nd, 4rde, 4th line

step four : exit

the good thing with this format is that i can write binary value instead of the ascii code for of the value (that require printf or similar). (yes, there is a difference between 255 and '255'   ).

Code:

ker2x@arthurus:~/asm/ppmb$ yasm -f elf64 ppmb.asm 
ker2x@arthurus:~/asm/ppmb$ gcc -o ppmb ppmb.o 
ker2x@arthurus:~/asm/ppmb$ ./ppmb | hexdump
0000000 3650 3420 3420 3220 3535 ff0a 0000 ff00
0000010 0000 ff00 ffff ffff 0000 ff00 0000 ff00
0000020 ffff ffff 0000 ff00 0000 ff00 ffff ffff
0000030 0000 ff00 0000 ff00 ffff 00ff          
000003b

of course, you can redirect to a file :
ker2x@arthurus:~/asm/ppmb$ ./ppmb > four.ppm
and open the resuling file with any image viewer.

note that you can't do :

Code:

    int 0x80
    int 0x80
    int 0x80
    int 0x80

because the eax register is overwritten by the return code of the system call, so you have to rewrite mov eax, 4 again  
(yes, i did that mistake, and it called some funny random system call) :

Code:

syscall_4294967282(0x1, 0x7fffdbdcda28, 0xc, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0) = -1 (errno 38)

enjoy. The next step will be file creation, which is easy (syscall again \o/ )

[ker2x]

the output, converted to png :

[ker2x]

ok you were right...

i just discovered that i mixed X86_64 and x86 (32bits) system call convention.
It works but it's wrong, i should rewrite everything

So i'll write a full tutorial somewhere and post a link later.

Feel free to PM if you have any question while i'm writing this tutorial offline 

[real_het]

But hey!

You must step on the interesting part which is available both on 32 and 64 bit modes: the SSE asm  Thats's where manual asm is needed: the 128bit data paralell instructions and the complicated workarounds to make them work.

[ker2x]

But hey!

You must step on the interesting part which is available both on 32 and 64 bit modes: the SSE asm  Thats's where manual asm is needed: the 128bit data paralell instructions and the complicated workarounds to make them work.

all my coding stuff is on standby, i was on vacation. but i'm still planning to complete this guide, SSE included of course