How about adding the attached text to the Documentation directory?  I

had to correct over the years to one or the other system call design

problems.  Other problems couldn't be corrected anymore and we have to

live with them.  Maybe spelling out the rules explicitly will help a bit.
I've added a few rules I could think of right now.  What should be

added as well is a rule for 64-bit parameters on 32-bit platforms.  I

leave this to the s390 people who have the biggest restrictions when

it comes to this.
Signed-off-by: Ulrich Drepper <drepper@redhat.com>
Rules for designing new system calls

------------------------------------
1. Do not use multiplexing system calls.
   A practical argument is that it invariably reduces the number of

   available parameters to the system call which will haunt people who

   have to care about architectures with a limited set of registers

   reserved for this purpose.
   Another aspect is that it is most likely slower.  The caller in

   most cases knows exactly which sub-function of the system call is

   needed.  If the decision about the sub-function is dynamic the

   computation of the code could just as well be a computation of a

   system call number.  The difference lies in the kernel where the

   multiplexing always has to happen, even if the required

   sub-function is known to the caller ahead of time.
   Adding new system calls is much cheaper: it is a word in a table.

   This is much less code and data than the switch statement or

   if-cascade needed to implement the multiplexer.
   Bad examples: sys_socketcall on x86, sys_futex, and several more
2. Use of ENOSYS:
   The runtime has to be able to distinguish non-existing system calls

   due to old kernel versions from error conditions in an implemented

   system call.  This means the ENOSYS error should never be used in

   an error condition once a system call is implemented.
   Example: In sys_fallocate, if the file system does not implement the

   falloca...
[ message continues ]

David Woodhouse wrote that already. Don't know if there is a patch

pending: http://marc.info/?l=linux-arch&m=118277150812137&w=2

-

Hi Ulrich,
Most definitely, but going through the list below, I could think of

maybe several more little things that people tend to forget when actually

/implementing/ the system call (and not necessarily the abstract level
Yes, that must definitely be spelt out clearly, probably with examples

of how to do it right.
Another thing that's a must when designing a syscall would be thinking

of any security implications that it brings about and clearly spelling

out expected behaviour in all cases -- security could mean different

things for different syscalls, but just getting that word in here would

mean people don't make basic mistakes like introducing "xxx_set_xxx"

kind of syscalls that go ahead and modify kernel/global structures

without authors having even thought of how and why that's wrong.
Other than that, as I said above, probably what we also need is a

"system call implementation checklist" of some sort, which lists out the

basic things (copying buffers from/to userspace, various security checks,

  ^^^
Satyam

-