Chris Tyler's Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====  Syscall  =====

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 [[Computer_Architecture#Interrupts_and_Exceptions|interrupt]] or exception request which transfers control to the operating system kernel. Note that switching to kernel mode requires a change of [[Computer_Architecture#Execution_State,_Priviledge_State,_Rings,_or_Privilege_Level|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 generic ''syscall'' wrapper, the ''write()'' wrapper, or through more complex functions such as ''puts'' or ''printf()''. [[Assembly Language|Assembly language]] programs will often access syscalls directly.

=====  Syscall Mechanism  =====

Every platform has a different syscall mechanism. Each mechanism is documented in the ABI standards for that platform, and a summary of various platforms is contained in the manpage for syscall(2) (run the command ''man 2 syscall'' to see this).

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''

(There are some alternate calling mechanisms, such as vsyscall and sysenter/sysexit, which are not discussed here).
====  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 names, numbers, and arguments  =====

====  Syscall names  ====

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). View this with the command ''man 2 syscalls''

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'').

====  Syscall numbers  ====

Syscall numbers are defined in <nowiki><asm/unistd.h></nowiki> (''/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 ''<nowiki>__</nowiki>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:

<code>
 #define __NR_write 64</code>

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

<code>
 #define __NR_write 1</code>

You can use the ''ausyscall'' utility, which part of the Linux //audit// package, to determine the number for a given syscall on a particular platform:

<code>
 $ ausyscall x86_64 write
 write              1
 pwrite             18
 writev             20
 pwritev            296
 process_vm_writev  311
 $ ausyscall aarch64 write
 write              64
 writev             66
 pwrite             68
 pwritev            70
 process_vm_writev  271</code>

Note that ''ausyscall'' searches the syscall table by name, and in the examples above the text "write" partially matches five different syscalls. The architecture defaults to the current platform if not specified.

====  Syscall arguments and return values  ====

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

<code>
 /* 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;</code>

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.

=====  Using the syscall number 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:

<code>
 cpp foo.S > foo.s
 as foo.s -o foo.o
 ld foo.o -o foo</code>

2. Use //gcc// to invoke the assembler and linker:

<code>
 gcc foo.S -o foo</code>

Note: 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''. However, when the assembler is invoked directly, the C initialization code is not inserted, and the entry point should be ''_start''.

Using either of these approaches, you can use the ''<nowiki>__</nowiki>NR_//xxxx//'' macros in your assembler code:

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