Documenting the VFS

Documenting the VFS

[Guillermo López Alejos]

Hi,

I'm writing documentation about the VFS. 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?)

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.

Where can I found an up to date documentation about the VFS interface?
If there is no such document, which is the correct mailing list to
submit my questions at? Is there any IRC channel to chat about this?
(I have visited a couple of times #kernelnewbies).

Thanks for your help and regards,

-- 
Guillermo

Re: Documenting the VFS

[Stephane Wirtel]

I believe ( but I am not sure ), there is a recent article (or book) 
on this subject.

> Where can I found an up to date documentation about the VFS interface?
Perhaps in Documentation/VFS, 

> If there is no such document, which is the correct mailing list to
> submit my questions at? Is there any IRC channel to chat about this?
> (I have visited a couple of times #kernelnewbies).
> 
> Thanks for your help and regards,
> 
> -- 
> Guillermo
> -
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/
> 

-- 
Stephane Wirtel <stephane.wirtel@belgacom.net>

Re: Documenting the VFS

[Daniel Phillips]

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

Re: Documenting the VFS

[Steve French]

> Where can I found an up to date documentation about the VFS interface?
There is an ok chapter on filesystems in the O'Reilly Linux Kernel book,
and the Linux Device Drivers book (also from O'Reilly) is essential
reading.

Pay careful attention to fs/libfs.c and the nice small fs fs/ramfs which calls 
libfs which are both useful as they help understand the minimum that certain 
vfs interfaces require.  This was helpful to me when I wrote the cifs
filesystem.

Documentation/filesystems/vfs.txt has a little bit of documentation, as
does Documentation/Locking and Documentation/directory-locking.

I may try to write something (perhaps articles?) longer and
more formal if I get time.  

Finally the lwn series (weekly articles) on kernel development is
invaluable in describing what changes.