Re: [PATCH 22/32] vfs: Provide documentation for new mount API [ver #9]
Randy Dunlap wrote: > I would review this but it sounds like I should just wait for the > next version. Probably a good idea. Thanks for the consideration anyway. David
Re: [PATCH 22/32] vfs: Provide documentation for new mount API [ver #9]
Randy Dunlap wrote: > I would review this but it sounds like I should just wait for the > next version. Probably a good idea. Thanks for the consideration anyway. David
Re: [PATCH 22/32] vfs: Provide documentation for new mount API [ver #9]
On 07/10/2018 03:43 PM, David Howells wrote: > Provide documentation for the new mount API. > > Signed-off-by: David Howells > --- > > Documentation/filesystems/mount_api.txt | 439 > +++ > 1 file changed, 439 insertions(+) > create mode 100644 Documentation/filesystems/mount_api.txt Hi, I would review this but it sounds like I should just wait for the next version. -- ~Randy
Re: [PATCH 22/32] vfs: Provide documentation for new mount API [ver #9]
On 07/10/2018 03:43 PM, David Howells wrote: > Provide documentation for the new mount API. > > Signed-off-by: David Howells > --- > > Documentation/filesystems/mount_api.txt | 439 > +++ > 1 file changed, 439 insertions(+) > create mode 100644 Documentation/filesystems/mount_api.txt Hi, I would review this but it sounds like I should just wait for the next version. -- ~Randy
[PATCH 22/32] vfs: Provide documentation for new mount API [ver #9]
Provide documentation for the new mount API.
Signed-off-by: David Howells
---
Documentation/filesystems/mount_api.txt | 439 +++
1 file changed, 439 insertions(+)
create mode 100644 Documentation/filesystems/mount_api.txt
diff --git a/Documentation/filesystems/mount_api.txt
b/Documentation/filesystems/mount_api.txt
new file mode 100644
index ..6269fb2476f8
--- /dev/null
+++ b/Documentation/filesystems/mount_api.txt
@@ -0,0 +1,439 @@
+
+FILESYSTEM MOUNT API
+
+
+CONTENTS
+
+ (1) Overview.
+
+ (2) The filesystem context.
+
+ (3) The filesystem context operations.
+
+ (4) Filesystem context security.
+
+ (5) VFS filesystem context operations.
+
+
+
+OVERVIEW
+
+
+The creation of new mounts is now to be done in a multistep process:
+
+ (1) Create a filesystem context.
+
+ (2) Parse the options and attach them to the context. Options are expected to
+ be passed individually from userspace, though legacy binary options can be
+ handled.
+
+ (3) Validate and pre-process the context.
+
+ (4) Get or create a superblock and mountable root.
+
+ (5) Perform the mount.
+
+ (6) Return an error message attached to the context.
+
+ (7) Destroy the context.
+
+To support this, the file_system_type struct gains a new field:
+
+ int (*init_fs_context)(struct fs_context *fc, struct dentry *reference);
+
+which is invoked to set up the filesystem-specific parts of a filesystem
+context, including the additional space. The reference parameter is used to
+convey a superblock and an automount point or a point to reconfigure from which
+the filesystem may draw extra information (such as namespaces) for submount
+(FS_CONTEXT_FOR_SUBMOUNT) or reconfiguration (FS_CONTEXT_FOR_RECONFIGURE)
+purposes - otherwise it will be NULL.
+
+Note that security initialisation is done *after* the filesystem is called so
+that the namespaces may be adjusted first.
+
+And the super_operations struct gains one field:
+
+ int (*reconfigure)(struct super_block *, struct fs_context *);
+
+This shadows the ->reconfigure() operation and takes a prepared filesystem
+context instead of the mount flags and data page. It may modify the sb_flags
+in the context for the caller to pick up.
+
+[NOTE] reconfigure is intended as a replacement for remount_fs.
+
+
+==
+THE FILESYSTEM CONTEXT
+==
+
+The creation and reconfiguration of a superblock is governed by a filesystem
+context. This is represented by the fs_context structure:
+
+ struct fs_context {
+ const struct fs_context_operations *ops;
+ struct file_system_type *fs_type;
+ void*fs_private;
+ struct dentry *root;
+ struct user_namespace *user_ns;
+ struct net *net_ns;
+ const struct cred *cred;
+ char*source;
+ char*subtype;
+ void*security;
+ void*s_fs_info;
+ unsigned intsb_flags;
+ enum fs_context_purpose purpose:8;
+ boolsloppy:1;
+ boolsilent:1;
+ ...
+ };
+
+The fs_context fields are as follows:
+
+ (*) const struct fs_context_operations *ops
+
+ These are operations that can be done on a filesystem context (see
+ below). This must be set by the ->init_fs_context() file_system_type
+ operation.
+
+ (*) struct file_system_type *fs_type
+
+ A pointer to the file_system_type of the filesystem that is being
+ constructed or reconfigured. This retains a reference on the type owner.
+
+ (*) void *fs_private
+
+ A pointer to the file system's private data. This is where the filesystem
+ will need to store any options it parses.
+
+ (*) struct dentry *root
+
+ A pointer to the root of the mountable tree (and indirectly, the
+ superblock thereof). This is filled in by the ->get_tree() op. If this
+ is set, an active reference on root->d_sb must also be held.
+
+ (*) struct user_namespace *user_ns
+ (*) struct net *net_ns
+
+ There are a subset of the namespaces in use by the invoking process. They
+ retain references on each namespace. The subscribed namespaces may be
+ replaced by the filesystem to reflect other sources, such as the parent
+ mount superblock on an automount.
+
+ (*) const struct cred *cred
+
+ The mounter's credentials. This retains a reference on the credentials.
+
+ (*) char *source
+
+ This specifies the source. It may be a block device (e.g. /dev/sda1) or
+ something more exotic, such as the "host:/path" that NFS desires.
+
+ (*) char *subtype
+
+
[PATCH 22/32] vfs: Provide documentation for new mount API [ver #9]
Provide documentation for the new mount API.
Signed-off-by: David Howells
---
Documentation/filesystems/mount_api.txt | 439 +++
1 file changed, 439 insertions(+)
create mode 100644 Documentation/filesystems/mount_api.txt
diff --git a/Documentation/filesystems/mount_api.txt
b/Documentation/filesystems/mount_api.txt
new file mode 100644
index ..6269fb2476f8
--- /dev/null
+++ b/Documentation/filesystems/mount_api.txt
@@ -0,0 +1,439 @@
+
+FILESYSTEM MOUNT API
+
+
+CONTENTS
+
+ (1) Overview.
+
+ (2) The filesystem context.
+
+ (3) The filesystem context operations.
+
+ (4) Filesystem context security.
+
+ (5) VFS filesystem context operations.
+
+
+
+OVERVIEW
+
+
+The creation of new mounts is now to be done in a multistep process:
+
+ (1) Create a filesystem context.
+
+ (2) Parse the options and attach them to the context. Options are expected to
+ be passed individually from userspace, though legacy binary options can be
+ handled.
+
+ (3) Validate and pre-process the context.
+
+ (4) Get or create a superblock and mountable root.
+
+ (5) Perform the mount.
+
+ (6) Return an error message attached to the context.
+
+ (7) Destroy the context.
+
+To support this, the file_system_type struct gains a new field:
+
+ int (*init_fs_context)(struct fs_context *fc, struct dentry *reference);
+
+which is invoked to set up the filesystem-specific parts of a filesystem
+context, including the additional space. The reference parameter is used to
+convey a superblock and an automount point or a point to reconfigure from which
+the filesystem may draw extra information (such as namespaces) for submount
+(FS_CONTEXT_FOR_SUBMOUNT) or reconfiguration (FS_CONTEXT_FOR_RECONFIGURE)
+purposes - otherwise it will be NULL.
+
+Note that security initialisation is done *after* the filesystem is called so
+that the namespaces may be adjusted first.
+
+And the super_operations struct gains one field:
+
+ int (*reconfigure)(struct super_block *, struct fs_context *);
+
+This shadows the ->reconfigure() operation and takes a prepared filesystem
+context instead of the mount flags and data page. It may modify the sb_flags
+in the context for the caller to pick up.
+
+[NOTE] reconfigure is intended as a replacement for remount_fs.
+
+
+==
+THE FILESYSTEM CONTEXT
+==
+
+The creation and reconfiguration of a superblock is governed by a filesystem
+context. This is represented by the fs_context structure:
+
+ struct fs_context {
+ const struct fs_context_operations *ops;
+ struct file_system_type *fs_type;
+ void*fs_private;
+ struct dentry *root;
+ struct user_namespace *user_ns;
+ struct net *net_ns;
+ const struct cred *cred;
+ char*source;
+ char*subtype;
+ void*security;
+ void*s_fs_info;
+ unsigned intsb_flags;
+ enum fs_context_purpose purpose:8;
+ boolsloppy:1;
+ boolsilent:1;
+ ...
+ };
+
+The fs_context fields are as follows:
+
+ (*) const struct fs_context_operations *ops
+
+ These are operations that can be done on a filesystem context (see
+ below). This must be set by the ->init_fs_context() file_system_type
+ operation.
+
+ (*) struct file_system_type *fs_type
+
+ A pointer to the file_system_type of the filesystem that is being
+ constructed or reconfigured. This retains a reference on the type owner.
+
+ (*) void *fs_private
+
+ A pointer to the file system's private data. This is where the filesystem
+ will need to store any options it parses.
+
+ (*) struct dentry *root
+
+ A pointer to the root of the mountable tree (and indirectly, the
+ superblock thereof). This is filled in by the ->get_tree() op. If this
+ is set, an active reference on root->d_sb must also be held.
+
+ (*) struct user_namespace *user_ns
+ (*) struct net *net_ns
+
+ There are a subset of the namespaces in use by the invoking process. They
+ retain references on each namespace. The subscribed namespaces may be
+ replaced by the filesystem to reflect other sources, such as the parent
+ mount superblock on an automount.
+
+ (*) const struct cred *cred
+
+ The mounter's credentials. This retains a reference on the credentials.
+
+ (*) char *source
+
+ This specifies the source. It may be a block device (e.g. /dev/sda1) or
+ something more exotic, such as the "host:/path" that NFS desires.
+
+ (*) char *subtype
+
+
