[PATCH 0/4] vfs: update ->get_link() related documentation

[PATCH 0/4] vfs: update ->get_link() related documentation

[Eric Biggers]

Update the documentation as per the discussion at
https://marc.info/?t=155485312800001&r=1.

Eric Biggers (4):
  Documentation/filesystems/vfs.txt: remove bogus "Last updated" date
  Documentation/filesystems/vfs.txt: document how ->i_link works
  Documentation/filesystems/Locking: fix ->get_link() prototype
  libfs: document simple_get_link()

 Documentation/filesystems/Locking |  2 +-
 Documentation/filesystems/vfs.txt |  8 ++++++--
 fs/libfs.c                        | 14 ++++++++++++++
 3 files changed, 21 insertions(+), 3 deletions(-)

-- 
2.21.0.392.gf8f6787159e-goog

[PATCH 1/4] Documentation/filesystems/vfs.txt: remove bogus "Last updated" date

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

This file has actually been updated over 100 times since the claimed
"Last updated" date.

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 Documentation/filesystems/vfs.txt | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt
index 761c6fd24a53c..33120f220f86f 100644
--- a/Documentation/filesystems/vfs.txt
+++ b/Documentation/filesystems/vfs.txt
@@ -3,8 +3,6 @@
 
 	Original author: Richard Gooch <rgooch@atnf.csiro.au>
 
-		  Last updated on June 24, 2007.
-
   Copyright (C) 1999 Richard Gooch
   Copyright (C) 2005 Pekka Enberg
 
-- 
2.21.0.392.gf8f6787159e-goog

[PATCH 2/4] Documentation/filesystems/vfs.txt: document how ->i_link works

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 Documentation/filesystems/vfs.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt
index 33120f220f86f..57fc576b1f3ea 100644
--- a/Documentation/filesystems/vfs.txt
+++ b/Documentation/filesystems/vfs.txt
@@ -463,6 +463,12 @@ otherwise noted.
 	argument.  If request can't be handled without leaving RCU mode,
 	have it return ERR_PTR(-ECHILD).
 
+	If the filesystem stores the symlink target in ->i_link, the
+	VFS may use it directly without calling ->get_link(); however,
+	->get_link() must still be provided.  ->i_link must not be
+	freed until after an RCU grace period.  Writing to ->i_link
+	post-iget() time requires a 'release' memory barrier.
+
   readlink: this is now just an override for use by readlink(2) for the
 	cases when ->get_link uses nd_jump_link() or object is not in
 	fact a symlink.  Normally filesystems should only implement
-- 
2.21.0.392.gf8f6787159e-goog

[PATCH 3/4] Documentation/filesystems/Locking: fix ->get_link() prototype

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 Documentation/filesystems/Locking | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking
index efea228ccd8af..428455bf9c97a 100644
--- a/Documentation/filesystems/Locking
+++ b/Documentation/filesystems/Locking
@@ -52,7 +52,7 @@ prototypes:
 	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 *, void **);
+	const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *);
 	void (*truncate) (struct inode *);
 	int (*permission) (struct inode *, int, unsigned int);
 	int (*get_acl)(struct inode *, int);
-- 
2.21.0.392.gf8f6787159e-goog

[PATCH 4/4] libfs: document simple_get_link()

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 fs/libfs.c | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/fs/libfs.c b/fs/libfs.c
index 0fb590d79f30e..5f74a98729742 100644
--- a/fs/libfs.c
+++ b/fs/libfs.c
@@ -1167,6 +1167,20 @@ simple_nosetlease(struct file *filp, long arg, struct file_lock **flp,
 }
 EXPORT_SYMBOL(simple_nosetlease);
 
+/**
+ * simple_get_link - generic helper to get the target of "fast" symlinks
+ * @dentry: not used here
+ * @inode: the symlink inode
+ * @done: not used here
+ *
+ * Generic helper for filesystems to use for symlink inodes where a pointer to
+ * the symlink target is stored in ->i_link.  NOTE: this isn't normally called,
+ * since as an optimization the path lookup code uses any non-NULL ->i_link
+ * directly, without calling ->get_link().  But ->get_link() still must be set,
+ * to mark the inode_operations as being for a symlink.
+ *
+ * Return: the symlink target
+ */
 const char *simple_get_link(struct dentry *dentry, struct inode *inode,
 			    struct delayed_call *done)
 {
-- 
2.21.0.392.gf8f6787159e-goog

Re: [PATCH 0/4] vfs: update ->get_link() related documentation

[Eric Biggers]

On Thu, Apr 11, 2019 at 04:16:26PM -0700, Eric Biggers wrote:
> Update the documentation as per the discussion at
> https://marc.info/?t=155485312800001&r=1.
> 
> Eric Biggers (4):
>   Documentation/filesystems/vfs.txt: remove bogus "Last updated" date
>   Documentation/filesystems/vfs.txt: document how ->i_link works
>   Documentation/filesystems/Locking: fix ->get_link() prototype
>   libfs: document simple_get_link()
> 
>  Documentation/filesystems/Locking |  2 +-
>  Documentation/filesystems/vfs.txt |  8 ++++++--
>  fs/libfs.c                        | 14 ++++++++++++++
>  3 files changed, 21 insertions(+), 3 deletions(-)
> 
> -- 
> 2.21.0.392.gf8f6787159e-goog
> 

Al, any comment on this?  Will you be taking these?

- Eric

Re: [PATCH 0/4] vfs: update ->get_link() related documentation

[Eric Biggers]

On Mon, Apr 22, 2019 at 11:03:47AM -0700, Eric Biggers wrote:
> On Thu, Apr 11, 2019 at 04:16:26PM -0700, Eric Biggers wrote:
> > Update the documentation as per the discussion at
> > https://marc.info/?t=155485312800001&r=1.
> > 
> > Eric Biggers (4):
> >   Documentation/filesystems/vfs.txt: remove bogus "Last updated" date
> >   Documentation/filesystems/vfs.txt: document how ->i_link works
> >   Documentation/filesystems/Locking: fix ->get_link() prototype
> >   libfs: document simple_get_link()
> > 
> >  Documentation/filesystems/Locking |  2 +-
> >  Documentation/filesystems/vfs.txt |  8 ++++++--
> >  fs/libfs.c                        | 14 ++++++++++++++
> >  3 files changed, 21 insertions(+), 3 deletions(-)
> > 
> > -- 
> > 2.21.0.392.gf8f6787159e-goog
> > 
> 
> Al, any comment on this?  Will you be taking these?
> 
> - Eric

Ping?

Re: [PATCH 0/4] vfs: update ->get_link() related documentation

[Al Viro]

On Tue, Apr 30, 2019 at 05:25:17PM -0700, Eric Biggers wrote:
> On Mon, Apr 22, 2019 at 11:03:47AM -0700, Eric Biggers wrote:
> > On Thu, Apr 11, 2019 at 04:16:26PM -0700, Eric Biggers wrote:
> > > Update the documentation as per the discussion at
> > > https://marc.info/?t=155485312800001&r=1.
> > > 
> > > Eric Biggers (4):
> > >   Documentation/filesystems/vfs.txt: remove bogus "Last updated" date
> > >   Documentation/filesystems/vfs.txt: document how ->i_link works
> > >   Documentation/filesystems/Locking: fix ->get_link() prototype
> > >   libfs: document simple_get_link()
> > > 
> > >  Documentation/filesystems/Locking |  2 +-
> > >  Documentation/filesystems/vfs.txt |  8 ++++++--
> > >  fs/libfs.c                        | 14 ++++++++++++++
> > >  3 files changed, 21 insertions(+), 3 deletions(-)
> > > 
> > > -- 
> > > 2.21.0.392.gf8f6787159e-goog
> > > 
> > 
> > Al, any comment on this?  Will you be taking these?
> > 
> > - Eric
> 
> Ping?

*blink*

Thought I'd replied; apparently not...  Anyway, the problem with those
is that there'd been a series of patches converting vfs.txt to new
format; I'm not sure what Jon is going to do with it, but these are
certain to conflict.  I've no objections to the contents of changes,
but if that stuff is getting massive reformatting the first two
probably ought to go through Jon's tree.  I can take the last two
at any point.

Jon, what's the status of the format conversion?

Re: [PATCH 0/4] vfs: update ->get_link() related documentation

[Jonathan Corbet]

On Wed, 1 May 2019 02:36:49 +0100
Al Viro <viro@zeniv.linux.org.uk> wrote:

> Thought I'd replied; apparently not...  Anyway, the problem with those
> is that there'd been a series of patches converting vfs.txt to new
> format; I'm not sure what Jon is going to do with it, but these are
> certain to conflict.  I've no objections to the contents of changes,
> but if that stuff is getting massive reformatting the first two
> probably ought to go through Jon's tree.  I can take the last two
> at any point.
> 
> Jon, what's the status of the format conversion?

Last I saw, it seemed that you wanted changes in how things were done and
that Tobin (added to CC) had stepped back.  Tobin, are your thoughts on
the matter different?  I could try to shoehorn them in for 5.2 still, I
guess, but perhaps the best thing to do is to just take Eric's patch, and
the reformatting can work around it if need be.

Thanks,

jon

Re: [PATCH 0/4] vfs: update ->get_link() related documentation

[Al Viro]

On Tue, Apr 30, 2019 at 07:49:43PM -0600, Jonathan Corbet wrote:
> On Wed, 1 May 2019 02:36:49 +0100
> Al Viro <viro@zeniv.linux.org.uk> wrote:
> 
> > Thought I'd replied; apparently not...  Anyway, the problem with those
> > is that there'd been a series of patches converting vfs.txt to new
> > format; I'm not sure what Jon is going to do with it, but these are
> > certain to conflict.  I've no objections to the contents of changes,
> > but if that stuff is getting massive reformatting the first two
> > probably ought to go through Jon's tree.  I can take the last two
> > at any point.
> > 
> > Jon, what's the status of the format conversion?
> 
> Last I saw, it seemed that you wanted changes in how things were done and
> that Tobin (added to CC) had stepped back.  Tobin, are your thoughts on
> the matter different?  I could try to shoehorn them in for 5.2 still, I
> guess, but perhaps the best thing to do is to just take Eric's patch, and
> the reformatting can work around it if need be.

I can certainly apply Eric's series (or ACK it if we end up deciding to
feed it through your tree).

Rereading my replies in that thread, I hadn't been clear back then and
I can see how that could've been created the wrong impression. 

I do have problems with vfs.txt approach in general and I hope we end up
with per object type documents; however, that's completely orthogonal to
format conversion.  IOW, I have no objections whatsoever to format switch
done first; any migration of e.g. dentry-related parts into a separate
document, with lifecycle explicitly documented and descriptions of
methods tied to that can just as well go on top of that.

I don't think that vfs.txt will survive in recognizable form in the long
run, but by all means, let's get the format conversion out of the way
first.  And bits and pieces of contents will survive in the replacement
files when those appear.

Re: [PATCH 0/4] vfs: update ->get_link() related documentation

[Jonathan Corbet]

On Wed, 1 May 2019 03:14:23 +0100
Al Viro <viro@zeniv.linux.org.uk> wrote:

> I do have problems with vfs.txt approach in general and I hope we end up
> with per object type documents; however, that's completely orthogonal to
> format conversion.  IOW, I have no objections whatsoever to format switch
> done first; any migration of e.g. dentry-related parts into a separate
> document, with lifecycle explicitly documented and descriptions of
> methods tied to that can just as well go on top of that.

OK, great.  

That said, let's hold the format conversion for 5.3 (or *maybe*
late-merge-window 5.2).  It's a big set of patches to shovel in at this
point, and while it's good work, it's not screamingly urgent.  My
suggestion would be to take Eric's stuff, it shouldn't be a problem to
adjust to it.

Sound good?

Thanks,

jon

Re: [PATCH 0/4] vfs: update ->get_link() related documentation

[Al Viro]

On Tue, Apr 30, 2019 at 08:17:41PM -0600, Jonathan Corbet wrote:
> On Wed, 1 May 2019 03:14:23 +0100
> Al Viro <viro@zeniv.linux.org.uk> wrote:
> 
> > I do have problems with vfs.txt approach in general and I hope we end up
> > with per object type documents; however, that's completely orthogonal to
> > format conversion.  IOW, I have no objections whatsoever to format switch
> > done first; any migration of e.g. dentry-related parts into a separate
> > document, with lifecycle explicitly documented and descriptions of
> > methods tied to that can just as well go on top of that.
> 
> OK, great.  
> 
> That said, let's hold the format conversion for 5.3 (or *maybe*
> late-merge-window 5.2).  It's a big set of patches to shovel in at this
> point, and while it's good work, it's not screamingly urgent.  My
> suggestion would be to take Eric's stuff, it shouldn't be a problem to
> adjust to it.

OK, it's in vfs.git#work.misc; will be in #for-next when I sort the
work.icache mess out...

Re: [PATCH 0/4] vfs: update ->get_link() related documentation

[Tobin C. Harding]

On Wed, May 01, 2019 at 03:14:23AM +0100, Al Viro wrote:
> On Tue, Apr 30, 2019 at 07:49:43PM -0600, Jonathan Corbet wrote:
> > On Wed, 1 May 2019 02:36:49 +0100
> > Al Viro <viro@zeniv.linux.org.uk> wrote:
> > 
> > > Thought I'd replied; apparently not...  Anyway, the problem with those
> > > is that there'd been a series of patches converting vfs.txt to new
> > > format; I'm not sure what Jon is going to do with it, but these are
> > > certain to conflict.  I've no objections to the contents of changes,
> > > but if that stuff is getting massive reformatting the first two
> > > probably ought to go through Jon's tree.  I can take the last two
> > > at any point.
> > > 
> > > Jon, what's the status of the format conversion?
> > 
> > Last I saw, it seemed that you wanted changes in how things were done and
> > that Tobin (added to CC) had stepped back.  Tobin, are your thoughts on
> > the matter different?  I could try to shoehorn them in for 5.2 still, I
> > guess, but perhaps the best thing to do is to just take Eric's patch, and
> > the reformatting can work around it if need be.
> 
> I can certainly apply Eric's series (or ACK it if we end up deciding to
> feed it through your tree).
> 
> Rereading my replies in that thread, I hadn't been clear back then and
> I can see how that could've been created the wronng impression. 

Yes, I had stepped back.  I thought from Al's comments that he didn't like
the current content of vfs.txt

Since the conversion set I did did not fundamentally change the content
but just moved it to the source files it seemed like this set was a dead
end.

FWIW I don't think that a _simple_ conversion for vfs.txt to vfs.rst is
useful if the VFS is to be re-documented.  It isn't trivial to do if we
want to make any use of RST features and if we do not want to then why
bother converting it?

> I do have problems with vfs.txt approach in general and I hope we end up
> with per object type documents; however, that's completely orthogonal to
> format conversion.  IOW, I have no objections whatsoever to format switch
> done first; any migration of e.g. dentry-related parts into a separate
> document, with lifecycle explicitly documented and descriptions of
> methods tied to that can just as well go on top of that.

I'd like to work on this but considering I don't know what I'm talking
about and have to learn as I go this is a long project ...

> I don't think that vfs.txt will survive in recognizable form in the long
> run, but by all means, let's get the format conversion out of the way
> first.  And bits and pieces of contents will survive in the replacement
> files when those appear.

IMO vfs.txt is so outdated the conversion really needs to be done by
someone that knows the VFS inside out.

I am more than happy to take directions on this if there is something
useful I can do.

Cheers,
Tobin.

Re: [PATCH 0/4] vfs: update ->get_link() related documentation

[Jonathan Corbet]

On Wed, 1 May 2019 14:15:15 +1000
"Tobin C. Harding" <me@tobin.cc> wrote:

> Since the conversion set I did did not fundamentally change the content
> but just moved it to the source files it seemed like this set was a dead
> end.
> 
> FWIW I don't think that a _simple_ conversion for vfs.txt to vfs.rst is
> useful if the VFS is to be re-documented.  It isn't trivial to do if we
> want to make any use of RST features and if we do not want to then why
> bother converting it?

I think it's worth converting; it's sufficiently better than nothing,
IMO, that we don't want to just throw it away.  If we bring it up to
current formatting standards and make it more accessible, it just might
motivate others to help make it better.  So if you feel like sending me a
current patch set, I'd be happy to apply it.

Thanks,

jon