==================================================================
Ya_HOWTO_adda_syscall ("Yet Another HOWTO Add a Syscall to Linux")
==================================================================
Randy Dunlap          <rddunlap AT ieee.org>         2002-April-05
==================================================================


This is a short, quick example of how to add a system call to
Linux for x86.  This example is specific to Linux version
2.4.18 but it should be easy to modify the patch to work with
other kernel versions.

Summary:  Add the following to the Linux kernel:

. system call number (in linux/include/asm-i386/unistd.h)
. system call entry point in the system call table
  (<sys_call_table> in linux/arch/i386/kernel/entry.S)
. system call function implementation in a current or new
  source file

The system call number and entry point items are trivial
and not explained in any (more) detail.

For the system call function implementation, you can add a source
file (in which case you must modify the Makefile in its directory),
or add the system call function to an existing source file if that
makes sense.

For the system call function implementation, the function must be
declared using the "asmlinkage" keyword and have the precise number
and types of parameters.  For a system call with N parameters,
you can use the _syscallN macro (from linux/include/asm-i386/unistd.h)
to declare a function prototype.  For example, for a (new) system
call (named "log_message") with 2 parameters with types as listed:

	#include <asm/unistd.h>

	_syscall2(int, log_message, char *, message, int, len);

and the system call function implementation looks like:

asmlinkage int sys_log_message(char *message, int len)
{
...
}

The kernel changes are in the patch file "addasyscall_2418.patch".

A test program for the new system call is in the file "logmsg.c".

======================================================================

System calls implemented in loadable modules are not supported in Linux,
partly for philosophical reasons and partly for technical reasons....

  Philosophical:  There is no desire in the Linux community to enable
  syscalls that are implemented in binary loadable modules.

  Technical:  Updating function pointers in the sys_call_table cannot be
  done by simply setting a table pointer entry for some processor architectures,
  like IA-64.

                                ###