1File systems overview 2--------------------- 3 4Each filesystem driver must define a few structures which act as the 5interface between the VFS and the filesystem implementation. These 6structures contain function pointers, some of which are optional, 7which should point to functions defined by the implementer that 8perform the appropriate filesystem operation as defined by the 9documentation. 10 11See docs/user/drivers/fs_interface.dox for more detailed documentation 12of this interface. 13 14It's important to note that while there may be some similarities in 15the interface with that of other operations systems, one should not 16make any assumptions about the desired behavior based soley on the 17function prototypes defined in fs_interface.h. 18 19The following is a list of notes calling out some potential mistakes. 20 21# fs_vnode_ops.read_symlink 22 23Defining this function means that the filesystem driver supports 24symbolic links, and the function that f_vnode_ops.read_symlink points 25to should read the contents of a symlink from the specified node. 26 27This may seem similar to the posix function readlink(), but it is 28slightly different. Unlike readlink(), which returns the number of 29bytes copied into the output buffer, fs_vnode_ops.read_symlink is 30expected to always return the length of the symlink contents, even if 31the provided buffer is not large enough to contain the entire symlink 32contents. 33 34Development tools 35----------------- 36 37fs_shell 38........ 39 40It is not convenient to test a filesystem by reloading its driver into a 41running Haiku system (kernel debugging is often not as easy as userland). 42Moreover, the filesystem interacts with other components of the system 43(file cache, block cache, but also any application reading or writing files). 44 45For the early development steps, it is much easier to run the filesystem code 46in a more controlled environment. This can be achieved through the use of 47a "filesystem shell": a simple application that runs the filesystem code, and 48allows performing specific operations through a command line interface. It can be 49executed on any platform (Haiku or another supported one such as Linux). 50 51Example of fs_shell implementations are available under src/tests/add-ons/kernel/file_systems/ 52for the bfs and btrfs filesystems. 53 54For example, to build the fs_shell for btrfs, use 55 56.. code-block:: bash 57 58 jam -q "<build>btrfs_shell" 59 60To run it, use 61 62.. code-block:: bash 63 64 jam run ":<build>btrfs_shell" <.img file> 65 66:ref:`XFS Page` has a concrete example which can be tweaked for other filesystems. 67 68You need to pass at least a file or device containing a filesystem image as an 69argument. You need some tool to create one. It is possible to work using an 70actual disk volume (but be careful, it's risky to use one with useful data in it), 71a file, or a RAM disk, depending on what you are doing. 72 73userlandfs 74.......... 75 76As a second step, it's possible to use the filesystem as part of a running 77system, while still running it in userland. This allows use of Debugger, 78memory protection, and in general any kind of userland debugging or tracing 79tool. When the filesystem crashes, it does not bring down the whole system. 80 81Userlandfs can run the filesystem code using the same interface as the kernel, 82therefore, once everything is working with userlandfs, running the filesystem 83as kernel code is usually quite easy (and provides a performance boost) 84 85See more here: :ref:`Userland FS Page` 86 87Torture and performance tests 88............................. 89 90Once the basic operations are working fine, it is a good idea to perform more 91agressive testing. Examples of scripts doing this are available in 92src/tests/add-ons/kernel/file_systems/ for the fat and ext2 filesystems. 93