This is an automated email from the ASF dual-hosted git repository.

xiaoxiang781216 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git

commit f3fa69b6ece39bb3832f56a736c55ed0ab3d299a
Author: p-szafonimateusz <[email protected]>
AuthorDate: Mon Aug 24 15:15:55 2026 +0200

    fs/vfs: Add notify callback and notify_event injection API
    
    Let a file system participate in inotify: the notify method is called
    once per watched path (NOTIFY_WATCH_ADD returns a file system watch
    handle, NOTIFY_WATCH_RM passes it back) so the backing store can
    start/stop reporting changes, and notify_event() injects the reported
    events into the local queue.  While a path has a file system watch,
    locally generated events on it are suppressed so each operation is
    reported once.  No file system uses the callback yet.
    
    Signed-off-by: p-szafonimateusz <[email protected]>
    Signed-off-by: jingfei <[email protected]>
---
 Documentation/os/filesystem/inotify.rst |  18 +++
 Documentation/os/filesystem/nfs.rst     |   6 +
 fs/vfs/fs_inotify.c                     | 236 +++++++++++++++++++++++++++++++-
 include/nuttx/fs/fs.h                   |  40 ++++++
 4 files changed, 293 insertions(+), 7 deletions(-)

diff --git a/Documentation/os/filesystem/inotify.rst 
b/Documentation/os/filesystem/inotify.rst
index cab61b4a881..b6e3a6bf613 100644
--- a/Documentation/os/filesystem/inotify.rst
+++ b/Documentation/os/filesystem/inotify.rst
@@ -135,3 +135,21 @@ NOTE
 Inotify file descriptors can be monitored using select, poll, and
 epoll.  When an event is available, the file descriptor indicates as
 readable.
+
+File system participation
+-------------------------
+
+Events are generated by the VFS, so only local operations are
+reported.  A file system whose backing store can change elsewhere
+(e.g. ``rpmsgfs``) may implement the optional ``notify`` method of
+``struct mountpt_operations``: ``NOTIFY_WATCH_ADD`` is called when the
+first watch is created on a path and returns a file system watch
+handle; ``NOTIFY_WATCH_RM`` receives that handle back when the last
+watch is removed.  The file system injects the changes reported by its
+backing store with:
+
+.. c:function:: void notify_event(FAR struct inode *mountpt, FAR const char 
*relpath, uint32_t mask)
+
+While a path has a file system watch handle, locally generated events
+on it are suppressed: all events for that path come from the file
+system, so each operation is reported once.
diff --git a/Documentation/os/filesystem/nfs.rst 
b/Documentation/os/filesystem/nfs.rst
index d883c323b18..199bd1d50c3 100644
--- a/Documentation/os/filesystem/nfs.rst
+++ b/Documentation/os/filesystem/nfs.rst
@@ -3,3 +3,9 @@ NFS
 ===
 
 Network file system (NFS) client file system.
+
+Limitations
+===========
+
+Advisory locks are local to this NuttX instance (no NLM/NFSv4
+locking) and inotify watches report only locally initiated changes.
diff --git a/fs/vfs/fs_inotify.c b/fs/vfs/fs_inotify.c
index 2c2a01a0bfd..bb2a38f41fe 100644
--- a/fs/vfs/fs_inotify.c
+++ b/fs/vfs/fs_inotify.c
@@ -51,6 +51,21 @@
 #define INOTIFY_CLASSES (IN_ALL_EVENTS | IN_UNMOUNT)
 #define INOTIFY_NCLASS  14
 
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+/* A list with a file system watch handle receives its events from the
+ * file system through notify_event(); locally generated events are
+ * suppressed on it to avoid duplicates.
+ */
+
+#ifndef CONFIG_DISABLE_MOUNTPOINT
+#  define NOTIFY_IS_REMOTE(list) ((list)->mwd >= 0)
+#else
+#  define NOTIFY_IS_REMOTE(list) false
+#endif
+
 /****************************************************************************
  * Private Types
  ****************************************************************************/
@@ -77,6 +92,9 @@ struct inotify_watch_list_s
 {
   struct list_node watches;
   FAR char        *path;
+#ifndef CONFIG_DISABLE_MOUNTPOINT
+  int              mwd;      /* File system watch handle, -1 if none */
+#endif
 };
 
 struct inotify_watch_s
@@ -113,6 +131,10 @@ static int     inotify_poll(FAR struct file *filep, FAR 
struct pollfd_s *fds,
                             bool setup);
 static int     inotify_ioctl(FAR struct file *filep, int cmd,
                              unsigned long arg);
+#ifndef CONFIG_DISABLE_MOUNTPOINT
+static FAR struct inotify_watch_list_s *
+               inotify_get_watch_list(FAR const char *path);
+#endif
 
 /****************************************************************************
  * Private Data
@@ -335,6 +357,125 @@ static void inotify_queue_event(FAR struct 
inotify_device_s *dev, int wd,
     }
 }
 
+/****************************************************************************
+ * Name: inotify_notify_fs
+ *
+ * Description:
+ *   Look up the file system backing path and invoke its notify method.
+ *   Returns the method result, or -ENODEV when path is not on a
+ *   mountpoint with a notify method.
+ *
+ ****************************************************************************/
+
+#ifndef CONFIG_DISABLE_MOUNTPOINT
+static int inotify_notify_fs(FAR const char *path, int action, int wd,
+                             uint32_t mask)
+{
+  struct inode_search_s desc;
+  FAR struct inode *inode;
+  int ret;
+
+  ret = inode_search_setup(&desc, path, false);
+  if (ret < 0)
+    {
+      return ret;
+    }
+
+  ret = -ENODEV;
+  if (inode_find(&desc, &inode) >= 0)
+    {
+      if (INODE_IS_MOUNTPT(inode) && inode->u.i_mops->notify != NULL)
+        {
+          ret = inode->u.i_mops->notify(inode, wd, desc.relpath != NULL ?
+                                        desc.relpath : "", action, mask);
+        }
+
+      inode_release(inode);
+    }
+
+  inode_search_release(&desc);
+  return ret;
+}
+
+/****************************************************************************
+ * Name: inotify_update_watch
+ *
+ * Description:
+ *   Add or remove the file system watch that backs abspath.  Must be
+ *   called WITHOUT the inotify locks: the file system method may wait
+ *   on a local server whose own file operations take them.
+ *
+ *   For NOTIFY_WATCH_ADD the file system is (re)told the union of all
+ *   watch masks on the path so a later broader watch widens the file
+ *   system watch; the file system returns the same handle for a path it
+ *   already watches (see the notify method contract).  The list is
+ *   revalidated before the handle is stored; if the watch disappeared
+ *   meanwhile the file system watch is removed again.
+ *
+ ****************************************************************************/
+
+static void inotify_update_watch(FAR struct inotify_watch_list_s *list,
+                                 FAR const char *abspath, int action)
+{
+  FAR struct inotify_watch_s *watch;
+  uint32_t mask = 0;
+  bool present;
+  int wd;
+
+  if (action == NOTIFY_WATCH_RM)
+    {
+      if (list->mwd >= 0)
+        {
+          inotify_notify_fs(abspath, NOTIFY_WATCH_RM, list->mwd, 0);
+        }
+
+      return;
+    }
+
+  /* Compute the union of the watch masks (the list may have gone away) */
+
+  nxmutex_lock(&g_inotify.lock);
+  present = inotify_get_watch_list(abspath) == list;
+  if (present)
+    {
+      list_for_every_entry(&list->watches, watch, struct inotify_watch_s,
+                           l_node)
+        {
+          mask |= watch->mask;
+        }
+    }
+
+  nxmutex_unlock(&g_inotify.lock);
+  if (!present || mask == 0)
+    {
+      return;
+    }
+
+  wd = inotify_notify_fs(abspath, NOTIFY_WATCH_ADD, -1, mask);
+  if (wd < 0)
+    {
+      return;
+    }
+
+  /* Store the handle if the watch list still exists; undo otherwise */
+
+  nxmutex_lock(&g_inotify.lock);
+  present = inotify_get_watch_list(abspath) == list;
+  if (present)
+    {
+      list->mwd = wd;
+    }
+
+  nxmutex_unlock(&g_inotify.lock);
+  if (!present)
+    {
+      inotify_notify_fs(abspath, NOTIFY_WATCH_RM, wd, 0);
+    }
+}
+#else
+#  define inotify_update_watch(list, abspath, action)
+#endif
+
 /****************************************************************************
  * Name: inotify_remove_watch_no_event
  *
@@ -357,6 +498,7 @@ inotify_remove_watch_no_event(FAR struct inotify_watch_s 
*watch)
     {
       ENTRY item;
 
+      inotify_update_watch(list, list->path, NOTIFY_WATCH_RM);
       item.key = list->path;
       hsearch_r(item, DELETE, NULL, &g_inotify.hash);
     }
@@ -794,6 +936,9 @@ inotify_alloc_watch_list(FAR const char *path)
     }
 
   list_initialize(&list->watches);
+#ifndef CONFIG_DISABLE_MOUNTPOINT
+  list->mwd = -1;
+#endif
   list->path = fs_heap_strdup(path);
   if (list->path == NULL)
     {
@@ -893,7 +1038,7 @@ inotify_queue_watch_list_event(FAR struct 
inotify_watch_list_s *list,
  ****************************************************************************/
 
 static void inotify_queue_parent_event(FAR char *path, uint32_t mask,
-                                       uint32_t cookie)
+                                       uint32_t cookie, bool remote)
 {
   FAR struct inotify_watch_list_s *list;
   FAR char *name;
@@ -906,21 +1051,23 @@ static void inotify_queue_parent_event(FAR char *path, 
uint32_t mask,
 
   *(name - 1) = '\0';
   list = inotify_get_watch_list(path);
-  if (list != NULL)
+  if (list != NULL && (remote || !NOTIFY_IS_REMOTE(list)))
     {
       inotify_queue_watch_list_event(list, mask | IN_ISDIR, cookie, name);
     }
 }
 
 /****************************************************************************
- * Name: notify_queue_path_event
+ * Name: notify_queue_path_event2
  *
  * Description:
- *   Send the notification by the path.
+ *   Send the notification by the path.  remote marks an event injected
+ *   by the file system through notify_event().
  *
  ****************************************************************************/
 
-static void notify_queue_path_event(FAR const char *path, uint32_t mask)
+static void notify_queue_path_event2(FAR const char *path, uint32_t mask,
+                                     bool remote)
 {
   FAR struct inotify_watch_list_s *list;
   FAR char *abspath;
@@ -960,9 +1107,9 @@ static void notify_queue_path_event(FAR const char *path, 
uint32_t mask)
     }
 
   list = inotify_get_watch_list(abspath);
-  inotify_queue_parent_event(abspath, mask, cookie);
+  inotify_queue_parent_event(abspath, mask, cookie, remote);
   lib_put_pathbuffer(pathbuffer);
-  if (list == NULL)
+  if (list == NULL || (!remote && NOTIFY_IS_REMOTE(list)))
     {
       return;
     }
@@ -990,6 +1137,19 @@ static void notify_queue_path_event(FAR const char *path, 
uint32_t mask)
     }
 }
 
+/****************************************************************************
+ * Name: notify_queue_path_event
+ *
+ * Description:
+ *   Send the notification for a locally generated event.
+ *
+ ****************************************************************************/
+
+static void notify_queue_path_event(FAR const char *path, uint32_t mask)
+{
+  notify_queue_path_event2(path, mask, false);
+}
+
 /****************************************************************************
  * Name: notify_check_inode
  *
@@ -1222,6 +1382,15 @@ out:
   nxmutex_unlock(&dev->lock);
   nxmutex_unlock(&g_inotify.lock);
 
+  /* Establish the file system watch (idempotent) without the locks
+   * held (see inotify_update_watch).
+   */
+
+  if (ret >= 0)
+    {
+      inotify_update_watch(list, abspath, NOTIFY_WATCH_ADD);
+    }
+
 out_free:
   file_put(filep);
   lib_put_tempbuffer(tmpbuffer);
@@ -1584,3 +1753,56 @@ void notify_rename(FAR const char *oldpath, bool 
oldisdir,
   notify_queue_path_event(newpath, newmask);
   nxmutex_unlock(&g_inotify.lock);
 }
+
+/****************************************************************************
+ * Name: notify_event
+ *
+ * Description:
+ *   Inject a file change notification that originated outside the local
+ *   VFS.  Must be called from thread context.
+ *
+ ****************************************************************************/
+
+void notify_event(FAR struct inode *mountpt, FAR const char *relpath,
+                  uint32_t mask)
+{
+  FAR char *pathbuffer;
+
+  if (relpath == NULL)
+    {
+      return;
+    }
+
+  pathbuffer = lib_get_pathbuffer();
+  if (pathbuffer == NULL)
+    {
+      return;
+    }
+
+  if (mountpt != NULL)
+    {
+      if (inode_getpath(mountpt, pathbuffer, PATH_MAX) < 0)
+        {
+          lib_put_pathbuffer(pathbuffer);
+          return;
+        }
+
+      /* inode_getpath() terminates a mountpoint path with '/' */
+
+      while (*relpath == '/')
+        {
+          relpath++;
+        }
+
+      strlcat(pathbuffer, relpath, PATH_MAX);
+    }
+  else
+    {
+      strlcpy(pathbuffer, relpath, PATH_MAX);
+    }
+
+  nxmutex_lock(&g_inotify.lock);
+  notify_queue_path_event2(pathbuffer, mask, true);
+  nxmutex_unlock(&g_inotify.lock);
+  lib_put_pathbuffer(pathbuffer);
+}
diff --git a/include/nuttx/fs/fs.h b/include/nuttx/fs/fs.h
index 55ea1902b59..7c00d86dbe7 100644
--- a/include/nuttx/fs/fs.h
+++ b/include/nuttx/fs/fs.h
@@ -182,6 +182,11 @@
 #define CH_STAT_SIZE       (1 << 7)
 #define CH_STAT_NOFOLLOW   (1 << 8)  /* Do not follow a final symbolic link */
 
+/* Actions passed to the notify method of struct mountpt_operations */
+
+#define NOTIFY_WATCH_ADD   0  /* First watch created on a path */
+#define NOTIFY_WATCH_RM    1  /* Last watch on a path removed  */
+
 /****************************************************************************
  * Public Type Definitions
  ****************************************************************************/
@@ -424,6 +429,22 @@ struct mountpt_operations
                         FAR const char *relpath,
                         FAR struct stat *buf);
 #endif
+
+#ifdef CONFIG_FS_NOTIFY
+  /* Optional method, appended at the end so that the leading block
+   * stays union-compatible with struct file_operations.
+   * NOTIFY_WATCH_ADD returns a file system watch handle (or a negated
+   * errno) for the path; NOTIFY_WATCH_RM receives that handle back in
+   * wd.  Called whenever a watch on the path is added or removed, so
+   * the implementation must ignore a repeated add for a path it is
+   * already watching.  May block; called from inotify contexts, so it
+   * must not call back into the inotify engine synchronously.
+   */
+
+  CODE int     (*notify)(FAR struct inode *mountpt, int wd,
+                         FAR const char *relpath,
+                         int action, uint32_t mask);
+#endif
 };
 #endif /* CONFIG_DISABLE_MOUNTPOINT */
 
@@ -892,6 +913,25 @@ int nx_mount(FAR const char *source, FAR const char 
*target,
 int nx_umount2(FAR const char *target, unsigned int flags);
 #endif
 
+/****************************************************************************
+ * Name: notify_event
+ *
+ * Description:
+ *   Inject a file change notification that originated outside the local
+ *   VFS.  Must be called from thread context.
+ *
+ * Input Parameters:
+ *   mountpt - Mountpoint inode, or NULL if relpath is absolute
+ *   relpath - Path of the affected object relative to the mountpoint
+ *   mask    - inotify event mask
+ *
+ ****************************************************************************/
+
+#ifdef CONFIG_FS_NOTIFY
+void notify_event(FAR struct inode *mountpt, FAR const char *relpath,
+                  uint32_t mask);
+#endif
+
 /****************************************************************************
  * Name: fdlist_init
  *

Reply via email to