From efd39ff55afa6e63072820dee9c23f1637f0a6a7 Mon Sep 17 00:00:00 2001 From: Godzil Date: Mon, 13 Feb 2012 18:36:24 +0100 Subject: [PATCH] Update README file (and convert it to Markdown) --- README => README.markdown | 105 +++++++++++++++++++++----------------- 1 file changed, 58 insertions(+), 47 deletions(-) rename README => README.markdown (51%) diff --git a/README b/README.markdown similarity index 51% rename from README rename to README.markdown index b4edb5c..0343c37 100644 --- a/README +++ b/README.markdown @@ -2,13 +2,20 @@ FUSD: A Linux Framework for User-Space Devices ---------------------------------------------- -Welcome to FUSD! +**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: +This is FUSD snapshot 20110401, released 18 January 2012. This fork is based +on the found on the xiph.org SVN tracker. ( http://svn.xiph.org/trunk/fusd ) +They seems to no longuer update this tool (since 11 January 2007) and since it +longuer compile with recent Linux kernel (at around 2.6.21) and since I need +it in personal project, I ported it to newer version (current version is 2.6.32) -http://svn.xiph.org/trunk/fusd +Some feature are still missing missing or buggy form the Xiph version (due to +changes on the kernel source tree), but it's completly useable. + +The official URL for this fork is: + +http://github.com/Godzil/fusd There is extensive documentation available in the 'doc' directory. The FUSD User Manual is available in PDF, Postscript, and HTML format. @@ -17,7 +24,7 @@ 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. +license. See the file 'LICENSE' for details. QUICK START GUIDE @@ -25,81 +32,81 @@ 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 +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 +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 +3. Update the udev configuration (usually in /etc/udev/rules.d/) to include the following rule: - # fusd device - SUBSYSTEM=="fusd", NAME="fusd/%k" + fusd device + SUBSYSTEM=="fusd", NAME="fusd/%k" -After updating, restart udevd (skill udevd; udevd -d). + After updating, restart udevd (skill udevd; udevd -d). -4- Insert the FUSD kernel module (modprobe kfusd) +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, +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 +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!'. +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. +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 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 +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 +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, +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, +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 +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 +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, +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 +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 +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 +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. @@ -107,22 +114,22 @@ 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 +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 +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 +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 +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 +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 +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 @@ -130,10 +137,14 @@ drivers. For more information, please see the comprehensive documentation in the 'doc' directory. + +> Jeremy Elson
+> August 19, 2003
- Jeremy Elson - August 19, 2003 +> updated,
+> Monty
+> January 11, 2007
- updated, - Monty - January 11, 2007 +> Updated,
+> Godzil
+> March 01, 2011 / January 18, 2012 (public release on github)