3 Commits

3 changed files with 188 additions and 85 deletions

View File

@@ -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)

View File

@@ -44,6 +44,7 @@
# define __KFUSD_H__
# include "fusd_msg.h"
# include <linux/version.h>
/* magic numbers for structure checking; unique w.r.t
* /usr/src/linux/Documentation/magic-number.txt */
@@ -125,8 +126,11 @@ struct fusd_dev_t_s {
char *dev_name;
struct CLASS *clazz;
int owns_class;
#if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,29)
struct class_device *device;
#else
struct device *device;
#endif
void *private_data; /* User's private data */
struct cdev* handle;
dev_t dev_id;
@@ -269,8 +273,11 @@ static void fusd_vfree(void *ptr);
/* Functions like this should be in the kernel, but they are not. Sigh. */
# ifdef CONFIG_SMP
#if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,30)
DECLARE_MUTEX(atomic_ops);
#else
DEFINE_SEMAPHORE(atomic_ops);
#endif
static __inline__ int atomic_inc_and_ret(int *i)
{
int val;

View File

@@ -38,7 +38,7 @@
* Copyright (c) 2001, Sensoria Corporation
* Copyright (c) 2002-2003, Regents of the University of California
* Copyright (c) 2007 Monty and Xiph.Org
* Copyright (c) 2009-2011 Manoel Trapier <godzil@godzil.net>
* Copyright (c) 2009-2012 Manoel Trapier <godzil@godzil.net>
*
* $Id: kfusd.c 12354 2007-01-19 17:26:14Z xiphmont $
*/
@@ -114,37 +114,22 @@
# define CLASS_DEVICE_DESTROY(a, b) class_simple_device_remove(b)
#else
# define CLASS class
# if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,15)
# define CLASS_DEVICE_CREATE(a, b, c, d, e) device_create(a, c, d, e)
# define CLASS_DEVICE_CREATE(a, b, c, d, e) class_device_create(a, c, d, e)
# else
# if LINUX_VERSION_CODE > KERNEL_VERSION(2,6,30)
# define CLASS_DEVICE_CREATE(a, b, c, d, e) device_create(a, b, c, d, e)
# else
# define CLASS_DEVICE_CREATE(a, b, c, d, e) device_create(a, b, c, d, e)
# endif
# endif
#endif
#if LINUX_VERSION_CODE > KERNEL_VERSION(2,6,30)
# define CLASS_DEVICE_DESTROY(a, b) device_destroy(a, b)
#else
# define CLASS_DEVICE_DESTROY(a, b) device_destroy(a, b)
#endif
#if LINUX_VERSION_CODE > KERNEL_VERSION(2,6,19)
@@ -209,6 +194,11 @@ struct class_private {
#endif
/*
struct sysfs_dirent *attr_sd = dentry->d_fsdata;
struct kobject *kobj = attr_sd->s_parent->s_dir.kobj;
*/
static inline struct kobject * to_kobj (struct dentry * dentry)
{
struct sysfs_dirent * sd = dentry->d_fsdata;
@@ -216,7 +206,7 @@ static inline struct kobject * to_kobj (struct dentry * dentry)
#if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,20)
return ((struct kobject *) sd->s_element );
#else
return ((struct kobject *) sd->s_dir.kobj );
return ((struct kobject *) sd->s_parent->s_dir.kobj );
#endif
else
return NULL;
@@ -242,8 +232,14 @@ STATIC dev_t status_id;
static struct CLASS *fusd_class;
#if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,29)
static struct class_device *fusd_control_device;
static struct class_device *fusd_status_device;
#else
static struct device *fusd_control_device;
static struct device *fusd_status_device;
#endif
extern struct CLASS *sound_class;
@@ -258,11 +254,15 @@ STATIC DECLARE_WAIT_QUEUE_HEAD (new_device_wait);
/* the list of valid devices, and sem to protect it */
LIST_HEAD (fusd_devlist_head);
#if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,30)
DECLARE_MUTEX (fusd_devlist_sem);
#else
DEFINE_SEMAPHORE (fusd_devlist_sem);
#endif
//#ifdef MODULE_LICENSE
MODULE_AUTHOR ("Jeremy Elson <jelson@acm.org> (c)2001");
MODULE_AUTHOR ("Manoel Trapier <godzil@godzil.net> (c)2009-2011");
MODULE_AUTHOR ("Manoel Trapier <godzil@godzil.net> (c)2009-2012");
MODULE_LICENSE ("GPL");
//#endif
@@ -320,7 +320,12 @@ STATIC void rdebug_real (char *fmt, ...)
# define MAX_MEM_DEBUG 10000
#if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,30)
DECLARE_MUTEX (fusd_memdebug_sem);
#else
DEFINE_SEMAPHORE (fusd_memdebug_sem);
#endif
typedef struct
{
@@ -469,6 +474,7 @@ STATIC inline void free_fusd_msg (fusd_msg_t **fusd_msg)
VFREE(( *fusd_msg )->data);
( *fusd_msg )->data = NULL;
}
RDEBUG(1, "Freeing fusd_msg [%p] then set to NULL", fusd_msg);
KFREE(*fusd_msg);
*fusd_msg = NULL;
}
@@ -840,8 +846,10 @@ STATIC int fusd_fops_call_send (fusd_file_t *fusd_file_arg,
/* fill the rest of the structure */
fusd_msg->parm.fops_msg.pid = current->pid;
// fusd_msg->parm.fops_msg.uid = current_uid();
// fusd_msg->parm.fops_msg.gid = current_gid();
#if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,29)
fusd_msg->parm.fops_msg.uid = current_uid();
fusd_msg->parm.fops_msg.gid = current_gid();
#endif
fusd_msg->parm.fops_msg.flags = fusd_file->file->f_flags;
fusd_msg->parm.fops_msg.offset = fusd_file->file->f_pos;
fusd_msg->parm.fops_msg.device_info = fusd_dev->private_data;
@@ -1140,8 +1148,13 @@ int fusd_dev_add_file (struct file *file, fusd_dev_t *fusd_dev, fusd_file_t **fu
init_waitqueue_head(&fusd_file->file_wait);
init_waitqueue_head(&fusd_file->poll_wait);
INIT_LIST_HEAD(&fusd_file->transactions);
#if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,30)
init_MUTEX(&fusd_file->file_sem);
init_MUTEX(&fusd_file->transactions_sem);
#else
sema_init(&fusd_file->file_sem, 1);
sema_init(&fusd_file->transactions_sem, 1);
#endif
fusd_file->last_poll_sent = -1;
fusd_file->magic = FUSD_FILE_MAGIC;
fusd_file->fusd_dev = fusd_dev;
@@ -1589,8 +1602,13 @@ invalid_file:
return -EPIPE;
}
#ifndef HAVE_UNLOCKED_IOCTL
STATIC int fusd_client_ioctl (struct inode *inode, struct file *file,
unsigned int cmd, unsigned long arg)
#else
STATIC long fusd_client_unlocked_ioctl (struct file *file,
unsigned int cmd, unsigned long arg)
#endif
{
fusd_dev_t *fusd_dev;
fusd_file_t *fusd_file;
@@ -1937,8 +1955,7 @@ invalid_dev:
return POLLPRI;
}
#ifndef HAVE_UNLOCKED_IOCTL
STATIC struct file_operations fusd_client_fops = {
.owner = THIS_MODULE,
.open = fusd_client_open,
@@ -1949,7 +1966,18 @@ STATIC struct file_operations fusd_client_fops = {
.poll = fusd_client_poll,
.mmap = fusd_client_mmap
};
#else
STATIC struct file_operations fusd_client_fops = {
.owner = THIS_MODULE,
.open = fusd_client_open,
.release = fusd_client_release,
.read = fusd_client_read,
.write = fusd_client_write,
.unlocked_ioctl = fusd_client_unlocked_ioctl,
.poll = fusd_client_poll,
.mmap = fusd_client_mmap
};
#endif
/*************************************************************************/
/*************************************************************************/
@@ -2177,7 +2205,7 @@ STATIC int fusd_register_device (fusd_dev_t *fusd_dev,
if ( sysfs )
{
/* Get FS superblock */
/* Get FS superblock */
sb = sget(sysfs, systest, NULL, NULL);
/* because put_filesystem isn't exported */
@@ -2192,7 +2220,7 @@ STATIC int fusd_register_device (fusd_dev_t *fusd_dev,
{
struct qstr name;
/* Search for directory "class" in the root of this filesystem */
/* Search for directory "class" in the root of this filesystem */
name.name = "class";
name.len = 5;
name.hash = full_name_hash(name.name, name.len);
@@ -2200,7 +2228,7 @@ STATIC int fusd_register_device (fusd_dev_t *fusd_dev,
if ( classdir )
{
/* Found, now search for class wanted name */
/* Found, now search for class wanted name */
name.name = register_msg.clazz;
name.len = strlen(name.name);
name.hash = full_name_hash(name.name, name.len);
@@ -2212,15 +2240,16 @@ STATIC int fusd_register_device (fusd_dev_t *fusd_dev,
struct kobject *ko = to_kobj(classdir2);
sys_class = ( ko ? to_class(ko)->class : NULL );
if ( sys_class )
{
#if 0
if ( sys_class )
{
/* W T F ???? Using an existing sys_class will led to a NULL pointer crash
* during device creation.. Need more investigation, this comportement is clearly not
* normal. */
RDEBUG(1, "ERROR: Using existing class name is currently unsported !!!");
goto register_failed4;
}
RDEBUG(1, "ERROR: Using existing class name is currently unsported !!!");
goto register_failed4;
}
#endif
if ( !sys_class )
RDEBUG(2, "WARNING: sysfs entry for %s has no kobject!\n", register_msg.clazz);
}
@@ -2351,7 +2380,11 @@ STATIC int fusd_open (struct inode *inode, struct file *file)
goto file_malloc_failed;
init_waitqueue_head(&fusd_dev->dev_wait);
#if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,30)
init_MUTEX(&fusd_dev->dev_sem);
#else
sema_init(&fusd_dev->dev_sem, 1);
#endif
fusd_dev->magic = FUSD_DEV_MAGIC;
fusd_dev->pid = current->pid;
fusd_dev->task = current;
@@ -2609,7 +2642,7 @@ STATIC ssize_t fusd_write (struct file *file,
RDEBUG(1, "%s: [%p:%p:%d:%p] [sl: %d]!!", __func__, file, buffer, length, offset, sizeof (fusd_msg_t ));
return fusd_process_write(file, buffer, length, NULL, 0);
}
#ifndef HAVE_UNLOCKED_IOCTL
STATIC ssize_t fusd_writev (struct file *file,
const struct iovec *iov,
unsigned long count,
@@ -2625,11 +2658,34 @@ STATIC ssize_t fusd_writev (struct file *file,
iov[0].iov_base, iov[0].iov_len,
iov[1].iov_base, iov[1].iov_len);
}
#else
STATIC ssize_t fusd_aio_write (struct kiocb *iocb,
const struct iovec *iov,
unsigned long count,
loff_t offset)
{
if ( count != 2 )
{
RDEBUG(2, "fusd_writev: got illegal iov count of %ld", count);
return -EINVAL;
}
return fusd_process_write(iocb->ki_filp,
iov[0].iov_base, iov[0].iov_len,
iov[1].iov_base, iov[1].iov_len);
}
#endif
#ifndef HAVE_UNLOCKED_IOCTL
STATIC int fusd_ioctl (struct inode *inode, struct file *file,
unsigned int cmd, unsigned long arg)
#else
STATIC long fusd_unlocked_ioctl (struct file *file,
unsigned int cmd, unsigned long arg)
#endif
{
void __user *argp = (void __user *) arg;
#if 0
struct iovec iov;
if ( ( argp != NULL ) && ( cmd == 0xb16b00b5 ) )
@@ -2646,6 +2702,7 @@ STATIC int fusd_ioctl (struct inode *inode, struct file *file,
return -EIO;
}
}
#endif
RDEBUG(2, "%s: got illegal ioctl #%08X# Or ARG is null [%p]", __func__, cmd, argp);
return -EINVAL;
}
@@ -2839,7 +2896,7 @@ invalid_dev:
return 0;
}
#ifndef HAVE_UNLOCKED_IOCTL
STATIC struct file_operations fusd_fops = {
.owner = THIS_MODULE,
.open = fusd_open,
@@ -2850,6 +2907,19 @@ STATIC struct file_operations fusd_fops = {
.release = fusd_release,
.poll = fusd_poll,
};
#else
STATIC struct file_operations fusd_fops = {
.owner = THIS_MODULE,
.open = fusd_open,
.read = fusd_read,
.write = fusd_write,
.aio_write = fusd_aio_write,
.unlocked_ioctl = fusd_unlocked_ioctl,
.release = fusd_release,
.poll = fusd_poll,
};
#endif
/*************************************************************************/
@@ -2904,8 +2974,13 @@ STATIC int fusd_status_release (struct inode *inode, struct file *file)
}
/* ioctl() on /dev/fusd/status */
#ifndef HAVE_UNLOCKED_IOCTL
STATIC int fusd_status_ioctl (struct inode *inode, struct file *file,
unsigned int cmd, unsigned long arg)
#else
STATIC long fusd_status_unlocked_ioctl (struct file *file,
unsigned int cmd, unsigned long arg)
#endif
{
fusd_statcontext_t *fs = (fusd_statcontext_t *) file->private_data;
@@ -3123,7 +3198,7 @@ STATIC unsigned int fusd_status_poll (struct file *file, poll_table *wait)
return 0;
}
#ifndef HAVE_UNLOCKED_IOCTL
STATIC struct file_operations fusd_status_fops = {
.owner = THIS_MODULE,
.open = fusd_status_open,
@@ -3132,6 +3207,16 @@ STATIC struct file_operations fusd_status_fops = {
.release = fusd_status_release,
.poll = fusd_status_poll,
};
#else
STATIC struct file_operations fusd_status_fops = {
.owner = THIS_MODULE,
.open = fusd_status_open,
.unlocked_ioctl = fusd_status_unlocked_ioctl,
.read = fusd_status_read,
.release = fusd_status_release,
.poll = fusd_status_poll,
};
#endif
/*************************************************************************/