Add VOP_READ_PGCACHE(9)

PR:	253894

(cherry picked from commit 55eb51ab6649c3c10bf201f82a4ec410fe4da4a2)

4 files changed, 137 insertions, 0 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 7b55bf8516c7..50e760d3e047 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -425,6 +425,7 @@ MAN=	accept_filter.9 \
 	VOP_PATHCONF.9 \
 	VOP_PRINT.9 \
 	VOP_RDWR.9 \
+	VOP_READ_PGCACHE.9 \
 	VOP_READDIR.9 \
 	VOP_READLINK.9 \
 	VOP_REALLOCBLKS.9 \
diff --git a/share/man/man9/VOP_RDWR.9 b/share/man/man9/VOP_RDWR.9
index 4719ebabd094..2de7f9c9e7d2 100644
--- a/share/man/man9/VOP_RDWR.9
+++ b/share/man/man9/VOP_RDWR.9
@@ -83,6 +83,7 @@ Data already in VMIO space.
 .El
 .Sh LOCKS
 The file should be locked on entry and will still be locked on exit.
+Rangelock covering the whole i/o range should be owned around the call.
 .Sh RETURN VALUES
 Zero is returned on success, otherwise an error code is returned.
 .Sh ERRORS
diff --git a/share/man/man9/VOP_READ_PGCACHE.9 b/share/man/man9/VOP_READ_PGCACHE.9
new file mode 100644
index 000000000000..3e6ae9be4fc7
--- /dev/null
+++ b/share/man/man9/VOP_READ_PGCACHE.9
@@ -0,0 +1,134 @@
+.\" Copyright (c) 2021 The FreeBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" 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 reads the contents of a file.
+The intent is to provide the data from caches, which do not require
+expensive operations or any disk 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.
+.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; it also might choose
+to not provide any data.
+In these cases, the
+.Fa uio
+must be advanced by the amount of read data,
+.Nm
+should return
+.Er EJUSTRETURN ,
+and VFS would handle the rest of the read operation using the
+.Xr VOP_READ 9 .
+.Pp
+The VFS layer does the same deadlock avoidance for accessing userspace
+pages from
+.Nm
+as for
+.Xr VOP_READ 9 .
+.Pp
+Vnode is not locked on the call entry and should not be locked on return.
+For a filesystem that requires vnode lock to return any data, it does
+not make sense to implement
+.Nm
+(and set
+.Dv VIRF_PGREAD
+flag) since VFS arranges the call to
+.Xr VOP_READ 9
+as needed.
+.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, see
+.Xr VOP_READ 9
+for the list.
+.It Fa cred
+The credentials of the caller.
+.El
+.Pp
+.Nm
+does not handle non-zero
+.Fa ioflag
+argument.
+.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.
+.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.
+The
+.Dv uio
+records should be updated according to the partial operation done.
+.Pp
+Otherwise an error code is returned,
+same as from
+.Xr VOP_READ 9
+.Sh SEE ALSO
+.Xr uiomove 9 ,
+.Xr vnode 9 ,
+.Xr VOP_READ 9
diff --git a/share/man/man9/vnode.9 b/share/man/man9/vnode.9
index 91360a755fbc..7a58f07b22b0 100644
--- a/share/man/man9/vnode.9
+++ b/share/man/man9/vnode.9
@@ -181,6 +181,7 @@ intertwining of VM Objects and Vnodes.
 .Xr VOP_PATHCONF 9 ,
 .Xr VOP_PRINT 9 ,
 .Xr VOP_RDWR 9 ,
+.Xr VOP_READ_PGCACHE 9 ,
 .Xr VOP_READDIR 9 ,
 .Xr VOP_READLINK 9 ,
 .Xr VOP_REALLOCBLKS 9 ,