Message-Id: <20190318231437.1666-10-tobin@kernel.org>
Date:   Tue, 19 Mar 2019 10:14:33 +1100
From:   "Tobin C. Harding" <tobin@...nel.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     "Tobin C. Harding" <tobin@...nel.org>,
        Randy Dunlap <rdunlap@...radead.org>,
        linux-doc@...r.kernel.org, linux-fsdevel@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: [PATCH v2 09/13] docs: filesystems: vfs: Add code-block and txt->RST

Use code-block for C source code.  With this in place we can rename the
.txt file to  .rst.  This introduces a few warnings that will be fixed
in proceeding patches.

Add '.. code-block:: c' to C source code snippets.  Rename the file to
use rst file suffix.

Tested-by: Randy Dunlap <rdunlap@...radead.org>
Signed-off-by: Tobin C. Harding <tobin@...nel.org>
---

This ones a punish to review.  It fixes up spacing around the struct
definitions.  In hindsight this may not be what we want because now the
docs do not _exactly_ mirror the code.  If this goes through update to
vfs.rst aims to patch the code first then update vfs.rst :)

 Documentation/filesystems/index.rst           |   1 +
 .../filesystems/{vfs.txt => vfs.rst}          | 321 +++++++++---------
 2 files changed, 169 insertions(+), 153 deletions(-)
 rename Documentation/filesystems/{vfs.txt => vfs.rst} (86%)

diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d77f6..35644840a690 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -16,6 +16,7 @@ algorithms work.
 .. toctree::
    :maxdepth: 2
 
+   vfs
    path-lookup.rst
    api-summary
    splice
diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.rst
similarity index 86%
rename from Documentation/filesystems/vfs.txt
rename to Documentation/filesystems/vfs.rst
index 6e709815a6dd..dc2dd81f5e83 100644
--- a/Documentation/filesystems/vfs.txt
+++ b/Documentation/filesystems/vfs.rst
@@ -87,6 +87,8 @@ Registering and Mounting a Filesystem
 To register and unregister a filesystem, use the following API
 functions:
 
+.. code-block:: c
+
    #include <linux/fs.h>
 
    extern int register_filesystem(struct file_system_type *);
@@ -110,18 +112,19 @@ struct file_system_type
 This describes the filesystem.  As of kernel 2.6.39, the following
 members are defined:
 
-struct file_system_type {
-	const char *name;
-	int fs_flags;
-        struct dentry *(*mount) (struct file_system_type *, int,
-                       const char *, void *);
-        void (*kill_sb) (struct super_block *);
-        struct module *owner;
-        struct file_system_type * next;
-        struct list_head fs_supers;
-	struct lock_class_key s_lock_key;
-	struct lock_class_key s_umount_key;
-};
+.. code-block:: c
+
+   struct file_system_type {
+	   const char *name;
+	   int fs_flags;
+	   struct dentry *(*mount) (struct file_system_type *, int, const char *, void *);
+	   void (*kill_sb) (struct super_block *);
+	   struct module *owner;
+	   struct file_system_type * next;
+	   struct list_head fs_supers;
+	   struct lock_class_key s_lock_key;
+	   struct lock_class_key s_umount_key;
+   };
 
 - name: the name of the filesystem type, such as "ext2", "iso9660",
 	"msdos" and so on
@@ -206,30 +209,31 @@ struct super_operations
 This describes how the VFS can manipulate the superblock of your
 filesystem.  As of kernel 2.6.22, the following members are defined:
 
-struct super_operations {
-        struct inode *(*alloc_inode)(struct super_block *sb);
-        void (*destroy_inode)(struct inode *);
-
-        void (*dirty_inode) (struct inode *, int flags);
-        int (*write_inode) (struct inode *, int);
-        void (*drop_inode) (struct inode *);
-        void (*delete_inode) (struct inode *);
-        void (*put_super) (struct super_block *);
-        int (*sync_fs)(struct super_block *sb, int wait);
-        int (*freeze_fs) (struct super_block *);
-        int (*unfreeze_fs) (struct super_block *);
-        int (*statfs) (struct dentry *, struct kstatfs *);
-        int (*remount_fs) (struct super_block *, int *, char *);
-        void (*clear_inode) (struct inode *);
-        void (*umount_begin) (struct super_block *);
-
-        int (*show_options)(struct seq_file *, struct dentry *);
-
-        ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
-        ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
-	int (*nr_cached_objects)(struct super_block *);
-	void (*free_cached_objects)(struct super_block *, int);
-};
+.. code-block:: c
+
+   struct super_operations {
+	   struct inode *(*alloc_inode)(struct super_block *sb);
+	   void (*destroy_inode)(struct inode *);
+	   void (*dirty_inode) (struct inode *, int flags);
+	   int (*write_inode) (struct inode *, int);
+	   void (*drop_inode) (struct inode *);
+	   void (*delete_inode) (struct inode *);
+	   void (*put_super) (struct super_block *);
+	   int (*sync_fs)(struct super_block *sb, int wait);
+	   int (*freeze_fs) (struct super_block *);
+	   int (*unfreeze_fs) (struct super_block *);
+	   int (*statfs) (struct dentry *, struct kstatfs *);
+	   int (*remount_fs) (struct super_block *, int *, char *);
+	   void (*clear_inode) (struct inode *);
+	   void (*umount_begin) (struct super_block *);
+
+	   int (*show_options)(struct seq_file *, struct dentry *);
+
+	   ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
+	   ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
+	   int (*nr_cached_objects)(struct super_block *);
+	   void (*free_cached_objects)(struct super_block *, int);
+   };
 
 All methods are called without any locks being held, unless otherwise
 noted.  This means that most methods can block safely.  All methods are
@@ -365,30 +369,32 @@ struct inode_operations
 This describes how the VFS can manipulate an inode in your filesystem.
 As of kernel 2.6.22, the following members are defined:
 
-struct inode_operations {
-	int (*create) (struct inode *,struct dentry *, umode_t, bool);
-	struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
-	int (*link) (struct dentry *,struct inode *,struct dentry *);
-	int (*unlink) (struct inode *,struct dentry *);
-	int (*symlink) (struct inode *,struct dentry *,const char *);
-	int (*mkdir) (struct inode *,struct dentry *,umode_t);
-	int (*rmdir) (struct inode *,struct dentry *);
-	int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t);
-	int (*rename) (struct inode *, struct dentry *,
-			struct inode *, struct dentry *, unsigned int);
-	int (*readlink) (struct dentry *, char __user *,int);
-	const char *(*get_link) (struct dentry *, struct inode *,
-				 struct delayed_call *);
-	int (*permission) (struct inode *, int);
-	int (*get_acl)(struct inode *, int);
-	int (*setattr) (struct dentry *, struct iattr *);
-	int (*getattr) (const struct path *, struct kstat *, u32, unsigned int);
-	ssize_t (*listxattr) (struct dentry *, char *, size_t);
-	void (*update_time)(struct inode *, struct timespec *, int);
-	int (*atomic_open)(struct inode *, struct dentry *, struct file *,
-			unsigned open_flag, umode_t create_mode);
-	int (*tmpfile) (struct inode *, struct dentry *, umode_t);
-};
+.. code-block:: c
+
+   struct inode_operations {
+	   int (*create) (struct inode *,struct dentry *, umode_t, bool);
+	   struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
+	   int (*link) (struct dentry *,struct inode *,struct dentry *);
+	   int (*unlink) (struct inode *,struct dentry *);
+	   int (*symlink) (struct inode *,struct dentry *,const char *);
+	   int (*mkdir) (struct inode *,struct dentry *,umode_t);
+	   int (*rmdir) (struct inode *,struct dentry *);
+	   int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t);
+	   int (*rename) (struct inode *, struct dentry *,
+			  struct inode *, struct dentry *, unsigned int);
+	   int (*readlink) (struct dentry *, char __user *,int);
+	   const char *(*get_link) (struct dentry *, struct inode *,
+				    struct delayed_call *);
+	   int (*permission) (struct inode *, int);
+	   int (*get_acl)(struct inode *, int);
+	   int (*setattr) (struct dentry *, struct iattr *);
+	   int (*getattr) (const struct path *, struct kstat *, u32, unsigned int);
+	   ssize_t (*listxattr) (struct dentry *, char *, size_t);
+	   void (*update_time)(struct inode *, struct timespec *, int);
+	   int (*atomic_open)(struct inode *, struct dentry *, struct file *,
+			      unsigned open_flag, umode_t create_mode);
+	   int (*tmpfile) (struct inode *, struct dentry *, umode_t);
+   };
 
 Again, all methods are called without any locks being held, unless
 otherwise noted.
@@ -624,39 +630,41 @@ struct address_space_operations
 This describes how the VFS can manipulate mapping of a file to page
 cache in your filesystem.  The following members are defined:
 
-struct address_space_operations {
-	int (*writepage)(struct page *page, struct writeback_control *wbc);
-	int (*readpage)(struct file *, struct page *);
-	int (*writepages)(struct address_space *, struct writeback_control *);
-	int (*set_page_dirty)(struct page *page);
-	int (*readpages)(struct file *filp, struct address_space *mapping,
-			struct list_head *pages, unsigned nr_pages);
-	int (*write_begin)(struct file *, struct address_space *mapping,
-				loff_t pos, unsigned len, unsigned flags,
-				struct page **pagep, void **fsdata);
-	int (*write_end)(struct file *, struct address_space *mapping,
-				loff_t pos, unsigned len, unsigned copied,
-				struct page *page, void *fsdata);
-	sector_t (*bmap)(struct address_space *, sector_t);
-	void (*invalidatepage) (struct page *, unsigned int, unsigned int);
-	int (*releasepage) (struct page *, int);
-	void (*freepage)(struct page *);
-	ssize_t (*direct_IO)(struct kiocb *, struct iov_iter *iter);
-	/* isolate a page for migration */
-	bool (*isolate_page) (struct page *, isolate_mode_t);
-	/* migrate the contents of a page to the specified target */
-	int (*migratepage) (struct page *, struct page *);
-	/* put migration-failed page back to right list */
-	void (*putback_page) (struct page *);
-	int (*launder_page) (struct page *);
-
-	int (*is_partially_uptodate) (struct page *, unsigned long,
-					unsigned long);
-	void (*is_dirty_writeback) (struct page *, bool *, bool *);
-	int (*error_remove_page) (struct mapping *mapping, struct page *page);
-	int (*swap_activate)(struct file *);
-	int (*swap_deactivate)(struct file *);
-};
+.. code-block:: c
+
+   struct address_space_operations {
+	   int (*writepage)(struct page *page, struct writeback_control *wbc);
+	   int (*readpage)(struct file *, struct page *);
+	   int (*writepages)(struct address_space *, struct writeback_control *);
+	   int (*set_page_dirty)(struct page *page);
+	   int (*readpages)(struct file *filp, struct address_space *mapping,
+			    struct list_head *pages, unsigned nr_pages);
+	   int (*write_begin)(struct file *, struct address_space *mapping,
+			      loff_t pos, unsigned len, unsigned flags,
+			      struct page **pagep, void **fsdata);
+	   int (*write_end)(struct file *, struct address_space *mapping,
+			    loff_t pos, unsigned len, unsigned copied,
+			    struct page *page, void *fsdata);
+	   sector_t (*bmap)(struct address_space *, sector_t);
+	   void (*invalidatepage) (struct page *, unsigned int, unsigned int);
+	   int (*releasepage) (struct page *, int);
+	   void (*freepage)(struct page *);
+	   ssize_t (*direct_IO)(struct kiocb *, struct iov_iter *iter);
+	   /* isolate a page for migration */
+	   bool (*isolate_page) (struct page *, isolate_mode_t);
+	   /* migrate the contents of a page to the specified target */
+	   int (*migratepage) (struct page *, struct page *);
+	   /* put migration-failed page back to right list */
+	   void (*putback_page) (struct page *);
+	   int (*launder_page) (struct page *);
+
+	   int (*is_partially_uptodate) (struct page *, unsigned long,
+					 unsigned long);
+	   void (*is_dirty_writeback) (struct page *, bool *, bool *);
+	   int (*error_remove_page) (struct mapping *mapping, struct page *page);
+	   int (*swap_activate)(struct file *);
+	   int (*swap_deactivate)(struct file *);
+   };
 
 - writepage: called by the VM to write a dirty page to backing store.
       This may happen for data integrity reasons (i.e. 'sync'), or
@@ -852,45 +860,50 @@ struct file_operations
 This describes how the VFS can manipulate an open file.  As of kernel
 4.18, the following members are defined:
 
-struct file_operations {
-	struct module *owner;
-	loff_t (*llseek) (struct file *, loff_t, int);
-	ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
-	ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
-	ssize_t (*read_iter) (struct kiocb *, struct iov_iter *);
-	ssize_t (*write_iter) (struct kiocb *, struct iov_iter *);
-	int (*iopoll)(struct kiocb *kiocb, bool spin);
-	int (*iterate) (struct file *, struct dir_context *);
-	int (*iterate_shared) (struct file *, struct dir_context *);
-	__poll_t (*poll) (struct file *, struct poll_table_struct *);
-	long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
-	long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
-	int (*mmap) (struct file *, struct vm_area_struct *);
-	int (*open) (struct inode *, struct file *);
-	int (*flush) (struct file *, fl_owner_t id);
-	int (*release) (struct inode *, struct file *);
-	int (*fsync) (struct file *, loff_t, loff_t, int datasync);
-	int (*fasync) (int, struct file *, int);
-	int (*lock) (struct file *, int, struct file_lock *);
-	ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int);
-	unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned long, unsigned long, unsigned long);
-	int (*check_flags)(int);
-	int (*flock) (struct file *, int, struct file_lock *);
-	ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *, size_t, unsigned int);
-	ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *, size_t, unsigned int);
-	int (*setlease)(struct file *, long, struct file_lock **, void **);
-	long (*fallocate)(struct file *file, int mode, loff_t offset,
-			  loff_t len);
-	void (*show_fdinfo)(struct seq_file *m, struct file *f);
-#ifndef CONFIG_MMU
-	unsigned (*mmap_capabilities)(struct file *);
-#endif
-	ssize_t (*copy_file_range)(struct file *, loff_t, struct file *, loff_t, size_t, unsigned int);
-	loff_t (*remap_file_range)(struct file *file_in, loff_t pos_in,
-				   struct file *file_out, loff_t pos_out,
-				   loff_t len, unsigned int remap_flags);
-	int (*fadvise)(struct file *, loff_t, loff_t, int);
-};
+.. code-block:: c
+
+   struct file_operations {
+	   struct module *owner;
+	   loff_t (*llseek) (struct file *, loff_t, int);
+	   ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
+	   ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
+	   ssize_t (*read_iter) (struct kiocb *, struct iov_iter *);
+	   ssize_t (*write_iter) (struct kiocb *, struct iov_iter *);
+	   int (*iopoll)(struct kiocb *kiocb, bool spin);
+	   int (*iterate) (struct file *, struct dir_context *);
+	   int (*iterate_shared) (struct file *, struct dir_context *);
+	   __poll_t (*poll) (struct file *, struct poll_table_struct *);
+	   long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
+	   long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
+	   int (*mmap) (struct file *, struct vm_area_struct *);
+	   int (*open) (struct inode *, struct file *);
+	   int (*flush) (struct file *, fl_owner_t id);
+	   int (*release) (struct inode *, struct file *);
+	   int (*fsync) (struct file *, loff_t, loff_t, int datasync);
+	   int (*fasync) (int, struct file *, int);
+	   int (*lock) (struct file *, int, struct file_lock *);
+	   ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int);
+	   unsigned long (*get_unmapped_area)(struct file *, unsigned long,
+					      unsigned long, unsigned long, unsigned long);
+	   int (*check_flags)(int);
+	   int (*flock) (struct file *, int, struct file_lock *);
+	   ssize_t (*splice_write)(struct pipe_inode_info *, struct file *,
+				   loff_t *, size_t, unsigned int);
+	   ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *,
+				  size_t, unsigned int);
+	   int (*setlease)(struct file *, long, struct file_lock **, void **);
+	   long (*fallocate)(struct file *file, int mode, loff_t offset, loff_t len);
+	   void (*show_fdinfo)(struct seq_file *m, struct file *f);
+   #ifndef CONFIG_MMU
+	   unsigned (*mmap_capabilities)(struct file *);
+   #endif
+	   ssize_t (*copy_file_range)(struct file *, loff_t, struct file *, loff_t,
+				      size_t, unsigned int);
+	   loff_t (*remap_file_range)(struct file *file_in, loff_t pos_in,
+				      struct file *file_out, loff_t pos_out,
+				      loff_t len, unsigned int remap_flags);
+	   int (*fadvise)(struct file *, loff_t, loff_t, int);
+   };
 
 Again, all methods are called without any locks being held, unless
 otherwise noted.
@@ -1006,21 +1019,23 @@ here.  These methods may be set to NULL, as they are either optional or
 the VFS uses a default.  As of kernel 2.6.22, the following members are
 defined:
 
-struct dentry_operations {
-	int (*d_revalidate)(struct dentry *, unsigned int);
-	int (*d_weak_revalidate)(struct dentry *, unsigned int);
-	int (*d_hash)(const struct dentry *, struct qstr *);
-	int (*d_compare)(const struct dentry *,
-			unsigned int, const char *, const struct qstr *);
-	int (*d_delete)(const struct dentry *);
-	int (*d_init)(struct dentry *);
-	void (*d_release)(struct dentry *);
-	void (*d_iput)(struct dentry *, struct inode *);
-	char *(*d_dname)(struct dentry *, char *, int);
-	struct vfsmount *(*d_automount)(struct path *);
-	int (*d_manage)(const struct path *, bool);
-	struct dentry *(*d_real)(struct dentry *, const struct inode *);
-};
+.. code-block:: c
+
+   struct dentry_operations {
+	   int (*d_revalidate)(struct dentry *, unsigned int);
+	   int (*d_weak_revalidate)(struct dentry *, unsigned int);
+	   int (*d_hash)(const struct dentry *, struct qstr *);
+	   int (*d_compare)(const struct dentry *,
+			    unsigned int, const char *, const struct qstr *);
+	   int (*d_delete)(const struct dentry *);
+	   int (*d_init)(struct dentry *);
+	   void (*d_release)(struct dentry *);
+	   void (*d_iput)(struct dentry *, struct inode *);
+	   char *(*d_dname)(struct dentry *, char *, int);
+	   struct vfsmount *(*d_automount)(struct path *);
+	   int (*d_manage)(const struct path *, bool);
+	   struct dentry *(*d_real)(struct dentry *, const struct inode *);
+   };
 
 - d_revalidate: called when the VFS needs to revalidate a dentry.  This
 	is called whenever a name look-up finds a dentry in the
@@ -1106,13 +1121,13 @@ struct dentry_operations {
 	at the end of the buffer, and returns a pointer to the first char.
 	dynamic_dname() helper function is provided to take care of this.
 
-	Example :
+	.. code-block:: c
 
-	static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen)
-	{
-		return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]",
-				dentry->d_inode->i_ino);
-	}
+	   static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen)
+	   {
+		   return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]",
+					dentry->d_inode->i_ino);
+	   }
 
 - d_automount: called when an automount dentry is to be traversed (optional).
 	This should create a new VFS mount record and return the record to the
-- 
2.21.0

Powered by blists - more mailing lists