Skip to contentSkip to conversation

vfs: update ->get_link() related documentation

PATCH In review Eric Biggers 4 participants 14 messages Apr 11, 2019 – May 3, 2019

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover vfs: update ->get_link() related documentation

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(-)
Signature · 1 line
2.21.0.392.gf8f6787159e-goog
#1 lore raw

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

From: Eric Biggers <[email protected]>

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

---
 Documentation/filesystems/vfs.txt | 2 --
 1 file changed, 2 deletions(-)
Documentation/filesystems/vfs.txt +0 -2
index 761c6fd24a53c..33120f220f86f 100644
@@ -3,8 +3,6 @@
 
 	Original author: Richard Gooch <[email protected]>
 
-		  Last updated on June 24, 2007.
-
   Copyright (C) 1999 Richard Gooch
   Copyright (C) 2005 Pekka Enberg
 
Signature · 1 line
2.21.0.392.gf8f6787159e-goog
#4 lore raw

PATCH 4/4 libfs: document simple_get_link()

In reply to Eric Biggers

From: Eric Biggers <[email protected]>

---
 fs/libfs.c | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
fs/libfs.c +14 -0
index 0fb590d79f30e..5f74a98729742 100644
@@ -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)
 {
Signature · 1 line
2.21.0.392.gf8f6787159e-goog
#2 lore raw

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

In reply to Eric Biggers

From: Eric Biggers <[email protected]>

---
 Documentation/filesystems/vfs.txt | 6 ++++++
 1 file changed, 6 insertions(+)
Documentation/filesystems/vfs.txt +6 -0
index 33120f220f86f..57fc576b1f3ea 100644
@@ -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
Signature · 1 line
2.21.0.392.gf8f6787159e-goog
#3 lore raw

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

In reply to Eric Biggers

From: Eric Biggers <[email protected]>

---
 Documentation/filesystems/Locking | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/filesystems/Locking +1 -1
index efea228ccd8af..428455bf9c97a 100644
@@ -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);
Signature · 1 line
2.21.0.392.gf8f6787159e-goog
#5 lore raw
In reply to Eric Biggers
Quoted 9 lines · 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()

Quoted 8 lines
 Documentation/filesystems/Locking |  2 +-
 Documentation/filesystems/vfs.txt |  8 ++++++--
 fs/libfs.c                        | 14 ++++++++++++++
 3 files changed, 21 insertions(+), 3 deletions(-)
Signature · 1 line
2.21.0.392.gf8f6787159e-goog

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

- Eric

#6 lore raw
Quoted 15 lines · Eric Biggers
Quoted 14 lines · 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(-)
Quoted 7 lines
Quoted 3 lines
Signature · 1 line
2.21.0.392.gf8f6787159e-goog

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

- Eric

Ping?

maintainer
#7 lore raw
Quoted 20 lines · Eric Biggers
Quoted 19 lines · Eric Biggers
Quoted 17 lines · 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(-)
Signature · 1 line
2.21.0.392.gf8f6787159e-goog
Quoted 5 lines
Quoted 3 lines

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?

maintainer
#8 lore raw
Quoted 9 lines · On Wed, 1 May 2019 02:36:49 +0100 Al Viro <[email protected]> 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

maintainer
#9 lore raw
Quoted 11 lines · Jonathan Corbet
Quoted 8 lines · On Wed, 1 May 2019 02:36:49 +0100 Al Viro <[email protected]> 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.

Quoted 7 lines
Quoted 1 line

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.

maintainer
#10 lore raw
Quoted 6 lines · On Wed, 1 May 2019 03:14:23 +0100 Al Viro <[email protected]> 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

maintainer
#11 lore raw
Quoted 10 lines · Jonathan Corbet
Quoted 6 lines · On Wed, 1 May 2019 03:14:23 +0100 Al Viro <[email protected]> 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.

Quoted 7 lines

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...

#12 lore raw
In reply to Al Viro
Quoted 20 lines · Al Viro
Quoted 11 lines · Jonathan Corbet
Quoted 8 lines · On Wed, 1 May 2019 02:36:49 +0100 Al Viro <[email protected]> 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.

Quoted 7 lines
Quoted 1 line

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.

Quoted 5 lines

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?

Quoted 6 lines

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 ...

Quoted 4 lines

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.

maintainer
#13 lore raw
Quoted 8 lines · On Wed, 1 May 2019 14:15:15 +1000 "Tobin C. Harding" <[email protected]> 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