1/*
2 * Copyright (c) 2000-2016 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28/* Copyright (c) 1995 NeXT Computer, Inc. All Rights Reserved */
29/*
30 * Copyright (c) 1982, 1986, 1989, 1993
31 * The Regents of the University of California. All rights reserved.
32 * (c) UNIX System Laboratories, Inc.
33 * All or some portions of this file are derived from material licensed
34 * to the University of California by American Telephone and Telegraph
35 * Co. or Unix System Laboratories, Inc. and are reproduced herein with
36 * the permission of UNIX System Laboratories, Inc.
37 *
38 * Redistribution and use in source and binary forms, with or without
39 * modification, are permitted provided that the following conditions
40 * are met:
41 * 1. Redistributions of source code must retain the above copyright
42 * notice, this list of conditions and the following disclaimer.
43 * 2. Redistributions in binary form must reproduce the above copyright
44 * notice, this list of conditions and the following disclaimer in the
45 * documentation and/or other materials provided with the distribution.
46 * 3. All advertising materials mentioning features or use of this software
47 * must display the following acknowledgement:
48 * This product includes software developed by the University of
49 * California, Berkeley and its contributors.
50 * 4. Neither the name of the University nor the names of its contributors
51 * may be used to endorse or promote products derived from this software
52 * without specific prior written permission.
53 *
54 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
55 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
56 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
57 * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
58 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
59 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
60 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
61 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
62 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
63 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
64 * SUCH DAMAGE.
65 *
66 * @(#)buf.h 8.9 (Berkeley) 3/30/95
67 */
68
69#ifndef _SYS_BUF_H_
70#define _SYS_BUF_H_
71
72#include <sys/cdefs.h>
73#include <sys/kernel_types.h>
74#include <sys/ucred.h>
75#include <mach/memory_object_types.h>
76
77
78#define B_WRITE 0x00000000 /* Write buffer (pseudo flag). */
79#define B_READ 0x00000001 /* Read buffer. */
80#define B_ASYNC 0x00000002 /* Start I/O, do not wait. */
81#define B_NOCACHE 0x00000004 /* Do not cache block after use. */
82#define B_DELWRI 0x00000008 /* Delay I/O until buffer reused. */
83#define B_LOCKED 0x00000010 /* Locked in core (not reusable). */
84#define B_PHYS 0x00000020 /* I/O to user memory. */
85#define B_CLUSTER 0x00000040 /* UPL based I/O generated by cluster layer */
86#define B_PAGEIO 0x00000080 /* Page in/out */
87#define B_META 0x00000100 /* buffer contains meta-data. */
88#define B_RAW 0x00000200 /* Set by physio for raw transfers. */
89#define B_FUA 0x00000400 /* Write-through disk cache(if supported) */
90#define B_PASSIVE 0x00000800 /* PASSIVE I/Os are ignored by THROTTLE I/O */
91#define B_IOSTREAMING 0x00001000 /* sequential access pattern detected */
92#define B_THROTTLED_IO 0x00002000 /* low priority I/O (deprecated) */
93#define B_ENCRYPTED_IO 0x00004000 /* Encrypted I/O */
94#define B_STATICCONTENT 0x00008000 /* Buffer is likely to remain unaltered */
95
96/*
97 * make sure to check when adding flags that
98 * that the new flags don't overlap the definitions
99 * in buf_internal.h
100 */
101
102__BEGIN_DECLS
103
104/*!
105 @function buf_markaged
106 @abstract Mark a buffer as "aged," i.e. as a good candidate to be discarded and reused after buf_brelse().
107 @param bp Buffer to mark.
108 */
109void buf_markaged(buf_t bp);
110
111/*!
112 @function buf_markinvalid
113 @abstract Mark a buffer as not having valid data and being ready for immediate reuse after buf_brelse().
114 @param bp Buffer to mark.
115 */
116void buf_markinvalid(buf_t bp);
117
118/*!
119 @function buf_markdelayed
120 @abstract Mark a buffer as a delayed write: mark it dirty without actually scheduling I/O.
121 @discussion Data will be flushed to disk at some later time, not with brelse(). A sync()/fsync()
122 or pressure necessitating reuse of the buffer will cause it to be written back to disk.
123 @param bp Buffer to mark.
124 */
125void buf_markdelayed(buf_t bp);
126
127void buf_markclean(buf_t);
128
129/*!
130 @function buf_markeintr
131 @abstract Mark a buffer as having been interrupted during I/O.
132 @discussion Waiters for I/O to complete (buf_biowait()) will return with EINTR when woken up.
133 buf_markeintr does not itself do a wakeup.
134 @param bp Buffer to mark.
135 */
136void buf_markeintr(buf_t bp);
137
138/*!
139 @function buf_markfua
140 @abstract Mark a buffer for write through disk cache, if disk supports it.
141 @param bp Buffer to mark.
142 */
143void buf_markfua(buf_t bp);
144
145/*!
146 @function buf_fua
147 @abstract Check if a buffer is marked for write through disk caches.
148 @param bp Buffer to test.
149 @return Nonzero if buffer is marked for write-through, 0 if not.
150 */
151int buf_fua(buf_t bp);
152
153/*!
154 @function buf_valid
155 @abstract Check if a buffer contains valid data.
156 @param bp Buffer to test.
157 @return Nonzero if buffer has valid data, 0 if not.
158 */
159int buf_valid(buf_t bp);
160
161/*!
162 @function buf_fromcache
163 @abstract Check if a buffer's data was found in core.
164 @discussion Will return truth after a buf_getblk that finds a valid buffer in the cache or the relevant
165 data in core (but not in a buffer).
166 @param bp Buffer to test.
167 @return Nonzero if we got this buffer's data without doing I/O, 0 if not.
168 */
169int buf_fromcache(buf_t bp);
170
171/*!
172 @function buf_upl
173 @abstract Get the upl (Universal Page List) associated with a buffer.
174 @discussion Buffers allocated with buf_alloc() are not returned with a upl, and
175 traditional buffers only have a upl while an I/O is in progress.
176 @param bp Buffer whose upl to grab.
177 @return Buffer's upl if it has one, else NULL.
178 */
179void * buf_upl(buf_t bp);
180
181/*!
182 @function buf_uploffset
183 @abstract Get the offset into a UPL at which this buffer begins.
184 @discussion This function should only be called on iobufs, i.e. buffers allocated with buf_alloc().
185 @param bp Buffer whose uploffset to grab.
186 @return Buffer's uploffset--does not check whether that value makes sense for this buffer.
187 */
188uint32_t buf_uploffset(buf_t bp);
189
190/*!
191 @function buf_rcred
192 @abstract Get the credential associated with a buffer for reading.
193 @discussion No reference is taken; if the credential is to be held on to persistently, an additional
194 reference must be taken with kauth_cred_ref.
195 @param bp Buffer whose credential to grab.
196 @return Credential if it exists, else NULL.
197 */
198kauth_cred_t buf_rcred(buf_t bp);
199
200/*!
201 @function buf_wcred
202 @abstract Get the credential associated with a buffer for writing.
203 @discussion No reference is taken; if the credential is to be held on to persistently, an additional
204 reference must be taken with kauth_cred_ref.
205 @param bp Buffer whose credential to grab.
206 @return Credential if it exists, else NULL.
207 */
208kauth_cred_t buf_wcred(buf_t bp);
209
210/*!
211 @function buf_proc
212 @abstract Get the process associated with this buffer.
213 @discussion buf_proc() will generally return NULL; a process is currently only associated with
214 a buffer in the event of a physio() call.
215 @param bp Buffer whose associated process to find.
216 @return Associated process, possibly NULL.
217 */
218proc_t buf_proc(buf_t bp);
219
220/*!
221 @function buf_dirtyoff
222 @abstract Get the starting offset of the dirty region associated with a buffer.
223 @discussion The dirty offset is zero unless someone explicitly calls buf_setdirtyoff() (which the kernel does not).
224 @param bp Buffer whose dirty offset to get.
225 @return Dirty offset (0 if not explicitly changed).
226 */
227uint32_t buf_dirtyoff(buf_t bp);
228
229/*!
230 @function buf_dirtyend
231 @abstract Get the ending offset of the dirty region associated with a buffer.
232 @discussion If the buffer's data was found incore and dirty, the dirty end is the size of the block; otherwise, unless
233 someone outside of xnu explicitly changes it by calling buf_setdirtyend(), it will be zero.
234 @param bp Buffer whose dirty end to get.
235 @return 0 if buffer is found clean; size of buffer if found dirty. Can be set to any value by callers of buf_setdirtyend().
236 */
237uint32_t buf_dirtyend(buf_t bp);
238
239/*!
240 @function buf_setdirtyoff
241 @abstract Set the starting offset of the dirty region associated with a buffer.
242 @discussion This value is zero unless someone set it explicitly.
243 @param bp Buffer whose dirty end to set.
244 */
245void buf_setdirtyoff(buf_t bp, uint32_t);
246
247/*!
248 @function buf_setdirtyend
249 @abstract Set the ending offset of the dirty region associated with a buffer.
250 @discussion If the buffer's data was found incore and dirty, the dirty end is the size of the block; otherwise, unless
251 someone outside of xnu explicitly changes it by calling buf_setdirtyend(), it will be zero.
252 @param bp Buffer whose dirty end to set.
253 */
254void buf_setdirtyend(buf_t bp, uint32_t);
255
256/*!
257 @function buf_error
258 @abstract Get the error value associated with a buffer.
259 @discussion Errors are set with buf_seterror().
260 @param bp Buffer whose error value to retrieve.
261 @return Error value, directly.
262 */
263errno_t buf_error(buf_t bp);
264
265/*!
266 @function buf_seterror
267 @abstract Set an error value on a buffer.
268 @param bp Buffer whose error value to set.
269 */
270void buf_seterror(buf_t bp, errno_t);
271
272/*!
273 @function buf_setflags
274 @abstract Set flags on a buffer.
275 @discussion buffer_flags |= flags
276 @param bp Buffer whose flags to set.
277 @param flags Flags to add to buffer's mask. B_LOCKED/B_NOCACHE/B_ASYNC/B_READ/B_WRITE/B_PAGEIO/B_FUA
278 */
279void buf_setflags(buf_t bp, int32_t flags);
280
281/*!
282 @function buf_clearflags
283 @abstract Clear flags on a buffer.
284 @discussion buffer_flags &= ~flags
285 @param bp Buffer whose flags to clear.
286 @param flags Flags to remove from buffer's mask. B_LOCKED/B_NOCACHE/B_ASYNC/B_READ/B_WRITE/B_PAGEIO/B_FUA
287 */
288void buf_clearflags(buf_t bp, int32_t flags);
289
290/*!
291 @function buf_flags
292 @abstract Get flags set on a buffer.
293 @discussion Valid flags are B_LOCKED/B_NOCACHE/B_ASYNC/B_READ/B_WRITE/B_PAGEIO/B_FUA.
294 @param bp Buffer whose flags to grab.
295 @return flags.
296 */
297int32_t buf_flags(buf_t bp);
298
299/*!
300 @function buf_reset
301 @abstract Reset I/O flag state on a buffer.
302 @discussion Clears current flags on a buffer (internal and external) and allows some new flags to be set.
303 Used perhaps to prepare an iobuf for reuse.
304 @param bp Buffer whose flags to grab.
305 @param flags Flags to set on buffer: B_READ, B_WRITE, B_ASYNC, B_NOCACHE.
306 */
307void buf_reset(buf_t bp, int32_t flags);
308
309/*!
310 @function buf_map
311 @abstract Get virtual mappings for buffer data.
312 @discussion For buffers created through buf_getblk() (i.e. traditional buffer cache usage),
313 buf_map() just returns the address at which data was mapped by but_getblk(). For a B_CLUSTER buffer, i.e. an iobuf
314 whose upl state is managed manually, there are two possibilities. If the buffer was created
315 with an underlying "real" buffer through cluster_bp(), the mapping of the "real" buffer is returned.
316 Otherwise, the buffer was created with buf_alloc() and buf_setupl() was subsequently called; buf_map()
317 will call ubc_upl_map() to get a mapping for the buffer's upl and return the start of that mapping
318 plus the buffer's upl offset (set in buf_setupl()). In the last case, buf_unmap() must later be called
319 to tear down the mapping. NOTE: buf_map() does not set the buffer data pointer; this must be done with buf_setdataptr().
320 @param bp Buffer whose mapping to find or create.
321 @param io_addr Destination for mapping address.
322 @return 0 for success, ENOMEM if unable to map the buffer.
323 */
324errno_t buf_map(buf_t bp, caddr_t *io_addr);
325
326/*!
327 @function buf_unmap
328 @abstract Release mappings for buffer data.
329 @discussion For buffers created through buf_getblk() (i.e. traditional buffer cache usage),
330 buf_unmap() does nothing; buf_brelse() will take care of unmapping. For a B_CLUSTER buffer, i.e. an iobuf
331 whose upl state is managed manually, there are two possibilities. If the buffer was created
332 with an underlying "real" buffer through cluster_bp(), buf_unmap() does nothing; buf_brelse() on the
333 underlying buffer will tear down the mapping. Otherwise, the buffer was created with buf_alloc() and
334 buf_setupl() was subsequently called; buf_map() created the mapping. In this case, buf_unmap() will
335 unmap the buffer.
336 @param bp Buffer whose mapping to find or create.
337 @return 0 for success, EINVAL if unable to unmap buffer.
338 */
339errno_t buf_unmap(buf_t bp);
340
341/*!
342 @function buf_setdrvdata
343 @abstract Set driver-specific data on a buffer.
344 @param bp Buffer whose driver-data to set.
345 @param drvdata Opaque driver data.
346 */
347void buf_setdrvdata(buf_t bp, void *drvdata);
348
349/*!
350 @function buf_setdrvdata
351 @abstract Get driver-specific data from a buffer.
352 @param bp Buffer whose driver data to get.
353 @return Opaque driver data.
354 */
355void * buf_drvdata(buf_t bp);
356
357/*!
358 @function buf_setfsprivate
359 @abstract Set filesystem-specific data on a buffer.
360 @param bp Buffer whose filesystem data to set.
361 @param fsprivate Opaque filesystem data.
362 */
363void buf_setfsprivate(buf_t bp, void *fsprivate);
364
365/*!
366 @function buf_fsprivate
367 @abstract Get filesystem-specific data from a buffer.
368 @param bp Buffer whose filesystem data to get.
369 @return Opaque filesystem data.
370 */
371void * buf_fsprivate(buf_t bp);
372
373/*!
374 @function buf_blkno
375 @abstract Get physical block number associated with a buffer, in the sense of VNOP_BLOCKMAP.
376 @discussion When a buffer's physical block number is the same is its logical block number, then the physical
377 block number is considered uninitialized. A physical block number of -1 indicates that there is no valid
378 physical mapping (e.g. the logical block is invalid or corresponds to a sparse region in a file). Physical
379 block number is normally set by the cluster layer or by buf_getblk().
380 @param bp Buffer whose physical block number to get.
381 @return Block number.
382 */
383daddr64_t buf_blkno(buf_t bp);
384
385/*!
386 @function buf_lblkno
387 @abstract Get logical block number associated with a buffer.
388 @discussion Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(),
389 for example by buf_bread().
390 @param bp Buffer whose logical block number to get.
391 @return Block number.
392 */
393daddr64_t buf_lblkno(buf_t bp);
394
395/*!
396 @function buf_setblkno
397 @abstract Set physical block number associated with a buffer.
398 @discussion Physical block number is generally set by the cluster layer or by buf_getblk().
399 @param bp Buffer whose physical block number to set.
400 @param blkno Block number to set.
401 */
402void buf_setblkno(buf_t bp, daddr64_t blkno);
403
404/*!
405 @function buf_setlblkno
406 @abstract Set logical block number associated with a buffer.
407 @discussion Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(),
408 for example by buf_bread().
409 @param bp Buffer whose logical block number to set.
410 @param lblkno Block number to set.
411 */
412void buf_setlblkno(buf_t bp, daddr64_t lblkno);
413
414/*!
415 @function buf_count
416 @abstract Get count of valid bytes in a buffer. This may be less than the space allocated to the buffer.
417 @param bp Buffer whose byte count to get.
418 @return Byte count.
419 */
420uint32_t buf_count(buf_t bp);
421
422/*!
423 @function buf_size
424 @abstract Get size of data region allocated to a buffer.
425 @discussion May be larger than amount of valid data in buffer.
426 @param bp Buffer whose size to get.
427 @return Size.
428 */
429uint32_t buf_size(buf_t bp);
430
431/*!
432 @function buf_resid
433 @abstract Get a count of bytes which were not consumed by an I/O on a buffer.
434 @discussion Set when an I/O operations completes.
435 @param bp Buffer whose outstanding count to get.
436 @return Count of unwritten/unread bytes.
437 */
438uint32_t buf_resid(buf_t bp);
439
440/*!
441 @function buf_setcount
442 @abstract Set count of valid bytes in a buffer. This may be less than the space allocated to the buffer.
443 @param bp Buffer whose byte count to set.
444 @param bcount Count to set.
445 */
446void buf_setcount(buf_t bp, uint32_t bcount);
447
448/*!
449 @function buf_setsize
450 @abstract Set size of data region allocated to a buffer.
451 @discussion May be larger than amount of valid data in buffer. Should be used by
452 code which is manually providing storage for an iobuf, one allocated with buf_alloc().
453 @param bp Buffer whose size to set.
454 */
455void buf_setsize(buf_t bp, uint32_t);
456
457/*!
458 @function buf_setresid
459 @abstract Set a count of bytes outstanding for I/O in a buffer.
460 @discussion Set when an I/O operations completes. Examples: called by IOStorageFamily when I/O
461 completes, often called on an "original" buffer when using a manipulated buffer to perform I/O
462 on behalf of the first.
463 @param bp Buffer whose outstanding count to set.
464 */
465void buf_setresid(buf_t bp, uint32_t resid);
466
467/*!
468 @function buf_setdataptr
469 @abstract Set the address at which a buffer's data will be stored.
470 @discussion In traditional buffer use, the data pointer will be set automatically. This routine is
471 useful with iobufs (allocated with buf_alloc()).
472 @param bp Buffer whose data pointer to set.
473 @param data Pointer to data region.
474 */
475void buf_setdataptr(buf_t bp, uintptr_t data);
476
477/*!
478 @function buf_dataptr
479 @abstract Get the address at which a buffer's data is stored; for iobufs, this must
480 be set with buf_setdataptr(). See buf_map().
481 @param bp Buffer whose data pointer to retrieve.
482 @return Data pointer; NULL if unset.
483 */
484uintptr_t buf_dataptr(buf_t bp);
485
486/*!
487 @function buf_vnode
488 @abstract Get the vnode associated with a buffer.
489 @discussion Every buffer is associated with a file. Because there is an I/O in flight,
490 there is an iocount on this vnode; it is returned WITHOUT an extra iocount, and vnode_put()
491 need NOT be called.
492 @param bp Buffer whose vnode to retrieve.
493 @return Buffer's vnode.
494 */
495vnode_t buf_vnode(buf_t bp);
496
497/*!
498 @function buf_setvnode
499 @abstract Set the vnode associated with a buffer.
500 @discussion This call need not be used on traditional buffers; it is for use with iobufs.
501 @param bp Buffer whose vnode to set.
502 @param vp The vnode to attach to the buffer.
503 */
504void buf_setvnode(buf_t bp, vnode_t vp);
505
506/*!
507 @function buf_device
508 @abstract Get the device ID associated with a buffer.
509 @discussion In traditional buffer use, this value is NODEV until buf_strategy() is called unless
510 buf_getblk() was passed a device vnode. It is set on an iobuf if buf_alloc() is passed a device
511 vnode or if buf_setdevice() is called.
512 @param bp Buffer whose device ID to retrieve.
513 @return Device id.
514 */
515dev_t buf_device(buf_t bp);
516
517/*!
518 @function buf_setdevice
519 @abstract Set the device associated with a buffer.
520 @discussion A buffer's device is set in buf_strategy() (or in buf_getblk() if the file is a device).
521 It is also set on an iobuf if buf_alloc() is passed a device vnode.
522 @param bp Buffer whose device ID to set.
523 @param vp Device to set on the buffer.
524 @return 0 for success, EINVAL if vp is not a device file.
525 */
526errno_t buf_setdevice(buf_t bp, vnode_t vp);
527
528/*!
529 @function buf_strategy
530 @abstract Pass an I/O request for a buffer down to the device layer.
531 @discussion This is one of the most important routines in the buffer cache layer. For buffers obtained
532 through buf_getblk, it handles finding physical block numbers for the I/O (with VNOP_BLKTOOFF and
533 VNOP_BLOCKMAP), packaging the I/O into page-sized chunks, and initiating I/O on the disk by calling
534 the device's strategy routine. If a buffer's UPL has been set manually with buf_setupl(), it assumes
535 that the request is already correctly configured with a block number and a size divisible by page size
536 and will just call directly to the device.
537 @param devvp Device on which to perform I/O
538 @param ap vnop_strategy_args structure (most importantly, a buffer).
539 @return 0 for success, or errors from filesystem or device layers.
540 */
541errno_t buf_strategy(vnode_t devvp, void *ap);
542
543/*
544 * Flags for buf_invalblkno()
545 */
546#define BUF_WAIT 0x01
547
548/*!
549 @function buf_invalblkno
550 @abstract Invalidate a filesystem logical block in a file.
551 @discussion buf_invalblkno() tries to make the data for a given block in a file
552 invalid; if the buffer for that block is found in core and is not busy, we mark it
553 invalid and call buf_brelse() (see "flags" param for what happens if the buffer is busy).
554 buf_brelse(), noticing that it is invalid, will
555 will return the buffer to the empty-buffer list and tell the VM subsystem to abandon
556 the relevant pages. Data will not be written to backing store--it will be cast aside.
557 Note that this function will only work if the block in question has been
558 obtained with a buf_getblk(). If data has been read into core without using
559 traditional buffer cache routines, buf_invalblkno() will not be able to invalidate it--this
560 includes the use of iobufs.
561 @param vp vnode whose block to invalidate.
562 @param lblkno Logical block number.
563 @param flags BUF_WAIT: wait for busy buffers to become unbusy and invalidate them then. Otherwise,
564 just return EBUSY for busy blocks.
565 @return 0 for success, EINVAL if vp is not a device file.
566 */
567errno_t buf_invalblkno(vnode_t vp, daddr64_t lblkno, int flags);
568
569/*!
570 @function buf_callback
571 @abstract Get the function set to be called when I/O on a buffer completes.
572 @discussion A function returned by buf_callback was originally set with buf_setcallback().
573 @param bp Buffer whose callback to get.
574 @return 0 for success, or errors from filesystem or device layers.
575 */
576void * buf_callback(buf_t bp);
577
578/*!
579 @function buf_setcallback
580 @abstract Set a function to be called once when I/O on a buffer completes.
581 @discussion A one-shot callout set with buf_setcallback() will be called from buf_biodone()
582 when I/O completes. It will be passed the "transaction" argument as well as the buffer.
583 buf_setcallback() also marks the buffer as B_ASYNC.
584 @param bp Buffer whose callback to set.
585 @param callback function to use as callback.
586 @param transaction Additional argument to callback function.
587 @return 0; always succeeds.
588 */
589errno_t buf_setcallback(buf_t bp, void (*callback)(buf_t, void *), void *transaction);
590
591/*!
592 @function buf_setupl
593 @abstract Set the UPL (Universal Page List), and offset therein, on a buffer.
594 @discussion buf_setupl() should only be called on buffers allocated with buf_alloc().
595 A subsequent call to buf_map() will map the UPL and give back the address at which data
596 begins. After buf_setupl() is called, a buffer is marked B_CLUSTER; when this is the case,
597 buf_strategy() assumes that a buffer is correctly configured to be passed to the device
598 layer without modification. Passing a NULL upl will clear the upl and the B_CLUSTER flag on the
599 buffer.
600 @param bp Buffer whose upl to set.
601 @param upl UPL to set in the buffer.
602 @param offset Offset within upl at which relevant data begin.
603 @return 0 for success, EINVAL if the buffer was not allocated with buf_alloc().
604 */
605errno_t buf_setupl(buf_t bp, upl_t upl, uint32_t offset);
606
607/*!
608 @function buf_clone
609 @abstract Clone a buffer with a restricted range and an optional callback.
610 @discussion Generates a buffer which is identical to its "bp" argument except that
611 it spans a subset of the data of the original. The buffer to be cloned should
612 have been allocated with buf_alloc(). Checks its arguments to make sure
613 that the data subset is coherent. Optionally, adds a callback function and argument to it
614 to be called when I/O completes (as with buf_setcallback(), but B_ASYNC is not set). If the original buffer had
615 a upl set through buf_setupl(), this upl is copied to the new buffer; otherwise, the original's
616 data pointer is used raw. The buffer must be released with buf_free().
617 @param bp Buffer to clone.
618 @param io_offset Offset, relative to start of data in original buffer, at which new buffer's data will begin.
619 @param io_size Size of buffer region in new buffer, in the sense of buf_count().
620 @param iodone Callback to be called from buf_biodone() when I/O completes, in the sense of buf_setcallback().
621 @param arg Argument to pass to iodone() callback.
622 @return NULL if io_offset/io_size combination is invalid for the buffer to be cloned; otherwise, the new buffer.
623 */
624buf_t buf_clone(buf_t bp, int io_offset, int io_size, void (*iodone)(buf_t, void *), void *arg);
625
626
627/*!
628 @function buf_create_shadow
629 @abstract Create a shadow buffer with optional private storage and an optional callback.
630 @param bp Buffer to shadow.
631 @param force_copy If TRUE, do not link the shadaow to 'bp' and if 'external_storage' == NULL,
632 force a copy of the data associated with 'bp'.
633 @param external_storage If non-NULL, associate it with the new buffer as its storage instead of the
634 storage currently associated with 'bp'.
635 @param iodone Callback to be called from buf_biodone() when I/O completes, in the sense of buf_setcallback().
636 @param arg Argument to pass to iodone() callback.
637 @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.
638*/
639
640buf_t buf_create_shadow(buf_t bp, boolean_t force_copy, uintptr_t external_storage, void (*iodone)(buf_t, void *), void *arg);
641
642
643/*!
644 @function buf_shadow
645 @abstract returns true if 'bp' is a shadow of another buffer.
646 @param bp Buffer to query.
647 @return 1 if 'bp' is a shadow, 0 otherwise.
648*/
649int buf_shadow(buf_t bp);
650
651
652/*!
653 @function buf_alloc
654 @abstract Allocate an uninitialized buffer.
655 @discussion A buffer returned by buf_alloc() is marked as busy and as an iobuf; it has no storage set up and must be
656 set up using buf_setdataptr() or buf_setupl()/buf_map().
657 @param vp vnode to associate with the buffer: optionally NULL. If vp is a device file, then
658 the buffer's associated device will be set. If vp is NULL, it can be set later with buf_setvnode().
659 @return New buffer.
660 */
661buf_t buf_alloc(vnode_t vp);
662
663/*!
664 @function buf_free
665 @abstract Free a buffer that was allocated with buf_alloc().
666 @discussion The storage (UPL, data pointer) associated with an iobuf must be freed manually.
667 @param bp The buffer to free.
668 */
669void buf_free(buf_t bp);
670
671/*
672 * flags for buf_invalidateblks
673 */
674#define BUF_WRITE_DATA 0x0001 /* write data blocks first */
675#define BUF_SKIP_META 0x0002 /* skip over metadata blocks */
676#define BUF_INVALIDATE_LOCKED 0x0004 /* force B_LOCKED blocks to be invalidated */
677
678/*!
679 @function buf_invalidateblks
680 @abstract Invalidate all the blocks associated with a vnode.
681 @discussion This function does for all blocks associated with a vnode what buf_invalblkno does for one block.
682 Again, it will only be able to invalidate data which were populated with traditional buffer cache routines,
683 i.e. by buf_getblk() and callers thereof. Unlike buf_invalblkno(), it can be made to write dirty data to disk
684 rather than casting it aside.
685 @param vp The vnode whose data to invalidate.
686 @param flags BUF_WRITE_DATA: write dirty data to disk with VNOP_BWRITE() before kicking buffer cache entries out.
687 BUF_SKIP_META: do not invalidate metadata blocks.
688 @param slpflag Flags to pass to "msleep" while waiting to acquire busy buffers.
689 @param slptimeo Timeout in "hz" (1/100 second) to wait for a buffer to become unbusy before waking from sleep
690 and re-starting the scan.
691 @return 0 for success, error values from msleep().
692 */
693int buf_invalidateblks(vnode_t vp, int flags, int slpflag, int slptimeo);
694
695/*
696 * flags for buf_flushdirtyblks and buf_iterate
697 */
698#define BUF_SKIP_NONLOCKED 0x01
699#define BUF_SKIP_LOCKED 0x02
700#define BUF_SCAN_CLEAN 0x04 /* scan the clean buffers */
701#define BUF_SCAN_DIRTY 0x08 /* scan the dirty buffers */
702#define BUF_NOTIFY_BUSY 0x10 /* notify the caller about the busy pages during the scan */
703
704
705#define BUF_RETURNED 0
706#define BUF_RETURNED_DONE 1
707#define BUF_CLAIMED 2
708#define BUF_CLAIMED_DONE 3
709/*!
710 @function buf_flushdirtyblks
711 @abstract Write dirty file blocks to disk.
712 @param vp The vnode whose blocks to flush.
713 @param wait Wait for writes to complete before returning.
714 @param flags Can pass zero, meaning "flush all dirty buffers."
715 BUF_SKIP_NONLOCKED: Skip buffers which are not busy when we encounter them.
716 BUF_SKIP_LOCKED: Skip buffers which are busy when we encounter them.
717 @param msg String to pass to msleep().
718 */
719void buf_flushdirtyblks(vnode_t vp, int wait, int flags, const char *msg);
720
721/*!
722 @function buf_iterate
723 @abstract Perform some operation on all buffers associated with a vnode.
724 @param vp The vnode whose buffers to scan.
725 @param callout Function to call on each buffer. Should return one of:
726 BUF_RETURNED: buf_iterate() should call buf_brelse() on the buffer.
727 BUF_RETURNED_DONE: buf_iterate() should call buf_brelse() on the buffer and then stop iterating.
728 BUF_CLAIMED: buf_iterate() should continue iterating (and not call buf_brelse()).
729 BUF_CLAIMED_DONE: buf_iterate() should stop iterating (and not call buf_brelse()).
730 @param flags
731 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.
732 BUF_SCAN_CLEAN: Call out on clean buffers.
733 BUF_SCAN_DIRTY: Call out on dirty buffers.
734 BUF_NOTIFY_BUSY: If a buffer cannot be acquired, pass a NULL buffer to callout; otherwise,
735 that buffer will be silently skipped.
736 @param arg Argument to pass to callout in addition to buffer.
737 */
738void buf_iterate(vnode_t vp, int (*callout)(buf_t, void *), int flags, void *arg);
739
740/*!
741 @function buf_clear
742 @abstract Zero out the storage associated with a buffer.
743 @discussion Calls buf_map() to get the buffer's data address; for a B_CLUSTER
744 buffer (one which has had buf_setupl() called on it), it tries to map the buffer's
745 UPL into memory; should only be called once during the life cycle of an iobuf (one allocated
746 with buf_alloc()).
747 @param bp The buffer to zero out.
748 */
749void buf_clear(buf_t bp);
750
751/*!
752 @function buf_bawrite
753 @abstract Start an asychronous write on a buffer.
754 @discussion Calls VNOP_BWRITE to start the process of propagating an asynchronous write down to the device layer.
755 Callers can wait for writes to complete at their discretion using buf_biowait(). When this function is called,
756 data should already have been written to the buffer's data region.
757 @param bp The buffer on which to initiate I/O.
758 @return EWOULDBLOCK if write count is high and "throttle" is zero; otherwise, errors from VNOP_BWRITE.
759 */
760errno_t buf_bawrite(buf_t bp);
761
762/*!
763 @function buf_bdwrite
764 @abstract Mark a buffer for delayed write.
765 @discussion Marks a buffer as waiting for delayed write and the current I/O as complete; data will be written to backing store
766 before the buffer is reused, but it will not be queued for I/O immediately. Note that for buffers allocated
767 with buf_alloc(), there are no such guarantees; you must take care of your own flushing to disk. If
768 the number of delayed writes pending on the system is greater than an internal limit and the caller has not
769 requested otherwise [see return_error] , buf_bdwrite() will unilaterally launch an asynchronous I/O with buf_bawrite() to keep the pile of
770 delayed writes from getting too large.
771 @param bp The buffer to mark for delayed write.
772 @return EAGAIN for return_error != 0 case, 0 for succeess, errors from buf_bawrite.
773 */
774errno_t buf_bdwrite(buf_t bp);
775
776/*!
777 @function buf_bwrite
778 @abstract Write a buffer's data to backing store.
779 @discussion Once the data in a buffer has been modified, buf_bwrite() starts sending it to disk by calling
780 VNOP_STRATEGY. Unless B_ASYNC has been set on the buffer (by buf_setflags() or otherwise), data will have
781 been written to disk when buf_bwrite() returns. See Bach (p 56).
782 @param bp The buffer to write to disk.
783 @return 0 for success; errors from buf_biowait().
784 */
785errno_t buf_bwrite(buf_t bp);
786
787/*!
788 @function buf_biodone
789 @abstract Mark an I/O as completed.
790 @discussion buf_biodone() should be called by whosoever decides that an I/O on a buffer is complete; for example,
791 IOStorageFamily. It clears the dirty flag on a buffer and signals on the vnode that a write has completed
792 with vnode_writedone(). If a callout or filter has been set on the buffer, that function is called. In the case
793 of a callout, that function is expected to take care of cleaning up and freeing the buffer.
794 Otherwise, if the buffer is marked B_ASYNC (e.g. it was passed to buf_bawrite()), then buf_biodone()
795 considers itself justified in calling buf_brelse() to return it to free lists--no one is waiting for it. Finally,
796 waiters on the bp (e.g. in buf_biowait()) are woken up.
797 @param bp The buffer to mark as done with I/O.
798 */
799void buf_biodone(buf_t bp);
800
801/*!
802 @function buf_biowait
803 @abstract Wait for I/O on a buffer to complete.
804 @discussion Waits for I/O on a buffer to finish, as marked by a buf_biodone() call.
805 @param bp The buffer to wait on.
806 @return 0 for a successful wait; nonzero the buffer has been marked as EINTR or had an error set on it.
807 */
808errno_t buf_biowait(buf_t bp);
809
810/*!
811 @function buf_brelse
812 @abstract Release any claim to a buffer, sending it back to free lists.
813 @discussion buf_brelse() cleans up buffer state and releases a buffer to the free lists. If the buffer
814 is not marked invalid and its pages are dirty (e.g. a delayed write was made), its data will be commited
815 to backing store. If it is marked invalid, its data will be discarded completely.
816 A valid, cacheable buffer will be put on a list and kept in the buffer hash so it
817 can be found again; otherwise, it will be dissociated from its vnode and treated as empty. Which list a valid
818 buffer is placed on depends on the use of buf_markaged(), whether it is metadata, and the B_LOCKED flag. A
819 B_LOCKED buffer will not be available for reuse by other files, though its data may be paged out.
820 Note that buf_brelse() is intended for use with traditionally allocated buffers.
821 @param bp The buffer to release.
822 */
823void buf_brelse(buf_t bp);
824
825/*!
826 @function buf_bread
827 @abstract Synchronously read a block of a file.
828 @discussion buf_bread() is the traditional way to read a single logical block of a file through the buffer cache.
829 It tries to find the buffer and corresponding page(s) in core, calls VNOP_STRATEGY if necessary to bring the data
830 into memory, and waits for I/O to complete. It should not be used to read blocks of greater than 4K (one VM page)
831 in size; use cluster routines for large reads. Indeed, the cluster layer is a more efficient choice for reading DATA
832 unless you need some finely-tuned semantics that it cannot provide.
833 @param vp The file from which to read.
834 @param blkno The logical (filesystem) block number to read.
835 @param size Size of block; do not use for sizes > 4K.
836 @param cred Credential to store and use for reading from disk if data are not already in core.
837 @param bpp Destination pointer for buffer.
838 @return 0 for success, or an error from buf_biowait().
839 */
840errno_t buf_bread(vnode_t vp, daddr64_t blkno, int size, kauth_cred_t cred, buf_t *bpp);
841
842/*!
843 @function buf_breadn
844 @abstract Read a block from a file with read-ahead.
845 @discussion buf_breadn() reads one block synchronously in the style of buf_bread() and fires
846 off a specified set of asynchronous reads to improve the likelihood of future cache hits.
847 It should not be used to read blocks of greater than 4K (one VM page) in size; use cluster
848 routines for large reads. Indeed, the cluster layer is a more efficient choice for reading DATA
849 unless you need some finely-tuned semantics that it cannot provide.
850 @param vp The file from which to read.
851 @param blkno The logical (filesystem) block number to read synchronously.
852 @param size Size of block; do not use for sizes > 4K.
853 @param rablks Array of logical block numbers for asynchronous read-aheads.
854 @param rasizes Array of block sizes for asynchronous read-aheads, each index corresponding to same index in "rablks."
855 @param nrablks Number of entries in read-ahead arrays.
856 @param cred Credential to store and use for reading from disk if data are not already in core.
857 @param bpp Destination pointer for buffer.
858 @return 0 for success, or an error from buf_biowait().
859 */
860errno_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);
861
862/*!
863 @function buf_meta_bread
864 @abstract Synchronously read a metadata block of a file.
865 @discussion buf_meta_bread() is the traditional way to read a single logical block of a file through the buffer cache.
866 It tries to find the buffer and corresponding page(s) in core, calls VNOP_STRATEGY if necessary to bring the data
867 into memory, and waits for I/O to complete. It should not be used to read blocks of greater than 4K (one VM page)
868 in size; use cluster routines for large reads. Reading meta-data through the traditional buffer cache, unlike
869 reading data, is efficient and encouraged, especially if the blocks being read are significantly smaller than page size.
870 @param vp The file from which to read.
871 @param blkno The logical (filesystem) block number to read.
872 @param size Size of block; do not use for sizes > 4K.
873 @param cred Credential to store and use for reading from disk if data are not already in core.
874 @param bpp Destination pointer for buffer.
875 @return 0 for success, or an error from buf_biowait().
876 */
877errno_t buf_meta_bread(vnode_t vp, daddr64_t blkno, int size, kauth_cred_t cred, buf_t *bpp);
878
879/*!
880 @function buf_meta_breadn
881 @abstract Read a metadata block from a file with read-ahead.
882 @discussion buf_meta_breadn() reads one block synchronously in the style of buf_meta_bread() and fires
883 off a specified set of asynchronous reads to improve the likelihood of future cache hits.
884 It should not be used to read blocks of greater than 4K (one VM page) in size; use cluster
885 routines for large reads.
886 @param vp The file from which to read.
887 @param blkno The logical (filesystem) block number to read synchronously.
888 @param size Size of block; do not use for sizes > 4K.
889 @param rablks Array of logical block numbers for asynchronous read-aheads.
890 @param rasizes Array of block sizes for asynchronous read-aheads, each index corresponding to same index in "rablks."
891 @param nrablks Number of entries in read-ahead arrays.
892 @param cred Credential to store and use for reading from disk if data are not already in core.
893 @param bpp Destination pointer for buffer.
894 @return 0 for success, or an error from buf_biowait().
895 */
896errno_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);
897
898/*!
899 @function minphys
900 @abstract Adjust a buffer's count to be no more than maximum physical I/O transfer size for the host architecture.
901 @discussion physio() takes as a parameter a function to bound transfer sizes for each VNOP_STRATEGY() call. minphys()
902 is a default implementation. It calls buf_setcount() to make the buffer's count the min() of its current count
903 and the max I/O size for the host architecture.
904 @param bp The buffer whose byte count to modify.
905 @return New byte count.
906 */
907u_int minphys(buf_t bp);
908
909/*!
910 @function physio
911 @abstract Perform I/O on a device to/from target memory described by a uio.
912 @discussion physio() allows I/O directly from a device to user-space memory. It waits
913 for all I/O to complete before returning.
914 @param f_strategy Strategy routine to call to initiate I/O.
915 @param bp Buffer to configure and pass to strategy routine; can be NULL.
916 @param dev Device on which to perform I/O.
917 @param flags B_READ or B_WRITE.
918 @param f_minphys Function which calls buf_setcount() to set a byte count which is suitably
919 small for the device in question. Returns byte count that has been set (or unchanged) on the buffer.
920 @param uio UIO describing the I/O operation.
921 @param blocksize Logical block size for this vnode.
922 @return 0 for success; EFAULT for an invalid uio; errors from buf_biowait().
923 */
924int 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);
925
926
927/*
928 * Flags for operation type in getblk()
929 */
930#define BLK_READ 0x01 /* buffer for read */
931#define BLK_WRITE 0x02 /* buffer for write */
932#define BLK_META 0x10 /* buffer for metadata */
933/*
934 * modifier for above flags... if set, getblk will only return
935 * a bp that is already valid... i.e. found in the cache
936 */
937#define BLK_ONLYVALID 0x80000000
938
939/*!
940 @function buf_getblk
941 @abstract Traditional buffer cache routine to get a buffer corresponding to a logical block in a file.
942 @discussion buf_getblk() gets a buffer, not necessarily containing valid data, representing a block in a file.
943 A metadata buffer will be returned with its own zone-allocated storage, managed by the traditional buffer-cache
944 layer, whereas data buffers will be returned hooked into backing by the UBC (which in fact controls the caching of data).
945 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
946 unbusy, depending on the slpflag and slptimeo parameters. If the buffer is found unbusy and is a metadata buffer,
947 it must already contain valid data and will be returned directly; data buffers will have a UPL configured to
948 prepare for interaction with the underlying UBC. If the buffer is found in core, it will be marked as such
949 and buf_fromcache() will return truth. A buffer is allocated and initialized (but not filled with data)
950 if none is found in core. buf_bread(), buf_breadn(), buf_meta_bread(), and buf_meta_breadn() all
951 return buffers obtained with buf_getblk().
952 @param vp File for which to get block.
953 @param blkno Logical block number.
954 @param size Size of block.
955 @param slpflag Flag to pass to msleep() while waiting for buffer to become unbusy.
956 @param slptimeo Time, in milliseconds, to wait for buffer to become unbusy. 0 means to wait indefinitely.
957 @param operation BLK_READ: want a read buffer. BLK_WRITE: want a write buffer. BLK_META: want a metadata buffer. BLK_ONLYVALID:
958 only return buffers which are found in core (do not allocate anew), and do not change buffer size. The last remark means
959 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.
960 @return Buffer found in core or newly allocated, either containing valid data or ready for I/O.
961 */
962buf_t buf_getblk(vnode_t vp, daddr64_t blkno, int size, int slpflag, int slptimeo, int operation);
963
964/*!
965 @function buf_geteblk
966 @abstract Get a metadata buffer which is marked invalid and not associated with any vnode.
967 @discussion A buffer is returned with zone-allocated storage of the specified size, marked B_META and invalid.
968 It has no vnode and is not visible in the buffer hash.
969 @param size Size of buffer.
970 @return Always returns a new buffer.
971 */
972buf_t buf_geteblk(int size);
973
974/*!
975 @function buf_clear_redundancy_flags
976 @abstract Clear flags on a buffer.
977 @discussion buffer_redundancy_flags &= ~flags
978 @param bp Buffer whose flags to clear.
979 @param flags Flags to remove from buffer's mask
980 */
981void buf_clear_redundancy_flags(buf_t bp, uint32_t flags);
982
983/*!
984 @function buf_redundancyflags
985 @abstract Get redundancy flags set on a buffer.
986 @param bp Buffer whose redundancy flags to grab.
987 @return flags.
988 */
989uint32_t buf_redundancy_flags(buf_t bp);
990
991/*!
992 @function buf_setredundancyflags
993 @abstract Set redundancy flags on a buffer.
994 @discussion buffer_redundancy_flags |= flags
995 @param bp Buffer whose flags to set.
996 @param flags Flags to add to buffer's redundancy flags
997 */
998void buf_set_redundancy_flags(buf_t bp, uint32_t flags);
999
1000/*!
1001 @function buf_attr
1002 @abstract Gets the attributes for this buf.
1003 @param bp Buffer whose attributes to get.
1004 @return bufattr_t.
1005 */
1006bufattr_t buf_attr(buf_t bp);
1007
1008/*!
1009 @function buf_markstatic
1010 @abstract Mark a buffer as being likely to contain static data.
1011 @param bp Buffer to mark.
1012 */
1013 void buf_markstatic(buf_t bp);
1014
1015/*!
1016 @function buf_static
1017 @abstract Check if a buffer contains static data.
1018 @param bp Buffer to test.
1019 @return Nonzero if buffer has static data, 0 otherwise.
1020 */
1021int buf_static(buf_t bp);
1022
1023#ifdef KERNEL_PRIVATE
1024void buf_setfilter(buf_t, void (*)(buf_t, void *), void *, void (**)(buf_t, void *), void **);
1025
1026/* bufattr allocation/duplication/deallocation functions */
1027bufattr_t bufattr_alloc(void);
1028bufattr_t bufattr_dup (bufattr_t bap);
1029void bufattr_free(bufattr_t bap);
1030
1031/*!
1032 @function bufattr_cpx
1033 @abstract Returns a pointer to a cpx_t structure.
1034 @param bap Buffer Attribute whose cpx_t structure you wish to get.
1035 @return Returns a cpx_t structure, or NULL if not valid
1036 */
1037struct cpx *bufattr_cpx(bufattr_t bap);
1038
1039/*!
1040 @function bufattr_setcpx
1041 @abstract Set the cp_ctx on a buffer attribute.
1042 @param bap Buffer Attribute that you wish to change
1043 */
1044void bufattr_setcpx(bufattr_t bap, struct cpx *cpx);
1045
1046/*!
1047 @function bufattr_cpoff
1048 @abstract Gets the file offset on the buffer.
1049 @param bap Buffer Attribute whose file offset value is used
1050 */
1051uint64_t bufattr_cpoff(bufattr_t bap);
1052
1053/*!
1054 @function bufattr_setcpoff
1055 @abstract Set the file offset for a content protected I/O on
1056 a buffer attribute.
1057 @param bap Buffer Attribute whose cp file offset has to be set
1058 */
1059void bufattr_setcpoff(bufattr_t bap, uint64_t);
1060
1061/*!
1062 @function bufattr_rawencrypted
1063 @abstract Check if a buffer contains raw encrypted data.
1064 @param bap Buffer attribute to test.
1065 @return Nonzero if buffer has raw encrypted data, 0 otherwise.
1066 */
1067int bufattr_rawencrypted(bufattr_t bap);
1068
1069/*!
1070 @function bufattr_markgreedymode
1071 @abstract Mark a buffer to use the greedy mode for writing.
1072 @param bap Buffer attributes to mark.
1073 @discussion Greedy Mode: request improved write performance from the underlying device at the expense of storage efficiency
1074 */
1075 void bufattr_markgreedymode(bufattr_t bap);
1076
1077/*!
1078 @function bufattr_greedymode
1079 @abstract Check if a buffer is written using the Greedy Mode
1080 @param bap Buffer attributes to test.
1081 @discussion Greedy Mode: request improved write performance from the underlying device at the expense of storage efficiency
1082 @return Nonzero if buffer uses greedy mode, 0 otherwise.
1083 */
1084int bufattr_greedymode(bufattr_t bap);
1085
1086/*!
1087 @function bufattr_markisochronous
1088 @abstract Mark a buffer to use the isochronous throughput mode for writing.
1089 @param bap Buffer attributes to mark.
1090 @discussion isochronous mode: request improved write performance from the underlying device at the expense of storage efficiency
1091 */
1092 void bufattr_markisochronous(bufattr_t bap);
1093
1094 /*!
1095 @function bufattr_isochronous
1096 @abstract Check if a buffer is written using the isochronous
1097 @param bap Buffer attributes to test.
1098 @discussion isochronous mode: request improved write performance from the underlying device at the expense of storage efficiency
1099 @return Nonzero if buffer uses isochronous mode, 0 otherwise.
1100 */
1101int bufattr_isochronous(bufattr_t bap);
1102
1103
1104/*!
1105 @function bufattr_throttled
1106 @abstract Check if a buffer is throttled.
1107 @param bap Buffer attribute to test.
1108 @return Nonzero if the buffer is throttled, 0 otherwise.
1109 */
1110int bufattr_throttled(bufattr_t bap);
1111
1112/*!
1113 @function bufattr_passive
1114 @abstract Check if a buffer is marked passive.
1115 @param bap Buffer attribute to test.
1116 @return Nonzero if the buffer is marked passive, 0 otherwise.
1117 */
1118int bufattr_passive(bufattr_t bap);
1119
1120/*!
1121 @function bufattr_nocache
1122 @abstract Check if a buffer has nocache attribute.
1123 @param bap Buffer attribute to test.
1124 @return Nonzero if the buffer is not cached, 0 otherwise.
1125 */
1126int bufattr_nocache(bufattr_t bap);
1127
1128/*!
1129 @function bufattr_meta
1130 @abstract Check if a buffer has the bufattr meta attribute.
1131 @param bap Buffer attribute to test.
1132 @return Nonzero if the buffer has meta attribute, 0 otherwise.
1133 */
1134
1135int bufattr_meta(bufattr_t bap);
1136
1137/*!
1138 @function bufattr_markmeta
1139 @abstract Set the bufattr meta attribute.
1140 @param bap Buffer attribute to manipulate.
1141 */
1142void bufattr_markmeta(bufattr_t bap);
1143
1144
1145/*!
1146 @function bufattr_delayidlesleep
1147 @abstract Check if a buffer is marked to delay idle sleep on disk IO.
1148 @param bap Buffer attribute to test.
1149 @return Nonzero if the buffer is marked to delay idle sleep on disk IO, 0 otherwise.
1150 */
1151int bufattr_delayidlesleep(bufattr_t bap);
1152
1153/*!
1154 @function buf_kernel_addrperm_addr
1155 @abstract Obfuscate the buf pointers.
1156 @param addr Buf_t pointer.
1157 @return Obfuscated pointer if addr is non zero, 0 otherwise.
1158 */
1159vm_offset_t buf_kernel_addrperm_addr(void * addr);
1160
1161/*!
1162 @function bufattr_markquickcomplete
1163 @abstract Mark a buffer to hint quick completion to the driver.
1164 @discussion This flag hints the storage driver that some thread is waiting for this I/O to complete.
1165 It should therefore attempt to complete it as soon as possible at the cost of device efficiency.
1166 @param bap Buffer attributes to mark.
1167 */
1168void bufattr_markquickcomplete(bufattr_t bap);
1169
1170/*!
1171 @function bufattr_quickcomplete
1172 @abstract Check if a buffer is marked for quick completion
1173 @discussion This flag hints the storage driver that some thread is waiting for this I/O to complete.
1174 It should therefore attempt to complete it as soon as possible at the cost of device efficiency.
1175 @param bap Buffer attribute to test.
1176 @return Nonzero if the buffer is marked for quick completion, 0 otherwise.
1177 */
1178int bufattr_quickcomplete(bufattr_t bap);
1179
1180int count_lock_queue(void);
1181
1182/*
1183 * Flags for buf_acquire
1184 */
1185#define BAC_NOWAIT 0x01 /* Don't wait if buffer is busy */
1186#define BAC_REMOVE 0x02 /* Remove from free list once buffer is acquired */
1187#define BAC_SKIP_NONLOCKED 0x04 /* Don't return LOCKED buffers */
1188#define BAC_SKIP_LOCKED 0x08 /* Only return LOCKED buffers */
1189
1190errno_t buf_acquire(buf_t, int, int, int);
1191
1192buf_t buf_create_shadow_priv(buf_t bp, boolean_t force_copy, uintptr_t external_storage, void (*iodone)(buf_t, void *), void *arg);
1193
1194void buf_drop(buf_t);
1195
1196#endif /* KERNEL_PRIVATE */
1197
1198__END_DECLS
1199
1200
1201/* Macros to clear/set/test flags. */
1202#define SET(t, f) (t) |= (f)
1203#define CLR(t, f) (t) &= ~(f)
1204#define ISSET(t, f) ((t) & (f))
1205
1206
1207#endif /* !_SYS_BUF_H_ */
1208