123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139 |
- FUSD: A Linux Framework for User-Space Devices
- ----------------------------------------------
- Welcome to FUSD!
- This is FUSD snapshot 20070111, released 11 January 2007. You can get
- the most recent source, along with online documentation, from xiph.org
- SVN:
- http://svn.xiph.org/trunk/fusd
- There is extensive documentation available in the 'doc' directory.
- The FUSD User Manual is available in PDF, Postscript, and HTML format.
- Most of this documentation dates from earlier versions of fusd; until
- it is fully updated, it may not cover all features that exist in the
- current version of fusd.
- FUSD is free and open source software, released under a BSD-style
- license. See the file 'LICENSE' for details.
- QUICK START GUIDE
- =================
- Instructions for the impatient:
- 1- Make sure you're using a system running Linux 2.6.x with udev; this
- version of fusd is incompatable with the now-deprecated devfs. If the
- kernel is a packaged version from a distribution, also verify any
- optional packages needed for building new kernel modules are also
- installed.
- 2- 'make ; make install' builds everything including examples, then
- installs the libraries, includes and kernel module.
- 3- Update the udev configuration (usually in /etc/udev/rules.d/) to
- include the following rule:
- # fusd device
- SUBSYSTEM=="fusd", NAME="fusd/%k"
- After updating, restart udevd (skill udevd; udevd -d).
- 4- Insert the FUSD kernel module (modprobe kfusd)
- 5- Verify the fusd devices /dev/fusd/status and /dev/fusd/control
- exist. If the modprobe succeeds but no fusd devices appear,
- doublecheck the udev rule config change and make sure udevd restarted
- successfully. The kfusd kernel module must be inserted after udev has
- been correctly configured and restarted.
- 6- Try running the helloworld example program (examples/helloworld).
- When helloworld is running, 'cat /dev/helloworld' should return
- 'Hello, world!'.
- 7- For more information, read the User's Manual in the 'doc' directory.
- WHAT IS FUSD?
- =============
- FUSD (pronounced "fused") is a Linux framework for proxying device
- file callbacks into user-space, allowing device files to be
- implemented by daemons instead of kernel code. Despite being
- implemented in user-space, FUSD devices can look and act just like any
- other file under /dev which is implemented by kernel callbacks.
- A user-space device driver can do many of the things that kernel
- drivers can't, such as perform a long-running computation, block while
- waiting for an event, or read files from the file system. Unlike
- kernel drivers, a user-space device driver can use other device
- drivers--that is, access the network, talk to a serial port, get
- interactive input from the user, pop up GUI windows, or read from
- disks. User-space drivers implemented using FUSD can be much easier to
- debug; it is impossible for them to crash the machine, are easily
- traceable using tools such as gdb, and can be killed and restarted
- without rebooting. FUSD drivers don't have to be in C--Perl, Python,
- or any other language that knows how to read from and write to a file
- descriptor can work with FUSD. User-space drivers can be swapped out,
- whereas kernel drivers lock physical memory.
- FUSD drivers are conceptually similar to kernel drivers: a set of
- callback functions called in response to system calls made on file
- descriptors by user programs. FUSD's C library provides a device
- registration function, similar to the kernel's devfs_register_chrdev()
- function, to create new devices. fusd_register() accepts the device
- name and a structure full of pointers. Those pointers are callback
- functions which are called in response to certain user system
- calls--for example, when a process tries to open, close, read from, or
- write to the device file. The callback functions should conform to
- the standard definitions of POSIX system call behavior. In many ways,
- the user-space FUSD callback functions are identical to their kernel
- counterparts.
- The proxying of kernel system calls that makes this kind of program
- possible is implemented by FUSD, using a combination of a kernel
- module and cooperating user-space library. The kernel module
- implements a character device, /dev/fusd, which is used as a control
- channel between the two. fusd_register() uses this channel to send a
- message to the FUSD kernel module, telling the name of the device the
- user wants to register. The kernel module, in turn, registers that
- device with the kernel proper using devfs. devfs and the kernel don't
- know anything unusual is happening; it appears from their point of
- view that the registered devices are simply being implemented by the
- FUSD module.
- Later, when kernel makes a callback due to a system call (e.g. when
- the character device file is opened or read), the FUSD kernel module's
- callback blocks the calling process, marshals the arguments of the
- callback into a message and sends it to user-space. Once there, the
- library half of FUSD unmarshals it and calls whatever user-space
- callback the FUSD driver passed to fusd_register(). When that
- user-space callback returns a value, the process happens in reverse:
- the return value and its side-effects are marshaled by the library
- and sent to the kernel. The FUSD kernel module unmarshals this
- message, matches it up with a corresponding outstanding request, and
- completes the system call. The calling process is completely unaware
- of this trickery; it simply enters the kernel once, blocks, unblocks,
- and returns from the system call---just as it would for any other
- blocking call.
- One of the primary design goals of FUSD is stability. It should
- not be possible for a FUSD driver to corrupt or crash the kernel,
- either due to error or malice. Of course, a buggy driver itself may
- corrupt itself (e.g., due to a buffer overrun). However, strict error
- checking is implemented at the user-kernel boundary which should
- prevent drivers from corrupting the kernel or any other user-space
- process---including the errant driver's own clients, and other FUSD
- drivers.
- For more information, please see the comprehensive documentation in
- the 'doc' directory.
- Jeremy Elson <jelson@circlemud.org>
- August 19, 2003
- updated,
- Monty <monty@xiph.org>
- January 11, 2007
|