git: 86a52e262a6f - main - Document vnode_pager_setsize(9)

[Konstantin Belousov]

On Wed, Apr 07, 2021 at 11:13:02AM +0000, Ka Ho Ng wrote:
> The branch main has been updated by khng:
> 
> URL: https://cgit.FreeBSD.org/src/commit/?id=86a52e262a6faf75ee34eaa801f6d8ddaad20733
> 
> commit 86a52e262a6faf75ee34eaa801f6d8ddaad20733
> Author:     Ka Ho Ng <khng at FreeBSD.org>
> AuthorDate: 2021-04-07 11:00:31 +0000
> Commit:     Ka Ho Ng <khng at FreeBSD.org>
> CommitDate: 2021-04-07 11:11:26 +0000
> 
>     Document vnode_pager_setsize(9)
I am sorry to say this, but the documentation is rather content-free.

Main outcome of vnode_pager_setsize() is that it defines which offsets
from mapping of the file are handled by the fault handler, and which
results in SIGBUS.

Clearing of the page cache is a secondary-level functionality, and more,
we allow to keep pages with indexes larger than the object size, on the
object queue.

>     
>     MFC after:      3 days
>     Sponsored by:   The FreeBSD Foundation
>     Reviewed by:    bcr
>     Approved by:    philip (mentor)
>     Differential Revision:  https://reviews.freebsd.org/D29408
> ---
>  share/man/man9/Makefile              |  1 +
>  share/man/man9/vnode_pager_setsize.9 | 74 ++++++++++++++++++++++++++++++++++++
>  2 files changed, 75 insertions(+)
> 
> diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
> index 52a5d373a417..efdd8b2f6e9c 100644
> --- a/share/man/man9/Makefile
> +++ b/share/man/man9/Makefile
> @@ -401,6 +401,7 @@ MAN=	accept_filter.9 \
>  	vn_isdisk.9 \
>  	vnet.9 \
>  	vnode.9 \
> +	vnode_pager_setsize.9 \
>  	VOP_ACCESS.9 \
>  	VOP_ACLCHECK.9 \
>  	VOP_ADVISE.9 \
> diff --git a/share/man/man9/vnode_pager_setsize.9 b/share/man/man9/vnode_pager_setsize.9
> new file mode 100644
> index 000000000000..c59a01796f20
> --- /dev/null
> +++ b/share/man/man9/vnode_pager_setsize.9
> @@ -0,0 +1,74 @@
> +.\"
> +.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
> +.\"
> +.\" Copyright (c) 2021 The FreeBSD Foundation
> +.\"
> +.\" Portions of this software were developed by Ka Ho Ng
> +.\" 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 AUTHOR 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 AUTHOR 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.
> +.\"
> +.Dd April 6, 2021
> +.Dt VNODE_PAGER_SETSIZE 9
> +.Os
> +.Sh NAME
> +.Nm vnode_pager_setsize
> +.Nd "notify the VM system about updates in the file size"
> +.Sh SYNOPSIS
> +.In sys/param.h
> +.In vm/vm.h
> +.In vm/vm_extern.h
> +.Ft void
> +.Fn vnode_pager_setsize "struct vnode *vp" "vm_ooffset_t nsize"
> +.Sh DESCRIPTION
> +.Nm
> +lets the VM system know about a change in size for a file.
> +Content beyond the new EOF specified by the
> +.Fa nsize
> +argument will be purged from the cache.
This is not true.  Only content between new EOF and old EOF is purged.
Removing everything past new EOF would break UFS, for instance.

> +This function is useful for use within file system code to implement
> +truncation in
> +.Xr VOP_SETATTR 9 .
> +.Sh IMPLEMENTATION NOTES
> +In case the new EOF specified by the
> +.Fa nsize
> +argument is not aligned to page boundaries,
> +partial-page area starting beyond the EOF will be zeroed.
> +In partial-page area,
> +for content occupying whole blocks within block
> +boundaries,
> +the dirty bits for the corresponding blocks will be cleared.
> +.Sh LOCKING
> +Writer lock of the VM object of
> +.Fa vp
> +will be held within the function.
Object is locked internally on as needed basis, but why would this matter
for anybody?

Again missed in the man page, but very important part of the interface
is that for correct and race-less use of the function, the vnode lock
must be held in exclusive mode. Otherwise truncation would interact
wrongly with page faults.

Unfortunately not all filesystems lock the vnode, the last offender is
ZFS.  For it, I had to add MNTK_VMSETSIZE_BUG to ignore the preconditions.

> +.Sh SEE ALSO
> +.Xr vnode 9
> +.Sh HISTORY
> +The
> +.Nm
> +manual page first appeared in
> +.Fx 14 .
> +.Sh AUTHORS
> +This
> +manual page was written by
> +.An Ka Ho Ng Aq Mt khng at FreeBSD.org .