Re: Documenting the VFS

[Daniel Phillips <phillips@arcor.de>]

On Sunday 14 August 2005 05:05, Guillermo López Alejos wrote:
> Hi,
>
> I'm writing documentation about the VFS.

Best of luck.  It is a complex topic, but if you manage to produce an accurate 
reference, it will be widely read.

> More concretely, I want to 
> document the following information about the methods defined in the
> VFS interface (i.e. the struct *_operations):
>     - Prototype.
>     - Description (brief description of what the method has to do).
>     - Description of the parameters (explanation of the purpose of
> each parameter).
>     - Return value (including possible error values).
>     - Responsibility (what the method is expected to do, including
> specific cases).
>     - Default method (is there any method that can be used instead of
> defining a new one?)
>     - Mandatory (Is the method mandatory? or it can be assigned a NULL?)

Locking is a crucial topic.  Filesystem developers need to understand what 
locking the VFS does for them and what they must do themselves.  You need to 
cover this method by method and lock by lock.  Also note that you can't 
really understand the vfs separately from things like the page cache, inode 
cache and dentry cache, and respective operations.  It crosses over into 
virtual memory topics too, because of mmap.  A discussion of the vfs would 
not be complete without discussing the life cycles of all the objects 
involved.

> It is rather difficult to find this information by looking at the
> kernel sources, and the documentation I have found does not provide
> the details I'm looking for.

You pretty much have to read the source to learn this since there is no 
authoritative reference.  As others have mentioned, Richard Gootch's vfs.txt 
document is helpful.  It is several years out of date though, and doesn't 
cover things like aio, new security hooks, dnotify and inotify event 
interface, cluster hooks, etc. etc.

> Where can I found an up to date documentation about the VFS interface?

It's pretty sparse.

   http://lxr.linux.no/source/Documentation/filesystems/vfs.txt
   http://lxr.linux.no/source/Documentation/filesystems/Locking
   http://www.faqs.org/docs/kernel_2_4/lki-3.html
   http://www.oreilly.com/catalog/linuxkernel/
   http://lwn.net

> If there is no such document, which is the correct mailing list to
> submit my questions at?

This is the right place, or fsdevel, or both.  You probably want to post your 
drafts or pointers to your drafts here for corrections and additions.

> Is there any IRC channel to chat about this? 
> (I have visited a couple of times #kernelnewbies).

#kernelnewbies is good, the name is a little deceiving.  Also, try Matt 
Mackall's kernelmentors mailing list and Arnaldo Carvalho de Melo's kernel 
janitors mailing list.

> Thanks for your help and regards,

Thanks for volunteering!

Regards,

Daniel