buf.h

Includes:

Overview

Use the links in the table of contents to the left to access the documentation.

Functions

buf_alloc: Allocate an uninitialized buffer.
buf_bawrite: Start an asychronous write on a buffer.
buf_bdwrite: Mark a buffer for delayed write.
buf_biodone: Mark an I/O as completed.
buf_biowait: Wait for I/O on a buffer to complete.
buf_blkno: Get physical block number associated with a buffer, in the sense of VNOP_BLOCKMAP.
buf_bread: Synchronously read a block of a file.
buf_breadn: Read a block from a file with read-ahead.
buf_brelse: Release any claim to a buffer, sending it back to free lists.
buf_bwrite: Write a buffer's data to backing store.
buf_callback: Get the function set to be called when I/O on a buffer completes.
buf_clear: Zero out the storage associated with a buffer.
buf_clearflags: Clear flags on a buffer. @discussion: buffer_flags &= ~flags
buf_clone: Clone a buffer with a restricted range and an optional callback.
buf_count: Get count of valid bytes in a buffer. This may be less than the space allocated to the buffer.
buf_dataptr: Get the address at which a buffer's data is stored; for iobufs, this must be set with buf_setdataptr(). See buf_map().
buf_device: Get the device ID associated with a buffer.
buf_dirtyend: Get the ending offset of the dirty region associated with a buffer.
buf_dirtyoff: Get the starting offset of the dirty region associated with a buffer.
buf_drvdata: Get driver-specific data from a buffer.
buf_error: Get the error value associated with a buffer.
buf_flags: Get flags set on a buffer.
buf_flushdirtyblks: Write dirty file blocks to disk.
buf_free: Free a buffer that was allocated with buf_alloc().
buf_fromcache: Check if a buffer's data was found in core.
buf_fsprivate: Get filesystem-specific data from a buffer.
buf_fua: Check if a buffer is marked for write through disk caches.
buf_getblk: Traditional buffer cache routine to get a buffer corresponding to a logical block in a file.
buf_geteblk: Get a metadata buffer which is marked invalid and not associated with any vnode.
buf_invalblkno: Invalidate a filesystem logical block in a file.
buf_invalidateblks: Invalidate all the blocks associated with a vnode.
buf_iterate: Perform some operation on all buffers associated with a vnode.
buf_lblkno: Get logical block number associated with a buffer.
buf_map: Get virtual mappings for buffer data.
buf_markaged: Mark a buffer as "aged," i.e. as a good candidate to be discarded and reused after buf_brelse().
buf_markdelayed: Mark a buffer as a delayed write: mark it dirty without actually scheduling I/O.
buf_markeintr: Mark a buffer as having been interrupted during I/O.
buf_markfua: Mark a buffer for write through disk cache, if disk supports it.
buf_markinvalid: Mark a buffer as not having valid data and being ready for immediate reuse after buf_brelse().
buf_meta_bread: Synchronously read a metadata block of a file.
buf_meta_breadn: Read a metadata block from a file with read-ahead.
buf_proc: Get the process associated with this buffer.
buf_rcred: Get the credential associated with a buffer for reading.
buf_reset: Reset I/O flag state on a buffer.
buf_resid: Get a count of bytes which were not consumed by an I/O on a buffer.
buf_setblkno: Set physical block number associated with a buffer.
buf_setcallback: Set a function to be called once when I/O on a buffer completes.
buf_setcount: Set count of valid bytes in a buffer. This may be less than the space allocated to the buffer.
buf_setdataptr: Set the address at which a buffer's data will be stored.
buf_setdevice: Set the device associated with a buffer.
buf_setdirtyend: Set the ending offset of the dirty region associated with a buffer.
buf_setdirtyoff: Set the starting offset of the dirty region associated with a buffer.
buf_setdrvdata(buf_t): Get driver-specific data from a buffer.
buf_setdrvdata(buf_t, void *): Set driver-specific data on a buffer.
buf_seterror: Set an error value on a buffer.
buf_setflags: Set flags on a buffer. @discussion: buffer_flags |= flags
buf_setfsprivate: Set filesystem-specific data on a buffer.
buf_setlblkno: Set logical block number associated with a buffer.
buf_setresid: Set a count of bytes outstanding for I/O in a buffer.
buf_setsize: Set size of data region allocated to a buffer.
buf_setupl: Set the UPL (Universal Page List), and offset therein, on a buffer.
buf_setvnode: Set the vnode associated with a buffer.
buf_size: Get size of data region allocated to a buffer.
buf_strategy: Pass an I/O request for a buffer down to the device layer.
buf_unmap: Release mappings for buffer data.
buf_upl: Get the upl (Universal Page List) associated with a buffer.
buf_uploffset: Get the offset into a UPL at which this buffer begins.
buf_valid: Check if a buffer contains valid data.
buf_vnode: Get the vnode associated with a buffer.
buf_wcred: Get the credential associated with a buffer for writing.
minphys: Adjust a buffer's count to be no more than maximum physical I/O transfer size for the host architecture.
physio: Perform I/O on a device to/from target memory described by a uio.

buf_alloc

Allocate an uninitialized buffer.


buf_t buf_alloc(
    vnode_t);

Parameters

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 Value

New 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().

buf_bawrite

Start an asychronous write on a buffer.


errno_t buf_bawrite(
    buf_t);

Parameters

bp: The buffer on which to initiate I/O.
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 Value

EWOULDBLOCK if write count is high and "throttle" is zero; otherwise, errors from VNOP_BWRITE.

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.

buf_bdwrite

Mark a buffer for delayed write.


errno_t buf_bdwrite(
    buf_t);

Parameters

bp: The buffer to mark for delayed write.
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 Value

EAGAIN for return_error != 0 case, 0 for succeess, errors from buf_bawrite.

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.

buf_biodone

Mark an I/O as completed.


void buf_biodone(
    buf_t);

Parameters

bp: The buffer to mark as done with I/O.

Return Value

void.

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.

buf_biowait

Wait for I/O on a buffer to complete.


errno_t buf_biowait(
    buf_t);

Parameters

bp: The buffer to wait on.

Return Value

0 for a successful wait; nonzero the buffer has been marked as EINTR or had an error set on it.

Discussion

Waits for I/O on a buffer to finish, as marked by a buf_biodone() call.

buf_blkno

Get physical block number associated with a buffer, in the sense of VNOP_BLOCKMAP.


daddr64_t buf_blkno(
    buf_t);

Parameters

bp: Buffer whose physical block number to get.

Return Value

Block number.

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().

buf_bread

Synchronously read a block of a file.


errno_t buf_bread(
    vnode_t,
    daddr64_t,
    int,
    kauth_cred_t,
    buf_t *);

Parameters

vp: The file from which to read.
blkno: The logical (filesystem) block number to read.
size: Size of block; do not use for sizes > 4K.
cred: Credential to store and use for reading from disk if data are not already in core.
bpp: Destination pointer for buffer.

Return Value

0 for success, or an error from buf_biowait().

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.

buf_breadn

Read a block from a file with read-ahead.


errno_t buf_breadn(
    vnode_t,
    daddr64_t,
    int,
    daddr64_t *,
    int *,
    int,
    kauth_cred_t,
    buf_t *);

Parameters

vp: The file from which to read.
blkno: The logical (filesystem) block number to read synchronously.
size: Size of block; do not use for sizes > 4K.
rablks: Array of logical block numbers for asynchronous read-aheads.
rasizes: Array of block sizes for asynchronous read-aheads, each index corresponding to same index in "rablks."
nrablks: Number of entries in read-ahead arrays.
cred: Credential to store and use for reading from disk if data are not already in core.
bpp: Destination pointer for buffer.

Return Value

0 for success, or an error from buf_biowait().

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.

buf_brelse

Release any claim to a buffer, sending it back to free lists.


void buf_brelse(
    buf_t);

Parameters

bp: The buffer to release. @retrn void.

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.

buf_bwrite

Write a buffer's data to backing store.


errno_t buf_bwrite(
    buf_t);

Parameters

bp: The buffer to write to disk.

Return Value

0 for success; errors from buf_biowait().

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).

buf_callback

Get the function set to be called when I/O on a buffer completes.


void * buf_callback(
    buf_t);

Parameters

bp: Buffer whose callback to get.

Return Value

0 for success, or errors from filesystem or device layers.

Discussion

A function returned by buf_callback was originally set with buf_setcallback().

buf_clear

Zero out the storage associated with a buffer.


void buf_clear(
    buf_t);

Parameters

bp: The buffer to zero out.

Return Value

void.

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()).

buf_clearflags

Clear flags on a buffer. @discussion: buffer_flags &= ~flags


void buf_clearflags(
    buf_t,
    int32_t);

Parameters

bp: Buffer whose flags to clear.
flags: Flags to remove from buffer's mask. B_LOCKED/B_NOCACHE/B_ASYNC/B_READ/B_WRITE/B_PAGEIO/B_FUA

Return Value

void.

buf_clone

Clone a buffer with a restricted range and an optional callback.


buf_t buf_clone(
    buf_t,
    int,
    int,
    void (*)(
        buf_t,
        void *),
    void *);

Parameters

bp: Buffer to clone.
io_offset: Offset, relative to start of data in original buffer, at which new buffer's data will begin.
io_size: Size of buffer region in new buffer, in the sense of buf_count().
iodone: Callback to be called from buf_biodone() when I/O completes, in the sense of buf_setcallback().
arg: Argument to pass to iodone() callback.

Return Value

NULL if io_offset/io_size combination is invalid for the buffer to be cloned; otherwise, the new buffer.

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().

buf_count

Get count of valid bytes in a buffer. This may be less than the space allocated to the buffer.


uint32_t buf_count(
    buf_t);

Parameters

bp: Buffer whose byte count to get.

Return Value

Byte count.

buf_dataptr

Get the address at which a buffer's data is stored; for iobufs, this must be set with buf_setdataptr(). See buf_map().


uintptr_t buf_dataptr(
    buf_t);

Parameters

bp: Buffer whose data pointer to retrieve.

Return Value

Data pointer; NULL if unset.

buf_device

Get the device ID associated with a buffer.


dev_t buf_device(
    buf_t);

Parameters

bp: Buffer whose device ID to retrieve.

Return Value

Device id.

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.

buf_dirtyend

Get the ending offset of the dirty region associated with a buffer.


uint32_t buf_dirtyend(
    buf_t);

Parameters

bp: Buffer whose dirty end to get.

Return Value

0 if buffer is found clean; size of buffer if found dirty. Can be set to any value by callers of buf_setdirtyend().

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.

buf_dirtyoff

Get the starting offset of the dirty region associated with a buffer.


uint32_t buf_dirtyoff(
    buf_t);

Parameters

bp: Buffer whose dirty offset to get.

Return Value

Dirty offset (0 if not explicitly changed).

Discussion

The dirty offset is zero unless someone explicitly calls buf_setdirtyoff() (which the kernel does not).

buf_drvdata

Get driver-specific data from a buffer.


void * buf_drvdata(
    buf_t);

Parameters

bp: Buffer whose driver data to get.

Return Value

Opaque driver data.

buf_error

Get the error value associated with a buffer.


errno_t buf_error(
    buf_t);

Parameters

bp: Buffer whose error value to retrieve.

Return Value

Error value, directly.

Discussion

Errors are set with buf_seterror().

buf_flags

Get flags set on a buffer.


int32_t buf_flags(
    buf_t);

Parameters

bp: Buffer whose flags to grab.

Return Value

flags.

Discussion

Valid flags are B_LOCKED/B_NOCACHE/B_ASYNC/B_READ/B_WRITE/B_PAGEIO/B_FUA.

buf_flushdirtyblks

Write dirty file blocks to disk.


void buf_flushdirtyblks(
    vnode_t,
    int,
    int,
    const char *);

Parameters

vp: The vnode whose blocks to flush.
wait: Wait for writes to complete before returning.
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.
msg: String to pass to msleep().

Return Value

void.

buf_free

Free a buffer that was allocated with buf_alloc().


void buf_free(
    buf_t);

Parameters

bp: The buffer to free.

Return Value

void.

Discussion

The storage (UPL, data pointer) associated with an iobuf must be freed manually.

buf_fromcache

Check if a buffer's data was found in core.


int buf_fromcache(
    buf_t);

Parameters

bp: Buffer to test.

Return Value

Nonzero if we got this buffer's data without doing I/O, 0 if not.

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).

buf_fsprivate

Get filesystem-specific data from a buffer.


void * buf_fsprivate(
    buf_t);

Parameters

bp: Buffer whose filesystem data to get.

Return Value

Opaque filesystem data.

buf_fua

Check if a buffer is marked for write through disk caches.


int buf_fua(
    buf_t);

Parameters

bp: Buffer to test.

Return Value

Nonzero if buffer is marked for write-through, 0 if not.

buf_getblk

Traditional buffer cache routine to get a buffer corresponding to a logical block in a file.


buf_t buf_getblk(
    vnode_t,
    daddr64_t,
    int,
    int,
    int,
    int);

Parameters

vp: File for which to get block.
blkno: Logical block number.
size: Size of block.
slpflag: Flag to pass to msleep() while waiting for buffer to become unbusy.
slptimeo: Time, in milliseconds, to wait for buffer to become unbusy. 0 means to wait indefinitely.
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 Value

Buffer found in core or newly allocated, either containing valid data or ready for I/O.

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().

buf_geteblk

Get a metadata buffer which is marked invalid and not associated with any vnode.


buf_t buf_geteblk(
    int);

Parameters

size: Size of buffer.

Return Value

Always returns a new buffer.

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.

buf_invalblkno

Invalidate a filesystem logical block in a file.


errno_t buf_invalblkno(
    vnode_t,
    daddr64_t,
    int);

Parameters

bp: Buffer whose block to invalidate.
lblkno: Logical block number.
flags: BUF_WAIT: wait for busy buffers to become unbusy and invalidate them then. Otherwise, just return EBUSY for busy blocks.

Return Value

0 for success, EINVAL if vp is not a device 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.

buf_invalidateblks

Invalidate all the blocks associated with a vnode.


int buf_invalidateblks(
    vnode_t,
    int,
    int,
    int);

Parameters

bp: The buffer whose data to invalidate.
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.
slpflag: Flags to pass to "msleep" while waiting to acquire busy buffers.
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 Value

0 for success, error values from msleep().

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.

buf_iterate

Perform some operation on all buffers associated with a vnode.


void buf_iterate(
    vnode_t,
    int (*)(
        buf_t,
        void *),
    int,
    void *);

Parameters

vp: The vnode whose buffers to scan.
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()).
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.
arg: Argument to pass to callout in addition to buffer.

Return Value

void.

buf_lblkno

Get logical block number associated with a buffer.


daddr64_t buf_lblkno(
    buf_t);

Parameters

bp: Buffer whose logical block number to get.

Return Value

Block number.

Discussion

Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(), for example by buf_bread().

buf_map

Get virtual mappings for buffer data.


errno_t buf_map(
    buf_t,
    caddr_t *);

Parameters

bp: Buffer whose mapping to find or create.
io_addr: Destination for mapping address.

Return Value

0 for success, ENOMEM if unable to map the buffer.

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().

buf_markaged

Mark a buffer as "aged," i.e. as a good candidate to be discarded and reused after buf_brelse().


void buf_markaged(
    buf_t);

Parameters

bp: Buffer to mark.

buf_markdelayed

Mark a buffer as a delayed write: mark it dirty without actually scheduling I/O.


void buf_markdelayed(
    buf_t);

Parameters

bp: Buffer to mark.

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.

buf_markeintr

Mark a buffer as having been interrupted during I/O.


void buf_markeintr(
    buf_t);

Parameters

bp: Buffer to mark.

Discussion

Waiters for I/O to complete (buf_biowait()) will return with EINTR when woken up. buf_markeintr does not itself do a wakeup.

buf_markfua

Mark a buffer for write through disk cache, if disk supports it.


void buf_markfua(
    buf_t);

Parameters

bp: Buffer to mark.

buf_markinvalid

Mark a buffer as not having valid data and being ready for immediate reuse after buf_brelse().


void buf_markinvalid(
    buf_t);

Parameters

bp: Buffer to mark.

buf_meta_bread

Synchronously read a metadata block of a file.


errno_t buf_meta_bread(
    vnode_t,
    daddr64_t,
    int,
    kauth_cred_t,
    buf_t *);

Parameters

vp: The file from which to read.
blkno: The logical (filesystem) block number to read.
size: Size of block; do not use for sizes > 4K.
cred: Credential to store and use for reading from disk if data are not already in core.
bpp: Destination pointer for buffer.

Return Value

0 for success, or an error from buf_biowait().

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.

buf_meta_breadn

Read a metadata block from a file with read-ahead.


errno_t buf_meta_breadn(
    vnode_t,
    daddr64_t,
    int,
    daddr64_t *,
    int *,
    int,
    kauth_cred_t,
    buf_t *);

Parameters

vp: The file from which to read.
blkno: The logical (filesystem) block number to read synchronously.
size: Size of block; do not use for sizes > 4K.
rablks: Array of logical block numbers for asynchronous read-aheads.
rasizes: Array of block sizes for asynchronous read-aheads, each index corresponding to same index in "rablks."
nrablks: Number of entries in read-ahead arrays.
cred: Credential to store and use for reading from disk if data are not already in core.
bpp: Destination pointer for buffer.

Return Value

0 for success, or an error from buf_biowait().

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.

buf_proc

Get the process associated with this buffer.


proc_t buf_proc(
    buf_t);

Parameters

bp: Buffer whose associated process to find.

Return Value

Associated process, possibly NULL.

Discussion

buf_proc() will generally return NULL; a process is currently only associated with a buffer in the event of a physio() call.

buf_rcred

Get the credential associated with a buffer for reading.


kauth_cred_t buf_rcred(
    buf_t);

Parameters

bp: Buffer whose credential to grab.

Return Value

Credential if it exists, else NULL.

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.

buf_reset

Reset I/O flag state on a buffer.


void buf_reset(
    buf_t,
    int32_t);

Parameters

bp: Buffer whose flags to grab.
flags: Flags to set on buffer: B_READ, B_WRITE, B_ASYNC, B_NOCACHE.

Return Value

void.

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.

buf_resid

Get a count of bytes which were not consumed by an I/O on a buffer.


uint32_t buf_resid(
    buf_t);

Parameters

bp: Buffer whose outstanding count to get.

Return Value

Count of unwritten/unread bytes.

Discussion

Set when an I/O operations completes.

buf_setblkno

Set physical block number associated with a buffer.


void buf_setblkno(
    buf_t,
    daddr64_t);

Parameters

bp: Buffer whose physical block number to set.
blkno: Block number to set.

Return Value

void.

Discussion

Physical block number is generally set by the cluster layer or by buf_getblk().

buf_setcallback

Set a function to be called once when I/O on a buffer completes.


errno_t buf_setcallback(
    buf_t,
    void (*)(
        buf_t,
        void *),
    void *);

Parameters

bp: Buffer whose callback to set.
callback: function to use as callback.
transaction: Additional argument to callback function.

Return Value

0; always succeeds.

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.

buf_setcount

Set count of valid bytes in a buffer. This may be less than the space allocated to the buffer.


void buf_setcount(
    buf_t,
    uint32_t);

Parameters

bp: Buffer whose byte count to set.
bcount: Count to set.

Return Value

void.

buf_setdataptr

Set the address at which a buffer's data will be stored.


void buf_setdataptr(
    buf_t,
    uintptr_t);

Parameters

bp: Buffer whose data pointer to set.
data: Pointer to data region.

Return Value

void.

Discussion

In traditional buffer use, the data pointer will be set automatically. This routine is useful with iobufs (allocated with buf_alloc()).

buf_setdevice

Set the device associated with a buffer.


errno_t buf_setdevice(
    buf_t,
    vnode_t);

Parameters

bp: Buffer whose device ID to set.
vp: Device to set on the buffer.

Return Value

0 for success, EINVAL if vp is not a device file.

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.

buf_setdirtyend

Set the ending offset of the dirty region associated with a buffer.


void buf_setdirtyend(
    buf_t,
    uint32_t);

Parameters

bp: Buffer whose dirty end to set.

Return Value

void.

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.

buf_setdirtyoff

Set the starting offset of the dirty region associated with a buffer.


void buf_setdirtyoff(
    buf_t,
    uint32_t);

Parameters

bp: Buffer whose dirty end to set.

Return Value

void.

Discussion

This value is zero unless someone set it explicitly.

buf_setdrvdata(buf_t)

Get driver-specific data from a buffer.


void * buf_drvdata(
    buf_t);

Parameters

bp: Buffer whose driver data to get.

Return Value

Opaque driver data.

buf_setdrvdata(buf_t, void *)

Set driver-specific data on a buffer.


void buf_setdrvdata(
    buf_t,
    void *);

Parameters

bp: Buffer whose driver-data to set.
drvdata: Opaque driver data.

Return Value

void.

buf_seterror

Set an error value on a buffer.


void buf_seterror(
    buf_t,
    errno_t);

Parameters

bp: Buffer whose error value to set.

Return Value

void.

buf_setflags

Set flags on a buffer. @discussion: buffer_flags |= flags


void buf_setflags(
    buf_t,
    int32_t);

Parameters

bp: Buffer whose flags to set.
flags: Flags to add to buffer's mask. B_LOCKED/B_NOCACHE/B_ASYNC/B_READ/B_WRITE/B_PAGEIO/B_FUA

Return Value

void.

buf_setfsprivate

Set filesystem-specific data on a buffer.


void buf_setfsprivate(
    buf_t,
    void *);

Parameters

bp: Buffer whose filesystem data to set.
fsprivate: Opaque filesystem data.

Return Value

void.

buf_setlblkno

Set logical block number associated with a buffer.


void buf_setlblkno(
    buf_t,
    daddr64_t);

Parameters

bp: Buffer whose logical block number to set.
lblkno: Block number to set.

Return Value

void.

Discussion

Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(), for example by buf_bread().

buf_setresid

Set a count of bytes outstanding for I/O in a buffer.


void buf_setresid(
    buf_t,
    uint32_t);

Parameters

bp: Buffer whose outstanding count to set.

Return Value

Count of unwritten/unread bytes.

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.

buf_setsize

Set size of data region allocated to a buffer.


void buf_setsize(
    buf_t,
    uint32_t);

Parameters

bp: Buffer whose size to set.

Return Value

void.

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().

buf_setupl

Set the UPL (Universal Page List), and offset therein, on a buffer.


errno_t buf_setupl(
    buf_t,
    upl_t,
    uint32_t);

Parameters

bp: Buffer whose upl to set.
upl: UPL to set in the buffer. @parma offset Offset within upl at which relevant data begin.

Return Value

0 for success, EINVAL if the buffer was not allocated with buf_alloc().

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.

buf_setvnode

Set the vnode associated with a buffer.


void buf_setvnode(
    buf_t,
    vnode_t);

Parameters

bp: Buffer whose vnode to set.
vp: The vnode to attach to the buffer.

Return Value

void.

Discussion

This call need not be used on traditional buffers; it is for use with iobufs.

buf_size

Get size of data region allocated to a buffer.


uint32_t buf_size(
    buf_t);

Parameters

bp: Buffer whose size to get.

Return Value

Size.

Discussion

May be larger than amount of valid data in buffer.

buf_strategy

Pass an I/O request for a buffer down to the device layer.


errno_t buf_strategy(
    vnode_t,
    void *);

Parameters

devvp: Device on which to perform I/O
ap: vnop_strategy_args structure (most importantly, a buffer).

Return Value

0 for success, or errors from filesystem or device layers.

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.

buf_unmap

Release mappings for buffer data.


errno_t buf_unmap(
    buf_t);

Parameters

bp: Buffer whose mapping to find or create.
io_addr: Destination for mapping address.

Return Value

0 for success, EINVAL if unable to unmap buffer.

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.

buf_upl

Get the upl (Universal Page List) associated with a buffer.


void * buf_upl(
    buf_t);

Parameters

bp: Buffer whose upl to grab.

Return Value

Buffer's upl if it has one, else NULL.

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.

buf_uploffset

Get the offset into a UPL at which this buffer begins.


uint32_t buf_uploffset(
    buf_t);

Parameters

bp: Buffer whose uploffset to grab.

Return Value

Buffer's uploffset--does not check whether that value makes sense for this buffer.

Discussion

This function should only be called on iobufs, i.e. buffers allocated with buf_alloc().

buf_valid

Check if a buffer contains valid data.


int buf_valid(
    buf_t);

Parameters

bp: Buffer to test.

Return Value

Nonzero if buffer has valid data, 0 if not.

buf_vnode

Get the vnode associated with a buffer.


vnode_t buf_vnode(
    buf_t);

Parameters

bp: Buffer whose vnode to retrieve.

Return Value

Buffer's vnode.

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.

buf_wcred

Get the credential associated with a buffer for writing.


kauth_cred_t buf_wcred(
    buf_t);

Parameters

bp: Buffer whose credential to grab.

Return Value

Credential if it exists, else NULL.

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.

minphys

Adjust a buffer's count to be no more than maximum physical I/O transfer size for the host architecture.


u_int minphys(
    buf_t bp);

Parameters

bp: The buffer whose byte count to modify.

Return Value

New byte count.

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.

physio

Perform I/O on a device to/from target memory described by a uio.


int physio(
    void (*)(
        buf_t),
    buf_t,
    dev_t,
    int,
    u_int (*)(
        buf_t),
    struct uio *,
    int );

Parameters

f_strategy: Strategy routine to call to initiate I/O.
bp: Buffer to configure and pass to strategy routine; can be NULL.
dev: Device on which to perform I/O.
flags: B_READ or B_WRITE.
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.
uio: UIO describing the I/O operation.
blocksize: Logical block size for this vnode.

Return Value

0 for success; EFAULT for an invalid uio; errors from buf_biowait().

Discussion

physio() allows I/O directly from a device to user-space memory. It waits for all I/O to complete before returning.

Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: Kernel Device Drivers Kernel Framework Reference

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Last Updated: 2010-07-29