VFS: Add documentation for Virtual File System Part 1

[sigmanature]

Description

Hello! I am an undergraduate student passionate about the Linux kernel. I have previously contributed an RFC patch for large folios to the f2fs community.

This is my first pull request to linux-insides. My goal is to start writing a new series of articles for the Virtual File System (VFS) section. This first article serves as an introduction to VFS, explaining its role as an abstraction layer that provides a unified interface for filesystems, and introduces its core data structures.

Changes proposed in this pull request:

• Add the new VFS/ directory.
• Add the new article VFS/linux-vfs-1.md.
• Add a VFS/README.md for future planning.

Questions for the Maintainer

Before I proceed with further work, I have a few questions about the project's contribution style and direction. I would greatly appreciate your guidance:

1. Writing Style: I've noticed that most linux-insides articles focus on code and flow analysis. Do you have any specific style guidelines? Would you encourage the use of more diagrams to aid explanation?
2. External Links: I'd like to cite some high-quality technical articles from the Chinese community, especially if my work is inspired by or references them. Is this acceptable?
3. Modifying Existing Content: Is it permissible to modify existing articles? Some changes might be substantial.
4. Chapter Structure: Some complex topics (like mount in VFS) might be best explained in several sub-parts. This structure doesn't seem to be used in existing articles. What are your thoughts on this approach?
5. Code Evolution: Many kernel subsystems (like swap in the mm subsystem) have undergone significant changes since kernel 3.18. I think it could be valuable to analyze the code from different versions to show the evolution and motivation. What do you think of this idea for future articles?

Thank you for your time and for reviewing my contribution. I look forward to your feedback!

Related issues
N/A

[0xAX]

Hello @sigmanature. First of all thank you for your work!

Writing Style: I've noticed that most linux-insides articles focus on code and flow analysis. Do you have any specific style guidelines? Would you encourage the use of more diagrams to aid explanation?

There is no any guidelines since somewhen I started to write it for myself mostly. Actually any information about the kernel and its parts is appreciated. For the start it is ok I think if you will more-less follow the common structure that each part has - short introduction, main part, conclusion, links.

External Links: I'd like to cite some high-quality technical articles from the Chinese community, especially if my work is inspired by or references them. Is this acceptable?

It is ok in general but may look somewhat strange if the articles themselves are written in Chinese. Usually each part as you probably have seen ends with links, I think it is pretty ok to have a small note that in addition these links were used.

Modifying Existing Content: Is it permissible to modify existing articles? Some changes might be substantial.

Of course, if you see something wrong, outdated or just you have better phrasing feel free to open PR.

Chapter Structure: Some complex topics (like mount in VFS) might be best explained in several sub-parts. This structure doesn't seem to be used in existing articles. What are your thoughts on this approach?

In this case I'd usally go with 'Main title. Part 1'

Code Evolution: Many kernel subsystems (like swap in the mm subsystem) have undergone significant changes since kernel 3.18. I think it could be valuable to analyze the code from different versions to show the evolution and motivation. What do you think of this idea for future articles?

It is always interesting from the historical perspective especially with description why it was changed. But of course it is always good to have the latest code despite any previous. I know and understand how hard it can be since the kernel is constantly developed.

The very first thing related to the review could you please add an annotation to each code snippet in your article. The examples you can find in any .md file in Booting. For example:

<!-- https://raw.githubusercontent.com/coreboot/coreboot/refs/heads/main/src/cpu/x86/entry16.S#L155-L159 -->

they are visible only in raw format - https://raw.githubusercontent.com/0xAX/linux-insides/refs/heads/master/Booting/linux-bootstrap-1.md. They are used by the script https://github.com/0xAX/linux-insides/blob/master/scripts/check_code_snippets.py that checks that the code snippets are valid and exist in the current kernel master branch. If I was not clear or you need help please let me know.

The content itself I will review at this week. Thank you again very much.

[sigmanature]

Hi @0xAX ,
Thank you for your nice and patient reply!

It is ok in general but may look somewhat strange if the articles themselves are written in Chinese. Usually each part as you probably have seen ends with links, I think it is pretty ok to have a small note that in addition these links were used.

In that way we'd better not put links to articles that entirely written in Chinese in the Links part in
English version?

It is always interesting from the historical perspective especially with description why it was changed. But of course it is always good to have the latest code despite any previous. I know and understand how hard it can be since the kernel is constantly developed.

So the more ideal approach would be to use text to explain the historical design of a certain submodule, while the code blocks show the code from the latest kernel ?

Chapter Structure: Some complex topics (like mount in VFS) might be best explained in several sub-parts. This structure doesn't seem to be used in existing articles. What are your thoughts on this approach?

In this case I'd usally go with 'Main title. Part 1'

Let me clarify my question with a concrete example.
Right now I’m writing the VFS chapter, and the first article is the introduction.
Following the structure used in Linux Inside, the title would be something like:

Virtual File System in Linux. Part 1.

Within the VFS chapter, mount is one of the major topics.
But mount itself is complicated enough that it will require several articles of its own.
This naturally creates a nested document structure: VFS → mount → multiple sub-parts.

My question is: how should I name the titles in this situation?
Do I need to write something like
VFS. Part X / Mount. Part Y
or is there a cleaner naming convention for nested topics like this?

The very first thing related to the review could you please add an annotation to each code snippet in your article. The examples you can find in any .md file in Booting. For example:

<!-- https://raw.githubusercontent.com/coreboot/coreboot/refs/heads/main/src/cpu/x86/entry16.S#L155-L159 -->
they are visible only in raw format - https://raw.githubusercontent.com/0xAX/linux-insides/refs/heads/master/Booting/linux-bootstrap-1.md. They are used by the script https://github.com/0xAX/linux-insides/blob/master/scripts/check_code_snippets.py that checks that the code snippets are valid and exist in the current kernel master branch. If I was not clear or you need help please let me know.

I have studied the check_code_snippet.py script in detail, and it seems that it performs a very strict, line-by-line verification between the code blocks in the article and the corresponding lines in the referenced kernel source files.

However, when I’m explaining a data structure, sometimes I only want to introduce the most essential members first. In such cases, I may want to show a simplified version of the struct that contains only a subset of the fields.
But obviously such a snippet will not pass the strict code check. At the same time, always pasting the full struct definition feels too long and makes the explanation less readable.

Another issue is the one you mentioned: currently the reference links are only visible in the raw format.
I was thinking—perhaps we could expose these links directly, or at least expose the kernel version associated with the snippet. This would make it much clearer for readers to understand the context and the exact kernel version the explanation refers to.

What do you think about this approach?

Looking forward for your kindly reply!

[0xAX]

In that way we'd better not put links to articles that entirely written in Chinese in the Links part in

As I said it is ok to put in the end of the links section and just mention that these sources are on Cheenese. Another variant is to put it in https://github.com/0xAX/linux-insides/blob/master/LINKS.md document in separate section and mention/refer in the post.

My question is: how should I name the titles in this situation? Do I need to write something like VFS. Part X / Mount. Part Y or is there a cleaner naming convention for nested topics like this?

Yes yes, I see what you mean. There is very similar situation for example with the kernel initialization - as it contsists of many many different things which is impossible to put in the single post. I did just it pretty straightforward and named it just - Kernel initialization Part 1, Kernel initialization Part 2 and so on. Inside the post itself just have some introduction and conclusion like here we see "mount stuff up to the X point" and in the next post we will continue to investigate/dive/whatever in this process. Do you see what I mean or not clear?

However, when I’m explaining a data structure, sometimes I only want to introduce the most essential members first. In such cases, I may want to show a simplified version of the struct that contains only a subset of the fields.
But obviously such a snippet will not pass the strict code check. At the same time, always pasting the full struct definition feels too long and makes the explanation less readable.

This is also true and I understand your concern. The same can be for any long function or structure like thread or whatever. I'd suggest for now just leave such cases without annotations and maybe create an issue with "TODOs" for such parts and I will try to improve the script to handle such cases. So for now please add these annotations just to whatever it is possible to add and we will see in future what to do with partial pieces of code.

Another issue is the one you mentioned: currently the reference links are only visible in the raw format.
I was thinking—perhaps we could expose these links directly, or at least expose the kernel version associated with the snippet. This would make it much clearer for readers to understand the context and the exact kernel version the explanation refers to.

The fact that they are invisible for any cases except the raw format it was done intentionally to have them only for validation scripts/CI. So I'd leave this approach as is for now. But of course in the text itself before (or after, depends on context) you can mention something like "the following structure/function/whatever X is defined in the LINK source code file" like it is in most of posts I think.