lib/libsys/README

   1 $DragonFly: src/lib/libsys/README,v 1.1 2005/05/08 18:14:52 dillon Exp $
   2
   3                     System Call Interfacing Layer
   4
   5     This library implements a system call interfacing layer between
   6     userland and the kernel.  Because we intend to support multiple
   7     combinations of user and kernel ABIs we do not try to tie this
   8     layer directly to the kernel.
   9
  10     This layer, not the master syscall list in the kernel, defines the
  11     ABI between userland and the kernel for all DragonFly releases.
  12
  13     Although we call this a 'library' the actual library linked into
  14     programs (statically or dynamically) is really just a stub section
  15     that the kernel and/or ld-elf will replace by mmap()ing both the actual
  16     jump table and also mmap()ing the interface layer itself.  The actual
  17     interface layer is a static-linked image that is directly mmap()'d.
  18
  19     The initial implementation of this layer contains no relocation
  20     sections at all.  No global variables or subroutine calls.. just
  21     the functions representing the system calls themselves.
  22
  23                         System Call Specifications
  24
  25     The syscall specifications file is very similar to e.g. syscalls.master,
  26     except it does not contain any legacy 'compatibility' system calls, only
  27     contemporary calls.  The other primary difference is that ALL
  28     structures contain a version suffix indicating the dragonfly version
  29     where the last change to the structure was made.  These versioned
  30     system interfacing structures are declared in parseable ABI header
  31     files.
  32
  33     It should be noted that we do NOT attempt to obtain structural data
  34     from system header files.  To ensure that the ABI is "set in stone",
  35     so to speak, all system interfacing structures are duplicated in the
  36     ABI headers.  The types are NOT NECESSARILY DUPLICATED EXACTLY, and
  37     in fact we use types like e.g. 'generic32_t' to specifically indicate
  38     that we only care about the data as pure storage, not as a type, but
  39     the size of the types is properly retained.
  40
  41                         System Call Configuration File
  42
  43     This is a work in progress.  Here is the grammer so far:
  44
  45     file:
  46         directive*
  47
  48     directive:
  49         BASE symbol ";"
  50         ADD integer { control* }
  51         INCLUDE string ";"
  52
  53     control:
  54         FUNCTION type_id "(" type_id [ "," type_id ]* ")" ";"
  55         IMPLEMENTATION DIRECT ";"
  56
  57     Basically this will control syscall generation for any version of
  58     DragonFly.  The configuration file for later releases simply overriides
  59     earlier releases.  There will be a method to specify a direct system
  60     call (i.e. if the program is fully compatible with the kernel), system
  61     calls where programmatic structutral adjustments are required (e.g.
  62     if the 'stat' structure changes), and fully custom conversions where
  63     the shim calls a separate userspace function to perform a more complex
  64     system call conversion.
  65
  66     The kernel will load the map file representing the conversion from
  67     the userland-specified ABI to the kernel ABI.  For example, if
  68     userland is running, say, 1.2.0, and the kernel is running 1.3,
  69     the mapping file will be something like:
  70
  71         "dragonfly_map_syscalls_1_2_0-1_3.map"
  72
  73     The idea is that *all* one then needs to run an older binary on a newer
  74     machine, or a newer binary on an older machine, is the correct .map file,
  75     and the system will refuse to run the program if it can't find it.
  76
  77     The 'native' mapping file, i.e. 1.2.0 running on a 1.2.0 system,
  78     would be built into the kernel directly, so e.g. static binaries
  79     would always be supported even if the map file directory doesn't
  80     exist.
  81