/* * Copyright (c) 2000-2005 Apple Computer, Inc. All rights reserved. * * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. The rights granted to you under the License * may not be used to create, or enable the creation or redistribution of, * unlawful or unlicensed copies of an Apple operating system, or to * circumvent, violate, or enable the circumvention or violation of, any * terms of an Apple operating system software license agreement. * * Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ */ /* Copyright (c) 1995 NeXT Computer, Inc. All Rights Reserved */ /* * Copyright (c) 1982, 1986, 1989, 1993 * The Regents of the University of California. All rights reserved. * (c) UNIX System Laboratories, Inc. * All or some portions of this file are derived from material licensed * to the University of California by American Telephone and Telegraph * Co. or Unix System Laboratories, Inc. and are reproduced herein with * the permission of UNIX System Laboratories, Inc. * * 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. * 3. All advertising materials mentioning features or use of this software * must display the following acknowledgement: * This product includes software developed by the University of * California, Berkeley and its contributors. * 4. Neither the name of the University nor the names of its contributors * may be used to endorse or promote products derived from this software * without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. * * @(#)buf.h 8.9 (Berkeley) 3/30/95 */ #ifndef _SYS_BUF_H_ #define _SYS_BUF_H_ #include #include #include #define B_WRITE 0x00000000 /* Write buffer (pseudo flag). */ #define B_READ 0x00000001 /* Read buffer. */ #define B_ASYNC 0x00000002 /* Start I/O, do not wait. */ #define B_NOCACHE 0x00000004 /* Do not cache block after use. */ #define B_DELWRI 0x00000008 /* Delay I/O until buffer reused. */ #define B_LOCKED 0x00000010 /* Locked in core (not reusable). */ #define B_PHYS 0x00000020 /* I/O to user memory. */ #define B_CLUSTER 0x00000040 /* UPL based I/O generated by cluster layer */ #define B_PAGEIO 0x00000080 /* Page in/out */ #define B_META 0x00000100 /* buffer contains meta-data. */ #define B_RAW 0x00000200 /* Set by physio for raw transfers. */ #define B_FUA 0x00000400 /* Write-through disk cache(if supported) */ #define B_PASSIVE 0x00000800 /* PASSIVE I/Os are ignored by THROTTLE I/O */ #define B_IOSTREAMING 0x00001000 /* sequential access pattern detected */ #define B_THROTTLED_IO 0x00002000 /* low priority I/O */ /* * make sure to check when adding flags that * that the new flags don't overlap the definitions * in buf_internal.h */ __BEGIN_DECLS /*! @function buf_markaged @abstract Mark a buffer as "aged," i.e. as a good candidate to be discarded and reused after buf_brelse(). @param bp Buffer to mark. */ void buf_markaged(buf_t); /*! @function buf_markinvalid @abstract Mark a buffer as not having valid data and being ready for immediate reuse after buf_brelse(). @param bp Buffer to mark. */ void buf_markinvalid(buf_t); /*! @function buf_markdelayed @abstract Mark a buffer as a delayed write: mark it dirty without actually scheduling I/O. @discussion Data will be flushed to disk at some later time, not with brelse(). A sync()/fsync() or pressure necessitating reuse of the buffer will cause it to be written back to disk. @param bp Buffer to mark. */ void buf_markdelayed(buf_t); /*! @function buf_markeintr @abstract Mark a buffer as having been interrupted during I/O. @discussion Waiters for I/O to complete (buf_biowait()) will return with EINTR when woken up. buf_markeintr does not itself do a wakeup. @param bp Buffer to mark. */ void buf_markeintr(buf_t); /*! @function buf_markfua @abstract Mark a buffer for write through disk cache, if disk supports it. @param bp Buffer to mark. */ void buf_markfua(buf_t); /*! @function buf_fua @abstract Check if a buffer is marked for write through disk caches. @param bp Buffer to test. @return Nonzero if buffer is marked for write-through, 0 if not. */ int buf_fua(buf_t); /*! @function buf_valid @abstract Check if a buffer contains valid data. @param bp Buffer to test. @return Nonzero if buffer has valid data, 0 if not. */ int buf_valid(buf_t); /*! @function buf_fromcache @abstract Check if a buffer's data was found in core. @discussion Will return truth after a buf_getblk that finds a valid buffer in the cache or the relevant data in core (but not in a buffer). @param bp Buffer to test. @return Nonzero if we got this buffer's data without doing I/O, 0 if not. */ int buf_fromcache(buf_t); /*! @function buf_upl @abstract Get the upl (Universal Page List) associated with a buffer. @discussion Buffers allocated with buf_alloc() are not returned with a upl, and traditional buffers only have a upl while an I/O is in progress. @param bp Buffer whose upl to grab. @return Buffer's upl if it has one, else NULL. */ void * buf_upl(buf_t); /*! @function buf_uploffset @abstract Get the offset into a UPL at which this buffer begins. @discussion This function should only be called on iobufs, i.e. buffers allocated with buf_alloc(). @param bp Buffer whose uploffset to grab. @return Buffer's uploffset--does not check whether that value makes sense for this buffer. */ uint32_t buf_uploffset(buf_t); /*! @function buf_proc @abstract Get the process associated with this buffer. @discussion buf_proc() will generally return NULL; a process is currently only associated with a buffer in the event of a physio() call. @param bp Buffer whose associated process to find. @return Associated process, possibly NULL. */ proc_t buf_proc(buf_t); /*! @function buf_dirtyoff @abstract Get the starting offset of the dirty region associated with a buffer. @discussion The dirty offset is zero unless someone explicitly calls buf_setdirtyoff() (which the kernel does not). @param bp Buffer whose dirty offset to get. @return Dirty offset (0 if not explicitly changed). */ uint32_t buf_dirtyoff(buf_t); /*! @function buf_dirtyend @abstract Get the ending offset of the dirty region associated with a buffer. @discussion If the buffer's data was found incore and dirty, the dirty end is the size of the block; otherwise, unless someone outside of xnu explicitly changes it by calling buf_setdirtyend(), it will be zero. @param bp Buffer whose dirty end to get. @return 0 if buffer is found clean; size of buffer if found dirty. Can be set to any value by callers of buf_setdirtyend(). */ uint32_t buf_dirtyend(buf_t); /*! @function buf_setdirtyoff @abstract Set the starting offset of the dirty region associated with a buffer. @discussion This value is zero unless someone set it explicitly. @param bp Buffer whose dirty end to set. @return void. */ void buf_setdirtyoff(buf_t, uint32_t); /*! @function buf_setdirtyend @abstract Set the ending offset of the dirty region associated with a buffer. @discussion If the buffer's data was found incore and dirty, the dirty end is the size of the block; otherwise, unless someone outside of xnu explicitly changes it by calling buf_setdirtyend(), it will be zero. @param bp Buffer whose dirty end to set. @return void. */ void buf_setdirtyend(buf_t, uint32_t); /*! @function buf_error @abstract Get the error value associated with a buffer. @discussion Errors are set with buf_seterror(). @param bp Buffer whose error value to retrieve. @return Error value, directly. */ errno_t buf_error(buf_t); /*! @function buf_seterror @abstract Set an error value on a buffer. @param bp Buffer whose error value to set. @return void. */ void buf_seterror(buf_t, errno_t); /*! @function buf_setflags @abstract Set flags on a buffer. @discussion: buffer_flags |= flags @param bp Buffer whose flags to set. @param flags Flags to add to buffer's mask. B_LOCKED/B_NOCACHE/B_ASYNC/B_READ/B_WRITE/B_PAGEIO/B_FUA @return void. */ void buf_setflags(buf_t, int32_t); /*! @function buf_clearflags @abstract Clear flags on a buffer. @discussion: buffer_flags &= ~flags @param bp Buffer whose flags to clear. @param flags Flags to remove from buffer's mask. B_LOCKED/B_NOCACHE/B_ASYNC/B_READ/B_WRITE/B_PAGEIO/B_FUA @return void. */ void buf_clearflags(buf_t, int32_t); /*! @function buf_flags @abstract Get flags set on a buffer. @discussion Valid flags are B_LOCKED/B_NOCACHE/B_ASYNC/B_READ/B_WRITE/B_PAGEIO/B_FUA. @param bp Buffer whose flags to grab. @return flags. */ int32_t buf_flags(buf_t); /*! @function buf_reset @abstract Reset I/O flag state on a buffer. @discussion Clears current flags on a buffer (internal and external) and allows some new flags to be set. Used perhaps to prepare an iobuf for reuse. @param bp Buffer whose flags to grab. @param flags Flags to set on buffer: B_READ, B_WRITE, B_ASYNC, B_NOCACHE. @return void. */ void buf_reset(buf_t, int32_t); /*! @function buf_map @abstract Get virtual mappings for buffer data. @discussion For buffers created through buf_getblk() (i.e. traditional buffer cache usage), buf_map() just returns the address at which data was mapped by but_getblk(). For a B_CLUSTER buffer, i.e. an iobuf whose upl state is managed manually, there are two possibilities. If the buffer was created with an underlying "real" buffer through cluster_bp(), the mapping of the "real" buffer is returned. Otherwise, the buffer was created with buf_alloc() and buf_setupl() was subsequently called; buf_map() will call ubc_upl_map() to get a mapping for the buffer's upl and return the start of that mapping plus the buffer's upl offset (set in buf_setupl()). In the last case, buf_unmap() must later be called to tear down the mapping. NOTE: buf_map() does not set the buffer data pointer; this must be done with buf_setdataptr(). @param bp Buffer whose mapping to find or create. @param io_addr Destination for mapping address. @return 0 for success, ENOMEM if unable to map the buffer. */ errno_t buf_map(buf_t, caddr_t *); /*! @function buf_unmap @abstract Release mappings for buffer data. @discussion For buffers created through buf_getblk() (i.e. traditional buffer cache usage), buf_unmap() does nothing; buf_brelse() will take care of unmapping. For a B_CLUSTER buffer, i.e. an iobuf whose upl state is managed manually, there are two possibilities. If the buffer was created with an underlying "real" buffer through cluster_bp(), buf_unmap() does nothing; buf_brelse() on the underlying buffer will tear down the mapping. Otherwise, the buffer was created with buf_alloc() and buf_setupl() was subsequently called; buf_map() created the mapping. In this case, buf_unmap() will unmap the buffer. @param bp Buffer whose mapping to find or create. @param io_addr Destination for mapping address. @return 0 for success, EINVAL if unable to unmap buffer. */ errno_t buf_unmap(buf_t); /*! @function buf_setdrvdata @abstract Set driver-specific data on a buffer. @param bp Buffer whose driver-data to set. @param drvdata Opaque driver data. @return void. */ void buf_setdrvdata(buf_t, void *); /*! @function buf_setdrvdata @abstract Get driver-specific data from a buffer. @param bp Buffer whose driver data to get. @return Opaque driver data. */ void * buf_drvdata(buf_t); /*! @function buf_setfsprivate @abstract Set filesystem-specific data on a buffer. @param bp Buffer whose filesystem data to set. @param fsprivate Opaque filesystem data. @return void. */ void buf_setfsprivate(buf_t, void *); /*! @function buf_fsprivate @abstract Get filesystem-specific data from a buffer. @param bp Buffer whose filesystem data to get. @return Opaque filesystem data. */ void * buf_fsprivate(buf_t); /*! @function buf_blkno @abstract Get physical block number associated with a buffer, in the sense of VNOP_BLOCKMAP. @discussion When a buffer's physical block number is the same is its logical block number, then the physical block number is considered uninitialized. A physical block number of -1 indicates that there is no valid physical mapping (e.g. the logical block is invalid or corresponds to a sparse region in a file). Physical block number is normally set by the cluster layer or by buf_getblk(). @param bp Buffer whose physical block number to get. @return Block number. */ daddr64_t buf_blkno(buf_t); /*! @function buf_lblkno @abstract Get logical block number associated with a buffer. @discussion Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(), for example by buf_bread(). @param bp Buffer whose logical block number to get. @return Block number. */ daddr64_t buf_lblkno(buf_t); /*! @function buf_setblkno @abstract Set physical block number associated with a buffer. @discussion Physical block number is generally set by the cluster layer or by buf_getblk(). @param bp Buffer whose physical block number to set. @param blkno Block number to set. @return void. */ void buf_setblkno(buf_t, daddr64_t); /*! @function buf_setlblkno @abstract Set logical block number associated with a buffer. @discussion Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(), for example by buf_bread(). @param bp Buffer whose logical block number to set. @param lblkno Block number to set. @return void. */ void buf_setlblkno(buf_t, daddr64_t); /*! @function buf_count @abstract Get count of valid bytes in a buffer. This may be less than the space allocated to the buffer. @param bp Buffer whose byte count to get. @return Byte count. */ uint32_t buf_count(buf_t); /*! @function buf_size @abstract Get size of data region allocated to a buffer. @discussion May be larger than amount of valid data in buffer. @param bp Buffer whose size to get. @return Size. */ uint32_t buf_size(buf_t); /*! @function buf_resid @abstract Get a count of bytes which were not consumed by an I/O on a buffer. @discussion Set when an I/O operations completes. @param bp Buffer whose outstanding count to get. @return Count of unwritten/unread bytes. */ uint32_t buf_resid(buf_t); /*! @function buf_setcount @abstract Set count of valid bytes in a buffer. This may be less than the space allocated to the buffer. @param bp Buffer whose byte count to set. @param bcount Count to set. @return void. */ void buf_setcount(buf_t, uint32_t); /*! @function buf_setsize @abstract Set size of data region allocated to a buffer. @discussion May be larger than amount of valid data in buffer. Should be used by code which is manually providing storage for an iobuf, one allocated with buf_alloc(). @param bp Buffer whose size to set. @return void. */ void buf_setsize(buf_t, uint32_t); /*! @function buf_setresid @abstract Set a count of bytes outstanding for I/O in a buffer. @discussion Set when an I/O operations completes. Examples: called by IOStorageFamily when I/O completes, often called on an "original" buffer when using a manipulated buffer to perform I/O on behalf of the first. @param bp Buffer whose outstanding count to set. @return Count of unwritten/unread bytes. */ void buf_setresid(buf_t, uint32_t); /*! @function buf_setdataptr @abstract Set the address at which a buffer's data will be stored. @discussion In traditional buffer use, the data pointer will be set automatically. This routine is useful with iobufs (allocated with buf_alloc()). @param bp Buffer whose data pointer to set. @param data Pointer to data region. @return void. */ void buf_setdataptr(buf_t, uintptr_t); /*! @function buf_dataptr @abstract Get the address at which a buffer's data is stored; for iobufs, this must be set with buf_setdataptr(). See buf_map(). @param bp Buffer whose data pointer to retrieve. @return Data pointer; NULL if unset. */ uintptr_t buf_dataptr(buf_t); /*! @function buf_vnode @abstract Get the vnode associated with a buffer. @discussion Every buffer is associated with a file. Because there is an I/O in flight, there is an iocount on this vnode; it is returned WITHOUT an extra iocount, and vnode_put() need NOT be called. @param bp Buffer whose vnode to retrieve. @return Buffer's vnode. */ vnode_t buf_vnode(buf_t); /*! @function buf_setvnode @abstract Set the vnode associated with a buffer. @discussion This call need not be used on traditional buffers; it is for use with iobufs. @param bp Buffer whose vnode to set. @param vp The vnode to attach to the buffer. @return void. */ void buf_setvnode(buf_t, vnode_t); /*! @function buf_setdevice @abstract Set the device associated with a buffer. @discussion A buffer's device is set in buf_strategy() (or in buf_getblk() if the file is a device). It is also set on an iobuf if buf_alloc() is passed a device vnode. @param bp Buffer whose device ID to set. @param vp Device to set on the buffer. @return 0 for success, EINVAL if vp is not a device file. */ errno_t buf_setdevice(buf_t, vnode_t); /*! @function buf_strategy @abstract Pass an I/O request for a buffer down to the device layer. @discussion This is one of the most important routines in the buffer cache layer. For buffers obtained through buf_getblk, it handles finding physical block numbers for the I/O (with VNOP_BLKTOOFF and VNOP_BLOCKMAP), packaging the I/O into page-sized chunks, and initiating I/O on the disk by calling the device's strategy routine. If a buffer's UPL has been set manually with buf_setupl(), it assumes that the request is already correctly configured with a block number and a size divisible by page size and will just call directly to the device. @param devvp Device on which to perform I/O @param ap vnop_strategy_args structure (most importantly, a buffer). @return 0 for success, or errors from filesystem or device layers. */ errno_t buf_strategy(vnode_t, void *); /* * Flags for buf_invalblkno() */ #define BUF_WAIT 0x01 /*! @function buf_invalblkno @abstract Invalidate a filesystem logical block in a file. @discussion buf_invalblkno() tries to make the data for a given block in a file invalid; if the buffer for that block is found in core and is not busy, we mark it invalid and call buf_brelse() (see "flags" param for what happens if the buffer is busy). buf_brelse(), noticing that it is invalid, will will return the buffer to the empty-buffer list and tell the VM subsystem to abandon the relevant pages. Data will not be written to backing store--it will be cast aside. Note that this function will only work if the block in question has been obtained with a buf_getblk(). If data has been read into core without using traditional buffer cache routines, buf_invalblkno() will not be able to invalidate it--this includes the use of iobufs. @param bp Buffer whose block to invalidate. @param lblkno Logical block number. @param flags BUF_WAIT: wait for busy buffers to become unbusy and invalidate them then. Otherwise, just return EBUSY for busy blocks. @return 0 for success, EINVAL if vp is not a device file. */ errno_t buf_invalblkno(vnode_t, daddr64_t, int); /*! @function buf_callback @abstract Get the function set to be called when I/O on a buffer completes. @discussion A function returned by buf_callback was originally set with buf_setcallback(). @param bp Buffer whose callback to get. @return 0 for success, or errors from filesystem or device layers. */ void * buf_callback(buf_t); /*! @function buf_setcallback @abstract Set a function to be called once when I/O on a buffer completes. @discussion A one-shot callout set with buf_setcallback() will be called from buf_biodone() when I/O completes. It will be passed the "transaction" argument as well as the buffer. buf_setcallback() also marks the buffer as B_ASYNC. @param bp Buffer whose callback to set. @param callback function to use as callback. @param transaction Additional argument to callback function. @return 0; always succeeds. */ errno_t buf_setcallback(buf_t, void (*)(buf_t, void *), void *); /*! @function buf_setupl @abstract Set the UPL (Universal Page List), and offset therein, on a buffer. @discussion buf_setupl() should only be called on buffers allocated with buf_alloc(). A subsequent call to buf_map() will map the UPL and give back the address at which data begins. After buf_setupl() is called, a buffer is marked B_CLUSTER; when this is the case, buf_strategy() assumes that a buffer is correctly configured to be passed to the device layer without modification. Passing a NULL upl will clear the upl and the B_CLUSTER flag on the buffer. @param bp Buffer whose upl to set. @param upl UPL to set in the buffer. @parma offset Offset within upl at which relevant data begin. @return 0 for success, EINVAL if the buffer was not allocated with buf_alloc(). */ errno_t buf_setupl(buf_t, upl_t, uint32_t); /*! @function buf_clone @abstract Clone a buffer with a restricted range and an optional callback. @discussion Generates a buffer which is identical to its "bp" argument except that it spans a subset of the data of the original. The buffer to be cloned should have been allocated with buf_alloc(). Checks its arguments to make sure that the data subset is coherent. Optionally, adds a callback function and argument to it to be called when I/O completes (as with buf_setcallback(), but B_ASYNC is not set). If the original buffer had a upl set through buf_setupl(), this upl is copied to the new buffer; otherwise, the original's data pointer is used raw. The buffer must be released with buf_free(). @param bp Buffer to clone. @param io_offset Offset, relative to start of data in original buffer, at which new buffer's data will begin. @param io_size Size of buffer region in new buffer, in the sense of buf_count(). @param iodone Callback to be called from buf_biodone() when I/O completes, in the sense of buf_setcallback(). @param arg Argument to pass to iodone() callback. @return NULL if io_offset/io_size combination is invalid for the buffer to be cloned; otherwise, the new buffer. */ buf_t buf_clone(buf_t, int, int, void (*)(buf_t, void *), void *); /*! @function buf_alloc @abstract Allocate an uninitialized buffer. @discussion A buffer returned by buf_alloc() is marked as busy and as an iobuf; it has no storage set up and must be set up using buf_setdataptr() or buf_setupl()/buf_map(). @param vp vnode to associate with the buffer: optionally NULL. If vp is a device file, then the buffer's associated device will be set. If vp is NULL, it can be set later with buf_setvnode(). @return New buffer. */ buf_t buf_alloc(vnode_t); /*! @function buf_free @abstract Free a buffer that was allocated with buf_alloc(). @discussion The storage (UPL, data pointer) associated with an iobuf must be freed manually. @param bp The buffer to free. @return void. */ void buf_free(buf_t); /* * flags for buf_invalidateblks */ #define BUF_WRITE_DATA 0x0001 /* write data blocks first */ #define BUF_SKIP_META 0x0002 /* skip over metadata blocks */ /*! @function buf_invalidateblks @abstract Invalidate all the blocks associated with a vnode. @discussion This function does for all blocks associated with a vnode what buf_invalblkno does for one block. Again, it will only be able to invalidate data which were populated with traditional buffer cache routines, i.e. by buf_getblk() and callers thereof. Unlike buf_invalblkno(), it can be made to write dirty data to disk rather than casting it aside. @param bp The buffer whose data to invalidate. @param flags BUF_WRITE_DATA: write dirty data to disk with VNOP_BWRITE() before kicking buffer cache entries out. BUF_SKIP_META: do not invalidate metadata blocks. @param slpflag Flags to pass to "msleep" while waiting to acquire busy buffers. @param slptimeo Timeout in "hz" (1/100 second) to wait for a buffer to become unbusy before waking from sleep and re-starting the scan. @return 0 for success, error values from msleep(). */ int buf_invalidateblks(vnode_t, int, int, int); /* * flags for buf_flushdirtyblks and buf_iterate */ #define BUF_SKIP_NONLOCKED 0x01 #define BUF_SKIP_LOCKED 0x02 #define BUF_SCAN_CLEAN 0x04 /* scan the clean buffers */ #define BUF_SCAN_DIRTY 0x08 /* scan the dirty buffers */ #define BUF_NOTIFY_BUSY 0x10 /* notify the caller about the busy pages during the scan */ #define BUF_RETURNED 0 #define BUF_RETURNED_DONE 1 #define BUF_CLAIMED 2 #define BUF_CLAIMED_DONE 3 /*! @function buf_flushdirtyblks @abstract Write dirty file blocks to disk. @param vp The vnode whose blocks to flush. @param wait Wait for writes to complete before returning. @param flags Can pass zero, meaning "flush all dirty buffers." BUF_SKIP_NONLOCKED: Skip buffers which are not busy when we encounter them. BUF_SKIP_LOCKED: Skip buffers which are busy when we encounter them. @param msg String to pass to msleep(). @return void. */ void buf_flushdirtyblks(vnode_t, int, int, const char *); /*! @function buf_iterate @abstract Perform some operation on all buffers associated with a vnode. @param vp The vnode whose buffers to scan. @param callout Function to call on each buffer. Should return one of: BUF_RETURNED: buf_iterate() should call buf_brelse() on the buffer. BUF_RETURNED_DONE: buf_iterate() should call buf_brelse() on the buffer and then stop iterating. BUF_CLAIMED: buf_iterate() should continue iterating (and not call buf_brelse()). BUF_CLAIMED_DONE: buf_iterate() should stop iterating (and not call buf_brelse()). @param flag BUF_SKIP_NONLOCKED: Skip buffers which are not busy when we encounter them. BUF_SKIP_LOCKED: Skip buffers which are busy when we encounter them. BUF_SCAN_CLEAN: Call out on clean buffers. BUF_SCAN_DIRTY: Call out on dirty buffers. BUF_NOTIFY_BUSY: If a buffer cannot be acquired, pass a NULL buffer to callout; otherwise, that buffer will be silently skipped. @param arg Argument to pass to callout in addition to buffer. @return void. */ void buf_iterate(vnode_t, int (*)(buf_t, void *), int, void *); /*! @function buf_clear @abstract Zero out the storage associated with a buffer. @discussion Calls buf_map() to get the buffer's data address; for a B_CLUSTER buffer (one which has had buf_setupl() called on it), it tries to map the buffer's UPL into memory; should only be called once during the life cycle of an iobuf (one allocated with buf_alloc()). @param bp The buffer to zero out. @return void. */ void buf_clear(buf_t); /*! @function buf_bawrite @abstract Start an asychronous write on a buffer. @discussion Calls VNOP_BWRITE to start the process of propagating an asynchronous write down to the device layer. Callers can wait for writes to complete at their discretion using buf_biowait(). When this function is called, data should already have been written to the buffer's data region. @param bp The buffer on which to initiate I/O. @param throttle If "throttle" is nonzero and more than VNODE_ASYNC_THROTTLE writes are in progress on this file, buf_bawrite() will block until the write count drops below VNODE_ASYNC_THROTTLE. If "throttle" is zero and the write count is high, it will fail with EWOULDBLOCK; the caller can decide whether to make a blocking call or pursue other opportunities. @return EWOULDBLOCK if write count is high and "throttle" is zero; otherwise, errors from VNOP_BWRITE. */ errno_t buf_bawrite(buf_t); /*! @function buf_bdwrite @abstract Mark a buffer for delayed write. @discussion Marks a buffer as waiting for delayed write and the current I/O as complete; data will be written to backing store before the buffer is reused, but it will not be queued for I/O immediately. Note that for buffers allocated with buf_alloc(), there are no such guarantees; you must take care of your own flushing to disk. If the number of delayed writes pending on the system is greater than an internal limit and the caller has not requested otherwise [see return_error] , buf_bdwrite() will unilaterally launch an asynchronous I/O with buf_bawrite() to keep the pile of delayed writes from getting too large. @param bp The buffer to mark for delayed write. @param return_error If the number of pending delayed writes systemwide is larger than an internal limit, return EAGAIN rather than doing an asynchronous write. @return EAGAIN for return_error != 0 case, 0 for succeess, errors from buf_bawrite. */ errno_t buf_bdwrite(buf_t); /*! @function buf_bwrite @abstract Write a buffer's data to backing store. @discussion Once the data in a buffer has been modified, buf_bwrite() starts sending it to disk by calling VNOP_STRATEGY. Unless B_ASYNC has been set on the buffer (by buf_setflags() or otherwise), data will have been written to disk when buf_bwrite() returns. See Bach (p 56). @param bp The buffer to write to disk. @return 0 for success; errors from buf_biowait(). */ errno_t buf_bwrite(buf_t); /*! @function buf_biodone @abstract Mark an I/O as completed. @discussion buf_biodone() should be called by whosoever decides that an I/O on a buffer is complete; for example, IOStorageFamily. It clears the dirty flag on a buffer and signals on the vnode that a write has completed with vnode_writedone(). If a callout or filter has been set on the buffer, that function is called. In the case of a callout, that function is expected to take care of cleaning up and freeing the buffer. Otherwise, if the buffer is marked B_ASYNC (e.g. it was passed to buf_bawrite()), then buf_biodone() considers itself justified in calling buf_brelse() to return it to free lists--no one is waiting for it. Finally, waiters on the bp (e.g. in buf_biowait()) are woken up. @param bp The buffer to mark as done with I/O. @return void. */ void buf_biodone(buf_t); /*! @function buf_biowait @abstract Wait for I/O on a buffer to complete. @discussion Waits for I/O on a buffer to finish, as marked by a buf_biodone() call. @param bp The buffer to wait on. @return 0 for a successful wait; nonzero the buffer has been marked as EINTR or had an error set on it. */ errno_t buf_biowait(buf_t); /*! @function buf_brelse @abstract Release any claim to a buffer, sending it back to free lists. @discussion buf_brelse() cleans up buffer state and releases a buffer to the free lists. If the buffer is not marked invalid and its pages are dirty (e.g. a delayed write was made), its data will be commited to backing store. If it is marked invalid, its data will be discarded completely. A valid, cacheable buffer will be put on a list and kept in the buffer hash so it can be found again; otherwise, it will be dissociated from its vnode and treated as empty. Which list a valid buffer is placed on depends on the use of buf_markaged(), whether it is metadata, and the B_LOCKED flag. A B_LOCKED buffer will not be available for reuse by other files, though its data may be paged out. Note that buf_brelse() is intended for use with traditionally allocated buffers. @param bp The buffer to release. @retrn void. */ void buf_brelse(buf_t); /*! @function minphys @abstract Adjust a buffer's count to be no more than maximum physical I/O transfer size for the host architecture. @discussion physio() takes as a parameter a function to bound transfer sizes for each VNOP_STRATEGY() call. minphys() is a default implementation. It calls buf_setcount() to make the buffer's count the min() of its current count and the max I/O size for the host architecture. @param bp The buffer whose byte count to modify. @return New byte count. */ u_int minphys(buf_t bp); /* * Flags for operation type in getblk() */ #define BLK_READ 0x01 /* buffer for read */ #define BLK_WRITE 0x02 /* buffer for write */ #define BLK_META 0x10 /* buffer for metadata */ /* * modifier for above flags... if set, getblk will only return * a bp that is already valid... i.e. found in the cache */ #define BLK_ONLYVALID 0x80000000 /*! @function buf_getblk @abstract Traditional buffer cache routine to get a buffer corresponding to a logical block in a file. @discussion buf_getblk() gets a buffer, not necessarily containing valid data, representing a block in a file. A metadata buffer will be returned with its own zone-allocated storage, managed by the traditional buffer-cache layer, whereas data buffers will be returned hooked into backing by the UBC (which in fact controls the caching of data). buf_getblk() first looks for the buffer header in cache; if the buffer is in-core but busy, buf_getblk() will wait for it to become unbusy, depending on the slpflag and slptimeo parameters. If the buffer is found unbusy and is a metadata buffer, it must already contain valid data and will be returned directly; data buffers will have a UPL configured to prepare for interaction with the underlying UBC. If the buffer is found in core, it will be marked as such and buf_fromcache() will return truth. A buffer is allocated and initialized (but not filled with data) if none is found in core. buf_bread(), buf_breadn(), buf_meta_bread(), and buf_meta_breadn() all return buffers obtained with buf_getblk(). @param vp File for which to get block. @param blkno Logical block number. @param size Size of block. @param slpflag Flag to pass to msleep() while waiting for buffer to become unbusy. @param slptimeo Time, in milliseconds, to wait for buffer to become unbusy. 0 means to wait indefinitely. @param operation BLK_READ: want a read buffer. BLK_WRITE: want a write buffer. BLK_META: want a metadata buffer. BLK_ONLYVALID: only return buffers which are found in core (do not allocate anew), and do not change buffer size. The last remark means that if a given logical block is found in core with a different size than what is requested, the buffer size will not be modified. @return Buffer found in core or newly allocated, either containing valid data or ready for I/O. */ buf_t buf_getblk(vnode_t, daddr64_t, int, int, int, int); /*! @function buf_geteblk @abstract Get a metadata buffer which is marked invalid and not associated with any vnode. @discussion A buffer is returned with zone-allocated storage of the specified size, marked B_META and invalid. It has no vnode and is not visible in the buffer hash. @param size Size of buffer. @return Always returns a new buffer. */ buf_t buf_geteblk(int); __END_DECLS /* Macros to clear/set/test flags. */ #define SET(t, f) (t) |= (f) #define CLR(t, f) (t) &= ~(f) #define ISSET(t, f) ((t) & (f)) #endif /* !_SYS_BUF_H_ */