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
 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.
 There is extensive documentation available in the 'doc' directory.
 The FUSD User Manual is available in PDF, Postscript, and HTML format.
 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.
 current version of fusd.
 
 
 FUSD is free and open source software, released under a BSD-style
 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
 QUICK START GUIDE
@@ -25,81 +32,81 @@ QUICK START GUIDE
 
 
 Instructions for the impatient:
 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
 kernel is a packaged version from a distribution, also verify any
 optional packages needed for building new kernel modules are also
 optional packages needed for building new kernel modules are also
 installed.
 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.
 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:
 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
 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.
 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?
 WHAT IS FUSD?
 =============
 =============
 
 
 FUSD (pronounced "fused") is a Linux framework for proxying device
 FUSD (pronounced "fused") is a Linux framework for proxying device
 file callbacks into user-space, allowing device files to be
 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
 implemented in user-space, FUSD devices can look and act just like any
 other file under /dev which is implemented by kernel callbacks.
 other file under /dev which is implemented by kernel callbacks.
 
 
 A user-space device driver can do many of the things that kernel
 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
 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
 kernel drivers, a user-space device driver can use other device
 drivers--that is, access the network, talk to a serial port, get
 drivers--that is, access the network, talk to a serial port, get
 interactive input from the user, pop up GUI windows, or read from
 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
 debug; it is impossible for them to crash the machine, are easily
 traceable using tools such as gdb, and can be killed and restarted
 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
 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.
 whereas kernel drivers lock physical memory.
 
 
 FUSD drivers are conceptually similar to kernel drivers: a set of
 FUSD drivers are conceptually similar to kernel drivers: a set of
 callback functions called in response to system calls made on file
 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()
 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
 functions which are called in response to certain user system
 calls--for example, when a process tries to open, close, read from, or
 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
 the user-space FUSD callback functions are identical to their kernel
 counterparts.
 counterparts.
 
 
 The proxying of kernel system calls that makes this kind of program
 The proxying of kernel system calls that makes this kind of program
 possible is implemented by FUSD, using a combination of a kernel
 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
 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
 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
 know anything unusual is happening; it appears from their point of
 view that the registered devices are simply being implemented by the
 view that the registered devices are simply being implemented by the
 FUSD module.
 FUSD module.
@@ -107,22 +114,22 @@ FUSD module.
 Later, when kernel makes a callback due to a system call (e.g. when
 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
 the character device file is opened or read), the FUSD kernel module's
 callback blocks the calling process, marshals the arguments of the
 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
 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:
 user-space callback returns a value, the process happens in reverse:
 the return value and its side-effects are marshaled by the library
 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
 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,
 of this trickery; it simply enters the kernel once, blocks, unblocks,
 and returns from the system call---just as it would for any other
 and returns from the system call---just as it would for any other
 blocking call.
 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,
 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
 checking is implemented at the user-kernel boundary which should
 prevent drivers from corrupting the kernel or any other user-space
 prevent drivers from corrupting the kernel or any other user-space
 process---including the errant driver's own clients, and other FUSD
 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
 For more information, please see the comprehensive documentation in
 the 'doc' directory.
 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)