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_map_range
328 * @abstract Get virtual mappings for buffer data.
329 * @discussion Similar to buf_map but the focus is on a range
330 * of the UPL. The b_uploffset and b_count control what part of the UPL will be mapped.
331 * @param bp Buffer whose mapping to find or create.
332 * @param io_addr Destination for mapping address.
333 * @return 0 for success, ENOMEM if unable to map the buffer.
334 */
335errno_t buf_map_range(buf_t bp, caddr_t *io_addr);
336
337/*!
338 * @function buf_map_range_with_prot
339 * @abstract Get virtual mappings for buffer data.
340 * @discussion Similar to buf_map_range but also takes protection so that part of the UPL
341 * will be mapped with the requested protection.
342 * @param bp Buffer whose mapping to find or create.
343 * @param io_addr Destination for mapping address.
344 * @return 0 for success, ENOMEM if unable to map the buffer.
345 */
346errno_t buf_map_range_with_prot(buf_t bp, caddr_t *io_addr, vm_prot_t prot);
347
348/*!
349 * @function buf_unmap
350 * @abstract Release mappings for buffer data.
351 * @discussion For buffers created through buf_getblk() (i.e. traditional buffer cache usage),
352 * buf_unmap() does nothing; buf_brelse() will take care of unmapping. For a B_CLUSTER buffer, i.e. an iobuf
353 * whose upl state is managed manually, there are two possibilities. If the buffer was created
354 * with an underlying "real" buffer through cluster_bp(), buf_unmap() does nothing; buf_brelse() on the
355 * underlying buffer will tear down the mapping. Otherwise, the buffer was created with buf_alloc() and
356 * buf_setupl() was subsequently called; buf_map() created the mapping. In this case, buf_unmap() will
357 * unmap the buffer.
358 * @param bp Buffer whose mapping to find or create.
359 * @return 0 for success, EINVAL if unable to unmap buffer.
360 */
361errno_t buf_unmap(buf_t bp);
362
363/*!
364 * @function buf_unmap_range
365 * @abstract Release mappings for buffer data.
366 * @discussion Similar to buf_unmap but the focus is on a range
367 * of the UPL. The b_uploffset and b_count control what part of the UPL will be unmapped.
368 * @param bp Buffer whose mapping to find or create.
369 * @return 0 for success, EINVAL if unable to unmap buffer.
370 */
371errno_t buf_unmap_range(buf_t bp);
372
373/*!
374 * @function buf_setdrvdata
375 * @abstract Set driver-specific data on a buffer.
376 * @param bp Buffer whose driver-data to set.
377 * @param drvdata Opaque driver data.
378 */
379void buf_setdrvdata(buf_t bp, void *drvdata);
380
381/*!
382 * @function buf_setdrvdata
383 * @abstract Get driver-specific data from a buffer.
384 * @param bp Buffer whose driver data to get.
385 * @return Opaque driver data.
386 */
387void * buf_drvdata(buf_t bp);
388
389/*!
390 * @function buf_setfsprivate
391 * @abstract Set filesystem-specific data on a buffer.
392 * @param bp Buffer whose filesystem data to set.
393 * @param fsprivate Opaque filesystem data.
394 */
395void buf_setfsprivate(buf_t bp, void *fsprivate);
396
397/*!
398 * @function buf_fsprivate
399 * @abstract Get filesystem-specific data from a buffer.
400 * @param bp Buffer whose filesystem data to get.
401 * @return Opaque filesystem data.
402 */
403void * buf_fsprivate(buf_t bp);
404
405/*!
406 * @function buf_blkno
407 * @abstract Get physical block number associated with a buffer, in the sense of VNOP_BLOCKMAP.
408 * @discussion When a buffer's physical block number is the same is its logical block number, then the physical
409 * block number is considered uninitialized. A physical block number of -1 indicates that there is no valid
410 * physical mapping (e.g. the logical block is invalid or corresponds to a sparse region in a file). Physical
411 * block number is normally set by the cluster layer or by buf_getblk().
412 * @param bp Buffer whose physical block number to get.
413 * @return Block number.
414 */
415daddr64_t buf_blkno(buf_t bp);
416
417/*!
418 * @function buf_lblkno
419 * @abstract Get logical block number associated with a buffer.
420 * @discussion Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(),
421 * for example by buf_bread().
422 * @param bp Buffer whose logical block number to get.
423 * @return Block number.
424 */
425daddr64_t buf_lblkno(buf_t bp);
426
427/*!
428 * @function buf_lblksize
429 * @abstract Get the block size used to calculate the logical block number associated with a buffer.
430 * @discussion Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(),
431 * for example by buf_bread(). Block size is the block size used to calculate the file offset.
432 * @param bp Buffer whose logical block size to get.
433 * @return Block size.
434 */
435uint32_t buf_lblksize(buf_t bp);
436
437/*!
438 * @function buf_setblkno
439 * @abstract Set physical block number associated with a buffer.
440 * @discussion Physical block number is generally set by the cluster layer or by buf_getblk().
441 * @param bp Buffer whose physical block number to set.
442 * @param blkno Block number to set.
443 */
444void buf_setblkno(buf_t bp, daddr64_t blkno);
445
446/*!
447 * @function buf_setlblkno
448 * @abstract Set logical block number associated with a buffer.
449 * @discussion Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(),
450 * for example by buf_bread().
451 * @param bp Buffer whose logical block number to set.
452 * @param lblkno Block number to set.
453 */
454void buf_setlblkno(buf_t bp, daddr64_t lblkno);
455
456/*!
457 * @function buf_setlblksize
458 * @abstract Set block size used to set the logical block number associated with a buffer.
459 * @discussion Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(),
460 * for example by buf_bread().
461 * @param bp Buffer whose logical block size to set.
462 * @param lblksize Block size to set.
463 */
464void buf_setlblksize(buf_t bp, uint32_t lblksize);
465
466/*!
467 * @function buf_count
468 * @abstract Get count of valid bytes in a buffer. This may be less than the space allocated to the buffer.
469 * @param bp Buffer whose byte count to get.
470 * @return Byte count.
471 */
472uint32_t buf_count(buf_t bp);
473
474/*!
475 * @function buf_size
476 * @abstract Get size of data region allocated to a buffer.
477 * @discussion May be larger than amount of valid data in buffer.
478 * @param bp Buffer whose size to get.
479 * @return Size.
480 */
481uint32_t buf_size(buf_t bp);
482
483/*!
484 * @function buf_resid
485 * @abstract Get a count of bytes which were not consumed by an I/O on a buffer.
486 * @discussion Set when an I/O operations completes.
487 * @param bp Buffer whose outstanding count to get.
488 * @return Count of unwritten/unread bytes.
489 */
490uint32_t buf_resid(buf_t bp);
491
492/*!
493 * @function buf_setcount
494 * @abstract Set count of valid bytes in a buffer. This may be less than the space allocated to the buffer.
495 * @param bp Buffer whose byte count to set.
496 * @param bcount Count to set.
497 */
498void buf_setcount(buf_t bp, uint32_t bcount);
499
500/*!
501 * @function buf_setsize
502 * @abstract Set size of data region allocated to a buffer.
503 * @discussion May be larger than amount of valid data in buffer. Should be used by
504 * code which is manually providing storage for an iobuf, one allocated with buf_alloc().
505 * @param bp Buffer whose size to set.
506 */
507void buf_setsize(buf_t bp, uint32_t);
508
509/*!
510 * @function buf_setresid
511 * @abstract Set a count of bytes outstanding for I/O in a buffer.
512 * @discussion Set when an I/O operations completes. Examples: called by IOStorageFamily when I/O
513 * completes, often called on an "original" buffer when using a manipulated buffer to perform I/O
514 * on behalf of the first.
515 * @param bp Buffer whose outstanding count to set.
516 */
517void buf_setresid(buf_t bp, uint32_t resid);
518
519/*!
520 * @function buf_setdataptr
521 * @abstract Set the address at which a buffer's data will be stored.
522 * @discussion In traditional buffer use, the data pointer will be set automatically. This routine is
523 * useful with iobufs (allocated with buf_alloc()).
524 * @param bp Buffer whose data pointer to set.
525 * @param data Pointer to data region.
526 */
527void buf_setdataptr(buf_t bp, uintptr_t data);
528
529/*!
530 * @function buf_dataptr
531 * @abstract Get the address at which a buffer's data is stored; for iobufs, this must
532 * be set with buf_setdataptr(). See buf_map().
533 * @param bp Buffer whose data pointer to retrieve.
534 * @return Data pointer; NULL if unset.
535 */
536uintptr_t buf_dataptr(buf_t bp);
537
538/*!
539 * @function buf_vnode
540 * @abstract Get the vnode associated with a buffer.
541 * @discussion Every buffer is associated with a file. Because there is an I/O in flight,
542 * there is an iocount on this vnode; it is returned WITHOUT an extra iocount, and vnode_put()
543 * need NOT be called.
544 * @param bp Buffer whose vnode to retrieve.
545 * @return Buffer's vnode.
546 */
547vnode_t buf_vnode(buf_t bp);
548
549/*!
550 * @function buf_setvnode
551 * @abstract Set the vnode associated with a buffer.
552 * @discussion This call need not be used on traditional buffers; it is for use with iobufs.
553 * @param bp Buffer whose vnode to set.
554 * @param vp The vnode to attach to the buffer.
555 */
556void buf_setvnode(buf_t bp, vnode_t vp);
557
558/*!
559 * @function buf_device
560 * @abstract Get the device ID associated with a buffer.
561 * @discussion In traditional buffer use, this value is NODEV until buf_strategy() is called unless
562 * buf_getblk() was passed a device vnode. It is set on an iobuf if buf_alloc() is passed a device
563 * vnode or if buf_setdevice() is called.
564 * @param bp Buffer whose device ID to retrieve.
565 * @return Device id.
566 */
567dev_t buf_device(buf_t bp);
568
569/*!
570 * @function buf_setdevice
571 * @abstract Set the device associated with a buffer.
572 * @discussion A buffer's device is set in buf_strategy() (or in buf_getblk() if the file is a device).
573 * It is also set on an iobuf if buf_alloc() is passed a device vnode.
574 * @param bp Buffer whose device ID to set.
575 * @param vp Device to set on the buffer.
576 * @return 0 for success, EINVAL if vp is not a device file.
577 */
578errno_t buf_setdevice(buf_t bp, vnode_t vp);
579
580/*!
581 * @function buf_strategy
582 * @abstract Pass an I/O request for a buffer down to the device layer.
583 * @discussion This is one of the most important routines in the buffer cache layer. For buffers obtained
584 * through buf_getblk, it handles finding physical block numbers for the I/O (with VNOP_BLKTOOFF and
585 * VNOP_BLOCKMAP), packaging the I/O into page-sized chunks, and initiating I/O on the disk by calling
586 * the device's strategy routine. If a buffer's UPL has been set manually with buf_setupl(), it assumes
587 * that the request is already correctly configured with a block number and a size divisible by page size
588 * and will just call directly to the device.
589 * @param devvp Device on which to perform I/O
590 * @param ap vnop_strategy_args structure (most importantly, a buffer).
591 * @return 0 for success, or errors from filesystem or device layers.
592 */
593errno_t buf_strategy(vnode_t devvp, void *ap);
594
595/*
596 * Flags for buf_invalblkno()
597 */
598#define BUF_WAIT 0x01
599
600/*!
601 * @function buf_invalblkno
602 * @abstract Invalidate a filesystem logical block in a file.
603 * @discussion buf_invalblkno() tries to make the data for a given block in a file
604 * invalid; if the buffer for that block is found in core and is not busy, we mark it
605 * invalid and call buf_brelse() (see "flags" param for what happens if the buffer is busy).
606 * buf_brelse(), noticing that it is invalid, will
607 * will return the buffer to the empty-buffer list and tell the VM subsystem to abandon
608 * the relevant pages. Data will not be written to backing store--it will be cast aside.
609 * Note that this function will only work if the block in question has been
610 * obtained with a buf_getblk(). If data has been read into core without using
611 * traditional buffer cache routines, buf_invalblkno() will not be able to invalidate it--this
612 * includes the use of iobufs.
613 * @param vp vnode whose block to invalidate.
614 * @param lblkno Logical block number.
615 * @param flags BUF_WAIT: wait for busy buffers to become unbusy and invalidate them then. Otherwise,
616 * just return EBUSY for busy blocks.
617 * @return 0 for success, EINVAL if vp is not a device file.
618 */
619errno_t buf_invalblkno(vnode_t vp, daddr64_t lblkno, int flags);
620
621/*!
622 * @function buf_callback
623 * @abstract Get the function set to be called when I/O on a buffer completes.
624 * @discussion A function returned by buf_callback was originally set with buf_setcallback().
625 * @param bp Buffer whose callback to get.
626 * @return 0 for success, or errors from filesystem or device layers.
627 */
628void * buf_callback(buf_t bp);
629
630/*!
631 * @function buf_setcallback
632 * @abstract Set a function to be called once when I/O on a buffer completes.
633 * @discussion A one-shot callout set with buf_setcallback() will be called from buf_biodone()
634 * when I/O completes. It will be passed the "transaction" argument as well as the buffer.
635 * buf_setcallback() also marks the buffer as B_ASYNC.
636 * @param bp Buffer whose callback to set.
637 * @param callback function to use as callback.
638 * @param transaction Additional argument to callback function.
639 * @return 0; always succeeds.
640 */
641errno_t buf_setcallback(buf_t bp, void (*callback)(buf_t, void *), void *transaction);
642
643/*!
644 * @function buf_setupl
645 * @abstract Set the UPL (Universal Page List), and offset therein, on a buffer.
646 * @discussion buf_setupl() should only be called on buffers allocated with buf_alloc().
647 * A subsequent call to buf_map() will map the UPL and give back the address at which data
648 * begins. After buf_setupl() is called, a buffer is marked B_CLUSTER; when this is the case,
649 * buf_strategy() assumes that a buffer is correctly configured to be passed to the device
650 * layer without modification. Passing a NULL upl will clear the upl and the B_CLUSTER flag on the
651 * buffer.
652 * @param bp Buffer whose upl to set.
653 * @param upl UPL to set in the buffer.
654 * @param offset Offset within upl at which relevant data begin.
655 * @return 0 for success, EINVAL if the buffer was not allocated with buf_alloc().
656 */
657errno_t buf_setupl(buf_t bp, upl_t upl, uint32_t offset);
658
659/*!
660 * @function buf_clone
661 * @abstract Clone a buffer with a restricted range and an optional callback.
662 * @discussion Generates a buffer which is identical to its "bp" argument except that
663 * it spans a subset of the data of the original. The buffer to be cloned should
664 * have been allocated with buf_alloc(). Checks its arguments to make sure
665 * that the data subset is coherent. Optionally, adds a callback function and argument to it
666 * to be called when I/O completes (as with buf_setcallback(), but B_ASYNC is not set). If the original buffer had
667 * a upl set through buf_setupl(), this upl is copied to the new buffer; otherwise, the original's
668 * data pointer is used raw. The buffer must be released with buf_free().
669 * @param bp Buffer to clone.
670 * @param io_offset Offset, relative to start of data in original buffer, at which new buffer's data will begin.
671 * @param io_size Size of buffer region in new buffer, in the sense of buf_count().
672 * @param iodone Callback to be called from buf_biodone() when I/O completes, in the sense of buf_setcallback().
673 * @param arg Argument to pass to iodone() callback.
674 * @return NULL if io_offset/io_size combination is invalid for the buffer to be cloned; otherwise, the new buffer.
675 */
676buf_t buf_clone(buf_t bp, int io_offset, int io_size, void (*iodone)(buf_t, void *), void *arg);
677
678
679/*!
680 * @function buf_create_shadow
681 * @abstract Create a shadow buffer with optional private storage and an optional callback.
682 * @param bp Buffer to shadow.
683 * @param force_copy If TRUE, do not link the shadaow to 'bp' and if 'external_storage' == NULL,
684 * force a copy of the data associated with 'bp'.
685 * @param external_storage If non-NULL, associate it with the new buffer as its storage instead of the
686 * storage currently associated with 'bp'.
687 * @param iodone Callback to be called from buf_biodone() when I/O completes, in the sense of buf_setcallback().
688 * @param arg Argument to pass to iodone() callback.
689 * @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.
690 */
691
692buf_t buf_create_shadow(buf_t bp, boolean_t force_copy, uintptr_t external_storage, void (*iodone)(buf_t, void *), void *arg);
693
694
695/*!
696 * @function buf_shadow
697 * @abstract returns true if 'bp' is a shadow of another buffer.
698 * @param bp Buffer to query.
699 * @return 1 if 'bp' is a shadow, 0 otherwise.
700 */
701int buf_shadow(buf_t bp);
702
703
704/*!
705 * @function buf_alloc
706 * @abstract Allocate an uninitialized buffer.
707 * @discussion A buffer returned by buf_alloc() is marked as busy and as an iobuf; it has no storage set up and must be
708 * set up using buf_setdataptr() or buf_setupl()/buf_map().
709 * @param vp vnode to associate with the buffer: optionally NULL. If vp is a device file, then
710 * the buffer's associated device will be set. If vp is NULL, it can be set later with buf_setvnode().
711 * @return New buffer.
712 */
713buf_t buf_alloc(vnode_t vp);
714
715/*!
716 * @function buf_free
717 * @abstract Free a buffer that was allocated with buf_alloc().
718 * @discussion The storage (UPL, data pointer) associated with an iobuf must be freed manually.
719 * @param bp The buffer to free.
720 */
721void buf_free(buf_t bp);
722
723/*
724 * flags for buf_invalidateblks
725 */
726#define BUF_WRITE_DATA 0x0001 /* write data blocks first */
727#define BUF_SKIP_META 0x0002 /* skip over metadata blocks */
728#define BUF_INVALIDATE_LOCKED 0x0004 /* force B_LOCKED blocks to be invalidated */
729
730/*!
731 * @function buf_invalidateblks
732 * @abstract Invalidate all the blocks associated with a vnode.
733 * @discussion This function does for all blocks associated with a vnode what buf_invalblkno does for one block.
734 * Again, it will only be able to invalidate data which were populated with traditional buffer cache routines,
735 * i.e. by buf_getblk() and callers thereof. Unlike buf_invalblkno(), it can be made to write dirty data to disk
736 * rather than casting it aside.
737 * @param vp The vnode whose data to invalidate.
738 * @param flags BUF_WRITE_DATA: write dirty data to disk with VNOP_BWRITE() before kicking buffer cache entries out.
739 * BUF_SKIP_META: do not invalidate metadata blocks.
740 * @param slpflag Flags to pass to "msleep" while waiting to acquire busy buffers.
741 * @param slptimeo Timeout in "hz" (1/100 second) to wait for a buffer to become unbusy before waking from sleep
742 * and re-starting the scan.
743 * @return 0 for success, error values from msleep().
744 */
745int buf_invalidateblks(vnode_t vp, int flags, int slpflag, int slptimeo);
746
747/*
748 * flags for buf_flushdirtyblks and buf_iterate
749 */
750#define BUF_SKIP_NONLOCKED 0x01
751#define BUF_SKIP_LOCKED 0x02
752#define BUF_SCAN_CLEAN 0x04 /* scan the clean buffers */
753#define BUF_SCAN_DIRTY 0x08 /* scan the dirty buffers */
754#define BUF_NOTIFY_BUSY 0x10 /* notify the caller about the busy pages during the scan */
755
756
757#define BUF_RETURNED 0
758#define BUF_RETURNED_DONE 1
759#define BUF_CLAIMED 2
760#define BUF_CLAIMED_DONE 3
761/*!
762 * @function buf_flushdirtyblks
763 * @abstract Write dirty file blocks to disk.
764 * @param vp The vnode whose blocks to flush.
765 * @param wait Wait for writes to complete before returning.
766 * @param flags Can pass zero, meaning "flush all dirty buffers."
767 * BUF_SKIP_NONLOCKED: Skip buffers which are not busy when we encounter them.
768 * BUF_SKIP_LOCKED: Skip buffers which are busy when we encounter them.
769 * @param msg String to pass to msleep().
770 */
771void buf_flushdirtyblks(vnode_t vp, int wait, int flags, const char *msg);
772
773/*!
774 * @function buf_iterate
775 * @abstract Perform some operation on all buffers associated with a vnode.
776 * @param vp The vnode whose buffers to scan.
777 * @param callout Function to call on each buffer. Should return one of:
778 * BUF_RETURNED: buf_iterate() should call buf_brelse() on the buffer.
779 * BUF_RETURNED_DONE: buf_iterate() should call buf_brelse() on the buffer and then stop iterating.
780 * BUF_CLAIMED: buf_iterate() should continue iterating (and not call buf_brelse()).
781 * BUF_CLAIMED_DONE: buf_iterate() should stop iterating (and not call buf_brelse()).
782 * @param flags
783 * 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.
784 * BUF_SCAN_CLEAN: Call out on clean buffers.
785 * BUF_SCAN_DIRTY: Call out on dirty buffers.
786 * BUF_NOTIFY_BUSY: If a buffer cannot be acquired, pass a NULL buffer to callout; otherwise,
787 * that buffer will be silently skipped.
788 * @param arg Argument to pass to callout in addition to buffer.
789 */
790void buf_iterate(vnode_t vp, int (*callout)(buf_t, void *), int flags, void *arg);
791
792/*!
793 * @function buf_clear
794 * @abstract Zero out the storage associated with a buffer.
795 * @discussion Calls buf_map() to get the buffer's data address; for a B_CLUSTER
796 * buffer (one which has had buf_setupl() called on it), it tries to map the buffer's
797 * UPL into memory; should only be called once during the life cycle of an iobuf (one allocated
798 * with buf_alloc()).
799 * @param bp The buffer to zero out.
800 */
801void buf_clear(buf_t bp);
802
803/*!
804 * @function buf_bawrite
805 * @abstract Start an asychronous write on a buffer.
806 * @discussion Calls VNOP_BWRITE to start the process of propagating an asynchronous write down to the device layer.
807 * Callers can wait for writes to complete at their discretion using buf_biowait(). When this function is called,
808 * data should already have been written to the buffer's data region.
809 * @param bp The buffer on which to initiate I/O.
810 * @return EWOULDBLOCK if write count is high and "throttle" is zero; otherwise, errors from VNOP_BWRITE.
811 */
812errno_t buf_bawrite(buf_t bp);
813
814/*!
815 * @function buf_bdwrite
816 * @abstract Mark a buffer for delayed write.
817 * @discussion Marks a buffer as waiting for delayed write and the current I/O as complete; data will be written to backing store
818 * before the buffer is reused, but it will not be queued for I/O immediately. Note that for buffers allocated
819 * with buf_alloc(), there are no such guarantees; you must take care of your own flushing to disk. If
820 * the number of delayed writes pending on the system is greater than an internal limit and the caller has not
821 * requested otherwise [see return_error] , buf_bdwrite() will unilaterally launch an asynchronous I/O with buf_bawrite() to keep the pile of
822 * delayed writes from getting too large.
823 * @param bp The buffer to mark for delayed write.
824 * @return EAGAIN for return_error != 0 case, 0 for succeess, errors from buf_bawrite.
825 */
826errno_t buf_bdwrite(buf_t bp);
827
828/*!
829 * @function buf_bwrite
830 * @abstract Write a buffer's data to backing store.
831 * @discussion Once the data in a buffer has been modified, buf_bwrite() starts sending it to disk by calling
832 * VNOP_STRATEGY. Unless B_ASYNC has been set on the buffer (by buf_setflags() or otherwise), data will have
833 * been written to disk when buf_bwrite() returns. See Bach (p 56).
834 * @param bp The buffer to write to disk.
835 * @return 0 for success; errors from buf_biowait().
836 */
837errno_t buf_bwrite(buf_t bp);
838
839/*!
840 * @function buf_biodone
841 * @abstract Mark an I/O as completed.
842 * @discussion buf_biodone() should be called by whosoever decides that an I/O on a buffer is complete; for example,
843 * IOStorageFamily. It clears the dirty flag on a buffer and signals on the vnode that a write has completed
844 * with vnode_writedone(). If a callout or filter has been set on the buffer, that function is called. In the case
845 * of a callout, that function is expected to take care of cleaning up and freeing the buffer.
846 * Otherwise, if the buffer is marked B_ASYNC (e.g. it was passed to buf_bawrite()), then buf_biodone()
847 * considers itself justified in calling buf_brelse() to return it to free lists--no one is waiting for it. Finally,
848 * waiters on the bp (e.g. in buf_biowait()) are woken up.
849 * @param bp The buffer to mark as done with I/O.
850 */
851void buf_biodone(buf_t bp);
852
853/*!
854 * @function buf_biowait
855 * @abstract Wait for I/O on a buffer to complete.
856 * @discussion Waits for I/O on a buffer to finish, as marked by a buf_biodone() call.
857 * @param bp The buffer to wait on.
858 * @return 0 for a successful wait; nonzero the buffer has been marked as EINTR or had an error set on it.
859 */
860errno_t buf_biowait(buf_t bp);
861
862/*!
863 * @function buf_brelse
864 * @abstract Release any claim to a buffer, sending it back to free lists.
865 * @discussion buf_brelse() cleans up buffer state and releases a buffer to the free lists. If the buffer
866 * is not marked invalid and its pages are dirty (e.g. a delayed write was made), its data will be commited
867 * to backing store. If it is marked invalid, its data will be discarded completely.
868 * A valid, cacheable buffer will be put on a list and kept in the buffer hash so it
869 * can be found again; otherwise, it will be dissociated from its vnode and treated as empty. Which list a valid
870 * buffer is placed on depends on the use of buf_markaged(), whether it is metadata, and the B_LOCKED flag. A
871 * B_LOCKED buffer will not be available for reuse by other files, though its data may be paged out.
872 * Note that buf_brelse() is intended for use with traditionally allocated buffers.
873 * @param bp The buffer to release.
874 */
875void buf_brelse(buf_t bp);
876
877/*!
878 * @function buf_bread
879 * @abstract Synchronously read a block of a file.
880 * @discussion buf_bread() is the traditional way to read a single logical block of a file through the buffer cache.
881 * It tries to find the buffer and corresponding page(s) in core, calls VNOP_STRATEGY if necessary to bring the data
882 * into memory, and waits for I/O to complete. It should not be used to read blocks of greater than 4K (one VM page)
883 * in size; use cluster routines for large reads. Indeed, the cluster layer is a more efficient choice for reading DATA
884 * unless you need some finely-tuned semantics that it cannot provide.
885 * @param vp The file from which to read.
886 * @param blkno The logical (filesystem) block number to read.
887 * @param size Size of block; do not use for sizes > 4K.
888 * @param cred Credential to store and use for reading from disk if data are not already in core.
889 * @param bpp Destination pointer for buffer.
890 * @return 0 for success, or an error from buf_biowait().
891 */
892errno_t buf_bread(vnode_t vp, daddr64_t blkno, int size, kauth_cred_t cred, buf_t *bpp);
893
894/*!
895 * @function buf_breadn
896 * @abstract Read a block from a file with read-ahead.
897 * @discussion buf_breadn() reads one block synchronously in the style of buf_bread() and fires
898 * off a specified set of asynchronous reads to improve the likelihood of future cache hits.
899 * It should not be used to read blocks of greater than 4K (one VM page) in size; use cluster
900 * routines for large reads. Indeed, the cluster layer is a more efficient choice for reading DATA
901 * unless you need some finely-tuned semantics that it cannot provide.
902 * @param vp The file from which to read.
903 * @param blkno The logical (filesystem) block number to read synchronously.
904 * @param size Size of block; do not use for sizes > 4K.
905 * @param rablks Array of logical block numbers for asynchronous read-aheads.
906 * @param rasizes Array of block sizes for asynchronous read-aheads, each index corresponding to same index in "rablks."
907 * @param nrablks Number of entries in read-ahead arrays.
908 * @param cred Credential to store and use for reading from disk if data are not already in core.
909 * @param bpp Destination pointer for buffer.
910 * @return 0 for success, or an error from buf_biowait().
911 */
912errno_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);
913
914/*!
915 * @function buf_meta_bread
916 * @abstract Synchronously read a metadata block of a file.
917 * @discussion buf_meta_bread() is the traditional way to read a single logical block of a file through the buffer cache.
918 * It tries to find the buffer and corresponding page(s) in core, calls VNOP_STRATEGY if necessary to bring the data
919 * into memory, and waits for I/O to complete. It should not be used to read blocks of greater than 4K (one VM page)
920 * in size; use cluster routines for large reads. Reading meta-data through the traditional buffer cache, unlike
921 * reading data, is efficient and encouraged, especially if the blocks being read are significantly smaller than page size.
922 * @param vp The file from which to read.
923 * @param blkno The logical (filesystem) block number to read.
924 * @param size Size of block; do not use for sizes > 4K.
925 * @param cred Credential to store and use for reading from disk if data are not already in core.
926 * @param bpp Destination pointer for buffer.
927 * @return 0 for success, or an error from buf_biowait().
928 */
929errno_t buf_meta_bread(vnode_t vp, daddr64_t blkno, int size, kauth_cred_t cred, buf_t *bpp);
930
931/*!
932 * @function buf_meta_breadn
933 * @abstract Read a metadata block from a file with read-ahead.
934 * @discussion buf_meta_breadn() reads one block synchronously in the style of buf_meta_bread() and fires
935 * off a specified set of asynchronous reads to improve the likelihood of future cache hits.
936 * It should not be used to read blocks of greater than 4K (one VM page) in size; use cluster
937 * routines for large reads.
938 * @param vp The file from which to read.
939 * @param blkno The logical (filesystem) block number to read synchronously.
940 * @param size Size of block; do not use for sizes > 4K.
941 * @param rablks Array of logical block numbers for asynchronous read-aheads.
942 * @param rasizes Array of block sizes for asynchronous read-aheads, each index corresponding to same index in "rablks."
943 * @param nrablks Number of entries in read-ahead arrays.
944 * @param cred Credential to store and use for reading from disk if data are not already in core.
945 * @param bpp Destination pointer for buffer.
946 * @return 0 for success, or an error from buf_biowait().
947 */
948errno_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);
949
950/*!
951 * @function minphys
952 * @abstract Adjust a buffer's count to be no more than maximum physical I/O transfer size for the host architecture.
953 * @discussion physio() takes as a parameter a function to bound transfer sizes for each VNOP_STRATEGY() call. minphys()
954 * is a default implementation. It calls buf_setcount() to make the buffer's count the min() of its current count
955 * and the max I/O size for the host architecture.
956 * @param bp The buffer whose byte count to modify.
957 * @return New byte count.
958 */
959u_int minphys(buf_t bp);
960
961/*!
962 * @function physio
963 * @abstract Perform I/O on a device to/from target memory described by a uio.
964 * @discussion physio() allows I/O directly from a device to user-space memory. It waits
965 * for all I/O to complete before returning.
966 * @param f_strategy Strategy routine to call to initiate I/O.
967 * @param bp Buffer to configure and pass to strategy routine; can be NULL.
968 * @param dev Device on which to perform I/O.
969 * @param flags B_READ or B_WRITE.
970 * @param f_minphys Function which calls buf_setcount() to set a byte count which is suitably
971 * small for the device in question. Returns byte count that has been set (or unchanged) on the buffer.
972 * @param uio UIO describing the I/O operation.
973 * @param blocksize Logical block size for this vnode.
974 * @return 0 for success; EFAULT for an invalid uio; errors from buf_biowait().
975 */
976int 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);
977
978
979/*
980 * Flags for operation type in getblk()
981 */
982#define BLK_READ 0x01 /* buffer for read */
983#define BLK_WRITE 0x02 /* buffer for write */
984#define BLK_META 0x10 /* buffer for metadata */
985/*
986 * modifier for above flags... if set, getblk will only return
987 * a bp that is already valid... i.e. found in the cache
988 */
989#define BLK_ONLYVALID 0x80000000
990
991/*!
992 * @function buf_getblk
993 * @abstract Traditional buffer cache routine to get a buffer corresponding to a logical block in a file.
994 * @discussion buf_getblk() gets a buffer, not necessarily containing valid data, representing a block in a file.
995 * A metadata buffer will be returned with its own zone-allocated storage, managed by the traditional buffer-cache
996 * layer, whereas data buffers will be returned hooked into backing by the UBC (which in fact controls the caching of data).
997 * 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
998 * unbusy, depending on the slpflag and slptimeo parameters. If the buffer is found unbusy and is a metadata buffer,
999 * it must already contain valid data and will be returned directly; data buffers will have a UPL configured to
1000 * prepare for interaction with the underlying UBC. If the buffer is found in core, it will be marked as such
1001 * and buf_fromcache() will return truth. A buffer is allocated and initialized (but not filled with data)
1002 * if none is found in core. buf_bread(), buf_breadn(), buf_meta_bread(), and buf_meta_breadn() all
1003 * return buffers obtained with buf_getblk().
1004 * @param vp File for which to get block.
1005 * @param blkno Logical block number.
1006 * @param size Size of block.
1007 * @param slpflag Flag to pass to msleep() while waiting for buffer to become unbusy.
1008 * @param slptimeo Time, in milliseconds, to wait for buffer to become unbusy. 0 means to wait indefinitely.
1009 * @param operation BLK_READ: want a read buffer. BLK_WRITE: want a write buffer. BLK_META: want a metadata buffer. BLK_ONLYVALID:
1010 * only return buffers which are found in core (do not allocate anew), and do not change buffer size. The last remark means
1011 * 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.
1012 * @return Buffer found in core or newly allocated, either containing valid data or ready for I/O.
1013 */
1014buf_t buf_getblk(vnode_t vp, daddr64_t blkno, int size, int slpflag, int slptimeo, int operation);
1015
1016/*!
1017 * @function buf_geteblk
1018 * @abstract Get a metadata buffer which is marked invalid and not associated with any vnode.
1019 * @discussion A buffer is returned with zone-allocated storage of the specified size, marked B_META and invalid.
1020 * It has no vnode and is not visible in the buffer hash.
1021 * @param size Size of buffer.
1022 * @return Always returns a new buffer.
1023 */
1024buf_t buf_geteblk(int size);
1025
1026/*!
1027 * @function buf_clear_redundancy_flags
1028 * @abstract Clear flags on a buffer.
1029 * @discussion buffer_redundancy_flags &= ~flags
1030 * @param bp Buffer whose flags to clear.
1031 * @param flags Flags to remove from buffer's mask
1032 */
1033void buf_clear_redundancy_flags(buf_t bp, uint32_t flags);
1034
1035/*!
1036 * @function buf_redundancyflags
1037 * @abstract Get redundancy flags set on a buffer.
1038 * @param bp Buffer whose redundancy flags to grab.
1039 * @return flags.
1040 */
1041uint32_t buf_redundancy_flags(buf_t bp);
1042
1043/*!
1044 * @function buf_setredundancyflags
1045 * @abstract Set redundancy flags on a buffer.
1046 * @discussion buffer_redundancy_flags |= flags
1047 * @param bp Buffer whose flags to set.
1048 * @param flags Flags to add to buffer's redundancy flags
1049 */
1050void buf_set_redundancy_flags(buf_t bp, uint32_t flags);
1051
1052/*!
1053 * @function buf_attr
1054 * @abstract Gets the attributes for this buf.
1055 * @param bp Buffer whose attributes to get.
1056 * @return bufattr_t.
1057 */
1058bufattr_t buf_attr(buf_t bp);
1059
1060/*!
1061 * @function buf_markstatic
1062 * @abstract Mark a buffer as being likely to contain static data.
1063 * @param bp Buffer to mark.
1064 */
1065void buf_markstatic(buf_t bp);
1066
1067/*!
1068 * @function buf_static
1069 * @abstract Check if a buffer contains static data.
1070 * @param bp Buffer to test.
1071 * @return Nonzero if buffer has static data, 0 otherwise.
1072 */
1073int buf_static(buf_t bp);
1074
1075/*!
1076 * @function bufattr_markiosched
1077 * @abstract Mark a buffer as belonging to an io scheduled mount point
1078 * @param bap Buffer attributes to mark.
1079 * @discussion Marks the buffer so that spec_strategy() will know that it belongs to an io scheduled mount point
1080 */
1081void bufattr_markioscheduled(bufattr_t bap);
1082
1083/*!
1084 * @function bufattr_iosched
1085 * @abstract Check if a buffer is marked as io scheduled
1086 * @param bap Buffer attributes to test.
1087 * @return Nonzero if the buffer is marked io scheduled, 0 otherwise.
1088 */
1089int bufattr_ioscheduled(bufattr_t bap);
1090
1091/*!
1092 * @function bufattr_markexpeditedmeta
1093 * @abstract Mark a metadata I/O buffer as expedited (i.e. requires a high I/O tier).
1094 * @param bap Buffer attributes to mark.
1095 * @discussion Marks the buffer so that spec_strategy() will know that it should be expedited
1096 */
1097void bufattr_markexpeditedmeta(bufattr_t bap);
1098
1099/*!
1100 * @function bufattr_expeditedmeta
1101 * @abstract Check if a buffer is marked as expedited metadata I/O.
1102 * @param bap Buffer attributes to test.
1103 * @return Nonzero if the buffer is marked expedited metadata I/O, 0 otherwise.
1104 */
1105int bufattr_expeditedmeta(bufattr_t bap);
1106
1107#ifdef KERNEL_PRIVATE
1108void buf_setfilter(buf_t, void (*)(buf_t, void *), void *, void(**)(buf_t, void *), void **);
1109
1110/* bufattr allocation/duplication/deallocation functions */
1111bufattr_t bufattr_alloc(void);
1112bufattr_t bufattr_dup(bufattr_t bap);
1113void bufattr_free(bufattr_t bap);
1114
1115/*!
1116 * @function bufattr_cpx
1117 * @abstract Returns a pointer to a cpx_t structure.
1118 * @param bap Buffer Attribute whose cpx_t structure you wish to get.
1119 * @return Returns a cpx_t structure, or NULL if not valid
1120 */
1121struct cpx *bufattr_cpx(bufattr_t bap);
1122
1123/*!
1124 * @function bufattr_setcpx
1125 * @abstract Set the cp_ctx on a buffer attribute.
1126 * @param bap Buffer Attribute that you wish to change
1127 */
1128void bufattr_setcpx(bufattr_t bap, struct cpx *cpx);
1129
1130/*!
1131 * @function bufattr_cpoff
1132 * @abstract Gets the file offset on the buffer.
1133 * @param bap Buffer Attribute whose file offset value is used
1134 */
1135uint64_t bufattr_cpoff(bufattr_t bap);
1136
1137/*!
1138 * @function bufattr_setcpoff
1139 * @abstract Set the file offset for a content protected I/O on
1140 * a buffer attribute.
1141 * @param bap Buffer Attribute whose cp file offset has to be set
1142 */
1143void bufattr_setcpoff(bufattr_t bap, uint64_t);
1144
1145/*!
1146 * @function bufattr_rawencrypted
1147 * @abstract Check if a buffer contains raw encrypted data.
1148 * @param bap Buffer attribute to test.
1149 * @return Nonzero if buffer has raw encrypted data, 0 otherwise.
1150 */
1151int bufattr_rawencrypted(bufattr_t bap);
1152
1153/*!
1154 * @function bufattr_markgreedymode
1155 * @abstract Mark a buffer to use the greedy mode for writing.
1156 * @param bap Buffer attributes to mark.
1157 * @discussion Greedy Mode: request improved write performance from the underlying device at the expense of storage efficiency
1158 */
1159void bufattr_markgreedymode(bufattr_t bap);
1160
1161/*!
1162 * @function bufattr_greedymode
1163 * @abstract Check if a buffer is written using the Greedy Mode
1164 * @param bap Buffer attributes to test.
1165 * @discussion Greedy Mode: request improved write performance from the underlying device at the expense of storage efficiency
1166 * @return Nonzero if buffer uses greedy mode, 0 otherwise.
1167 */
1168int bufattr_greedymode(bufattr_t bap);
1169
1170/*!
1171 * @function bufattr_markisochronous
1172 * @abstract Mark a buffer to use the isochronous throughput mode for writing.
1173 * @param bap Buffer attributes to mark.
1174 * @discussion isochronous mode: request improved write performance from the underlying device at the expense of storage efficiency
1175 */
1176void bufattr_markisochronous(bufattr_t bap);
1177
1178/*!
1179 * @function bufattr_isochronous
1180 * @abstract Check if a buffer is written using the isochronous
1181 * @param bap Buffer attributes to test.
1182 * @discussion isochronous mode: request improved write performance from the underlying device at the expense of storage efficiency
1183 * @return Nonzero if buffer uses isochronous mode, 0 otherwise.
1184 */
1185int bufattr_isochronous(bufattr_t bap);
1186
1187
1188/*!
1189 * @function bufattr_throttled
1190 * @abstract Check if a buffer is throttled.
1191 * @param bap Buffer attribute to test.
1192 * @return Nonzero if the buffer is throttled, 0 otherwise.
1193 */
1194int bufattr_throttled(bufattr_t bap);
1195
1196/*!
1197 * @function bufattr_willverify
1198 * @abstract Check if a buffer is verified by the cluster layer.
1199 * @param bap Buffer attribute to test.
1200 * @return Nonzero if the buffer will be verified, 0 otherwise.
1201 */
1202int bufattr_willverify(bufattr_t bap);
1203
1204/*!
1205 * @function bufattr_passive
1206 * @abstract Check if a buffer is marked passive.
1207 * @param bap Buffer attribute to test.
1208 * @return Nonzero if the buffer is marked passive, 0 otherwise.
1209 */
1210int bufattr_passive(bufattr_t bap);
1211
1212/*!
1213 * @function bufattr_nocache
1214 * @abstract Check if a buffer has nocache attribute.
1215 * @param bap Buffer attribute to test.
1216 * @return Nonzero if the buffer is not cached, 0 otherwise.
1217 */
1218int bufattr_nocache(bufattr_t bap);
1219
1220/*!
1221 * @function bufattr_meta
1222 * @abstract Check if a buffer has the bufattr meta attribute.
1223 * @param bap Buffer attribute to test.
1224 * @return Nonzero if the buffer has meta attribute, 0 otherwise.
1225 */
1226
1227int bufattr_meta(bufattr_t bap);
1228
1229/*!
1230 * @function bufattr_markmeta
1231 * @abstract Set the bufattr meta attribute.
1232 * @param bap Buffer attribute to manipulate.
1233 */
1234void bufattr_markmeta(bufattr_t bap);
1235
1236
1237/*!
1238 * @function bufattr_delayidlesleep
1239 * @abstract Check if a buffer is marked to delay idle sleep on disk IO.
1240 * @param bap Buffer attribute to test.
1241 * @return Nonzero if the buffer is marked to delay idle sleep on disk IO, 0 otherwise.
1242 */
1243int bufattr_delayidlesleep(bufattr_t bap);
1244
1245/*!
1246 * @function buf_kernel_addrperm_addr
1247 * @abstract Obfuscate the buf pointers.
1248 * @param addr Buf_t pointer.
1249 * @return Obfuscated pointer if addr is non zero, 0 otherwise.
1250 */
1251vm_offset_t buf_kernel_addrperm_addr(void * addr);
1252
1253/*!
1254 * @function bufattr_markquickcomplete
1255 * @abstract Mark a buffer to hint quick completion to the driver.
1256 * @discussion This flag hints the storage driver that some thread is waiting for this I/O to complete.
1257 * It should therefore attempt to complete it as soon as possible at the cost of device efficiency.
1258 * @param bap Buffer attributes to mark.
1259 */
1260void bufattr_markquickcomplete(bufattr_t bap);
1261
1262/*!
1263 * @function bufattr_quickcomplete
1264 * @abstract Check if a buffer is marked for quick completion
1265 * @discussion This flag hints the storage driver that some thread is waiting for this I/O to complete.
1266 * It should therefore attempt to complete it as soon as possible at the cost of device efficiency.
1267 * @param bap Buffer attribute to test.
1268 * @return Nonzero if the buffer is marked for quick completion, 0 otherwise.
1269 */
1270int bufattr_quickcomplete(bufattr_t bap);
1271
1272int count_lock_queue(void);
1273
1274/*
1275 * Flags for buf_acquire
1276 */
1277#define BAC_NOWAIT 0x01 /* Don't wait if buffer is busy */
1278#define BAC_REMOVE 0x02 /* Remove from free list once buffer is acquired */
1279#define BAC_SKIP_NONLOCKED 0x04 /* Don't return LOCKED buffers */
1280#define BAC_SKIP_LOCKED 0x08 /* Only return LOCKED buffers */
1281
1282errno_t buf_acquire(buf_t, int, int, int);
1283
1284buf_t buf_create_shadow_priv(buf_t bp, boolean_t force_copy, uintptr_t external_storage, void (*iodone)(buf_t, void *), void *arg);
1285
1286void buf_drop(buf_t);
1287
1288#endif /* KERNEL_PRIVATE */
1289
1290__END_DECLS
1291
1292
1293/* Macros to clear/set/test flags. */
1294#define SET(t, f) (t) |= (f)
1295#define CLR(t, f) (t) &= ~(f)
1296#define ISSET(t, f) ((t) & (f))
1297
1298
1299#endif /* !_SYS_BUF_H_ */
1300