Syscalls

The system call (syscall) mechanism is used by applications to access kernel services. The userland (application/non-kernel) program loads certain registers designating the system service (syscall) desired and the arguments to that syscall, then invokes a software interrupt or exception request which transfers control to the operating system kernel. Note that switching to kernel mode requires a change of processor mode (sometimes call the privilege level or exception level), because the kernel has access to instructions, memory structures, memory areas, and devices which userland programs can't access. The syscall numbers may vary between architectures, and the registers as well as the method used to invoke syscalls are architecture-specific. The processor modes and activity involved in a userland-to-kernel switch also vary by architecture.

High-level languages wrap the syscall interface in basic wrappers or more advanced mechanisms. For example, in C, the write syscall can be accessed through the write() wrapper, or through more complex functions such as printf(). Assembly language programs will often access syscalls directly.

Syscall Mechanism

To invoke a syscall in your own code, load the syscall number and arguments into the appropriate registers, and then invoke the architecture-specific syscall mechanism, using the details below:

x86 32-bit

• The syscall number is placed in eax.
• Integer and pointer arguments are placed in edi, esi, edx, ecx with spill over to the stack (refer to ABI documentation).
• Return value is in eax.
• The syscall is invoked with int 0x80

x86 64-bit

• The syscall number is placed in rax.
• Integer and pointer arguments are placed in rdi, rsi, rdx, rcx, r8d, r9d with spill over to the stack (refer to ABI documentation).
• Return value is in rax.
• The syscall is invoked with syscall

aarch64

• The syscall number is placed in r8.
• Integer and pointer arguments are placed in r0-r7 with spill over to the stack (refer to Procedure Call and ABI documentation).
• Return value is in r0.
• The syscall is invoked with svc 0

Syscall information, numbers, and arguments

Syscall numbers

Syscall numbers are defined in <asm/unistd.h> (/usr/include/asm/unistd.h). If you examine this file, you'll find that it includes different files depending on the platform, because the syscall numbers are platform-specific (on newer platforms, there has been an attempt to use consistent syscall numbers). In this included file, you will find macros for each syscall named __NR_syscall which identifies the number for each syscall. For example, aarch64 includes the file /usr/include/asm-generic/unistd.h, which lists this macro for the write syscall:

#define __NR_write 64

But on x86_64 the macro definition is taken from /usr/include/asm/unistd_64.h:

#define __NR_write 1

Syscall arguments and return values

The details of each syscall's arguments and return value are listed in <unistd.h> (/usr/include/unistd.h) in a combination of comments and C extern declarations.For example, for the write syscall:

/* Write N bytes of BUF to FD.  Return the number written, or -1.

   This function is a cancellation point and therefore not marked with
   __THROW.  */
extern ssize_t write (int __fd, const void *__buf, size_t __n) __wur;

This documents that the write syscall takes three arguments: the file descriptor, a pointer to the message buffer, and the message size, and returns the number of bytes written or -1 if there was an error.

Documentation

A list of syscalls can be found in the manpage for syscalls(2) (note: this is different from the manpage for syscall(2) which is a generic syscall wrapper).

Documentation for the C wrappers for most syscalls can be found in the manpage for that wrapper, usually in section 2 of the manual (e.g., write(2), which is accessed using the command man 2 write).

Using the syscall macro definitions in asm code

The syscall macros can be used in an assembly program if that program is processed by the C preprocessor (cpp). The extension .S (uppercase instead of lowercase) is used to designate an assembler source file that must be processed by cpp.

There are two ways to do this for a pure assembler source file:

1. Invoke cpp explicitly:

cpp foo.S > foo.s
as foo.s -o foo.o
ld foo.o -o foo

2. Use gcc to invoke the assembler and linker:

gcc foo.S -o foo

Initialization Code and Entry Point
When the assembler is invoked through gcc, C initialization code is inserted into the binary, which increases its size. This initialization uses the entry point _start and expects your code to have the entry point main.

Using either of these approaches, you can use the __NR_xxxx macros in your assembler code:

#include <asm/unistd.h>
...
        mov $__NR_write,%rax