Differential D28980 Diff 84823 share/man/man9/VOP_READ_PGCACHE.9

Changeset View

Standalone View

share/man/man9/VOP_READ_PGCACHE.9

This file was added.

				.\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
				.\" All rights reserved.
				gbeUnsubmitted Done Inline Actions This year could be updated to 2021. gbe: This year could be updated to 2021.
				.\"
				.\" This documentation was written by
				.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
				.\" from the FreeBSD Foundation.
				.\"
				.\" Redistribution and use in source and binary forms, with or without
				.\" modification, are permitted provided that the following conditions
				.\" are met:
				.\" 1. Redistributions of source code must retain the above copyright
				.\" notice, this list of conditions and the following disclaimer.
				.\" 2. Redistributions in binary form must reproduce the above copyright
				.\" notice, this list of conditions and the following disclaimer in the
				.\" documentation and/or other materials provided with the distribution.
				.\"
				.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
				.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
				.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
				.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
				.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
				.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
				.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
				.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
				.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
				.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
				.\" SUCH DAMAGE.
				.\"
				.\" $FreeBSD$
				.\"
				.Dd February 28, 2021
				.Dt VOP_READ_PGCACHE 9
				.Os
				.Sh NAME
				.Nm VOP_READ_PGCACHE
				.Nd read a file, fast
				.Sh SYNOPSIS
				.In sys/param.h
				.In sys/vnode.h
				.In sys/uio.h
				.Ft int
				.Fo VOP_READ_PGCACHE
				.Fa "struct vnode *vp"
				.Fa "struct uio *uio"
				.Fa "int ioflag"
				.Fa "struct ucred *cred"
				.Fc
				.Sh DESCRIPTION
				This entry point read the contents of a file.
				The intent is to provide the data from caches, which do not require
				expensive operations or any disk io.
				rwatsonUnsubmitted Done Inline Actions I would probably spell this IO. rwatson: I would probably spell this IO.
				For instance, if filesystem uses normal VM page cache and maintains
				.Dv v_object
				lifetime, it can use
				.Xr vn_read_from_obj 9
				helper to return data from the resident
				.Dv vp->v_object
				pages.
				rwatsonUnsubmitted Done Inline Actions Is it worth specifically stating how this differs from VOP_READ(9) -- i.e., the caller will not acquire the vnode lock, and will retry once holding the lock using VOP_READ(9) if this doesn't work? (Assuming I understand correctly.) Should the implementation of VO_READ_PGCACHE(9) promise not to do expensive things, such as disk IO, or is this simply an opportunity for it to provide a read operation without requiring the caller to lock? rwatson: Is it worth specifically stating how this differs from VOP_READ(9) -- i.e., the caller will not…
				kibAuthorUnsubmitted Done Inline Actions It is up to the filesystem to do whatever it intents to. Typically fs would not want to do `vn_lock(); VOP_READ(); VOP_UNLOCK();` if only because the vnode can be reclaimed before or during lock, in which case fs should not do read on it at all. WRT expensive ops, it is up to fs. The main difference in the call environment: lockless and the permit to delegate to later VOP_READ() by special error return, are stated. kib: It is up to the filesystem to do whatever it intents to. Typically fs would not want to do…
				.Pp
				The filesystem indicates support for the
				.Nm
				on specific vnode by setting the
				.Dv VIRF_PGREAD
				flag in
				.Dv vp->v_irflag .
				.Pp
				The function does not need to satisfy the whole request, also it might choose
				rwatsonUnsubmitted Done Inline Actions Perhaps instead: "request; it also might choose..." rwatson: Perhaps instead: "request; it also might choose..."
				to not provide any data.
				In these cases, the
				.Nm
				should return
				.Er EJUSTRETURN ,
				and VFS would handle the rest of the read operation using the
				.Xr VOP_READ 9 .
				.Pp
				The arguments are:
				.Bl -tag -width ioflag
				.It Fa vp
				The vnode of the file.
				.It Fa uio
				The location of the data to be read.
				.It Fa ioflag
				Various flags.
				rwatsonUnsubmitted Done Inline Actions Should we refer the reader to VOP_READ(9) for the possible flag values ..? rwatson: Should we refer the reader to VOP_READ(9) for the possible flag values ..?
				.It Fa cnp
				rwatsonUnsubmitted Done Inline Actions Should be "cred" not "cnp"? rwatson: Should be "cred" not "cnp"?
				The credentials of the caller.
				.El
				.Pp
				The
				rwatsonUnsubmitted Done Inline Actions Can drop the definite article, "The," here. rwatson: Can drop the definite article, "The," here.
				.Nm
				does not handle non-zero
				.Fa ioflag
				argument.
				rwatsonUnsubmitted Done Inline Actions Should we drop the argument? Or is the plan that we might support it at some point? (Can we assert this in a VOP pre-hook to avoid confusion arising..?) rwatson: Should we drop the argument? Or is the plan that we might support it at some point? (Can we…
				kibAuthorUnsubmitted Done Inline Actions It is up to filesystem, doing it in pre is not better than ensure that callers do it right. I do not want to drop the flag arg, we might want to pass some info, and I want to have KBI in stable to do it if needed. kib: It is up to filesystem, doing it in pre is not better than ensure that callers do it right. I…
				.Sh LOCKS
				The file should be referenced on entry on entry and will still be
				referenced on exit.
				Rangelock covering the whole read range should be owned around the call.
				rwatsonUnsubmitted Done Inline Actions Should we say something about the vnode lock not being required for callers .. and about whether the callee should or shouldn't acquire it? Should the callee fail if it needs to acquire the vnode lock, and let a followup call to VOP_READ(9) handle it? rwatson: Should we say something about the vnode lock not being required for callers .. and about…
				kibAuthorUnsubmitted Done Inline Actions I added the note about vnode not being locked. I do not want to give even a hint that the implementation of the VOP could lock the vnode. kib: I added the note about vnode not being locked. I do not want to give even a hint that the…
				.Sh RETURN VALUES
				Zero is returned on success, when the whole request is satisfied, and no
				more data cannot be provided for it by any means.
				If more data can be returned, but
				.Nm
				was unable to provide it,
				.Er EJUSTRETURN
				must be returned.
				rwatsonUnsubmitted Done Inline Actions In this case, the access is performed, and the uio is still updated to reflect data read ..? Or is this an error and VOP_READ should be tried? I guess it makes me slightly uncomfortable to have a non-zero success mode, as it's so easy for callers to get that horribly wrong (vis OpenSSL), but I suppose there's also only one caller of this. Regardless, I think the expected semantics should be documented more thoroughly here (and possibly above as well, rather than in the error code section). rwatson: In this case, the access is performed, and the uio is still updated to reflect data read ..? Or…
				kibAuthorUnsubmitted Done Inline Actions I added a note that uio is updated as far as IO is done. I thought that this is obvious (how would the caller know it, otherwise?) There should be a way to distinguish partial read vs. short read. EJUSTRETURN is as good as other ways to notify about partial read, e.g. explicit EOF flag. EJUSTRETURN not returned to userspace is used by other parts of VFS, e.g. for successful namei(9) call that does not return resulting vnode (e.g. CREATE). Of course it is important to handle EJUSTRETURN, but it is VFS problem and not fs issue. Somebody calling the VOP must know much more than somebody implementing it. Man pages are to provide the first look into the interface. kib: I added a note that uio is updated as far as IO is done. I thought that this is obvious (how…
				Otherwise an error code is returned.
				rwatsonUnsubmitted Done Inline Actions Possibly we should point at possible error returns from VOP_READ(9)? rwatson: Possibly we should point at possible error returns from VOP_READ(9)?
				.Sh SEE ALSO
				.Xr uiomove 9 ,
				.Xr vnode 9
				rwatsonUnsubmitted Not Done Inline Actions I wonder if it's worth rwatson: I wonder if it's worth
				kibAuthorUnsubmitted Done Inline Actions Can you explain this note, please? kib: Can you explain this note, please?
				rwatsonUnsubmitted Not Done Inline Actions I started making a comment and then decided not to make it, and experienced a user error. You can disregard this note. (I was going to suggest giving an example of such a situation, but ... I think it's OK without it.) rwatson: I started making a comment and then decided not to make it, and experienced a user error. You…