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