]> git.saurik.com Git - apple/xnu.git/blobdiff - bsd/sys/buf.h
xnu-6153.41.3.tar.gz
[apple/xnu.git] / bsd / sys / buf.h
index 08216cac0e1e898b9eb60eb073a8d4222019eeed..f46094803d7d5caa5013e09d9b112cd49f72678d 100644 (file)
@@ -1,8 +1,8 @@
 /*
- * Copyright (c) 2000-2005 Apple Computer, Inc. All rights reserved.
+ * Copyright (c) 2000-2016 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
  * 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,
@@ -22,7 +22,7 @@
  * 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 */
@@ -67,7 +67,7 @@
  */
 
 #ifndef _SYS_BUF_H_
-#define        _SYS_BUF_H_
+#define _SYS_BUF_H_
 
 #include <sys/cdefs.h>
 #include <sys/kernel_types.h>
 #include <mach/memory_object_types.h>
 
 
-#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 */
-#define B_ENCRYPTED_IO 0x00004000      /* Encrypted I/O */
+#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 (deprecated) */
+#define B_ENCRYPTED_IO  0x00004000      /* Encrypted I/O */
+#define B_STATICCONTENT 0x00008000      /* Buffer is likely to remain unaltered */
+
 /*
  * make sure to check when adding flags that
  * that the new flags don't overlap the definitions
 __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.
*  @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);
+void    buf_markaged(buf_t bp);
 
 /*!
- @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.
*  @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);
+void    buf_markinvalid(buf_t bp);
 
 /*!
- @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.
*  @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);
+void    buf_markdelayed(buf_t bp);
 
-void   buf_markclean(buf_t);
+void    buf_markclean(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.
*  @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);
+void    buf_markeintr(buf_t bp);
 
 /*!
- @function buf_markfua
- @abstract Mark a buffer for write through disk cache, if disk supports it.
- @param bp Buffer to mark.
*  @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);
+void    buf_markfua(buf_t bp);
 
 /*!
- @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.
*  @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);
+int     buf_fua(buf_t bp);
 
 /*!
- @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.
*  @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);
+int     buf_valid(buf_t bp);
 
 /*!
- @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.
*  @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);
+int     buf_fromcache(buf_t bp);
 
 /*!
- @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.
*  @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);
+void *  buf_upl(buf_t bp);
 
 /*!
- @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.
*  @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);
+uint32_t buf_uploffset(buf_t bp);
 
 /*!
- @function buf_rcred
- @abstract Get the credential associated with a buffer for reading.
- @discussion No reference is taken; if the credential is to be held on to persistently, an additional
- reference must be taken with kauth_cred_ref.
- @param bp Buffer whose credential to grab.
- @return Credential if it exists, else NULL.
*  @function buf_rcred
*  @abstract Get the credential associated with a buffer for reading.
*  @discussion No reference is taken; if the credential is to be held on to persistently, an additional
*  reference must be taken with kauth_cred_ref.
*  @param bp Buffer whose credential to grab.
*  @return Credential if it exists, else NULL.
  */
-kauth_cred_t buf_rcred(buf_t);
+kauth_cred_t buf_rcred(buf_t bp);
 
 /*!
- @function buf_wcred
- @abstract Get the credential associated with a buffer for writing.
- @discussion No reference is taken; if the credential is to be held on to persistently, an additional
- reference must be taken with kauth_cred_ref.
- @param bp Buffer whose credential to grab.
- @return Credential if it exists, else NULL.
*  @function buf_wcred
*  @abstract Get the credential associated with a buffer for writing.
*  @discussion No reference is taken; if the credential is to be held on to persistently, an additional
*  reference must be taken with kauth_cred_ref.
*  @param bp Buffer whose credential to grab.
*  @return Credential if it exists, else NULL.
  */
-kauth_cred_t buf_wcred(buf_t);
+kauth_cred_t buf_wcred(buf_t bp);
 
 /*!
- @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.
*  @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);
+proc_t  buf_proc(buf_t bp);
 
 /*!
- @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).
*  @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);
+uint32_t buf_dirtyoff(buf_t bp);
 
 /*!
- @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().
*  @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);
+uint32_t buf_dirtyend(buf_t bp);
 
 /*!
- @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.
+ *  @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.
  */
-void   buf_setdirtyoff(buf_t, uint32_t);
+void    buf_setdirtyoff(buf_t bp, 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.
+ *  @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.
  */
-void   buf_setdirtyend(buf_t, uint32_t);
+void    buf_setdirtyend(buf_t bp, 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.
*  @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);
+errno_t buf_error(buf_t bp);
 
 /*!
- @function buf_seterror
- @abstract Set an error value on a buffer.
- @param bp Buffer whose error value to set.
- @return void.
+ *  @function buf_seterror
+ *  @abstract Set an error value on a buffer.
+ *  @param bp Buffer whose error value to set.
  */
-void   buf_seterror(buf_t, errno_t);
+void    buf_seterror(buf_t bp, 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.
+ *  @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
  */
-void   buf_setflags(buf_t, int32_t);
+void    buf_setflags(buf_t bp, int32_t flags);
 
 /*!
- @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.
+ *  @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
  */
-void   buf_clearflags(buf_t, int32_t);
+void    buf_clearflags(buf_t bp, int32_t flags);
 
 /*!
- @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.
*  @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);
+int32_t buf_flags(buf_t bp);
 
 /*!
- @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.
+ *  @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.
  */
-void   buf_reset(buf_t, int32_t);
+void    buf_reset(buf_t bp, int32_t flags);
 
 /*!
- @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.
*  @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 *);
+errno_t buf_map(buf_t bp, caddr_t *io_addr);
 
 /*!
- @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.
+ *  @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.
+ *  @return 0 for success, EINVAL if unable to unmap buffer.
  */
-errno_t        buf_unmap(buf_t);
+errno_t buf_unmap(buf_t bp);
 
 /*!
- @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.
+ *  @function buf_setdrvdata
+ *  @abstract Set driver-specific data on a buffer.
+ *  @param bp Buffer whose driver-data to set.
+ *  @param drvdata Opaque driver data.
  */
-void   buf_setdrvdata(buf_t, void *);
+void    buf_setdrvdata(buf_t bp, void *drvdata);
 
 /*!
- @function buf_setdrvdata
- @abstract Get driver-specific data from a buffer.
- @param bp Buffer whose driver data to get.
- @return Opaque driver data.
*  @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);
+void *  buf_drvdata(buf_t bp);
 
 /*!
- @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.
+ *  @function buf_setfsprivate
+ *  @abstract Set filesystem-specific data on a buffer.
+ *  @param bp Buffer whose filesystem data to set.
+ *  @param fsprivate Opaque filesystem data.
  */
-void   buf_setfsprivate(buf_t, void *);
+void    buf_setfsprivate(buf_t bp, void *fsprivate);
 
 /*!
- @function buf_fsprivate
- @abstract Get filesystem-specific data from a buffer.
- @param bp Buffer whose filesystem data to get.
- @return Opaque filesystem data.
*  @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);
+void *  buf_fsprivate(buf_t bp);
 
 /*!
- @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.
*  @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);
+daddr64_t buf_blkno(buf_t bp);
 
 /*!
- @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.
*  @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);
+daddr64_t buf_lblkno(buf_t bp);
 
 /*!
- @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.
+ *  @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.
  */
-void   buf_setblkno(buf_t, daddr64_t);
+void    buf_setblkno(buf_t bp, daddr64_t blkno);
 
 /*!
- @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.
+ *  @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.
  */
-void   buf_setlblkno(buf_t, daddr64_t);
+void    buf_setlblkno(buf_t bp, daddr64_t lblkno);
 
 /*!
- @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.
*  @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);
+uint32_t buf_count(buf_t bp);
 
 /*!
- @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.
*  @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);
+uint32_t buf_size(buf_t bp);
 
 /*!
- @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.
*  @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);
+uint32_t buf_resid(buf_t bp);
 
 /*!
- @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.
+ *  @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.
  */
-void   buf_setcount(buf_t, uint32_t);
+void    buf_setcount(buf_t bp, uint32_t bcount);
 
 /*!
- @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.
+ *  @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.
  */
-void   buf_setsize(buf_t, uint32_t);
+void    buf_setsize(buf_t bp, 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.
+ *  @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.
  */
-void   buf_setresid(buf_t, uint32_t);
+void    buf_setresid(buf_t bp, uint32_t resid);
 
 /*!
- @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.
+ *  @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.
  */
-void   buf_setdataptr(buf_t, uintptr_t);
+void    buf_setdataptr(buf_t bp, uintptr_t data);
 
 /*!
- @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.
*  @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);
+uintptr_t buf_dataptr(buf_t bp);
 
 /*!
- @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.
*  @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);
+vnode_t buf_vnode(buf_t bp);
 
 /*!
- @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.
+ *  @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.
  */
-void   buf_setvnode(buf_t, vnode_t);
+void    buf_setvnode(buf_t bp, vnode_t vp);
 
 /*!
- @function buf_device
- @abstract Get the device ID associated with a buffer.
- @discussion In traditional buffer use, this value is NODEV until buf_strategy() is called unless
- buf_getblk() was passed a device vnode.  It is set on an iobuf if buf_alloc() is passed a device 
- vnode or if buf_setdevice() is called.
- @param bp Buffer whose device ID to retrieve.
- @return Device id.
*  @function buf_device
*  @abstract Get the device ID associated with a buffer.
*  @discussion In traditional buffer use, this value is NODEV until buf_strategy() is called unless
+ *  buf_getblk() was passed a device vnode.  It is set on an iobuf if buf_alloc() is passed a device
*  vnode or if buf_setdevice() is called.
*  @param bp Buffer whose device ID to retrieve.
*  @return Device id.
  */
-dev_t  buf_device(buf_t);
+dev_t   buf_device(buf_t bp);
 
 /*!
- @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.
*  @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);
+errno_t buf_setdevice(buf_t bp, vnode_t vp);
 
 /*!
- @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_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 devvp, void *ap);
+
+/*
+ * 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 vp vnode 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 vp, daddr64_t lblkno, int flags);
 
 /*!
- @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.
*  @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);
+void * buf_callback(buf_t bp);
 
 /*!
- @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_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 bp, void (*callback)(buf_t, void *), void *transaction);
 
 /*!
- @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_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.
+ *  @param 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 bp, upl_t upl, uint32_t offset);
 
+/*!
+ *  @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 bp, int io_offset, int io_size, void (*iodone)(buf_t, void *), void *arg);
+
+
+/*!
+ *  @function buf_create_shadow
+ *  @abstract Create a shadow buffer with optional private storage and an optional callback.
+ *  @param bp Buffer to shadow.
+ *  @param force_copy If TRUE, do not link the shadaow to 'bp' and if 'external_storage' == NULL,
+ *  force a copy of the data associated with 'bp'.
+ *  @param external_storage If non-NULL, associate it with the new buffer as its storage instead of the
+ *  storage currently associated with 'bp'.
+ *  @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 the buffer to be shadowed is not B_META or a primary buffer (i.e. not a shadow buffer); otherwise, the new buffer.
+ */
 
-/*!
- @function buf_create_shadow
- @abstract Create a shadow buffer with optional private storage and an optional callback.
- @param bp Buffer to shadow.
- @param force_copy If TRUE, do not link the shadaow to 'bp' and if 'external_storage' == NULL,
- force a copy of the data associated with 'bp'.
- @param external_storage If non-NULL, associate it with the new buffer as its storage instead of the 
- storage currently associated with 'bp'.
- @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 the buffer to be shadowed is not B_META or a primary buffer (i.e. not a shadow buffer); otherwise, the new buffer.
-*/
-
-buf_t  buf_create_shadow(buf_t bp, boolean_t force_copy, uintptr_t external_storage, void (*iodone)(buf_t, void *), void *arg);
+buf_t   buf_create_shadow(buf_t bp, boolean_t force_copy, uintptr_t external_storage, void (*iodone)(buf_t, void *), void *arg);
 
 
-/*!
- @function buf_shadow
- @abstract returns true if 'bp' is a shadow of another buffer.
- @param bp Buffer to query.
- @return 1 if 'bp' is a shadow, 0 otherwise.
-*/
-int    buf_shadow(buf_t bp);
-
-
-/*!
- @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.
+/*!
+ *  @function buf_shadow
+ *  @abstract returns true if 'bp' is a shadow of another buffer.
+ *  @param bp Buffer to query.
+ *  @return 1 if 'bp' is a shadow, 0 otherwise.
  */
-buf_t  buf_alloc(vnode_t);
+int     buf_shadow(buf_t bp);
+
 
 /*!
- @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.
+ *  @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.
  */
-void   buf_free(buf_t);
+buf_t   buf_alloc(vnode_t vp);
+
+/*!
+ *  @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.
+ */
+void    buf_free(buf_t bp);
 
 /*
  * flags for buf_invalidateblks
  */
-#define        BUF_WRITE_DATA  0x0001          /* write data blocks first */
-#define        BUF_SKIP_META   0x0002          /* skip over metadata blocks */
-#define BUF_INVALIDATE_LOCKED  0x0004  /* force B_LOCKED blocks to be invalidated */
+#define BUF_WRITE_DATA  0x0001          /* write data blocks first */
+#define BUF_SKIP_META   0x0002          /* skip over metadata blocks */
+#define BUF_INVALIDATE_LOCKED   0x0004  /* force B_LOCKED blocks to be invalidated */
 
 /*!
- @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().
*  @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 vp The vnode 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);
+int     buf_invalidateblks(vnode_t vp, int flags, int slpflag, int slptimeo);
 
 /*
  * 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 buf_bread
- @abstract Synchronously read a block of a file.
- @discussion buf_bread() is the traditional way to read a single logical block of a file through the buffer cache. 
- It tries to find the buffer and corresponding page(s) in core, calls VNOP_STRATEGY if necessary to bring the data
- into memory, and waits for I/O to complete.  It should not be used to read blocks of greater than 4K (one VM page) 
- in size; use cluster routines for large reads.  Indeed, the cluster layer is a more efficient choice for reading DATA
- unless you need some finely-tuned semantics that it cannot provide.
- @param vp The file from which to read.
- @param blkno The logical (filesystem) block number to read.
- @param size Size of block; do not use for sizes > 4K.
- @param cred Credential to store and use for reading from disk if data are not already in core.
- @param bpp Destination pointer for buffer.
- @return 0 for success, or an error from buf_biowait().
- */
-errno_t        buf_bread(vnode_t, daddr64_t, int, kauth_cred_t, buf_t *);
-
-/*!
- @function buf_breadn
- @abstract Read a block from a file with read-ahead.
- @discussion buf_breadn() reads one block synchronously in the style of buf_bread() and fires
- off a specified set of asynchronous reads to improve the likelihood of future cache hits.  
- It should not be used to read blocks of greater than 4K (one VM page) in size; use cluster 
- routines for large reads.  Indeed, the cluster layer is a more efficient choice for reading DATA
- unless you need some finely-tuned semantics that it cannot provide.
- @param vp The file from which to read.
- @param blkno The logical (filesystem) block number to read synchronously.
- @param size Size of block; do not use for sizes > 4K.
- @param rablks Array of logical block numbers for asynchronous read-aheads.
- @param rasizes Array of block sizes for asynchronous read-aheads, each index corresponding to same index in "rablks."
- @param nrablks Number of entries in read-ahead arrays.
- @param cred Credential to store and use for reading from disk if data are not already in core.
- @param bpp Destination pointer for buffer.
- @return 0 for success, or an error from buf_biowait().
- */
-errno_t        buf_breadn(vnode_t, daddr64_t, int, daddr64_t *, int *, int, kauth_cred_t, buf_t *);
-
-/*!
- @function buf_meta_bread
- @abstract Synchronously read a metadata block of a file.
- @discussion buf_meta_bread() is the traditional way to read a single logical block of a file through the buffer cache. 
- It tries to find the buffer and corresponding page(s) in core, calls VNOP_STRATEGY if necessary to bring the data
- into memory, and waits for I/O to complete.  It should not be used to read blocks of greater than 4K (one VM page) 
- in size; use cluster routines for large reads.  Reading meta-data through the traditional buffer cache, unlike
- reading data, is efficient and encouraged, especially if the blocks being read are significantly smaller than page size.
- @param vp The file from which to read.
- @param blkno The logical (filesystem) block number to read.
- @param size Size of block; do not use for sizes > 4K.
- @param cred Credential to store and use for reading from disk if data are not already in core.
- @param bpp Destination pointer for buffer.
- @return 0 for success, or an error from buf_biowait().
- */
-errno_t        buf_meta_bread(vnode_t, daddr64_t, int, kauth_cred_t, buf_t *);
-
-/*!
- @function buf_meta_breadn
- @abstract Read a metadata block from a file with read-ahead.
- @discussion buf_meta_breadn() reads one block synchronously in the style of buf_meta_bread() and fires
- off a specified set of asynchronous reads to improve the likelihood of future cache hits.  
- It should not be used to read blocks of greater than 4K (one VM page) in size; use cluster 
- routines for large reads.
- @param vp The file from which to read.
- @param blkno The logical (filesystem) block number to read synchronously.
- @param size Size of block; do not use for sizes > 4K.
- @param rablks Array of logical block numbers for asynchronous read-aheads.
- @param rasizes Array of block sizes for asynchronous read-aheads, each index corresponding to same index in "rablks."
- @param nrablks Number of entries in read-ahead arrays.
- @param cred Credential to store and use for reading from disk if data are not already in core.
- @param bpp Destination pointer for buffer.
- @return 0 for success, or an error from buf_biowait().
- */
-errno_t        buf_meta_breadn(vnode_t, daddr64_t, int, daddr64_t *, int *, int, kauth_cred_t, 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);
-
-/*!
- @function physio 
- @abstract Perform I/O on a device to/from target memory described by a uio.
- @discussion physio() allows I/O directly from a device to user-space memory.  It waits
- for all I/O to complete before returning.
- @param f_strategy Strategy routine to call to initiate I/O.
- @param bp Buffer to configure and pass to strategy routine; can be NULL.
- @param dev Device on which to perform I/O.
- @param flags B_READ or B_WRITE.
- @param f_minphys Function which calls buf_setcount() to set a byte count which is suitably
- small for the device in question.  Returns byte count that has been set (or unchanged) on the buffer.
- @param uio UIO describing the I/O operation.
- @param blocksize Logical block size for this vnode.
- @return 0 for success; EFAULT for an invalid uio; errors from buf_biowait().
- */
-int    physio(void (*)(buf_t), buf_t, dev_t, int ,  u_int (*)(buf_t), struct uio *, int );
+#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().
+ */
+void    buf_flushdirtyblks(vnode_t vp, int wait, int flags, const char *msg);
+
+/*!
+ *  @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 flags
+ *  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.
+ */
+void    buf_iterate(vnode_t vp, int (*callout)(buf_t, void *), int flags, void *arg);
+
+/*!
+ *  @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.
+ */
+void    buf_clear(buf_t bp);
+
+/*!
+ *  @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.
+ *  @return EWOULDBLOCK if write count is high and "throttle" is zero; otherwise, errors from VNOP_BWRITE.
+ */
+errno_t buf_bawrite(buf_t bp);
+
+/*!
+ *  @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.
+ *  @return EAGAIN for return_error != 0 case, 0 for succeess, errors from buf_bawrite.
+ */
+errno_t buf_bdwrite(buf_t bp);
+
+/*!
+ *  @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 bp);
+
+/*!
+ *  @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.
+ */
+void    buf_biodone(buf_t bp);
+
+/*!
+ *  @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 bp);
+
+/*!
+ *  @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.
+ */
+void    buf_brelse(buf_t bp);
+
+/*!
+ *  @function buf_bread
+ *  @abstract Synchronously read a block of a file.
+ *  @discussion buf_bread() is the traditional way to read a single logical block of a file through the buffer cache.
+ *  It tries to find the buffer and corresponding page(s) in core, calls VNOP_STRATEGY if necessary to bring the data
+ *  into memory, and waits for I/O to complete.  It should not be used to read blocks of greater than 4K (one VM page)
+ *  in size; use cluster routines for large reads.  Indeed, the cluster layer is a more efficient choice for reading DATA
+ *  unless you need some finely-tuned semantics that it cannot provide.
+ *  @param vp The file from which to read.
+ *  @param blkno The logical (filesystem) block number to read.
+ *  @param size Size of block; do not use for sizes > 4K.
+ *  @param cred Credential to store and use for reading from disk if data are not already in core.
+ *  @param bpp Destination pointer for buffer.
+ *  @return 0 for success, or an error from buf_biowait().
+ */
+errno_t buf_bread(vnode_t vp, daddr64_t blkno, int size, kauth_cred_t cred, buf_t *bpp);
+
+/*!
+ *  @function buf_breadn
+ *  @abstract Read a block from a file with read-ahead.
+ *  @discussion buf_breadn() reads one block synchronously in the style of buf_bread() and fires
+ *  off a specified set of asynchronous reads to improve the likelihood of future cache hits.
+ *  It should not be used to read blocks of greater than 4K (one VM page) in size; use cluster
+ *  routines for large reads.  Indeed, the cluster layer is a more efficient choice for reading DATA
+ *  unless you need some finely-tuned semantics that it cannot provide.
+ *  @param vp The file from which to read.
+ *  @param blkno The logical (filesystem) block number to read synchronously.
+ *  @param size Size of block; do not use for sizes > 4K.
+ *  @param rablks Array of logical block numbers for asynchronous read-aheads.
+ *  @param rasizes Array of block sizes for asynchronous read-aheads, each index corresponding to same index in "rablks."
+ *  @param nrablks Number of entries in read-ahead arrays.
+ *  @param cred Credential to store and use for reading from disk if data are not already in core.
+ *  @param bpp Destination pointer for buffer.
+ *  @return 0 for success, or an error from buf_biowait().
+ */
+errno_t buf_breadn(vnode_t vp, daddr64_t blkno, int size, daddr64_t *rablks, int *rasizes, int nrablks, kauth_cred_t cred, buf_t *bpp);
+
+/*!
+ *  @function buf_meta_bread
+ *  @abstract Synchronously read a metadata block of a file.
+ *  @discussion buf_meta_bread() is the traditional way to read a single logical block of a file through the buffer cache.
+ *  It tries to find the buffer and corresponding page(s) in core, calls VNOP_STRATEGY if necessary to bring the data
+ *  into memory, and waits for I/O to complete.  It should not be used to read blocks of greater than 4K (one VM page)
+ *  in size; use cluster routines for large reads.  Reading meta-data through the traditional buffer cache, unlike
+ *  reading data, is efficient and encouraged, especially if the blocks being read are significantly smaller than page size.
+ *  @param vp The file from which to read.
+ *  @param blkno The logical (filesystem) block number to read.
+ *  @param size Size of block; do not use for sizes > 4K.
+ *  @param cred Credential to store and use for reading from disk if data are not already in core.
+ *  @param bpp Destination pointer for buffer.
+ *  @return 0 for success, or an error from buf_biowait().
+ */
+errno_t buf_meta_bread(vnode_t vp, daddr64_t blkno, int size, kauth_cred_t cred, buf_t *bpp);
+
+/*!
+ *  @function buf_meta_breadn
+ *  @abstract Read a metadata block from a file with read-ahead.
+ *  @discussion buf_meta_breadn() reads one block synchronously in the style of buf_meta_bread() and fires
+ *  off a specified set of asynchronous reads to improve the likelihood of future cache hits.
+ *  It should not be used to read blocks of greater than 4K (one VM page) in size; use cluster
+ *  routines for large reads.
+ *  @param vp The file from which to read.
+ *  @param blkno The logical (filesystem) block number to read synchronously.
+ *  @param size Size of block; do not use for sizes > 4K.
+ *  @param rablks Array of logical block numbers for asynchronous read-aheads.
+ *  @param rasizes Array of block sizes for asynchronous read-aheads, each index corresponding to same index in "rablks."
+ *  @param nrablks Number of entries in read-ahead arrays.
+ *  @param cred Credential to store and use for reading from disk if data are not already in core.
+ *  @param bpp Destination pointer for buffer.
+ *  @return 0 for success, or an error from buf_biowait().
+ */
+errno_t buf_meta_breadn(vnode_t vp, daddr64_t blkno, int size, daddr64_t *rablks, int *rasizes, int nrablks, kauth_cred_t cred, buf_t *bpp);
+
+/*!
+ *  @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);
+
+/*!
+ *  @function physio
+ *  @abstract Perform I/O on a device to/from target memory described by a uio.
+ *  @discussion physio() allows I/O directly from a device to user-space memory.  It waits
+ *  for all I/O to complete before returning.
+ *  @param f_strategy Strategy routine to call to initiate I/O.
+ *  @param bp Buffer to configure and pass to strategy routine; can be NULL.
+ *  @param dev Device on which to perform I/O.
+ *  @param flags B_READ or B_WRITE.
+ *  @param f_minphys Function which calls buf_setcount() to set a byte count which is suitably
+ *  small for the device in question.  Returns byte count that has been set (or unchanged) on the buffer.
+ *  @param uio UIO describing the I/O operation.
+ *  @param blocksize Logical block size for this vnode.
+ *  @return 0 for success; EFAULT for an invalid uio; errors from buf_biowait().
+ */
+int     physio(void (*f_strategy)(buf_t), buf_t bp, dev_t dev, int flags, u_int (*f_minphys)(buf_t), struct uio *uio, int blocksize);
 
 
 /*
  * 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 */
+#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
-                                  
+#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 vp, daddr64_t blkno, int size, int slpflag, int slptimeo, int operation);
+
+/*!
+ *  @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 size);
+
+/*!
+ *  @function buf_clear_redundancy_flags
+ *  @abstract Clear flags on a buffer.
+ *  @discussion buffer_redundancy_flags &= ~flags
+ *  @param bp Buffer whose flags to clear.
+ *  @param flags Flags to remove from buffer's mask
+ */
+void    buf_clear_redundancy_flags(buf_t bp, uint32_t flags);
+
+/*!
+ *  @function buf_redundancyflags
+ *  @abstract Get redundancy flags set on a buffer.
+ *  @param bp Buffer whose redundancy flags to grab.
+ *  @return flags.
+ */
+uint32_t        buf_redundancy_flags(buf_t bp);
+
 /*!
- @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.
+ *  @function buf_setredundancyflags
+ *  @abstract Set redundancy flags on a buffer.
+ *  @discussion buffer_redundancy_flags |= flags
+ *  @param bp Buffer whose flags to set.
+ *  @param flags Flags to add to buffer's redundancy flags
  */
-buf_t  buf_getblk(vnode_t, daddr64_t, int, int, int, int);
+void    buf_set_redundancy_flags(buf_t bp, uint32_t flags);
 
 /*!
- @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.
+ *  @function buf_attr
+ *  @abstract Gets the attributes for this buf.
+ *  @param bp Buffer whose attributes to get.
+ *  @return bufattr_t.
  */
-buf_t  buf_geteblk(int);
+bufattr_t buf_attr(buf_t bp);
 
 /*!
- @function buf_clear_redundancy_flags
- @abstract Clear flags on a buffer.
- @discussion: buffer_redundancy_flags &= ~flags
- @param bp Buffer whose flags to clear.
- @param flags Flags to remove from buffer's mask
- @return void.
+ *  @function buf_markstatic
+ *  @abstract Mark a buffer as being likely to contain static data.
+ *  @param bp Buffer to mark.
  */
-void   buf_clear_redundancy_flags(buf_t, uint32_t);
+void buf_markstatic(buf_t bp);
 
 /*!
- @function buf_redundancyflags
@abstract Get redundancy flags set on a buffer.
@param bp Buffer whose redundancy flags to grab.
@return flags.
+ *  @function buf_static
*  @abstract Check if a buffer contains static data.
*  @param bp Buffer to test.
*  @return Nonzero if buffer has static data, 0 otherwise.
  */
-uint32_t       buf_redundancy_flags(buf_t);
+int     buf_static(buf_t bp);
 
 /*!
- @function buf_setredundancyflags
- @abstract Set redundancy flags on a buffer.
- @discussion: buffer_redundancy_flags |= flags
- @param bp Buffer whose flags to set.
- @param flags Flags to add to buffer's redundancy flags
- @return void.
+ *  @function bufattr_markiosched
+ *  @abstract Mark a buffer as belonging to an io scheduled mount point
+ *  @param bap Buffer attributes to mark.
+ *  @discussion Marks the buffer so that spec_strategy() will know that it belongs to an io scheduled mount point
  */
-void   buf_set_redundancy_flags(buf_t, uint32_t);
+void bufattr_markioscheduled(bufattr_t bap);
 
 /*!
- @function buf_attr
- @abstract Gets the attributes for this buf.
@param bp Buffer whose attributes to get.
@return bufattr_t.
+ *  @function bufattr_iosched
+ *  @abstract Check if a buffer is marked as io scheduled
*  @param bap Buffer attributes to test.
*  @return Nonzero if the buffer is marked io scheduled, 0 otherwise.
  */
-bufattr_t buf_attr(buf_t);
+int bufattr_ioscheduled(bufattr_t bap);
 
 #ifdef KERNEL_PRIVATE
-void   buf_setfilter(buf_t, void (*)(buf_t, void *), void *, void (**)(buf_t, void *), void **);
+void    buf_setfilter(buf_t, void (*)(buf_t, void *), void *, void(**)(buf_t, void *), void **);
+
+/* bufattr allocation/duplication/deallocation functions */
+bufattr_t bufattr_alloc(void);
+bufattr_t bufattr_dup(bufattr_t bap);
+void bufattr_free(bufattr_t bap);
+
+/*!
+ *  @function bufattr_cpx
+ *  @abstract Returns a pointer to a cpx_t structure.
+ *  @param bap Buffer Attribute whose cpx_t structure you wish to get.
+ *  @return Returns a cpx_t structure, or NULL if not valid
+ */
+struct cpx *bufattr_cpx(bufattr_t bap);
+
+/*!
+ *  @function bufattr_setcpx
+ *  @abstract Set the cp_ctx on a buffer attribute.
+ *  @param bap Buffer Attribute that you wish to change
+ */
+void bufattr_setcpx(bufattr_t bap, struct cpx *cpx);
+
+/*!
+ *  @function bufattr_cpoff
+ *  @abstract Gets the file offset on the buffer.
+ *  @param bap Buffer Attribute whose file offset value is used
+ */
+uint64_t bufattr_cpoff(bufattr_t bap);
+
+/*!
+ *  @function bufattr_setcpoff
+ *  @abstract Set the file offset for a content protected I/O on
+ *  a buffer attribute.
+ *  @param bap Buffer Attribute whose cp file offset has to be set
+ */
+void bufattr_setcpoff(bufattr_t bap, uint64_t);
+
+/*!
+ *  @function bufattr_rawencrypted
+ *  @abstract Check if a buffer contains raw encrypted data.
+ *  @param bap Buffer attribute to test.
+ *  @return Nonzero if buffer has raw encrypted data, 0 otherwise.
+ */
+int bufattr_rawencrypted(bufattr_t bap);
+
+/*!
+ *  @function bufattr_markgreedymode
+ *  @abstract Mark a buffer to use the greedy mode for writing.
+ *  @param bap Buffer attributes to mark.
+ *  @discussion Greedy Mode: request improved write performance from the underlying device at the expense of storage efficiency
+ */
+void bufattr_markgreedymode(bufattr_t bap);
 
+/*!
+ *  @function bufattr_greedymode
+ *  @abstract Check if a buffer is written using the Greedy Mode
+ *  @param bap Buffer attributes to test.
+ *  @discussion Greedy Mode: request improved write performance from the underlying device at the expense of storage efficiency
+ *  @return Nonzero if buffer uses greedy mode, 0 otherwise.
+ */
+int     bufattr_greedymode(bufattr_t bap);
 
 /*!
- @function buf_getcpaddr
@abstract Set the address of cp_entry on a buffer.
- @param bp Buffer whose cp entry value has to be set
- @return void.
+ *  @function bufattr_markisochronous
*  @abstract Mark a buffer to use the isochronous throughput mode for writing.
+ *  @param bap Buffer attributes to mark.
+ *  @discussion isochronous mode: request improved write performance from the underlying device at the expense of storage efficiency
  */
-void buf_setcpaddr(buf_t, void *);
+void bufattr_markisochronous(bufattr_t bap);
 
 /*!
- @function buf_getcpaddr
- @abstract Get the address of cp_entry on a buffer.
- @param bp Buffer whose error value to set.
- @return int.
+ *  @function bufattr_isochronous
+ *  @abstract Check if a buffer is written using the isochronous
+ *  @param bap Buffer attributes to test.
+ *  @discussion isochronous mode: request improved write performance from the underlying device at the expense of storage efficiency
+ *  @return Nonzero if buffer uses isochronous mode, 0 otherwise.
  */
-void *buf_getcpaddr(buf_t);
+int     bufattr_isochronous(bufattr_t bap);
+
 
 /*!
@function buf_throttled
- @abstract Check if a buffer is throttled.
- @param bap Buffer attribute to test.
- @return Nonzero if the buffer is throttled, 0 otherwise.
*  @function bufattr_throttled
*  @abstract Check if a buffer is throttled.
*  @param bap Buffer attribute to test.
*  @return Nonzero if the buffer is throttled, 0 otherwise.
  */
 int bufattr_throttled(bufattr_t bap);
-#endif /* KERNEL_PRIVATE */
 
+/*!
+ *  @function bufattr_passive
+ *  @abstract Check if a buffer is marked passive.
+ *  @param bap Buffer attribute to test.
+ *  @return Nonzero if the buffer is marked passive, 0 otherwise.
+ */
+int bufattr_passive(bufattr_t bap);
+
+/*!
+ *  @function bufattr_nocache
+ *  @abstract Check if a buffer has nocache attribute.
+ *  @param bap Buffer attribute to test.
+ *  @return Nonzero if the buffer is not cached, 0 otherwise.
+ */
+int bufattr_nocache(bufattr_t bap);
+
+/*!
+ *  @function bufattr_meta
+ *  @abstract Check if a buffer has the bufattr meta attribute.
+ *  @param bap Buffer attribute to test.
+ *  @return Nonzero if the buffer has meta attribute, 0 otherwise.
+ */
+
+int bufattr_meta(bufattr_t bap);
+
+/*!
+ *  @function bufattr_markmeta
+ *  @abstract Set the bufattr meta attribute.
+ *  @param bap Buffer attribute to manipulate.
+ */
+void bufattr_markmeta(bufattr_t bap);
+
+
+/*!
+ *  @function bufattr_delayidlesleep
+ *  @abstract Check if a buffer is marked to delay idle sleep on disk IO.
+ *  @param bap Buffer attribute to test.
+ *  @return Nonzero if the buffer is marked to delay idle sleep on disk IO, 0 otherwise.
+ */
+int bufattr_delayidlesleep(bufattr_t bap);
+
+/*!
+ *  @function buf_kernel_addrperm_addr
+ *  @abstract Obfuscate the buf pointers.
+ *  @param addr Buf_t pointer.
+ *  @return Obfuscated pointer if addr is non zero, 0 otherwise.
+ */
+vm_offset_t buf_kernel_addrperm_addr(void * addr);
+
+/*!
+ *  @function bufattr_markquickcomplete
+ *  @abstract Mark a buffer to hint quick completion to the driver.
+ *  @discussion This flag hints the storage driver that some thread is waiting for this I/O to complete.
+ *  It should therefore attempt to complete it as soon as possible at the cost of device efficiency.
+ *  @param bap Buffer attributes to mark.
+ */
+void bufattr_markquickcomplete(bufattr_t bap);
+
+/*!
+ *  @function bufattr_quickcomplete
+ *  @abstract Check if a buffer is marked for quick completion
+ *  @discussion This flag hints the storage driver that some thread is waiting for this I/O to complete.
+ *  It should therefore attempt to complete it as soon as possible at the cost of device efficiency.
+ *  @param bap Buffer attribute to test.
+ *  @return Nonzero if the buffer is marked for quick completion, 0 otherwise.
+ */
+int bufattr_quickcomplete(bufattr_t bap);
+
+int     count_lock_queue(void);
+
+/*
+ * Flags for buf_acquire
+ */
+#define BAC_NOWAIT              0x01    /* Don't wait if buffer is busy */
+#define BAC_REMOVE              0x02    /* Remove from free list once buffer is acquired */
+#define BAC_SKIP_NONLOCKED      0x04    /* Don't return LOCKED buffers */
+#define BAC_SKIP_LOCKED         0x08    /* Only return LOCKED buffers */
+
+errno_t buf_acquire(buf_t, int, int, int);
+
+buf_t   buf_create_shadow_priv(buf_t bp, boolean_t force_copy, uintptr_t external_storage, void (*iodone)(buf_t, void *), void *arg);
+
+void    buf_drop(buf_t);
+
+#endif /* KERNEL_PRIVATE */
 
 __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))
+#define SET(t, f)       (t) |= (f)
+#define CLR(t, f)       (t) &= ~(f)
+#define ISSET(t, f)     ((t) & (f))
 
 
 #endif /* !_SYS_BUF_H_ */