1.\" Copyright (c) 1998 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD: src/share/man/man9/buf.9,v 1.5.2.5 2001/12/17 11:30:18 ru Exp $ 29.\" 30.Dd December 21, 2004 31.Dt BUF 9 32.Os 33.Sh NAME 34.Nm buf 35.Nd "kernel buffer I/O scheme used in DragonFly VM system" 36.Sh DESCRIPTION 37The kernel implements a KVM abstraction of the buffer cache which allows it 38to map potentially disparate vm_page's into contiguous KVM for use by 39(mainly filesystem) devices and device I/O. 40This abstraction supports block sizes from 41.Dv DEV_BSIZE 42(usually 512) to upwards of several pages or more. 43It also supports a relatively primitive byte-granular valid range and dirty 44range currently hardcoded for use by NFS. 45The code implementing the VM Buffer abstraction is mostly concentrated in 46.Pa sys/kern/vfs_bio.c 47and 48.Pa sys/sys/buf.h . 49.Pp 50One of the most important things to remember when dealing with buffer pointers 51.Ft ( struct buf ) 52is that the underlying pages are mapped directly from the buffer cache. 53No data copying occurs in the scheme proper, though some filesystems 54such as UFS do have to copy a little when dealing with file fragments. 55The second most important thing to remember is that due to the underlying page 56mapping, the 57.Fa b_data 58base pointer in a buf is always 59.Em page 60aligned, not 61.Em block 62aligned. 63When you have a VM buffer representing some 64.Fa b_offset 65and 66.Fa b_size , 67the actual start of the buffer is 68.Fa ( b_data + ( Fa b_offset & Dv PAGE_MASK ) ) 69and not just 70.Fa b_data . 71Finally, the VM system's core buffer cache supports valid and dirty bits 72.Fa ( m->valid , m->dirty ) 73for pages in 74.Dv DEV_BSIZE chunks. 75Thus a platform with a hardware page size of 4096 bytes has 8 valid and 8 76dirty bits. 77These bits are generally set and cleared in groups based on the device 78block size of the device backing the page. 79Complete page's worth are often referred to using the 80.Dv VM_PAGE_BITS_ALL 81bitmask (i.e. 0xFF if the hardware page size is 4096). 82.Pp 83VM buffers also keep track of a byte-granular dirty range and valid range. 84This feature is normally only used by the NFS subsystem. 85I'm not sure why it is used at all, actually, since we have 86.Dv DEV_BSIZE 87valid/dirty granularity within the VM buffer. 88If a buffer dirty operation creates a 89.Sq hole , 90the dirty range will extend to cover the hole. 91If a buffer validation operation creates a 92.Sq hole 93the byte-granular valid range is left alone and will not take into account 94the new extension. 95Thus the whole byte-granular abstraction is considered a bad hack and it 96would be nice if we could get rid of it completely. 97.Pp 98A VM buffer is capable of mapping the underlying VM cache pages into KVM in 99order to allow the kernel to directly manipulate the data associated with 100the 101.Ft ( vnode , Fa b_offset , Fa b_size ) . 102The kernel typically unmaps VM buffers the moment they are no longer needed 103but often keeps the 104.Ft struct buf 105structure instantiated and even 106.Fa bp->b_pages 107array instantiated despite having unmapped them from KVM. 108If a page making up a VM buffer is about to undergo I/O, the system typically 109unmaps it from KVM and replaces the page in the 110.Fa b_pages[] 111array with a placemarker called 112.Fa bogus_page . 113The placemarker forces any kernel subsystems referencing the associated 114.Ft struct buf 115to re-lookup the associated page. 116I believe the placemarker hack is used to allow sophisticated devices 117such as filesystem devices to remap underlying pages in order to deal with, 118for example, remapping a file fragment into a file block. 119.Pp 120VM buffers are used to track I/O operations within the kernel. 121Unfortunately, the I/O implementation is also somewhat of a hack because 122the kernel wants to clear the dirty bit on the underlying pages the moment 123it queues the I/O to the VFS device, not when the physical I/O is actually 124initiated. 125This can create confusion within filesystem devices that use delayed-writes 126because you wind up with pages marked clean that are actually still dirty. 127If not treated carefully, these pages could be thrown away! 128Indeed, a number of serious bugs related to this hack were not fixed until 129the 130.Fx 2.2.8 / 3.0 131release. 132The kernel uses an instantiated VM buffer (i.e. 133.Ft struct buf ) 134to placemark pages in this special state. 135The buffer is typically flagged 136.Dv B_DELWRI . 137When a device no longer needs a buffer it typically flags it as 138.Dv B_RELBUF . 139Due to the underlying pages being marked clean, the 140.Dv B_DELWRI | B_RELBUF 141combination must be interpreted to mean that the buffer is still actually 142dirty and must be written to its backing store before it can actually be 143released. 144In the case where 145.Dv B_DELWRI 146is not set, the underlying dirty pages are still properly marked as dirty 147and the buffer can be completely freed without losing that clean/dirty state 148information. 149.\"( XXX do we have to check other flags in regards to this situation ??? ). 150.Pp 151The kernel reserves a portion of its KVM space to hold VM Buffer's data 152maps. 153Even though this is virtual space (since the buffers are mapped from the 154buffer cache), we cannot make it arbitrarily large because instantiated 155VM Buffers 156.Ft ( struct buf Ap s ) 157prevent their underlying pages in the buffer cache from being freed. 158This can complicate the life of the paging system. 159.\" .Sh SEE ALSO 160.\" .Xr <fillmein> 9 161.Sh HISTORY 162The 163.Nm 164manual page was originally written by 165.An Matthew Dillon 166and first appeared in 167.Fx 3.1 , 168December 1998. 169