fusd/README

   1
   2 FUSD: A Linux Framework for User-Space Devices
   3 ----------------------------------------------
   4
   5 Welcome to FUSD!
   6
   7 This is FUSD snapshot 20070111, released 11 January 2007.  You can get
   8 the most recent source, along with online documentation, from xiph.org
   9 SVN:
  10
  11 http://svn.xiph.org/trunk/fusd
  12
  13 There is extensive documentation available in the 'doc' directory.
  14 The FUSD User Manual is available in PDF, Postscript, and HTML format.
  15 Most of this documentation dates from earlier versions of fusd; until
  16 it is fully updated, it may not cover all features that exist in the
  17 current version of fusd.
  18
  19 FUSD is free and open source software, released under a BSD-style
  20 license.  See the file 'LICENSE' for details.
  21
  22
  23 QUICK START GUIDE
  24 =================
  25
  26 Instructions for the impatient:
  27
  28 1- Make sure you're using a system running Linux 2.6.x with udev; this
  29 version of fusd is incompatable with the now-deprecated devfs.  If the
  30 kernel is a packaged version from a distribution, also verify any
  31 optional packages needed for building new kernel modules are also
  32 installed.
  33
  34 2- 'make ; make install' builds everything including examples, then
  35 installs the libraries, includes and kernel module.
  36
  37 3- Update the udev configuration (usually in /etc/udev/rules.d/) to
  38 include the following rule:
  39
  40    # fusd device
  41    SUBSYSTEM=="fusd",                      NAME="fusd/%k"
  42
  43 After updating, restart udevd (skill udevd; udevd -d).
  44
  45 4- Insert the FUSD kernel module (modprobe kfusd)
  46
  47 5- Verify the fusd devices /dev/fusd/status and /dev/fusd/control
  48 exist.  If the modprobe succeeds but no fusd devices appear,
  49 doublecheck the udev rule config change and make sure udevd restarted
  50 successfully.  The kfusd kernel module must be inserted after udev has
  51 been correctly configured and restarted.
  52
  53 6- Try  running the helloworld  example program (examples/helloworld).
  54 When  helloworld  is  running,  'cat  /dev/helloworld'  should  return
  55 'Hello, world!'.
  56
  57 7- For more information, read the User's Manual in the 'doc' directory.
  58
  59 WHAT IS FUSD?
  60 =============
  61
  62 FUSD (pronounced "fused") is a Linux framework for proxying device
  63 file callbacks into user-space, allowing device files to be
  64 implemented by daemons instead of kernel code.  Despite being
  65 implemented in user-space, FUSD devices can look and act just like any
  66 other file under /dev which is implemented by kernel callbacks.
  67
  68 A user-space device driver can do many of the things that kernel
  69 drivers can't, such as perform a long-running computation, block while
  70 waiting for an event, or read files from the file system.  Unlike
  71 kernel drivers, a user-space device driver can use other device
  72 drivers--that is, access the network, talk to a serial port, get
  73 interactive input from the user, pop up GUI windows, or read from
  74 disks.  User-space drivers implemented using FUSD can be much easier to
  75 debug; it is impossible for them to crash the machine, are easily
  76 traceable using tools such as gdb, and can be killed and restarted
  77 without rebooting.  FUSD drivers don't have to be in C--Perl, Python,
  78 or any other language that knows how to read from and write to a file
  79 descriptor can work with FUSD.  User-space drivers can be swapped out,
  80 whereas kernel drivers lock physical memory.
  81
  82 FUSD drivers are conceptually similar to kernel drivers: a set of
  83 callback functions called in response to system calls made on file
  84 descriptors by user programs.  FUSD's C library provides a device
  85 registration function, similar to the kernel's devfs_register_chrdev()
  86 function, to create new devices.  fusd_register() accepts the device
  87 name and a structure full of pointers.  Those pointers are callback
  88 functions which are called in response to certain user system
  89 calls--for example, when a process tries to open, close, read from, or
  90 write to the device file.  The callback functions should conform to
  91 the standard definitions of POSIX system call behavior.  In many ways,
  92 the user-space FUSD callback functions are identical to their kernel
  93 counterparts.
  94
  95 The proxying of kernel system calls that makes this kind of program
  96 possible is implemented by FUSD, using a combination of a kernel
  97 module and cooperating user-space library.  The kernel module
  98 implements a character device, /dev/fusd, which is used as a control
  99 channel between the two.  fusd_register() uses this channel to send a
 100 message to the FUSD kernel module, telling the name of the device the
 101 user wants to register.  The kernel module, in turn, registers that
 102 device with the kernel proper using devfs.  devfs and the kernel don't
 103 know anything unusual is happening; it appears from their point of
 104 view that the registered devices are simply being implemented by the
 105 FUSD module.
 106
 107 Later, when kernel makes a callback due to a system call (e.g. when
 108 the character device file is opened or read), the FUSD kernel module's
 109 callback blocks the calling process, marshals the arguments of the
 110 callback into a message and sends it to user-space.  Once there, the
 111 library half of FUSD unmarshals it and calls whatever user-space
 112 callback the FUSD driver passed to fusd_register().  When that
 113 user-space callback returns a value, the process happens in reverse:
 114 the return value and its side-effects are marshaled by the library
 115 and sent to the kernel.  The FUSD kernel module unmarshals this
 116 message, matches it up with a corresponding outstanding request, and
 117 completes the system call.  The calling process is completely unaware
 118 of this trickery; it simply enters the kernel once, blocks, unblocks,
 119 and returns from the system call---just as it would for any other
 120 blocking call.
 121
 122 One of the primary design goals of FUSD is stability.  It should
 123 not be possible for a FUSD driver to corrupt or crash the kernel,
 124 either due to error or malice.  Of course, a buggy driver itself may
 125 corrupt itself (e.g., due to a buffer overrun).  However, strict error
 126 checking is implemented at the user-kernel boundary which should
 127 prevent drivers from corrupting the kernel or any other user-space
 128 process---including the errant driver's own clients, and other FUSD
 129 drivers.
 130
 131 For more information, please see the comprehensive documentation in
 132 the 'doc' directory.
 133
 134  Jeremy Elson <jelson@circlemud.org>
 135  August 19, 2003
 136
 137  updated,
 138  Monty <monty@xiph.org>
 139  January 11, 2007