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.\" 34.Dd December 21, 2004 35.Dt BUF 9 36.Os 37.Sh NAME 38.Nm buf 39.Nd "kernel buffer I/O scheme used in DragonFly VM system" 40.Sh DESCRIPTION 41The kernel implements a KVM abstraction of the buffer cache which allows it 42to map potentially disparate vm_page's into contiguous KVM for use by 43(mainly filesystem) devices and device I/O. 44This abstraction supports block sizes from 45.Dv DEV_BSIZE 46(usually 512) to upwards of several pages or more. 47It also supports a relatively primitive byte-granular valid range and dirty 48range currently hardcoded for use by NFS. 49The code implementing the VM Buffer abstraction is mostly concentrated in 50.Pa sys/kern/vfs_bio.c 51and 52.Pa sys/sys/buf.h . 53.Pp 54One of the most important things to remember when dealing with buffer pointers 55.Ft ( struct buf ) 56is that the underlying pages are mapped directly from the buffer cache. 57No data copying occurs in the scheme proper, though some filesystems 58such as UFS do have to copy a little when dealing with file fragments. 59The second most important thing to remember is that due to the underlying page 60mapping, the 61.Fa b_data 62base pointer in a buf is always 63.Em page 64aligned, not 65.Em block 66aligned. 67When you have a VM buffer representing some 68.Fa b_offset 69and 70.Fa b_size , 71the actual start of the buffer is 72.Fa ( b_data + ( Fa b_offset & Dv PAGE_MASK ) ) 73and not just 74.Fa b_data . 75Finally, the VM system's core buffer cache supports valid and dirty bits 76.Fa ( m->valid , m->dirty ) 77for pages in 78.Dv DEV_BSIZE chunks. 79Thus a platform with a hardware page size of 4096 bytes has 8 valid and 8 80dirty bits. 81These bits are generally set and cleared in groups based on the device 82block size of the device backing the page. 83Complete page's worth are often referred to using the 84.Dv VM_PAGE_BITS_ALL 85bitmask (i.e. 0xFF if the hardware page size is 4096). 86.Pp 87VM buffers also keep track of a byte-granular dirty range and valid range. 88This feature is normally only used by the NFS subsystem. 89I'm not sure why it is used at all, actually, since we have 90.Dv DEV_BSIZE 91valid/dirty granularity within the VM buffer. 92If a buffer dirty operation creates a 93.Sq hole , 94the dirty range will extend to cover the hole. 95If a buffer validation operation creates a 96.Sq hole 97the byte-granular valid range is left alone and will not take into account 98the new extension. 99Thus the whole byte-granular abstraction is considered a bad hack and it 100would be nice if we could get rid of it completely. 101.Pp 102A VM buffer is capable of mapping the underlying VM cache pages into KVM in 103order to allow the kernel to directly manipulate the data associated with 104the 105.Ft ( vnode , Fa b_offset , Fa b_size ) . 106The kernel typically unmaps VM buffers the moment they are no longer needed 107but often keeps the 108.Ft struct buf 109structure instantiated and even 110.Fa bp->b_pages 111array instantiated despite having unmapped them from KVM. 112If a page making up a VM buffer is about to undergo I/O, the system typically 113unmaps it from KVM and replaces the page in the 114.Fa b_pages[] 115array with a placemarker called 116.Fa bogus_page . 117The placemarker forces any kernel subsystems referencing the associated 118.Ft struct buf 119to re-lookup the associated page. 120I believe the placemarker hack is used to allow sophisticated devices 121such as filesystem devices to remap underlying pages in order to deal with, 122for example, remapping a file fragment into a file block. 123.Pp 124VM buffers are used to track I/O operations within the kernel. 125Unfortunately, the I/O implementation is also somewhat of a hack because 126the kernel wants to clear the dirty bit on the underlying pages the moment 127it queues the I/O to the VFS device, not when the physical I/O is actually 128initiated. 129This can create confusion within filesystem devices that use delayed-writes 130because you wind up with pages marked clean that are actually still dirty. 131If not treated carefully, these pages could be thrown away! 132Indeed, a number of serious bugs related to this hack were not fixed until 133the 134.Fx 2.2.8 / 3.0 135release. 136The kernel uses an instantiated VM buffer (i.e. 137.Ft struct buf ) 138to placemark pages in this special state. 139The buffer is typically flagged 140.Dv B_DELWRI . 141When a device no longer needs a buffer it typically flags it as 142.Dv B_RELBUF . 143Due to the underlying pages being marked clean, the 144.Dv B_DELWRI | B_RELBUF 145combination must be interpreted to mean that the buffer is still actually 146dirty and must be written to its backing store before it can actually be 147released. 148In the case where 149.Dv B_DELWRI 150is not set, the underlying dirty pages are still properly marked as dirty 151and the buffer can be completely freed without losing that clean/dirty state 152information. 153.\"( XXX do we have to check other flags in regards to this situation ??? ). 154.Pp 155The kernel reserves a portion of its KVM space to hold VM Buffer's data 156maps. 157Even though this is virtual space (since the buffers are mapped from the 158buffer cache), we cannot make it arbitrarily large because instantiated 159VM Buffers 160.Ft ( struct buf Ap s ) 161prevent their underlying pages in the buffer cache from being freed. 162This can complicate the life of the paging system. 163.\" .Sh SEE ALSO 164.\" .Xr <fillmein> 9 165.Sh HISTORY 166The 167.Nm 168manual page was originally written by 169.An Matthew Dillon 170and first appeared in 171.Fx 3.1 , 172December 1998. 173