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 | * @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 | */ |
335 | errno_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 | */ |
346 | errno_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 | */ |
361 | errno_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 | */ |
371 | errno_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 | */ |
379 | void 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 | */ |
387 | void * 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 | */ |
395 | void 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 | */ |
403 | void * 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 | */ |
415 | daddr64_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 | */ |
425 | daddr64_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 | */ |
435 | uint32_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 | */ |
444 | void 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 | */ |
454 | void 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 | */ |
464 | void 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 | */ |
472 | uint32_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 | */ |
481 | uint32_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 | */ |
490 | uint32_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 | */ |
498 | void 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 | */ |
507 | void 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 | */ |
517 | void 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 | */ |
527 | void 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 | */ |
536 | uintptr_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 | */ |
547 | vnode_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 | */ |
556 | void 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 | */ |
567 | dev_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 | */ |
578 | errno_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 | */ |
593 | errno_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 | */ |
619 | errno_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 | */ |
628 | void * 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 | */ |
641 | errno_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 | */ |
657 | errno_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 | */ |
676 | buf_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 | |
692 | buf_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 | */ |
701 | int 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 | */ |
713 | buf_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 | */ |
721 | void 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 | */ |
745 | int 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 | */ |
771 | void 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 | */ |
790 | void 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 | */ |
801 | void 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 | */ |
812 | errno_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 | */ |
826 | errno_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 | */ |
837 | errno_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 | */ |
851 | void 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 | */ |
860 | errno_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 | */ |
875 | void 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 | */ |
892 | errno_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 | */ |
912 | 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); |
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 | */ |
929 | errno_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 | */ |
948 | 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); |
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 | */ |
959 | u_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 | */ |
976 | 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); |
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 | */ |
1014 | buf_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 | */ |
1024 | buf_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 | */ |
1033 | void 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 | */ |
1041 | uint32_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 | */ |
1050 | void 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 | */ |
1058 | bufattr_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 | */ |
1065 | void 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 | */ |
1073 | int 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 | */ |
1081 | void 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 | */ |
1089 | int 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 | */ |
1097 | void 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 | */ |
1105 | int bufattr_expeditedmeta(bufattr_t bap); |
1106 | |
1107 | #ifdef KERNEL_PRIVATE |
1108 | void buf_setfilter(buf_t, void (*)(buf_t, void *), void *, void(**)(buf_t, void *), void **); |
1109 | |
1110 | /* bufattr allocation/duplication/deallocation functions */ |
1111 | bufattr_t bufattr_alloc(void); |
1112 | bufattr_t bufattr_dup(bufattr_t bap); |
1113 | void 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 | */ |
1121 | struct 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 | */ |
1128 | void 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 | */ |
1135 | uint64_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 | */ |
1143 | void 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 | */ |
1151 | int 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 | */ |
1159 | void 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 | */ |
1168 | int 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 | */ |
1176 | void 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 | */ |
1185 | int 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 | */ |
1194 | int 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 | */ |
1202 | int 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 | */ |
1210 | int 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 | */ |
1218 | int 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 | |
1227 | int 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 | */ |
1234 | void 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 | */ |
1243 | int 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 | */ |
1251 | vm_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 | */ |
1260 | void 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 | */ |
1270 | int bufattr_quickcomplete(bufattr_t bap); |
1271 | |
1272 | int 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 | |
1282 | errno_t buf_acquire(buf_t, int, int, int); |
1283 | |
1284 | buf_t buf_create_shadow_priv(buf_t bp, boolean_t force_copy, uintptr_t external_storage, void (*iodone)(buf_t, void *), void *arg); |
1285 | |
1286 | void 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 | |