+ * make sure to check when adding flags that
+ * that the new flags don't overlap the definitions
+ * in buf_internal.h
+ */
+
+__BEGIN_DECLS
+
+/*!
+ * @function buf_markaged
+ * @abstract Mark a buffer as "aged," i.e. as a good candidate to be discarded and reused after buf_brelse().
+ * @param bp Buffer to mark.
+ */
+void buf_markaged(buf_t 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.
+ */
+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.
+ */
+void buf_markdelayed(buf_t bp);
+
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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).
+ */
+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().
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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
+ */
+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
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ * @return 0 for success, EINVAL if unable to unmap buffer.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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 devvp, void *ap);
projects / apple / xnu.git / blobdiff