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 75chunks. 76Thus a platform with a hardware page size of 4096 bytes has 8 valid and 8 77dirty bits. 78These bits are generally set and cleared in groups based on the device 79block size of the device backing the page. 80Complete page's worth are often referred to using the 81.Dv VM_PAGE_BITS_ALL 82bitmask (i.e. 0xFF if the hardware page size is 4096). 83.Pp 84VM buffers also keep track of a byte-granular dirty range and valid range. 85This feature is normally only used by the NFS subsystem. 86I'm not sure why it is used at all, actually, since we have 87.Dv DEV_BSIZE 88valid/dirty granularity within the VM buffer. 89If a buffer dirty operation creates a 90.Sq hole , 91the dirty range will extend to cover the hole. 92If a buffer validation operation creates a 93.Sq hole 94the byte-granular valid range is left alone and will not take into account 95the new extension. 96Thus the whole byte-granular abstraction is considered a bad hack and it 97would be nice if we could get rid of it completely. 98.Pp 99A VM buffer is capable of mapping the underlying VM cache pages into KVM in 100order to allow the kernel to directly manipulate the data associated with 101the 102.Ft ( vnode , Fa b_offset , Fa b_size ) . 103The kernel typically unmaps VM buffers the moment they are no longer needed 104but often keeps the 105.Ft struct buf 106structure instantiated and even 107.Fa bp->b_pages 108array instantiated despite having unmapped them from KVM. 109If a page making up a VM buffer is about to undergo I/O, the system typically 110unmaps it from KVM and replaces the page in the 111.Fa b_pages[] 112array with a placemarker called 113.Fa bogus_page . 114The placemarker forces any kernel subsystems referencing the associated 115.Ft struct buf 116to re-lookup the associated page. 117I believe the placemarker hack is used to allow sophisticated devices 118such as filesystem devices to remap underlying pages in order to deal with, 119for example, remapping a file fragment into a file block. 120.Pp 121VM buffers are used to track I/O operations within the kernel. 122Unfortunately, the I/O implementation is also somewhat of a hack because 123the kernel wants to clear the dirty bit on the underlying pages the moment 124it queues the I/O to the VFS device, not when the physical I/O is actually 125initiated. 126This can create confusion within filesystem devices that use delayed-writes 127because you wind up with pages marked clean that are actually still dirty. 128If not treated carefully, these pages could be thrown away! 129Indeed, a number of serious bugs related to this hack were not fixed until 130the 131.Fx 2.2.8 / 3.0 132release. 133The kernel uses an instantiated VM buffer (i.e. 134.Ft struct buf ) 135to placemark pages in this special state. 136The buffer is typically flagged 137.Dv B_DELWRI . 138When a device no longer needs a buffer it typically flags it as 139.Dv B_RELBUF . 140Due to the underlying pages being marked clean, the 141.Dv B_DELWRI | B_RELBUF 142combination must be interpreted to mean that the buffer is still actually 143dirty and must be written to its backing store before it can actually be 144released. 145In the case where 146.Dv B_DELWRI 147is not set, the underlying dirty pages are still properly marked as dirty 148and the buffer can be completely freed without losing that clean/dirty state 149information. 150.\"( XXX do we have to check other flags in regards to this situation ??? ). 151.Pp 152The kernel reserves a portion of its KVM space to hold VM Buffer's data 153maps. 154Even though this is virtual space (since the buffers are mapped from the 155buffer cache), we cannot make it arbitrarily large because instantiated 156VM Buffers 157.Ft ( struct buf Ap s ) 158prevent their underlying pages in the buffer cache from being freed. 159This can complicate the life of the paging system. 160.\" .Sh SEE ALSO 161.\" .Xr <fillmein> 9 162.Sh HISTORY 163The 164.Nm 165manual page was originally written by 166.An Matthew Dillon 167and first appeared in 168.Fx 3.1 , 169December 1998. 170