Documentation/HACKING.txt

   1 * Building on old distributions.
   2   Trinity is developed using the latest glibc/kernel, which means from time to time
   3   changes are introduced which may make it fail to compile on older distributions
   4   (especially enterprise ones).  The preferred way to fix this is to add the missing
   5   declarations to compat.h
   6   If for some reason you can't detect presence of a definition in a header file
   7   (or need to test prescence of a header file), add it to configure.sh. This should
   8   be a last resort, in most cases an #ifndef addition to compat.h will be enough.
   9
  10   This means of course that trinity will be trying to run new syscalls on older kernels
  11   that don't implement them, but it will only call them once. After the first -ENOSYS,
  12   it gets marked as "Don't run this again".  It also allows us to run and test newer
  13   kernels on distributions with older userspace whose header files may not define those features.
  14
  15 * Porting to new architectures
  16   - Add a syscalls-{archname}.h defining the syscall table in the same order as your arch
  17   - Add a arch-{archname}.h to define useful things like PAGE_OFFSET
  18   - If your arch starts its Linux syscalls at non-zero (like MIPS/IA64 do), define SYSCALL_OFFSET
  19     in arch-{archname}.h
  20   - Add syscalls/{syscallname}.c for your arch specific syscalls.
  21   - Change setup_syscall_tables in tables.c to pick the correct syscall table for your arch.
  22   That should be it.
  23
  24 * Adding new sanitise routines
  25   syscalls:
  26    - First, decide if it's worth adding a sanitise routine at all, or if the generic
  27      sanitise routines are good enough, by setting each arguments .arg*type member
  28      to an appropriate ARG_*
  29    - In cases where the generic routines are either insufficient, or need to be overridden,
  30      the .sanitise member of the syscall struct can be pointed to a routine that will
  31      run after the generic sanitise routines.
  32    - The 'child' parameter of the sanitise function is to be used to index the various
  33      per-child arrays in the shm.
  34    - Likewise, after the syscall is run, you may need to free up resources allocated
  35      in the .sanitise.  You can do this in the .post function.
  36      There's an unsigned long in the shm named 'scratch' that may be used to store
  37      ptrs to resources etc for retrieval later in .post
  38    - Beware of 'over sanitising' and limiting the possibility for boundary conditions
  39      to be violated. A syscall that always succeeds is not the goal, you want to be
  40      exercising as many error paths as possible.
  41
  42   ioctls:
  43    TODO
  44
  45 * Process model.
  46   On startup, the first process sets up the shm etc, and then forks two processes.
  47
  48   1. The 'main' process (see main.c), which is responsible for..
  49      - initial opening of sockets/fd's.  See sockets.c/fds.c/files.c
  50      - forking new children See fork_children()
  51      - handling those children.  See handle_child()
  52
  53   2. A 'watchdog' process that makes sure the child processes are making progress,
  54      and assorted other 'periodic' tasks.  All this lives in watchdog.c
  55