Talkback: Discuss this article with peers

"Linux Gazette...making Linux just a little more fun!"

1. Introduction

1.1 Legal blurb

Copyright © 1999-2000 Konstantin Boldyshev. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation.

1.2 Obtatining this document

The latest version of this document is available from https://linuxassembly.org/intro.html. If you are reading a few-months-old copy, please check the url above for a new version.

1.3 Tools you need

You will need several tools to play with programs included in this tutorial.

First of all you need assembler (compiler). As a rule modern UNIX distribution includes gas (GNU Assembler), but all examples specified here use another assembler -- nasm (Netwide Assembler). You can download it from the nasm page, it comes with full source code. Compile it, or try to find precompiled binary for your OS; note that several distributions (at least Linux ones) already have nasm, check first.

Second, you need linker -- ld, since nasm produces only object code. Any distribution should embrace ld.

If you're going to dig in, you should also install include files for your OS, and if possible, kernel source.

Now you should be ready to start, welcome..

2. Hello, world!

Now we will write our program, classical "Hello, world" (hello.asm). You can download its sources and binaries here. But before let me explain several basics.

2.1 System call

Unless program is just implementing some math algorithms in assembly, it will deal with such things as getting input, producing output, and exiting. Here comes a need to call some OS service. In fact, programming in assembly language is quite the same in different OSes, unless OS services are touched.

There are two common ways of performing a system call in UNIX OS: trough the C library (libc) wrapper, or directly.

Using or not using libc in assembly programming is more a question of taste/belief than something practical. Libc wrappers are made to protect program from possible system call convention change, and to provide POSIX compatible interface, if kernel lacks it for some call. However usually UNIX kernel is more or less POSIX compliant, this means that syntax of most libc "system calls" exactly matches syntax of real kernel system calls (and vice versa). But main drawback of throwing libc away is that are loosing several functions that are not just syscall wrappers, like printf(), malloc() and similar.

This tutorial will show how to use direct kernel calls, since this is the fastest way to call kernel service; our code is not linked to any library, it communicates with kernel directly.

Things that differ in different UNIX kernels are set of system calls and system call convention (however as they strive for POSIX compliance, there's a lot of common between them).

Note for (former) DOS programmers: so, what is that system call? Better to explain it in such a way: if you ever wrote a DOS assembly program (and most IA32 assembly programmers did), you remember DOS services int 0x21, int 0x25, int 0x26 etc.. This is what can be designated as system call. However the actual implementation is absolutely different, and this doesn't mean that system calls necessary are done via some interrupt. Also, quite often DOS programmers mix OS services with BIOS services like int 0x10 or int 0x16, and are very surprised when they fail to perform them in UNIX, since these are not OS services).

2.2 Program layout

As a rule, modern IA32 UNIXes are 32bit (*grin*), run in protected mode, have flat memory model, and use ELF format for binaries.

Program can be divided into sections (or segments): .text for your code (read-only), .data for your data (read-write), .bss for uninitialized data (read-write); actually there can be few other, as well as user-defined sections, but there's rare need to use them and they are out of our interest here. Program must have at least .text section.

Ok, now we'll dive into OS specific details.

2.3 Linux

System calls in Linux are done through int 0x80. (actually there's a kernel patch allowing system calls to be done via syscall (sysenter) instruction on newer CPUs, but this thing is still experimental).

Linux differs from usual UNIX calling convention, and features "fastcall" convention for system calls (it resembles DOS). System function number is passed in eax, and arguments are passed through registers, not the stack. There can be up to five arguments in ebx, ecx, edx, esi, edi consequently. If there's more than five arguments, they are simply passed though the structure as first argument. Result is returned in eax, stack is not touched at all.

System call function numbers are in sys/syscall.h, but actually in asm/unistd.h, some documentation is in the 2nd section of manual (f.e. to find info on write system call, issue man 2 write).

There are several attempts to made up-to-date documentation of Linux system calls, examine URLs in the references.

So, our Linux program will look like:

---

section .text
    global _start                       ;must be declared for linker (ld)

msg     db      'Hello, world!',0xa     ;our dear string
len     equ     $ - msg                 ;length of our dear string

_start:                 ;we tell linker where is entry point

        mov     edx,len ;message length
        mov     ecx,msg ;message to write
        mov     ebx,1   ;file descriptor (stdout)
        mov     eax,4   ;system call number (sys_write)
        int     0x80    ;call kernel

        mov     eax,1   ;system call number (sys_exit)
        int     0x80    ;call kernel

---

As you will see futther, Linux syscall convention is the most compact one.

Kernel source references:

• arch/i386/kernel/entry.S
• include/asm-i386/unistd.h
• include/linux/sys.h

2.4 FreeBSD

FreeBSD has "usual" calling convention, when syscall number is in eax, and parameters are on the stack (the first argument is pushed the last). System call is to be performed through the function call to a function containing int 0x80 and ret, not just int 0x80 itself (return address MUST be on the stack before int 0x80 is issued!). Caller must clean up the stack after call. Result is returned as usual in eax.

Also there's an alternate way of using call 7:0 gate instead of int 0x80. End-result is the same, not counting increase of program size, since you will also need to push eax before, and these two instructions occupy more bytes.

System call function numbers are in sys/syscall.h, documentation is in the 2nd section of man.

Ok, I think the source will explain this better:

Note: Included code may run on other *BSD as well, I think.

---

section .text
    global _start                       ;must be declared for linker (ld)

msg     db      "Hello, world!",0xa     ;our dear string
len     equ     $ - msg                 ;length of our dear string

_syscall:               
        int     0x80            ;system call
        ret

_start:                         ;tell linker entry point

        push    dword len       ;message length
        push    dword msg       ;message to write
        push    dword 1         ;file descriptor (stdout)
        mov     eax,0x4         ;system call number (sys_write)
        call    _syscall        ;call kernel

                                ;actually there's an alternate
                                ;way to call kernel:
                                ;push   eax
                                ;call   7:0

        add     esp,12          ;clean stack (3 arguments * 4)

        push    dword 0         ;exit code
        mov     eax,0x1         ;system call number (sys_exit)
        call    _syscall        ;call kernel

                                ;we do not return from sys_exit,
                                ;there's no need to clean stack

---

Kernel source references:

• i386/i386/exception.s
• i386/i386/trap.c
• sys/syscall.h

2.5 BeOS

BeOS kernel is using "usual" UNIX calling convention too. The difference from FreeBSD example is that you call int 0x25.

On information where to find system call function numbers and other interesting details, examine asmutils, especially os_beos.inc file.

Note: to make nasm compile correctly on BeOS you need to insert #include "nasm.h" into float.h, and #include <stdio.h> into nasm.h.

---

section .text
    global _start                       ;must be declared for linker (ld)

msg     db      "Hello, world!",0xa     ;our dear string
len     equ     $ - msg                 ;length of our dear string

_syscall:                       ;system call
        int     0x25
        ret

_start:                         ;tell linker entry point

        push    dword len       ;message length
        push    dword msg       ;message to write
        push    dword 1         ;file descriptor (stdout)
        mov     eax,0x3         ;system call number (sys_write)
        call    _syscall        ;call kernel
        add     esp,12          ;clean stack (3 * 4)

        push    dword 0         ;exit code
        mov     eax,0x3f        ;system call number (sys_exit)
        call    _syscall        ;call kernel
                                ;no need to clean stack

---

2.6 Building binary

Building binary is usual two-step process of compiling and linking. To make binary from our hello.asm we must do the following:

$ nasm -f elf hello.asm         # this will produce hello.o object file
$ ld -s -o hello hello.o        # this will produce hello executable

That's it. Simple. Now you can launch hello program by entering ./hello, it should work. Look at the binary size -- surprised?

3. References

I hope you enjoyed the journey. If you get interested in assembly programming for UNIX, I strongly encourage you to visit Linux Assembly for more information, and download asmutils package, it contains a lot of sample code. For comprehensive overview of Linux/UNIX assembly programming refer to the Linux Assembly HOWTO.

Thank you for your interest!

Copyright © 2000, Konstantin Boldyshev
Published in Issue 53 of Linux Gazette, May 2000