Adding A System Call

1. About This Document

This document explains a way to add a system call to linux kernel. A
system call is the standard way an OS service is exported to a
user program. For example, to provide users a new semaphore like
synchronization method, some system calls need to be provided to access
it. Likewise, a system call may be used to give users access to
internal information of a file system such as superblock or inodes.
The following description is based on linux kernel version 2.2.14 on
i386 machine architecture. Also, it is assumed that readers
are familiar with Building
Linux Kernel.

2. Preparing for A New System Call

A system call cannot be called directly from a user process. Instead, they
are called indirectly via an interrupt and looked up in an interrupt table.
Thus, when you define a new system call you insert a new entry in this table.
You do this by editing the file linux/arch/i386/kernel/entry.S.
Inside, you should see lines like:

You should add #defines for your new system calls at the
end, with the prefix "__NR_" in front of it. For example, you might
add the line:

#define __NR_myservice 191

3. Places for Your System Call Source Files

After inserting your new system call entry in the interrupt table and
preparing a stub for it, you will need to define (or implement) the
system call. It will be easiest to have the system call definitions in your
own source code files, say myservice.h and myservice.c.

In general, header files for machine architecture independent system calls
and functions are kept under linux/include/linux/ and machine
architecture dependent ones are kept in linux/include/asm/.
Therefore, it would be a good idea to follow this convention. For example,
the header file for the system calls for your new synchronization method, of
which the implementation is machine architecture specific, would be
placed in linux/include/asm/, while the header file for your
machine architecture independent system call that access the superblock of
one or more of your file systems would be placed under
linux/include/linux.

The place for actual implementation file (myservice.c in
this example) could vary. For example, if you are implementing a new
process synchronization method, linux/ipc/ would be the best
place for it. If you are implementing a file system related one,
linux/fs/ would be the best place.

Remember that you will need to modify the Makefile in the
directory you placed your .c file so that your code gets compiled and linked
in properly. Modify the Makefile line to have a .o of your
source code. For example, adding myservice.o:

O_OBJS += ... myservice.o

The rest of the Makefiles can remain untouched (Makefile changes will
be similar if you choose to add your code elsewhere).

4. System Call Source File Basics

In order to be linked properly, your system calls need the word
"asmlinkage" prepended to their function header and "sys_" prepended
to the name.
For example, you would have:

Also, you will have to have #include <linux/linkage.h>
so the compiler will recognize the word "asmlinkage".

Lastly, the user "stub" can be automatically generated so that a
user program can use your system call. There are some macros defined
for this in <linux/unistd.h>. The format
is "_syscallN(return type, function name, arg1 type, arg1 name ...)"
where "N" is the number of parameters. For example, you
might have the line:

_syscall2(int, myservice, int, arg1, char*, arg2);

to generate the stub (in this case, the 2 is for 2 arguments). Note,
that your call to generate the stub (as above) should be put it in
your header file (myservice.h). Also, you need to
#include <linux/unistd.h> in myservice.h
to make this work. A user program could then just call
myservice() as they do other system calls.

Here is an example myservice.h and
myservice.c, assuming myservice.h is under
linux/include/linux/

5. Adding an Initialization Function

In case you need to have a system global variable that your
new system calls will use to keep states of some kind, which would
be the case for implementing a new process synchronization
primitive, it might be necessary to initialize the variable at system
bootup time. In this case, you need to add your own init function (in
your source file) with return type void followed by a
keyword __init. Remember to include
#include <linux/init.h> in the header to make
__init macro be recognized. Then, you need to add two
lines to linux/init/main.c to make your kernel invoke
your initialization function at bootup. For example:

6. Basic Kernel Library Functions

Here is a few basic kernel library functions that might be
useful. Refer to "man" pages for a detailed information. Note that
you should use care to use cli() and sti(),
since misuse of them can freeze your kernel with no error
messages.