[PATCH 6/6] Documentation: devel: add short section on file systems

[Ahmad Fatoum <a.fatoum@pengutronix.de>]

barebox has a lot of commands that can be used to exercise different
aspects of a file system. Add some documentation for that.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/devel/background-execution.rst |  2 +
 Documentation/devel/devel.rst                |  1 +
 Documentation/devel/filesystems.rst          | 73 ++++++++++++++++++++
 3 files changed, 76 insertions(+)
 create mode 100644 Documentation/devel/filesystems.rst

diff --git a/Documentation/devel/background-execution.rst b/Documentation/devel/background-execution.rst
index cf8675b9aa0e..e1e350785298 100644
--- a/Documentation/devel/background-execution.rst
+++ b/Documentation/devel/background-execution.rst
@@ -1,3 +1,5 @@
+.. _background_execution:
+
 Background execution in barebox
 ===============================
 
diff --git a/Documentation/devel/devel.rst b/Documentation/devel/devel.rst
index 39070074ca1b..3e9d44218334 100644
--- a/Documentation/devel/devel.rst
+++ b/Documentation/devel/devel.rst
@@ -9,6 +9,7 @@ Contents:
    :maxdepth: 2
 
    porting
+   filesystems
    background-execution
    project-ideas
 
diff --git a/Documentation/devel/filesystems.rst b/Documentation/devel/filesystems.rst
new file mode 100644
index 000000000000..454e736c701f
--- /dev/null
+++ b/Documentation/devel/filesystems.rst
@@ -0,0 +1,73 @@
+File system development in barebox
+==================================
+
+The barebox file system support is based heavily on Linux.
+
+Access to all file systems goes through the virtual file system
+layer, which provides uniform access to all mounted file systems
+under the same root.
+
+As power-fail safe writing of file system couldn't be guaranteed,
+most file systems supported by barebox are read-only.
+Safe writing is possible, however, via the :ref:`state_framework`.
+
+For an up-to-date listing of writable filesystems, refer to the
+``CONFIG_FS_WRITABLE`` Kconfig symbol.
+
+Testing File systems
+--------------------
+
+Nearly all file system operations have commands that directly exercise them:
+
++--------------------------+-----------------------------------------+
+| Command                  | Operations                              |
++==========================+=========================================+
+| :ref:`command_cat`       | ``open``, ``close``, ``read``           |
++--------------------------+-----------------------------------------+
+| :ref:`command_echo`      | ``create``, ``write``                   |
++--------------------------+-----------------------------------------+
+| :ref:`command_sync`      | ``flush``                               |
++--------------------------+-----------------------------------------+
+| :ref:`command_erase`     | ``erase``                               |
++--------------------------+-----------------------------------------+
+| :ref:`command_protect`   | ``protect``                             |
++--------------------------+-----------------------------------------+
+| :ref:`command_md`        | ``lseek``, ``memmap``                   |
++--------------------------+-----------------------------------------+
+| :ref:`command_rm`        | ``unlink``                              |
++--------------------------+-----------------------------------------+
+| :ref:`command_mkdir`     | ``mkdir``                               |
++--------------------------+-----------------------------------------+
+| :ref:`command_rmdir`     | ``rmdir``                               |
++--------------------------+-----------------------------------------+
+| :ref:`command_ln`        | ``symlink``                             |
++--------------------------+-----------------------------------------+
+| :ref:`command_readlink`  | ``readlink``                            |
++--------------------------+-----------------------------------------+
+| | :ref:`command_ls`      |  ``opendir``, ``readdir``, ``closedir`` |
+| | :ref:`command_tree`    |                                         |
++--------------------------+-----------------------------------------+
+| :ref:`command_stat`      | ``stat``                                |
++--------------------------+-----------------------------------------+
+| :ref:`command_truncate`  | ``truncate``                            |
++--------------------------+-----------------------------------------+
+
+This leaves two specialized operations that can't be easily tested
+via the shell:
+
+- ``discard_range``: Advise that a range need not be preserved
+- ``ioctl``: Issue device-specific output and input control commands
+
+Unused metadata
+---------------
+
+barebox currently ignores ownership and permission information
+inside file systems as well as special nodes like FIFOs or
+sockets. When porting file systems, these parts can be omitted.
+
+Background execution
+--------------------
+
+Outside command context (i.e. in
+:ref:`pollers and secondary barebox threads <background_execution>`),
+virtual file system access is only permitted with ramfs.
-- 
2.39.5