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