vnode(9) man page

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

vnode(9) man page

Benny Lofgren
While reading up on vnodes I found a couple of glitches in the
vnode(9) man page (diff below). It refers in one place to the
file sys/kern/vnode_if.src which was deleted by this commit:

----8<--------8<--------8<--------8<--------8<---- (cut)
From: Thordur I Bjornsson <[hidden email]>
Subject: [source-changes] CVS: cvs.openbsd.org: src
To: [hidden email]

CVSROOT: /cvs
Module name: src
Changes by: [hidden email] 2011/04/02 10:27:29

Removed files:
        sys/sys        : vnode_if.h
        sys/kern       : vnode_if.c vnode_if.src vnode_if.sh

Log message:
remove the vnode_if.* files, as they are now totally
obsolete.

the move to vfs_vops.c is here to stay, so they are
pointless.
----8<--------8<--------8<--------8<--------8<---- (cut)

The commit comment indicates to me that the underlying mechanism
changed significantly, so now I wonder if the information that
once was in vnode_if.src (regarding vnode locking disciplines) is
irrelevant, obsolete or if it needs to be updated and moved to
somewhere more appropriate? The diff below just removes the
reference to the file which may not be the right thing to do.


Regards,
/Benny

----8<--------8<--------8<--------8<--------8<---- (cut)
Index: vnode.9
===================================================================
RCS file: /cvs/src/share/man/man9/vnode.9,v
retrieving revision 1.27
diff -u -r1.27 vnode.9
--- vnode.9     12 Apr 2008 10:18:01 -0000      1.27
+++ vnode.9     17 Jul 2011 14:11:53 -0000
@@ -180,7 +180,7 @@
 orchestrate the reclamation of a vnode.
 They can be called on both active and inactive vnodes.
 .Pp
-When transitioning a vnode to the reclaimed state, the VFS will call
+When transitioning a vnode to the reclaimed state, the VFS will call the
 .Xr VOP_RECLAIM 9
 method.
 File systems use this method to free any file-system-specific data
@@ -225,8 +225,6 @@
 .Pp
 There is a discipline to using the vnode lock.
 Some VOP_ operations require that the vnode lock is held before being
called.
-A description of this rather arcane locking discipline is in
-.Pa sys/kern/vnode_if.src .
 .Pp
 The vnode lock is acquired by calling
 .Xr vn_lock 9
----8<--------8<--------8<--------8<--------8<---- (cut)


--
internetlabbet.se     / work:   +46 8 551 124 80      / "Words must
Benny Lvfgren        /  mobile: +46 70 718 11 90     /   be weighed,
                    /   fax:    +46 8 551 124 89    /    not counted."
                   /    email:  benny -at- internetlabbet.se

Reply | Threaded
Open this post in threaded view
|

Re: vnode(9) man page

Thordur Bjornsson-2
On Sun, Jul 17, 2011 at 04:25:59PM +0200, Benny Lofgren wrote:
> While reading up on vnodes I found a couple of glitches in the
> vnode(9) man page (diff below). It refers in one place to the
> file sys/kern/vnode_if.src which was deleted by this commit:

Good catch. I thought I had nuked that;

>
> ----8<--------8<--------8<--------8<--------8<---- (cut)
> From: Thordur I Bjornsson <[hidden email]>
> Subject: [source-changes] CVS: cvs.openbsd.org: src
> To: [hidden email]
>
> CVSROOT: /cvs
> Module name: src
> Changes by: [hidden email] 2011/04/02 10:27:29
>
> Removed files:
> sys/sys        : vnode_if.h
> sys/kern       : vnode_if.c vnode_if.src vnode_if.sh
>
> Log message:
> remove the vnode_if.* files, as they are now totally
> obsolete.
>
> the move to vfs_vops.c is here to stay, so they are
> pointless.
> ----8<--------8<--------8<--------8<--------8<---- (cut)
>
> The commit comment indicates to me that the underlying mechanism
> changed significantly, so now I wonder if the information that
> once was in vnode_if.src (regarding vnode locking disciplines) is
> irrelevant, obsolete or if it needs to be updated and moved to
> somewhere more appropriate? The diff below just removes the
> reference to the file which may not be the right thing to do.

The locking discipline in that file is subtly wrong in some places,
overtly wrong in others.

I'm reworking it actually, and I hope to have a man page for it
at some point.

For now, the best bet if you are messing with this is to check
to see what UFS/FFS does, as it as the best chance of being the
"most" correct.
 

> Regards,
> /Benny
>
> ----8<--------8<--------8<--------8<--------8<---- (cut)
> Index: vnode.9
> ===================================================================
> RCS file: /cvs/src/share/man/man9/vnode.9,v
> retrieving revision 1.27
> diff -u -r1.27 vnode.9
> --- vnode.9     12 Apr 2008 10:18:01 -0000      1.27
> +++ vnode.9     17 Jul 2011 14:11:53 -0000
> @@ -180,7 +180,7 @@
>  orchestrate the reclamation of a vnode.
>  They can be called on both active and inactive vnodes.
>  .Pp
> -When transitioning a vnode to the reclaimed state, the VFS will call
> +When transitioning a vnode to the reclaimed state, the VFS will call the
>  .Xr VOP_RECLAIM 9
>  method.
>  File systems use this method to free any file-system-specific data
> @@ -225,8 +225,6 @@
>  .Pp
>  There is a discipline to using the vnode lock.
>  Some VOP_ operations require that the vnode lock is held before being
> called.
> -A description of this rather arcane locking discipline is in
> -.Pa sys/kern/vnode_if.src .
>  .Pp
>  The vnode lock is acquired by calling
>  .Xr vn_lock 9
> ----8<--------8<--------8<--------8<--------8<---- (cut)
>
>
> --
> internetlabbet.se     / work:   +46 8 551 124 80      / "Words must
> Benny Lvfgren        /  mobile: +46 70 718 11 90     /   be weighed,
>                     /   fax:    +46 8 551 124 89    /    not counted."
>                    /    email:  benny -at- internetlabbet.se

Reply | Threaded
Open this post in threaded view
|

Re: vnode(9) man page

Jason McIntyre
On Sun, Jul 17, 2011 at 03:25:29PM +0000, Thordur Bjornsson wrote:

> >
> > The commit comment indicates to me that the underlying mechanism
> > changed significantly, so now I wonder if the information that
> > once was in vnode_if.src (regarding vnode locking disciplines) is
> > irrelevant, obsolete or if it needs to be updated and moved to
> > somewhere more appropriate? The diff below just removes the
> > reference to the file which may not be the right thing to do.
>
> The locking discipline in that file is subtly wrong in some places,
> overtly wrong in others.
>
> I'm reworking it actually, and I hope to have a man page for it
> at some point.
>
> For now, the best bet if you are messing with this is to check
> to see what UFS/FFS does, as it as the best chance of being the
> "most" correct.
>  

can we have the short term fix for now then, so at least the man page is
not wrong?

jmc

Reply | Threaded
Open this post in threaded view
|

Re: vnode(9) man page

Thordur Bjornsson-2
On Mon, Jul 18, 2011 at 07:11:54AM +0059, Jason McIntyre wrote:

> On Sun, Jul 17, 2011 at 03:25:29PM +0000, Thordur Bjornsson wrote:
> > >
> > > The commit comment indicates to me that the underlying mechanism
> > > changed significantly, so now I wonder if the information that
> > > once was in vnode_if.src (regarding vnode locking disciplines) is
> > > irrelevant, obsolete or if it needs to be updated and moved to
> > > somewhere more appropriate? The diff below just removes the
> > > reference to the file which may not be the right thing to do.
> >
> > The locking discipline in that file is subtly wrong in some places,
> > overtly wrong in others.
> >
> > I'm reworking it actually, and I hope to have a man page for it
> > at some point.
> >
> > For now, the best bet if you are messing with this is to check
> > to see what UFS/FFS does, as it as the best chance of being the
> > "most" correct.
> >  
>
> can we have the short term fix for now then, so at least the man page is
> not wrong?
Err, yes. I intended to commit the diff from Benny last night. It's in now.

Commited.