1 jelson 1.1 
  2            FUSD: A Linux Framework for User-Space Devices
  3            ----------------------------------------------
  4            
  5            Welcome to FUSD!
  6            

  7 jelson 1.4 This is FUSD version 1.0, first released 28 September 2001.  You can
  8            always get the most recent version, along with online documentation,
  9            from FUSD's official home page at

 10 jelson 1.1 
 11            http://www.circlemud.org/~jelson/software/fusd
 12            
 13            Also on that page is information on how to contact the author and
 14            subscribe to FUSD mailing lists.
 15            
 16            There is extensive documentation available in the 'doc' directory.
 17            The FUSD User Manual is available in PDF, Postscript, and HTML format.
 18            

 19 jelson 1.2 FUSD is free and open source software, released under a BSD-style
 20            license.  See the file 'LICENSE' for details.
 21            

 22 jelson 1.1 
 23            QUICK START GUIDE
 24            =================
 25            
 26            Instructions for the impatient:
 27            
 28            1- Make sure you're using a system running Linux 2.4.0 or greater.
 29            
 30            2- devfs is a requirement for FUSD.  Make sure devfs is up and
 31            running.  For more information, see the devfs home page at
 32            http://www.atnf.csiro.au/~rgooch/linux/docs/devfs.html
 33            
 34            3- Type 'make' to build everything
 35            
 36            4- Insert the FUSD kernel module, kfusd.o -- it'll be in the "obj.X"
 37            directory, where X is your platform name.
 38            
 39            5- Try running the example programs, such as helloworld.  Take a look
 40            at the example programs in the 'examples' directory.
 41            
 42            6- For more information, read the User's Manual in the 'doc' directory.
 43 jelson 1.1 
 44            
 45            WHAT IS FUSD?
 46            =============
 47            
 48            FUSD (pronounced "fused") is a Linux framework for proxying device
 49            file callbacks into user-space, allowing device files to be
 50            implemented by daemons instead of kernel code.  Despite being
 51            implemented in user-space, FUSD devices can look and act just like any
 52            other file under /dev which is implemented by kernel callbacks.
 53            
 54            A user-space device driver can do many of the things that kernel
 55            drivers can't, such as perform a long-running computation, block while
 56            waiting for an event, or read files from the file system.  Unlike
 57            kernel drivers, a user-space device driver can use other device
 58            drivers--that is, access the network, talk to a serial port, get
 59            interactive input from the user, pop up GUI windows, or read from
 60            disks.  User-space drivers implemented using FUSD can be much easier to
 61            debug; it is impossible for them to crash the machine, are easily
 62            traceable using tools such as gdb, and can be killed and restarted
 63            without rebooting.  FUSD drivers don't have to be in C--Perl, Python,
 64 jelson 1.1 or any other language that knows how to read from and write to a file
 65            descriptor can work with FUSD.  User-space drivers can be swapped out,
 66            whereas kernel drivers lock physical memory.
 67            
 68            FUSD drivers are conceptually similar to kernel drivers: a set of
 69            callback functions called in response to system calls made on file
 70            descriptors by user programs.  FUSD's C library provides a device
 71            registration function, similar to the kernel's devfs_register_chrdev()
 72            function, to create new devices.  fusd_register() accepts the device
 73            name and a structure full of pointers.  Those pointers are callback
 74            functions which are called in response to certain user system
 75            calls--for example, when a process tries to open, close, read from, or
 76            write to the device file.  The callback functions should conform to
 77            the standard definitions of POSIX system call behavior.  In many ways,
 78            the user-space FUSD callback functions are identical to their kernel
 79            counterparts.
 80            
 81            The proxying of kernel system calls that makes this kind of program
 82            possible is implemented by FUSD, using a combination of a kernel
 83            module and cooperating user-space library.  The kernel module
 84            implements a character device, /dev/fusd, which is used as a control
 85 jelson 1.1 channel between the two.  fusd_register() uses this channel to send a
 86            message to the FUSD kernel module, telling the name of the device the
 87            user wants to register.  The kernel module, in turn, registers that
 88            device with the kernel proper using devfs.  devfs and the kernel don't
 89            know anything unusual is happening; it appears from their point of
 90            view that the registered devices are simply being implemented by the
 91            FUSD module.
 92            
 93            Later, when kernel makes a callback due to a system call (e.g. when
 94            the character device file is opened or read), the FUSD kernel module's
 95            callback blocks the calling process, marshals the arguments of the
 96            callback into a message and sends it to user-space.  Once there, the
 97            library half of FUSD unmarshals it and calls whatever user-space
 98            callback the FUSD driver passed to fusd_register().  When that
 99            user-space callback returns a value, the process happens in reverse:
100            the return value and its side-effects are marshaled by the library
101            and sent to the kernel.  The FUSD kernel module unmarshals this
102            message, matches it up with a corresponding outstanding request, and
103            completes the system call.  The calling process is completely unaware
104            of this trickery; it simply enters the kernel once, blocks, unblocks,
105            and returns from the system call---just as it would for any other
106 jelson 1.1 blocking call.
107            
108            One of the primary design goals of FUSD is stability.  It should
109            not be possible for a FUSD driver to corrupt or crash the kernel,
110            either due to error or malice.  Of course, a buggy driver itself may
111            corrupt itself (e.g., due to a buffer overrun).  However, strict error
112            checking is implemented at the user-kernel boundary which should
113            prevent drivers from corrupting the kernel or any other user-space
114            process---including the errant driver's own clients, and other FUSD
115            drivers.
116            
117            For more information, please see the comprehensive documentation in
118            the 'doc' directory.
119            
120             Jeremy Elson <jelson@circlemud.org>
121             Sensoria Corporation
122             September 28, 2001