SULF - Stackable User-Level Filesystem.

0.3

Copyright © 2004-2005 Valient Gough <vgough@pobox.com>

Distributed under the LGPL license, see COPYING for details.

NOTE - THIS IS A DEFUNCT PROJECT

Aug 29, 2006: Yes, I know that some guy recently mentioned this project on his blog. He didn't contact me about it or search the mailing lists for current projects. Please don't download this expecting to use it with recent versions of FUSE. If you're looking for an alternative C# binding that isn't tied to Mono.Posix, or because you want to use the FUSE low-level API binding, then take a look at FuseWrapper

Introduction

SULF allows you to write a Linux filesystem in C#. It uses the FUSE library to do the actual Linux filesystem integration in user-space.

By using FUSE, the C# code can run entirely in user-space and not require any special permissions to serve the filesystem.

SULF is meant to be useful to filesystem developers. It currently contains only a simple test filesystem to use for testing.

Recent Builds

Note -- this online documentation is based on the current build, and may not correspond exactly to one of the snapshots below.

2005.04.29 -- 0.3, Queen's Day release

• major API changes. API has become simpler and is split into two libraries. The Fuse.dll library communicates with the FUSE kernel module and provides an API based on simple C# interfaces (Node, FileNode, DirNode). The Sulf.dll library builds on Fuse.dll and provides a more natural interface to C# objects (a Hashmap can be used as a directory, string as a file, etc).
• Updated FuseWrapper and Fuse interfaces for FUSE 2.3 (Kernel api version 6.1)

2005.01.15

• updated FuseWrapper and Fuse interfaces for FUSE 2.1 compatibility.
• implemented simple Hello-World filesystem in examples subdirectory, which is similar to libfuse's example/hello.c

2005.01.13

• release under LGPL license
• simplify build system to make it easier to build
• add snapshot (see Downloads)

Downloads

SULF is kept in revision control using Darcs (http://abridgegame.org/darcs/). The current development branch is available here: http://arg0.net/users/vgough/devel/sulf

To get the current distribution:

darcs get http://arg0.net/users/vgough/devel/sulf
cd sulf
darcs get http://arg0.net/users/vgough/devel/RLog

autoreconf
./configure
make

An easier way to get started is to use the snapshot, which contains pre-built objects: sulf-0.3.tar.gz.

See also Dependencies , and Getting Started

Previous Attempts

The old way

My first attempt at building a C# wrapper for fuse was based on capturing all the callbacks from libfuse in C code, and then have a conversion layer translate that into calls to C# code (using internal Mono C# API). This worked, but had some downsides:

• required internal Mono API, so it couldn't be compiled or run with other C# compilers or runtimes.

• could only run in single-threaded mode, since libfuse's threads created from C code would not play well with Mono's thread state.

The new way

The current method is significantly different. The C# code takes control immediately and talks directly to the FUSE kernel module with the help of a some C code (and wrappers generated automatically by SWIG).

This no longer requires the use of Mono internal API's, and it also allows the filesystem to run multi-threaded. The downside is that the FUSE kernel interface has been more variable then the libfuse interface, which means that the C# interface will work with fewer versions of the FUSE code tree.

Design - FuseWrapper.dll

FuseWrapper is a helper library for internal use by Fuse.dll. It consists of two parts -- a C shared object libFuseWrapper.so, and a C# library FuseWrapper.dll. It consists mostly of SWIG generated classes.

The build scripts for FuseWrapper try to automate the process of converting from a fuse_kernel.h (fuse kernel header file) into a set of C# classes.

Only Fuse 2.3 (kernel API 6.1) is supported. The communication with the Fuse kernel module consists of sending and receiving various C structs. FuseWrapper deals with this by keeping the reading and writing of the struct in C code, with wrappers for C# generated by SWIG.

Design - Fuse.dll

Fuse.dll consists of classes to communicate with the Fuse kernel (Fuse.Channel), decode and process requests (Fuse.Reactor), and interfaces for implementing user defined filesystem nodes (Fuse.FileSystem, Fuse.DirNode, Fuse.FileNode).

Implementing a filesystem using Fuse.dll requires implementing three sets of interfaces. These interfaces correspond to the type of function calls that they will handle: filesystem level, directory level, and file level.

1. Fuse.FileSystem interface, which defines a Stat operation and a means of getting the top level directory.

2. Fuse.DirNode interface, which is used for access to directories (one of which is returned by the filesystem level -- FileSystem.RootNode):

3. Fuse.FileNode interface is used for access to normal files

In addition to this three way split, the DirNode and FileNode interfaces also come in two flavors -- one for read-only objects, and another with write support. The Fuse.dll dispatch handler knows how to treat a file based on the interfaces it implements. For example, if a DirNode returns an object which implements FileNode (but not MutableFileNode), then the file will be read-only.

Design - Sulf.dll

The higher-level interface - Sulf.dll is meant to be a better / easier starting point for most filesystems, unless you need the full power of the underlying Fuse.dll interface.

The Sulf.dll design is meant to translate from the Fuse.dll api into something more transparent to C# objects. This layer is newer and is in development.

TODO: more to come. See examples and Sulf directories.

Dependencies

Sulf relies on these projects:

FUSE (Filesystem in User SpacE): http://sourceforge.net/projects/fuse
Version 2.3 (or pre-2.3 from CVS) is the only tested version

Mono (C# compiler and runtime): http://go-mono.org
Mono 1.1.7 is known to work, older versions may or may not work. 1.0.6 is known to NOT work due to some problem passing a delegate as a method argument. 1.1.6 has a bug (#74773) which causes incorrect code to be produced, causing strange runtime behavior.

SWIG (Simplified Wrapper and Interface Generator): http://www.swig.org/
Must use SWIG >= 1.3.24. SWIG's C# output has been maturing recently, and SULF will not build with earlier versions of SWIG..

Getting Started

As long as you have the necessary dependencies statisfied, you can build the SULF libraries and a simple test filesystem by doing the following:

./configure

make

cd examples     

make run        # run hello-fs example which mounts to /tmp/hellofs

---