+/*!
+ @function buf_setblkno
+ @abstract Set physical block number associated with a buffer.
+ @discussion Physical block number is generally set by the cluster layer or by buf_getblk().
+ @param bp Buffer whose physical block number to set.
+ @param blkno Block number to set.
+ @return void.
+ */
+void buf_setblkno(buf_t, daddr64_t);
+
+/*!
+ @function buf_setlblkno
+ @abstract Set logical block number associated with a buffer.
+ @discussion Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(),
+ for example by buf_bread().
+ @param bp Buffer whose logical block number to set.
+ @param lblkno Block number to set.
+ @return void.
+ */
+void buf_setlblkno(buf_t, daddr64_t);
+
+/*!
+ @function buf_count
+ @abstract Get count of valid bytes in a buffer. This may be less than the space allocated to the buffer.
+ @param bp Buffer whose byte count to get.
+ @return Byte count.
+ */
+uint32_t buf_count(buf_t);
+
+/*!
+ @function buf_size
+ @abstract Get size of data region allocated to a buffer.
+ @discussion May be larger than amount of valid data in buffer.
+ @param bp Buffer whose size to get.
+ @return Size.
+ */
+uint32_t buf_size(buf_t);
+
+/*!
+ @function buf_resid
+ @abstract Get a count of bytes which were not consumed by an I/O on a buffer.
+ @discussion Set when an I/O operations completes.
+ @param bp Buffer whose outstanding count to get.
+ @return Count of unwritten/unread bytes.
+ */
+uint32_t buf_resid(buf_t);
+
+/*!
+ @function buf_setcount
+ @abstract Set count of valid bytes in a buffer. This may be less than the space allocated to the buffer.
+ @param bp Buffer whose byte count to set.
+ @param bcount Count to set.
+ @return void.
+ */
+void buf_setcount(buf_t, uint32_t);
+
+/*!
+ @function buf_setsize
+ @abstract Set size of data region allocated to a buffer.
+ @discussion May be larger than amount of valid data in buffer. Should be used by
+ code which is manually providing storage for an iobuf, one allocated with buf_alloc().
+ @param bp Buffer whose size to set.
+ @return void.
+ */
+void buf_setsize(buf_t, uint32_t);
+
+/*!
+ @function buf_setresid
+ @abstract Set a count of bytes outstanding for I/O in a buffer.
+ @discussion Set when an I/O operations completes. Examples: called by IOStorageFamily when I/O
+ completes, often called on an "original" buffer when using a manipulated buffer to perform I/O
+ on behalf of the first.
+ @param bp Buffer whose outstanding count to set.
+ @return Count of unwritten/unread bytes.
+ */
+void buf_setresid(buf_t, uint32_t);
+
+/*!
+ @function buf_setdataptr
+ @abstract Set the address at which a buffer's data will be stored.
+ @discussion In traditional buffer use, the data pointer will be set automatically. This routine is
+ useful with iobufs (allocated with buf_alloc()).
+ @param bp Buffer whose data pointer to set.
+ @param data Pointer to data region.
+ @return void.
+ */
+void buf_setdataptr(buf_t, uintptr_t);
+
+/*!
+ @function buf_dataptr
+ @abstract Get the address at which a buffer's data is stored; for iobufs, this must
+ be set with buf_setdataptr(). See buf_map().
+ @param bp Buffer whose data pointer to retrieve.
+ @return Data pointer; NULL if unset.
+ */
+uintptr_t buf_dataptr(buf_t);
+
+/*!
+ @function buf_vnode
+ @abstract Get the vnode associated with a buffer.
+ @discussion Every buffer is associated with a file. Because there is an I/O in flight,
+ there is an iocount on this vnode; it is returned WITHOUT an extra iocount, and vnode_put()
+ need NOT be called.
+ @param bp Buffer whose vnode to retrieve.
+ @return Buffer's vnode.
+ */
+vnode_t buf_vnode(buf_t);
+
+/*!
+ @function buf_setvnode
+ @abstract Set the vnode associated with a buffer.
+ @discussion This call need not be used on traditional buffers; it is for use with iobufs.
+ @param bp Buffer whose vnode to set.
+ @param vp The vnode to attach to the buffer.
+ @return void.
+ */
+void buf_setvnode(buf_t, vnode_t);
+
+/*!
+ @function buf_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);
+
+/*!
+ @function buf_setdevice
+ @abstract Set the device associated with a buffer.
+ @discussion A buffer's device is set in buf_strategy() (or in buf_getblk() if the file is a device).
+ It is also set on an iobuf if buf_alloc() is passed a device vnode.
+ @param bp Buffer whose device ID to set.
+ @param vp Device to set on the buffer.
+ @return 0 for success, EINVAL if vp is not a device file.
+ */
+errno_t buf_setdevice(buf_t, vnode_t);
+
+/*!
+ @function buf_strategy
+ @abstract Pass an I/O request for a buffer down to the device layer.
+ @discussion This is one of the most important routines in the buffer cache layer. For buffers obtained
+ through buf_getblk, it handles finding physical block numbers for the I/O (with VNOP_BLKTOOFF and
+ VNOP_BLOCKMAP), packaging the I/O into page-sized chunks, and initiating I/O on the disk by calling
+ the device's strategy routine. If a buffer's UPL has been set manually with buf_setupl(), it assumes
+ that the request is already correctly configured with a block number and a size divisible by page size
+ and will just call directly to the device.
+ @param devvp Device on which to perform I/O
+ @param ap vnop_strategy_args structure (most importantly, a buffer).
+ @return 0 for success, or errors from filesystem or device layers.
+ */
+errno_t buf_strategy(vnode_t, void *);
+
+/*
+ * Flags for buf_invalblkno()
+ */
+#define BUF_WAIT 0x01
+
+/*!
+ @function buf_invalblkno
+ @abstract Invalidate a filesystem logical block in a file.
+ @discussion buf_invalblkno() tries to make the data for a given block in a file
+ invalid; if the buffer for that block is found in core and is not busy, we mark it
+ invalid and call buf_brelse() (see "flags" param for what happens if the buffer is busy).
+ buf_brelse(), noticing that it is invalid, will
+ will return the buffer to the empty-buffer list and tell the VM subsystem to abandon
+ the relevant pages. Data will not be written to backing store--it will be cast aside.
+ Note that this function will only work if the block in question has been
+ obtained with a buf_getblk(). If data has been read into core without using
+ traditional buffer cache routines, buf_invalblkno() will not be able to invalidate it--this
+ includes the use of iobufs.
+ @param bp Buffer whose block to invalidate.
+ @param lblkno Logical block number.
+ @param flags BUF_WAIT: wait for busy buffers to become unbusy and invalidate them then. Otherwise,
+ just return EBUSY for busy blocks.
+ @return 0 for success, EINVAL if vp is not a device file.
+ */
+errno_t buf_invalblkno(vnode_t, daddr64_t, int);
+
+/*!
+ @function buf_callback
+ @abstract Get the function set to be called when I/O on a buffer completes.
+ @discussion A function returned by buf_callback was originally set with buf_setcallback().
+ @param bp Buffer whose callback to get.
+ @return 0 for success, or errors from filesystem or device layers.
+ */
+void * buf_callback(buf_t);
+
+/*!
+ @function buf_setcallback
+ @abstract Set a function to be called once when I/O on a buffer completes.
+ @discussion A one-shot callout set with buf_setcallback() will be called from buf_biodone()
+ when I/O completes. It will be passed the "transaction" argument as well as the buffer.
+ buf_setcallback() also marks the buffer as B_ASYNC.
+ @param bp Buffer whose callback to set.
+ @param callback function to use as callback.
+ @param transaction Additional argument to callback function.
+ @return 0; always succeeds.
+ */
+errno_t buf_setcallback(buf_t, void (*)(buf_t, void *), void *);
+
+/*!
+ @function buf_setupl
+ @abstract Set the UPL (Universal Page List), and offset therein, on a buffer.
+ @discussion buf_setupl() should only be called on buffers allocated with buf_alloc().
+ A subsequent call to buf_map() will map the UPL and give back the address at which data
+ begins. After buf_setupl() is called, a buffer is marked B_CLUSTER; when this is the case,
+ buf_strategy() assumes that a buffer is correctly configured to be passed to the device
+ layer without modification. Passing a NULL upl will clear the upl and the B_CLUSTER flag on the
+ buffer.
+ @param bp Buffer whose upl to set.
+ @param upl UPL to set in the buffer.
+ @parma offset Offset within upl at which relevant data begin.
+ @return 0 for success, EINVAL if the buffer was not allocated with buf_alloc().
+ */
+errno_t buf_setupl(buf_t, upl_t, uint32_t);
+
+/*!
+ @function buf_clone
+ @abstract Clone a buffer with a restricted range and an optional callback.
+ @discussion Generates a buffer which is identical to its "bp" argument except that
+ it spans a subset of the data of the original. The buffer to be cloned should
+ have been allocated with buf_alloc(). Checks its arguments to make sure
+ that the data subset is coherent. Optionally, adds a callback function and argument to it
+ to be called when I/O completes (as with buf_setcallback(), but B_ASYNC is not set). If the original buffer had
+ a upl set through buf_setupl(), this upl is copied to the new buffer; otherwise, the original's
+ data pointer is used raw. The buffer must be released with buf_free().
+ @param bp Buffer to clone.
+ @param io_offset Offset, relative to start of data in original buffer, at which new buffer's data will begin.
+ @param io_size Size of buffer region in new buffer, in the sense of buf_count().
+ @param iodone Callback to be called from buf_biodone() when I/O completes, in the sense of buf_setcallback().
+ @param arg Argument to pass to iodone() callback.
+ @return NULL if io_offset/io_size combination is invalid for the buffer to be cloned; otherwise, the new buffer.
+ */
+buf_t buf_clone(buf_t, int, int, void (*)(buf_t, void *), void *);
+
+
+/*!
+ @function buf_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);
+
+
+/*!
+ @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.
+ */
+buf_t buf_alloc(vnode_t);
+
+/*!
+ @function buf_free
+ @abstract Free a buffer that was allocated with buf_alloc().
+ @discussion The storage (UPL, data pointer) associated with an iobuf must be freed manually.
+ @param bp The buffer to free.
+ @return void.
+ */
+void buf_free(buf_t);
projects / apple / xnu.git / blobdiff