$DragonFly: src/lib/libsys/README,v 1.1 2005/05/08 18:14:52 dillon Exp $

		    System Call Interfacing Layer

    This library implements a system call interfacing layer between
    userland and the kernel.  Because we intend to support multiple
    combinations of user and kernel ABIs we do not try to tie this
    layer directly to the kernel.

    This layer, not the master syscall list in the kernel, defines the
    ABI between userland and the kernel for all DragonFly releases.

    Although we call this a 'library' the actual library linked into
    programs (statically or dynamically) is really just a stub section
    that the kernel and/or ld-elf will replace by mmap()ing both the actual
    jump table and also mmap()ing the interface layer itself.  The actual
    interface layer is a static-linked image that is directly mmap()'d.

    The initial implementation of this layer contains no relocation
    sections at all.  No global variables or subroutine calls.. just
    the functions representing the system calls themselves.

			System Call Specifications

    The syscall specifications file is very similar to e.g. syscalls.master,
    except it does not contain any legacy 'compatibility' system calls, only
    contemporary calls.  The other primary difference is that ALL 
    structures contain a version suffix indicating the dragonfly version
    where the last change to the structure was made.  These versioned
    system interfacing structures are declared in parseable ABI header
    files.  

    It should be noted that we do NOT attempt to obtain structural data
    from system header files.  To ensure that the ABI is "set in stone",
    so to speak, all system interfacing structures are duplicated in the 
    ABI headers.  The types are NOT NECESSARILY DUPLICATED EXACTLY, and
    in fact we use types like e.g. 'generic32_t' to specifically indicate
    that we only care about the data as pure storage, not as a type, but
    the size of the types is properly retained.

			System Call Configuration File

    This is a work in progress.  Here is the grammer so far:

    file:
	directive*

    directive:
	BASE symbol ";"
	ADD integer { control* }
	INCLUDE string ";"

    control:
	FUNCTION type_id "(" type_id [ "," type_id ]* ")" ";"
	IMPLEMENTATION DIRECT ";"

    Basically this will control syscall generation for any version of 
    DragonFly.  The configuration file for later releases simply overriides
    earlier releases.  There will be a method to specify a direct system
    call (i.e. if the program is fully compatible with the kernel), system
    calls where programmatic structutral adjustments are required (e.g.
    if the 'stat' structure changes), and fully custom conversions where
    the shim calls a separate userspace function to perform a more complex
    system call conversion.

    The kernel will load the map file representing the conversion from
    the userland-specified ABI to the kernel ABI.  For example, if 
    userland is running, say, 1.2.0, and the kernel is running 1.3, 
    the mapping file will be something like:

	"dragonfly_map_syscalls_1_2_0-1_3.map"

    The idea is that *all* one then needs to run an older binary on a newer
    machine, or a newer binary on an older machine, is the correct .map file,
    and the system will refuse to run the program if it can't find it.

    The 'native' mapping file, i.e. 1.2.0 running on a 1.2.0 system, 
    would be built into the kernel directly, so e.g. static binaries
    would always be supported even if the map file directory doesn't 
    exist.