1
2 FUSD: A Linux Framework for User-Space Devices
3 ----------------------------------------------
4
5 Welcome to FUSD!
6
7 This is FUSD version 1.1, released 19 August 2003. You can always get
8 the most recent version, along with online documentation, from FUSD's
9 official home page at
10
11 http://www.circlemud.org/~jelson/software/fusd
12
13 Also on that page is information on how to contact the author and
14 subscribe to FUSD mailing lists.
15
16 There is extensive documentation available in the 'doc' directory.
17 The FUSD User Manual is available in PDF, Postscript, and HTML format.
18
19 FUSD is free and open source software, released under a BSD-style
20 license. See the file 'LICENSE' for details.
21
22
23 QUICK START GUIDE
24 =================
25
26 Instructions for the impatient:
27
28 1- Make sure you're using a system running Linux 2.4.x. Unfortunately,
29 there were some changes made in devfs in the later 2.5 (and 2.6 test)
30 kernels that make devfs incompatible with FUSD. This hasn't been
31 resolved yet.
32
33 2- devfs is a requirement for FUSD. Make sure devfs is up and
34 running. For more information, see the devfs home page at
35 http://www.atnf.csiro.au/~rgooch/linux/docs/devfs.html
36
37 3- Type 'make' to build everything
38
39 4- Insert the FUSD kernel module, kfusd.o -- it'll be in the "obj.X"
40 directory, where X is your platform name.
41
42 5- Try running the example programs, such as helloworld. Take a look
43 at the example programs in the 'examples' directory.
44
45 6- For more information, read the User's Manual in the 'doc' directory.
46
47
48 WHAT IS FUSD?
49 =============
50
51 FUSD (pronounced "fused") is a Linux framework for proxying device
52 file callbacks into user-space, allowing device files to be
53 implemented by daemons instead of kernel code. Despite being
54 implemented in user-space, FUSD devices can look and act just like any
55 other file under /dev which is implemented by kernel callbacks.
56
57 A user-space device driver can do many of the things that kernel
58 drivers can't, such as perform a long-running computation, block while
59 waiting for an event, or read files from the file system. Unlike
60 kernel drivers, a user-space device driver can use other device
61 drivers--that is, access the network, talk to a serial port, get
62 interactive input from the user, pop up GUI windows, or read from
63 disks. User-space drivers implemented using FUSD can be much easier to
64 debug; it is impossible for them to crash the machine, are easily
65 traceable using tools such as gdb, and can be killed and restarted
66 without rebooting. FUSD drivers don't have to be in C--Perl, Python,
67 or any other language that knows how to read from and write to a file
68 descriptor can work with FUSD. User-space drivers can be swapped out,
69 whereas kernel drivers lock physical memory.
70
71 FUSD drivers are conceptually similar to kernel drivers: a set of
72 callback functions called in response to system calls made on file
73 descriptors by user programs. FUSD's C library provides a device
74 registration function, similar to the kernel's devfs_register_chrdev()
75 function, to create new devices. fusd_register() accepts the device
76 name and a structure full of pointers. Those pointers are callback
77 functions which are called in response to certain user system
78 calls--for example, when a process tries to open, close, read from, or
79 write to the device file. The callback functions should conform to
80 the standard definitions of POSIX system call behavior. In many ways,
81 the user-space FUSD callback functions are identical to their kernel
82 counterparts.
83
84 The proxying of kernel system calls that makes this kind of program
85 possible is implemented by FUSD, using a combination of a kernel
86 module and cooperating user-space library. The kernel module
87 implements a character device, /dev/fusd, which is used as a control
88 channel between the two. fusd_register() uses this channel to send a
89 message to the FUSD kernel module, telling the name of the device the
90 user wants to register. The kernel module, in turn, registers that
91 device with the kernel proper using devfs. devfs and the kernel don't
92 know anything unusual is happening; it appears from their point of
93 view that the registered devices are simply being implemented by the
94 FUSD module.
95
96 Later, when kernel makes a callback due to a system call (e.g. when
97 the character device file is opened or read), the FUSD kernel module's
98 callback blocks the calling process, marshals the arguments of the
99 callback into a message and sends it to user-space. Once there, the
100 library half of FUSD unmarshals it and calls whatever user-space
101 callback the FUSD driver passed to fusd_register(). When that
102 user-space callback returns a value, the process happens in reverse:
103 the return value and its side-effects are marshaled by the library
104 and sent to the kernel. The FUSD kernel module unmarshals this
105 message, matches it up with a corresponding outstanding request, and
106 completes the system call. The calling process is completely unaware
107 of this trickery; it simply enters the kernel once, blocks, unblocks,
108 and returns from the system call---just as it would for any other
109 blocking call.
110
111 One of the primary design goals of FUSD is stability. It should
112 not be possible for a FUSD driver to corrupt or crash the kernel,
113 either due to error or malice. Of course, a buggy driver itself may
114 corrupt itself (e.g., due to a buffer overrun). However, strict error
115 checking is implemented at the user-kernel boundary which should
116 prevent drivers from corrupting the kernel or any other user-space
117 process---including the errant driver's own clients, and other FUSD
118 drivers.
119
120 For more information, please see the comprehensive documentation in
121 the 'doc' directory.
122
123 Jeremy Elson <jelson@circlemud.org>
124 August 19, 2003
125
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.
