Skip to contentSkip to conversation

Documenting the VFS

DISCUSSION Guillermo López Alejos 3 participants 3 messages Aug 13, 2005 – Aug 18, 2005

lore
Share & tools
lore
#0 lore raw

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,

Signature · 1 line
Guillermo
#1 lore raw

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

Quoted 1 line

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

Perhaps in Documentation/VFS,

Quoted 14 lines

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,

Signature · 6 lines
Guillermo
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/
Signature · 1 line
Stephane Wirtel <[email protected]>
#2 lore raw
In reply to Guillermo López Alejos
Quoted 3 lines · Guillermo López Alejos

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.

Quoted 5 lines

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).

Quoted 8 lines

- 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.

Quoted 3 lines

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.

Quoted 1 line

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

Quoted 2 lines

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.

Quoted 2 lines

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.

Quoted 1 line

Thanks for your help and regards,

Thanks for volunteering!

Regards,

Daniel