You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by "resyfer (via GitHub)" <gi...@apache.org> on 2024/02/20 15:40:28 UTC

[PR] fs: Add VFS docs [nuttx]

resyfer opened a new pull request, #11730:
URL: https://github.com/apache/nuttx/pull/11730

   This commit adds VFS documentation, and details about the VFS interface.
   
   ## Summary
   
   Adds VFS docs.
   Fixes small typo in VFAT docs.
   
   ## Impact
   
   VFS Docs.
   
   ## Testing
   
   Sphinx build. Had some warnings for "duplicate declaration" of C functions, but it was necessary here as the additions explain VFS interface methods as well.
   
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] fs: Add VFS docs [nuttx]

Posted by "resyfer (via GitHub)" <gi...@apache.org>.
resyfer commented on PR #11730:
URL: https://github.com/apache/nuttx/pull/11730#issuecomment-1954844423

   @raiden00pl Thanks for the tip. I also included the options for sphinx-autobuild, as it always listed these warnings even with the `known-warnings` files


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] fs: Add VFS docs [nuttx]

Posted by "xiaoxiang781216 (via GitHub)" <gi...@apache.org>.
xiaoxiang781216 merged PR #11730:
URL: https://github.com/apache/nuttx/pull/11730


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] fs: Add VFS docs [nuttx]

Posted by "raiden00pl (via GitHub)" <gi...@apache.org>.
raiden00pl commented on PR #11730:
URL: https://github.com/apache/nuttx/pull/11730#issuecomment-1954513399

   You can filter "duplicate declaration" warnings with https://github.com/apache/nuttx/blob/master/Documentation/known-warnings.txt
   
   CI also complains about this: https://github.com/apache/nuttx/actions/runs/7976088720/job/21775821212#step:5:1136


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] fs: Add VFS docs [nuttx]

Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis commented on code in PR #11730:
URL: https://github.com/apache/nuttx/pull/11730#discussion_r1496176638


##########
Documentation/components/filesystem/index.rst:
##########
@@ -41,6 +41,493 @@ pseudo file systems may be mounted in the true, root file system.
 The approach selected by NuttX is intended to support greater
 scalability from the very tiny platform to the moderate platform.
 
+Virtual File System (VFS)
+=========================
+
+Virtual File System provides a unified interface for various file systems to
+be able to co-exist together by exposing a blueprint that each file system
+needs to implement. This also allows the file system to be free from worry
+about the device driver implementations for storage devices, as they also
+expose a unified way of accessing the underlying devices.
+
+How VFS works
+-------------
+
+Threads are controllable sequences of instruction execution with their own
+stacks. Each task in NuttX is represented by a Task Control Block (TCB) (TCB
+is defined in ``include/nuttx/sched.h``) and tasks are organized in task
+lists.
+
+All threads that are created by ``pthread_create()`` are part of the same task
+group. A task group (defined in ``include/nuttx/sched.h``) is a shared
+structure pointed to by the TCBs of all the threads that belong to the same
+task group, and this task group contains all the resources shared across the
+task group which includes *file descriptors* in the form of a **file list**.
+
+A file list (defined in ``include/nuttx/fs/fs.h``) contains file structures
+that denote open files (along with a spinlock to manage access to the file
+list). With the devices listed in the :ref:`root file system <root_fs>` (on
+points like ``/dev/led``, ``/dev/mmcsd0``, etc. which are henceforth called
+blockdriver mount points) in an unmounted state, storage devices can be
+mounted using the ``mount()`` command (to any point like ``/dir/abcd``) with
+any specific supported file system, which internally calls its implemented
+``mountpt_operations->bind()`` method and passes the blockdriver's mount
+point inode to it, thus creating a **mount point**. The blockdriver mount
+point inode will have a ``mountpt->i_private`` which contains any (file system
+dependent) information about the mount and is to be filled by the file system
+during the execution of ``mountpt_operations->bind()`` (and usually this data
+includes a pointer to the blockdriver mount point as well). After that,
+according to system calls, the other exposed functions of the filesystem
+are called as per need.
+
+VFS Interface
+-------------
+
+VFS allows file systems to expose their own implementations of methods
+belonging to a unified interface:
+
+* **File operations**
+
+.. c:function:: int open(FAR struct file *filep, FAR const char *relpath, int oflags, mode_t mode)
+  
+  Opens a file. Files are required to be opened before any other file
+  operations are performed on it.
+
+  :param FAR struct file * filep: Open file's file structure pointer. The
+    ``filep->f_priv`` member needs to be set here with the file system
+    specific data that represents an open file.
+  :param FAR const char * relpath: Relative path of the file from the root of
+    the mounted file system.
+  :param int oflags: Flags in a bit field that specify the mode for openning
+    the file (eg. ``O_RDONLY``, ``O_RDWR``, etc. defined in
+    ``include/fcntl.h``).
+  :param mode_t mode: Specifies the mode (permissions). If ``oflags`` include
+    ``O_CREAT``, then this contains the mode for the file to be created.
+  :returns: Status of openning a file.
+  :retval OK (0): Success.
+  :retval < 0: Error.
+
+.. c:function:: int close(FAR struct file *filep)
+
+  This closes the opened file, and ideally syncs all the changes to the file
+  to be written to the disk, as well as free the memory allocated to store the
+  open file's data.
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :returns: Status of closing a file.
+  :retval OK (0): Success.
+  :retval < 0: Error.
+
+.. c:function:: ssize_t read(FAR struct file *filep, FAR char *buffer, size_t buflen)
+  
+  Reads maximum ``buflen`` bytes from an opened file (from the current offset
+  the opened file descriptor is pointing at if the file system supports
+  seeking).
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :param FAR char * buffer: Buffer to store the read data.
+  :param size_t buflen: Length of the maximum number of bytes to be read.
+  :returns: Number of bytes read.
+  :retval > 0: Size of bytes read.
+  :retval < 0: Error.
+
+.. c:function:: ssize_t write(FAR struct file *filep, FAR const char *buffer, size_t buflen)
+  
+  Writes maximum ``buflen`` bytes to an opened file (from the current offset
+  the opened file is at if the file system supports seeking).
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :param FAR char * buffer: Buffer which contains the data to be written.
+  :param size_t buflen: Length of the maximum number of bytes to be written.
+  :returns: Number of bytes written.
+  :retval > 0: Size of bytes written.
+  :retval < ``buflen``: Insufficient storage or file size limit reached
+  :retval < 0: Error.
+
+.. NOTE::
+  POSIX requires that a ``read()`` after a ``write()`` should get the newly
+  written data, but not all file systems confirm to POSIX, especially as
+  POSIX requires atomic writes, which is not usually not implemented
+  as it can impact performance.
+
+  To be POSIX compliant in concurrent situations, either the writes have to
+  be atomic, or read is blocked with a lock till an on-going write is

Review Comment:
   ```suggestion
     be atomic, or read is blocked with a lock until an on-going write is



##########
Documentation/components/filesystem/index.rst:
##########
@@ -41,6 +41,493 @@ pseudo file systems may be mounted in the true, root file system.
 The approach selected by NuttX is intended to support greater
 scalability from the very tiny platform to the moderate platform.
 
+Virtual File System (VFS)
+=========================
+
+Virtual File System provides a unified interface for various file systems to
+be able to co-exist together by exposing a blueprint that each file system
+needs to implement. This also allows the file system to be free from worry
+about the device driver implementations for storage devices, as they also
+expose a unified way of accessing the underlying devices.
+
+How VFS works
+-------------
+
+Threads are controllable sequences of instruction execution with their own
+stacks. Each task in NuttX is represented by a Task Control Block (TCB) (TCB
+is defined in ``include/nuttx/sched.h``) and tasks are organized in task
+lists.
+
+All threads that are created by ``pthread_create()`` are part of the same task
+group. A task group (defined in ``include/nuttx/sched.h``) is a shared
+structure pointed to by the TCBs of all the threads that belong to the same
+task group, and this task group contains all the resources shared across the
+task group which includes *file descriptors* in the form of a **file list**.
+
+A file list (defined in ``include/nuttx/fs/fs.h``) contains file structures
+that denote open files (along with a spinlock to manage access to the file
+list). With the devices listed in the :ref:`root file system <root_fs>` (on
+points like ``/dev/led``, ``/dev/mmcsd0``, etc. which are henceforth called
+blockdriver mount points) in an unmounted state, storage devices can be
+mounted using the ``mount()`` command (to any point like ``/dir/abcd``) with
+any specific supported file system, which internally calls its implemented
+``mountpt_operations->bind()`` method and passes the blockdriver's mount
+point inode to it, thus creating a **mount point**. The blockdriver mount
+point inode will have a ``mountpt->i_private`` which contains any (file system
+dependent) information about the mount and is to be filled by the file system
+during the execution of ``mountpt_operations->bind()`` (and usually this data
+includes a pointer to the blockdriver mount point as well). After that,
+according to system calls, the other exposed functions of the filesystem
+are called as per need.
+
+VFS Interface
+-------------
+
+VFS allows file systems to expose their own implementations of methods
+belonging to a unified interface:
+
+* **File operations**
+
+.. c:function:: int open(FAR struct file *filep, FAR const char *relpath, int oflags, mode_t mode)
+  
+  Opens a file. Files are required to be opened before any other file
+  operations are performed on it.
+
+  :param FAR struct file * filep: Open file's file structure pointer. The
+    ``filep->f_priv`` member needs to be set here with the file system
+    specific data that represents an open file.
+  :param FAR const char * relpath: Relative path of the file from the root of
+    the mounted file system.
+  :param int oflags: Flags in a bit field that specify the mode for openning
+    the file (eg. ``O_RDONLY``, ``O_RDWR``, etc. defined in
+    ``include/fcntl.h``).
+  :param mode_t mode: Specifies the mode (permissions). If ``oflags`` include
+    ``O_CREAT``, then this contains the mode for the file to be created.
+  :returns: Status of openning a file.
+  :retval OK (0): Success.
+  :retval < 0: Error.
+
+.. c:function:: int close(FAR struct file *filep)
+
+  This closes the opened file, and ideally syncs all the changes to the file
+  to be written to the disk, as well as free the memory allocated to store the
+  open file's data.
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :returns: Status of closing a file.
+  :retval OK (0): Success.
+  :retval < 0: Error.
+
+.. c:function:: ssize_t read(FAR struct file *filep, FAR char *buffer, size_t buflen)
+  
+  Reads maximum ``buflen`` bytes from an opened file (from the current offset
+  the opened file descriptor is pointing at if the file system supports
+  seeking).
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :param FAR char * buffer: Buffer to store the read data.
+  :param size_t buflen: Length of the maximum number of bytes to be read.
+  :returns: Number of bytes read.
+  :retval > 0: Size of bytes read.
+  :retval < 0: Error.
+
+.. c:function:: ssize_t write(FAR struct file *filep, FAR const char *buffer, size_t buflen)
+  
+  Writes maximum ``buflen`` bytes to an opened file (from the current offset
+  the opened file is at if the file system supports seeking).
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :param FAR char * buffer: Buffer which contains the data to be written.
+  :param size_t buflen: Length of the maximum number of bytes to be written.
+  :returns: Number of bytes written.
+  :retval > 0: Size of bytes written.
+  :retval < ``buflen``: Insufficient storage or file size limit reached
+  :retval < 0: Error.
+
+.. NOTE::
+  POSIX requires that a ``read()`` after a ``write()`` should get the newly
+  written data, but not all file systems confirm to POSIX, especially as

Review Comment:
   ```suggestion
     written data, but not all file systems conform to POSIX, especially as



##########
Documentation/components/filesystem/index.rst:
##########
@@ -41,6 +41,493 @@ pseudo file systems may be mounted in the true, root file system.
 The approach selected by NuttX is intended to support greater
 scalability from the very tiny platform to the moderate platform.
 
+Virtual File System (VFS)
+=========================
+
+Virtual File System provides a unified interface for various file systems to
+be able to co-exist together by exposing a blueprint that each file system
+needs to implement. This also allows the file system to be free from worry
+about the device driver implementations for storage devices, as they also
+expose a unified way of accessing the underlying devices.
+
+How VFS works
+-------------
+
+Threads are controllable sequences of instruction execution with their own
+stacks. Each task in NuttX is represented by a Task Control Block (TCB) (TCB
+is defined in ``include/nuttx/sched.h``) and tasks are organized in task
+lists.
+
+All threads that are created by ``pthread_create()`` are part of the same task
+group. A task group (defined in ``include/nuttx/sched.h``) is a shared
+structure pointed to by the TCBs of all the threads that belong to the same
+task group, and this task group contains all the resources shared across the
+task group which includes *file descriptors* in the form of a **file list**.
+
+A file list (defined in ``include/nuttx/fs/fs.h``) contains file structures
+that denote open files (along with a spinlock to manage access to the file
+list). With the devices listed in the :ref:`root file system <root_fs>` (on
+points like ``/dev/led``, ``/dev/mmcsd0``, etc. which are henceforth called
+blockdriver mount points) in an unmounted state, storage devices can be
+mounted using the ``mount()`` command (to any point like ``/dir/abcd``) with
+any specific supported file system, which internally calls its implemented
+``mountpt_operations->bind()`` method and passes the blockdriver's mount
+point inode to it, thus creating a **mount point**. The blockdriver mount
+point inode will have a ``mountpt->i_private`` which contains any (file system
+dependent) information about the mount and is to be filled by the file system
+during the execution of ``mountpt_operations->bind()`` (and usually this data
+includes a pointer to the blockdriver mount point as well). After that,
+according to system calls, the other exposed functions of the filesystem
+are called as per need.
+
+VFS Interface
+-------------
+
+VFS allows file systems to expose their own implementations of methods
+belonging to a unified interface:
+
+* **File operations**
+
+.. c:function:: int open(FAR struct file *filep, FAR const char *relpath, int oflags, mode_t mode)
+  
+  Opens a file. Files are required to be opened before any other file
+  operations are performed on it.
+
+  :param FAR struct file * filep: Open file's file structure pointer. The
+    ``filep->f_priv`` member needs to be set here with the file system
+    specific data that represents an open file.
+  :param FAR const char * relpath: Relative path of the file from the root of
+    the mounted file system.
+  :param int oflags: Flags in a bit field that specify the mode for openning
+    the file (eg. ``O_RDONLY``, ``O_RDWR``, etc. defined in
+    ``include/fcntl.h``).
+  :param mode_t mode: Specifies the mode (permissions). If ``oflags`` include
+    ``O_CREAT``, then this contains the mode for the file to be created.
+  :returns: Status of openning a file.
+  :retval OK (0): Success.
+  :retval < 0: Error.
+
+.. c:function:: int close(FAR struct file *filep)
+
+  This closes the opened file, and ideally syncs all the changes to the file
+  to be written to the disk, as well as free the memory allocated to store the
+  open file's data.
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :returns: Status of closing a file.
+  :retval OK (0): Success.
+  :retval < 0: Error.
+
+.. c:function:: ssize_t read(FAR struct file *filep, FAR char *buffer, size_t buflen)
+  
+  Reads maximum ``buflen`` bytes from an opened file (from the current offset
+  the opened file descriptor is pointing at if the file system supports
+  seeking).
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :param FAR char * buffer: Buffer to store the read data.
+  :param size_t buflen: Length of the maximum number of bytes to be read.
+  :returns: Number of bytes read.
+  :retval > 0: Size of bytes read.
+  :retval < 0: Error.
+
+.. c:function:: ssize_t write(FAR struct file *filep, FAR const char *buffer, size_t buflen)
+  
+  Writes maximum ``buflen`` bytes to an opened file (from the current offset
+  the opened file is at if the file system supports seeking).
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :param FAR char * buffer: Buffer which contains the data to be written.
+  :param size_t buflen: Length of the maximum number of bytes to be written.
+  :returns: Number of bytes written.
+  :retval > 0: Size of bytes written.
+  :retval < ``buflen``: Insufficient storage or file size limit reached
+  :retval < 0: Error.
+
+.. NOTE::
+  POSIX requires that a ``read()`` after a ``write()`` should get the newly
+  written data, but not all file systems confirm to POSIX, especially as
+  POSIX requires atomic writes, which is not usually not implemented

Review Comment:
   ```suggestion
     POSIX requires atomic writes, which is not usually implemented



##########
Documentation/components/filesystem/index.rst:
##########
@@ -41,6 +41,493 @@ pseudo file systems may be mounted in the true, root file system.
 The approach selected by NuttX is intended to support greater
 scalability from the very tiny platform to the moderate platform.
 
+Virtual File System (VFS)
+=========================
+
+Virtual File System provides a unified interface for various file systems to
+be able to co-exist together by exposing a blueprint that each file system
+needs to implement. This also allows the file system to be free from worry
+about the device driver implementations for storage devices, as they also
+expose a unified way of accessing the underlying devices.
+
+How VFS works
+-------------
+
+Threads are controllable sequences of instruction execution with their own
+stacks. Each task in NuttX is represented by a Task Control Block (TCB) (TCB
+is defined in ``include/nuttx/sched.h``) and tasks are organized in task
+lists.
+
+All threads that are created by ``pthread_create()`` are part of the same task
+group. A task group (defined in ``include/nuttx/sched.h``) is a shared
+structure pointed to by the TCBs of all the threads that belong to the same
+task group, and this task group contains all the resources shared across the
+task group which includes *file descriptors* in the form of a **file list**.
+
+A file list (defined in ``include/nuttx/fs/fs.h``) contains file structures
+that denote open files (along with a spinlock to manage access to the file
+list). With the devices listed in the :ref:`root file system <root_fs>` (on
+points like ``/dev/led``, ``/dev/mmcsd0``, etc. which are henceforth called
+blockdriver mount points) in an unmounted state, storage devices can be
+mounted using the ``mount()`` command (to any point like ``/dir/abcd``) with
+any specific supported file system, which internally calls its implemented
+``mountpt_operations->bind()`` method and passes the blockdriver's mount
+point inode to it, thus creating a **mount point**. The blockdriver mount
+point inode will have a ``mountpt->i_private`` which contains any (file system
+dependent) information about the mount and is to be filled by the file system
+during the execution of ``mountpt_operations->bind()`` (and usually this data
+includes a pointer to the blockdriver mount point as well). After that,
+according to system calls, the other exposed functions of the filesystem
+are called as per need.
+
+VFS Interface
+-------------
+
+VFS allows file systems to expose their own implementations of methods
+belonging to a unified interface:
+
+* **File operations**
+
+.. c:function:: int open(FAR struct file *filep, FAR const char *relpath, int oflags, mode_t mode)
+  
+  Opens a file. Files are required to be opened before any other file
+  operations are performed on it.
+
+  :param FAR struct file * filep: Open file's file structure pointer. The
+    ``filep->f_priv`` member needs to be set here with the file system
+    specific data that represents an open file.
+  :param FAR const char * relpath: Relative path of the file from the root of
+    the mounted file system.
+  :param int oflags: Flags in a bit field that specify the mode for openning
+    the file (eg. ``O_RDONLY``, ``O_RDWR``, etc. defined in
+    ``include/fcntl.h``).
+  :param mode_t mode: Specifies the mode (permissions). If ``oflags`` include
+    ``O_CREAT``, then this contains the mode for the file to be created.
+  :returns: Status of openning a file.
+  :retval OK (0): Success.
+  :retval < 0: Error.
+
+.. c:function:: int close(FAR struct file *filep)
+
+  This closes the opened file, and ideally syncs all the changes to the file
+  to be written to the disk, as well as free the memory allocated to store the
+  open file's data.
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :returns: Status of closing a file.
+  :retval OK (0): Success.
+  :retval < 0: Error.
+
+.. c:function:: ssize_t read(FAR struct file *filep, FAR char *buffer, size_t buflen)
+  
+  Reads maximum ``buflen`` bytes from an opened file (from the current offset
+  the opened file descriptor is pointing at if the file system supports
+  seeking).
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :param FAR char * buffer: Buffer to store the read data.
+  :param size_t buflen: Length of the maximum number of bytes to be read.
+  :returns: Number of bytes read.
+  :retval > 0: Size of bytes read.
+  :retval < 0: Error.
+
+.. c:function:: ssize_t write(FAR struct file *filep, FAR const char *buffer, size_t buflen)
+  
+  Writes maximum ``buflen`` bytes to an opened file (from the current offset
+  the opened file is at if the file system supports seeking).
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :param FAR char * buffer: Buffer which contains the data to be written.
+  :param size_t buflen: Length of the maximum number of bytes to be written.
+  :returns: Number of bytes written.
+  :retval > 0: Size of bytes written.
+  :retval < ``buflen``: Insufficient storage or file size limit reached
+  :retval < 0: Error.
+
+.. NOTE::
+  POSIX requires that a ``read()`` after a ``write()`` should get the newly
+  written data, but not all file systems confirm to POSIX, especially as
+  POSIX requires atomic writes, which is not usually not implemented
+  as it can impact performance.
+
+  To be POSIX compliant in concurrent situations, either the writes have to
+  be atomic, or read is blocked with a lock till an on-going write is
+  finished, which, as stated, would impact performance.
+
+.. c:function:: off_t seek(FAR struct file *filep, off_t offset, int whence)
+
+  Underlying implementation of ``lseek()``, it allows the open file's file
+  structure to point to any particular location in the file.
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :param off_t offset: The offset required.
+  :param int whence: This controls how the offset it applied. It can have
+    values (defined in ``/include/sys/types.h``):
+    
+    * SEEK_SET: Offset from start of file.
+    * SEEK_CUR: Offset from current location in file.
+    * SEEK_END: Offset *after* end of file.
+
+.. NOTE::
+
+  According to POSIX, lseek to any point after the end of the file *does not*

Review Comment:
   ```suggestion
     According to POSIX, ``lseek`` to any point after the end of the file *does not*



##########
Documentation/components/filesystem/index.rst:
##########
@@ -41,6 +41,493 @@ pseudo file systems may be mounted in the true, root file system.
 The approach selected by NuttX is intended to support greater
 scalability from the very tiny platform to the moderate platform.
 
+Virtual File System (VFS)
+=========================
+
+Virtual File System provides a unified interface for various file systems to
+be able to co-exist together by exposing a blueprint that each file system
+needs to implement. This also allows the file system to be free from worry
+about the device driver implementations for storage devices, as they also
+expose a unified way of accessing the underlying devices.
+
+How VFS works
+-------------
+
+Threads are controllable sequences of instruction execution with their own
+stacks. Each task in NuttX is represented by a Task Control Block (TCB) (TCB
+is defined in ``include/nuttx/sched.h``) and tasks are organized in task
+lists.
+
+All threads that are created by ``pthread_create()`` are part of the same task
+group. A task group (defined in ``include/nuttx/sched.h``) is a shared
+structure pointed to by the TCBs of all the threads that belong to the same
+task group, and this task group contains all the resources shared across the
+task group which includes *file descriptors* in the form of a **file list**.
+
+A file list (defined in ``include/nuttx/fs/fs.h``) contains file structures
+that denote open files (along with a spinlock to manage access to the file
+list). With the devices listed in the :ref:`root file system <root_fs>` (on
+points like ``/dev/led``, ``/dev/mmcsd0``, etc. which are henceforth called
+blockdriver mount points) in an unmounted state, storage devices can be
+mounted using the ``mount()`` command (to any point like ``/dir/abcd``) with
+any specific supported file system, which internally calls its implemented
+``mountpt_operations->bind()`` method and passes the blockdriver's mount
+point inode to it, thus creating a **mount point**. The blockdriver mount
+point inode will have a ``mountpt->i_private`` which contains any (file system
+dependent) information about the mount and is to be filled by the file system
+during the execution of ``mountpt_operations->bind()`` (and usually this data
+includes a pointer to the blockdriver mount point as well). After that,
+according to system calls, the other exposed functions of the filesystem
+are called as per need.
+
+VFS Interface
+-------------
+
+VFS allows file systems to expose their own implementations of methods
+belonging to a unified interface:
+
+* **File operations**
+
+.. c:function:: int open(FAR struct file *filep, FAR const char *relpath, int oflags, mode_t mode)
+  
+  Opens a file. Files are required to be opened before any other file
+  operations are performed on it.
+
+  :param FAR struct file * filep: Open file's file structure pointer. The
+    ``filep->f_priv`` member needs to be set here with the file system
+    specific data that represents an open file.
+  :param FAR const char * relpath: Relative path of the file from the root of
+    the mounted file system.
+  :param int oflags: Flags in a bit field that specify the mode for openning
+    the file (eg. ``O_RDONLY``, ``O_RDWR``, etc. defined in
+    ``include/fcntl.h``).
+  :param mode_t mode: Specifies the mode (permissions). If ``oflags`` include
+    ``O_CREAT``, then this contains the mode for the file to be created.
+  :returns: Status of openning a file.
+  :retval OK (0): Success.
+  :retval < 0: Error.
+
+.. c:function:: int close(FAR struct file *filep)
+
+  This closes the opened file, and ideally syncs all the changes to the file
+  to be written to the disk, as well as free the memory allocated to store the
+  open file's data.
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :returns: Status of closing a file.
+  :retval OK (0): Success.
+  :retval < 0: Error.
+
+.. c:function:: ssize_t read(FAR struct file *filep, FAR char *buffer, size_t buflen)
+  
+  Reads maximum ``buflen`` bytes from an opened file (from the current offset
+  the opened file descriptor is pointing at if the file system supports
+  seeking).
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :param FAR char * buffer: Buffer to store the read data.
+  :param size_t buflen: Length of the maximum number of bytes to be read.
+  :returns: Number of bytes read.
+  :retval > 0: Size of bytes read.
+  :retval < 0: Error.
+
+.. c:function:: ssize_t write(FAR struct file *filep, FAR const char *buffer, size_t buflen)
+  
+  Writes maximum ``buflen`` bytes to an opened file (from the current offset
+  the opened file is at if the file system supports seeking).
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :param FAR char * buffer: Buffer which contains the data to be written.
+  :param size_t buflen: Length of the maximum number of bytes to be written.
+  :returns: Number of bytes written.
+  :retval > 0: Size of bytes written.
+  :retval < ``buflen``: Insufficient storage or file size limit reached
+  :retval < 0: Error.
+
+.. NOTE::
+  POSIX requires that a ``read()`` after a ``write()`` should get the newly
+  written data, but not all file systems confirm to POSIX, especially as
+  POSIX requires atomic writes, which is not usually not implemented
+  as it can impact performance.
+
+  To be POSIX compliant in concurrent situations, either the writes have to
+  be atomic, or read is blocked with a lock till an on-going write is
+  finished, which, as stated, would impact performance.
+
+.. c:function:: off_t seek(FAR struct file *filep, off_t offset, int whence)
+
+  Underlying implementation of ``lseek()``, it allows the open file's file
+  structure to point to any particular location in the file.
+
+  :param FAR struct file * filep: Open file's file structure pointer.
+  :param off_t offset: The offset required.
+  :param int whence: This controls how the offset it applied. It can have
+    values (defined in ``/include/sys/types.h``):
+    
+    * SEEK_SET: Offset from start of file.
+    * SEEK_CUR: Offset from current location in file.
+    * SEEK_END: Offset *after* end of file.
+
+.. NOTE::
+
+  According to POSIX, lseek to any point after the end of the file *does not*
+  by itself increase the size of the file. Later writes to this part will,
+  however, increase it to atleast the end of the written data, and the "gap"

Review Comment:
   ```suggestion
     however, increase it to at least the end of the written data, and the "gap"



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org