Browse Source

Update README file (and convert it to Markdown)

Godzil 12 years ago
parent
commit
efd39ff55a
1 changed files with 58 additions and 47 deletions
  1. 58 47
      README.markdown

+ 58 - 47
README → 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 <jelson@circlemud.org>                              <br>
+> August 19, 2003                                                  <br>
 
- Jeremy Elson <jelson@circlemud.org>
- August 19, 2003
+> updated,<br>
+> Monty <monty@xiph.org>                                           <br>
+> January 11, 2007                                                 <br>
 
- updated,
- Monty <monty@xiph.org>
- January 11, 2007
+> Updated,                                                         <br>
+> Godzil <godzil@godzil.net>                                       <br>
+> March 01, 2011 / January 18, 2012 (public release on github)