Print this page
3742 zfs comments need cleaner, more consistent style
Submitted by: Will Andrews <willa@spectralogic.com>
Submitted by: Alan Somers <alans@spectralogic.com>
Reviewed by: Matthew Ahrens <mahrens@delphix.com>
Reviewed by: George Wilson <george.wilson@delphix.com>
Reviewed by: Eric Schrock <eric.schrock@delphix.com>
Split |
Close |
Expand all |
Collapse all |
--- old/usr/src/uts/common/fs/zfs/sys/zap.h
+++ new/usr/src/uts/common/fs/zfs/sys/zap.h
1 1 /*
2 2 * CDDL HEADER START
3 3 *
4 4 * The contents of this file are subject to the terms of the
5 5 * Common Development and Distribution License (the "License").
6 6 * You may not use this file except in compliance with the License.
7 7 *
8 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 9 * or http://www.opensolaris.org/os/licensing.
10 10 * See the License for the specific language governing permissions
11 11 * and limitations under the License.
12 12 *
13 13 * When distributing Covered Code, include this CDDL HEADER in each
14 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 15 * If applicable, add the following below this CDDL HEADER, with the
16 16 * fields enclosed by brackets "[]" replaced with your own identifying
17 17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 18 *
19 19 * CDDL HEADER END
20 20 */
21 21 /*
22 22 * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
23 23 * Copyright (c) 2012 by Delphix. All rights reserved.
24 24 */
25 25
26 26 #ifndef _SYS_ZAP_H
27 27 #define _SYS_ZAP_H
28 28
29 29 /*
30 30 * ZAP - ZFS Attribute Processor
31 31 *
32 32 * The ZAP is a module which sits on top of the DMU (Data Management
33 33 * Unit) and implements a higher-level storage primitive using DMU
34 34 * objects. Its primary consumer is the ZPL (ZFS Posix Layer).
35 35 *
36 36 * A "zapobj" is a DMU object which the ZAP uses to stores attributes.
37 37 * Users should use only zap routines to access a zapobj - they should
38 38 * not access the DMU object directly using DMU routines.
39 39 *
40 40 * The attributes stored in a zapobj are name-value pairs. The name is
41 41 * a zero-terminated string of up to ZAP_MAXNAMELEN bytes (including
42 42 * terminating NULL). The value is an array of integers, which may be
43 43 * 1, 2, 4, or 8 bytes long. The total space used by the array (number
44 44 * of integers * integer length) can be up to ZAP_MAXVALUELEN bytes.
45 45 * Note that an 8-byte integer value can be used to store the location
46 46 * (object number) of another dmu object (which may be itself a zapobj).
47 47 * Note that you can use a zero-length attribute to store a single bit
48 48 * of information - the attribute is present or not.
49 49 *
50 50 * The ZAP routines are thread-safe. However, you must observe the
51 51 * DMU's restriction that a transaction may not be operated on
52 52 * concurrently.
53 53 *
54 54 * Any of the routines that return an int may return an I/O error (EIO
55 55 * or ECHECKSUM).
56 56 *
57 57 *
58 58 * Implementation / Performance Notes:
59 59 *
60 60 * The ZAP is intended to operate most efficiently on attributes with
61 61 * short (49 bytes or less) names and single 8-byte values, for which
62 62 * the microzap will be used. The ZAP should be efficient enough so
63 63 * that the user does not need to cache these attributes.
64 64 *
65 65 * The ZAP's locking scheme makes its routines thread-safe. Operations
66 66 * on different zapobjs will be processed concurrently. Operations on
67 67 * the same zapobj which only read data will be processed concurrently.
68 68 * Operations on the same zapobj which modify data will be processed
69 69 * concurrently when there are many attributes in the zapobj (because
70 70 * the ZAP uses per-block locking - more than 128 * (number of cpus)
71 71 * small attributes will suffice).
72 72 */
73 73
74 74 /*
75 75 * We're using zero-terminated byte strings (ie. ASCII or UTF-8 C
76 76 * strings) for the names of attributes, rather than a byte string
77 77 * bounded by an explicit length. If some day we want to support names
78 78 * in character sets which have embedded zeros (eg. UTF-16, UTF-32),
↓ open down ↓ |
78 lines elided |
↑ open up ↑ |
79 79 * we'll have to add routines for using length-bounded strings.
80 80 */
81 81
82 82 #include <sys/dmu.h>
83 83
84 84 #ifdef __cplusplus
85 85 extern "C" {
86 86 #endif
87 87
88 88 /*
89 - * The matchtype specifies which entry will be accessed.
90 - * MT_EXACT: only find an exact match (non-normalized)
91 - * MT_FIRST: find the "first" normalized (case and Unicode
92 - * form) match; the designated "first" match will not change as long
93 - * as the set of entries with this normalization doesn't change
94 - * MT_BEST: if there is an exact match, find that, otherwise find the
95 - * first normalized match
89 + * Specifies matching criteria for ZAP lookups.
96 90 */
97 91 typedef enum matchtype
98 92 {
93 + /* Only find an exact match (non-normalized) */
99 94 MT_EXACT,
95 + /*
96 + * If there is an exact match, find that, otherwise find the
97 + * first normalized match.
98 + */
100 99 MT_BEST,
100 + /*
101 + * Find the "first" normalized (case and Unicode form) match;
102 + * the designated "first" match will not change as long as the
103 + * set of entries with this normalization doesn't change.
104 + */
101 105 MT_FIRST
102 106 } matchtype_t;
103 107
104 108 typedef enum zap_flags {
105 109 /* Use 64-bit hash value (serialized cursors will always use 64-bits) */
106 110 ZAP_FLAG_HASH64 = 1 << 0,
107 111 /* Key is binary, not string (zap_add_uint64() can be used) */
108 112 ZAP_FLAG_UINT64_KEY = 1 << 1,
109 113 /*
110 114 * First word of key (which must be an array of uint64) is
111 115 * already randomly distributed.
112 116 */
113 117 ZAP_FLAG_PRE_HASHED_KEY = 1 << 2,
114 118 } zap_flags_t;
115 119
116 120 /*
117 121 * Create a new zapobj with no attributes and return its object number.
118 122 * MT_EXACT will cause the zap object to only support MT_EXACT lookups,
119 123 * otherwise any matchtype can be used for lookups.
120 124 *
121 125 * normflags specifies what normalization will be done. values are:
122 126 * 0: no normalization (legacy on-disk format, supports MT_EXACT matching
123 127 * only)
124 128 * U8_TEXTPREP_TOLOWER: case normalization will be performed.
125 129 * MT_FIRST/MT_BEST matching will find entries that match without
126 130 * regard to case (eg. looking for "foo" can find an entry "Foo").
127 131 * Eventually, other flags will permit unicode normalization as well.
128 132 */
129 133 uint64_t zap_create(objset_t *ds, dmu_object_type_t ot,
130 134 dmu_object_type_t bonustype, int bonuslen, dmu_tx_t *tx);
131 135 uint64_t zap_create_norm(objset_t *ds, int normflags, dmu_object_type_t ot,
132 136 dmu_object_type_t bonustype, int bonuslen, dmu_tx_t *tx);
133 137 uint64_t zap_create_flags(objset_t *os, int normflags, zap_flags_t flags,
134 138 dmu_object_type_t ot, int leaf_blockshift, int indirect_blockshift,
135 139 dmu_object_type_t bonustype, int bonuslen, dmu_tx_t *tx);
136 140 uint64_t zap_create_link(objset_t *os, dmu_object_type_t ot,
137 141 uint64_t parent_obj, const char *name, dmu_tx_t *tx);
138 142
139 143 /*
140 144 * Create a new zapobj with no attributes from the given (unallocated)
141 145 * object number.
142 146 */
143 147 int zap_create_claim(objset_t *ds, uint64_t obj, dmu_object_type_t ot,
144 148 dmu_object_type_t bonustype, int bonuslen, dmu_tx_t *tx);
145 149 int zap_create_claim_norm(objset_t *ds, uint64_t obj,
146 150 int normflags, dmu_object_type_t ot,
147 151 dmu_object_type_t bonustype, int bonuslen, dmu_tx_t *tx);
148 152
149 153 /*
150 154 * The zapobj passed in must be a valid ZAP object for all of the
151 155 * following routines.
152 156 */
153 157
154 158 /*
155 159 * Destroy this zapobj and all its attributes.
156 160 *
157 161 * Frees the object number using dmu_object_free.
158 162 */
159 163 int zap_destroy(objset_t *ds, uint64_t zapobj, dmu_tx_t *tx);
160 164
161 165 /*
162 166 * Manipulate attributes.
163 167 *
164 168 * 'integer_size' is in bytes, and must be 1, 2, 4, or 8.
165 169 */
166 170
↓ open down ↓ |
56 lines elided |
↑ open up ↑ |
167 171 /*
168 172 * Retrieve the contents of the attribute with the given name.
169 173 *
170 174 * If the requested attribute does not exist, the call will fail and
171 175 * return ENOENT.
172 176 *
173 177 * If 'integer_size' is smaller than the attribute's integer size, the
174 178 * call will fail and return EINVAL.
175 179 *
176 180 * If 'integer_size' is equal to or larger than the attribute's integer
177 - * size, the call will succeed and return 0. * When converting to a
178 - * larger integer size, the integers will be treated as unsigned (ie. no
179 - * sign-extension will be performed).
181 + * size, the call will succeed and return 0.
182 + *
183 + * When converting to a larger integer size, the integers will be treated as
184 + * unsigned (ie. no sign-extension will be performed).
180 185 *
181 186 * 'num_integers' is the length (in integers) of 'buf'.
182 187 *
183 188 * If the attribute is longer than the buffer, as many integers as will
184 189 * fit will be transferred to 'buf'. If the entire attribute was not
185 190 * transferred, the call will return EOVERFLOW.
186 - *
191 + */
192 +int zap_lookup(objset_t *ds, uint64_t zapobj, const char *name,
193 + uint64_t integer_size, uint64_t num_integers, void *buf);
194 +
195 +/*
187 196 * If rn_len is nonzero, realname will be set to the name of the found
188 197 * entry (which may be different from the requested name if matchtype is
189 198 * not MT_EXACT).
190 199 *
191 200 * If normalization_conflictp is not NULL, it will be set if there is
192 201 * another name with the same case/unicode normalized form.
193 202 */
194 -int zap_lookup(objset_t *ds, uint64_t zapobj, const char *name,
195 - uint64_t integer_size, uint64_t num_integers, void *buf);
196 203 int zap_lookup_norm(objset_t *ds, uint64_t zapobj, const char *name,
197 204 uint64_t integer_size, uint64_t num_integers, void *buf,
198 205 matchtype_t mt, char *realname, int rn_len,
199 206 boolean_t *normalization_conflictp);
200 207 int zap_lookup_uint64(objset_t *os, uint64_t zapobj, const uint64_t *key,
201 208 int key_numints, uint64_t integer_size, uint64_t num_integers, void *buf);
202 209 int zap_contains(objset_t *ds, uint64_t zapobj, const char *name);
203 210 int zap_prefetch_uint64(objset_t *os, uint64_t zapobj, const uint64_t *key,
204 211 int key_numints);
205 212
206 213 int zap_count_write(objset_t *os, uint64_t zapobj, const char *name,
207 214 int add, uint64_t *towrite, uint64_t *tooverwrite);
208 215
209 216 /*
210 217 * Create an attribute with the given name and value.
211 218 *
212 219 * If an attribute with the given name already exists, the call will
213 220 * fail and return EEXIST.
214 221 */
215 222 int zap_add(objset_t *ds, uint64_t zapobj, const char *key,
216 223 int integer_size, uint64_t num_integers,
217 224 const void *val, dmu_tx_t *tx);
218 225 int zap_add_uint64(objset_t *ds, uint64_t zapobj, const uint64_t *key,
219 226 int key_numints, int integer_size, uint64_t num_integers,
220 227 const void *val, dmu_tx_t *tx);
221 228
222 229 /*
223 230 * Set the attribute with the given name to the given value. If an
224 231 * attribute with the given name does not exist, it will be created. If
225 232 * an attribute with the given name already exists, the previous value
226 233 * will be overwritten. The integer_size may be different from the
227 234 * existing attribute's integer size, in which case the attribute's
228 235 * integer size will be updated to the new value.
229 236 */
230 237 int zap_update(objset_t *ds, uint64_t zapobj, const char *name,
231 238 int integer_size, uint64_t num_integers, const void *val, dmu_tx_t *tx);
232 239 int zap_update_uint64(objset_t *os, uint64_t zapobj, const uint64_t *key,
233 240 int key_numints,
234 241 int integer_size, uint64_t num_integers, const void *val, dmu_tx_t *tx);
235 242
236 243 /*
237 244 * Get the length (in integers) and the integer size of the specified
238 245 * attribute.
239 246 *
240 247 * If the requested attribute does not exist, the call will fail and
241 248 * return ENOENT.
242 249 */
243 250 int zap_length(objset_t *ds, uint64_t zapobj, const char *name,
244 251 uint64_t *integer_size, uint64_t *num_integers);
245 252 int zap_length_uint64(objset_t *os, uint64_t zapobj, const uint64_t *key,
246 253 int key_numints, uint64_t *integer_size, uint64_t *num_integers);
247 254
248 255 /*
249 256 * Remove the specified attribute.
250 257 *
251 258 * If the specified attribute does not exist, the call will fail and
252 259 * return ENOENT.
253 260 */
254 261 int zap_remove(objset_t *ds, uint64_t zapobj, const char *name, dmu_tx_t *tx);
255 262 int zap_remove_norm(objset_t *ds, uint64_t zapobj, const char *name,
256 263 matchtype_t mt, dmu_tx_t *tx);
257 264 int zap_remove_uint64(objset_t *os, uint64_t zapobj, const uint64_t *key,
258 265 int key_numints, dmu_tx_t *tx);
259 266
260 267 /*
261 268 * Returns (in *count) the number of attributes in the specified zap
262 269 * object.
263 270 */
264 271 int zap_count(objset_t *ds, uint64_t zapobj, uint64_t *count);
265 272
266 273 /*
267 274 * Returns (in name) the name of the entry whose (value & mask)
268 275 * (za_first_integer) is value, or ENOENT if not found. The string
269 276 * pointed to by name must be at least 256 bytes long. If mask==0, the
270 277 * match must be exact (ie, same as mask=-1ULL).
271 278 */
272 279 int zap_value_search(objset_t *os, uint64_t zapobj,
273 280 uint64_t value, uint64_t mask, char *name);
274 281
275 282 /*
276 283 * Transfer all the entries from fromobj into intoobj. Only works on
277 284 * int_size=8 num_integers=1 values. Fails if there are any duplicated
278 285 * entries.
279 286 */
280 287 int zap_join(objset_t *os, uint64_t fromobj, uint64_t intoobj, dmu_tx_t *tx);
281 288
282 289 /* Same as zap_join, but set the values to 'value'. */
283 290 int zap_join_key(objset_t *os, uint64_t fromobj, uint64_t intoobj,
284 291 uint64_t value, dmu_tx_t *tx);
285 292
286 293 /* Same as zap_join, but add together any duplicated entries. */
287 294 int zap_join_increment(objset_t *os, uint64_t fromobj, uint64_t intoobj,
288 295 dmu_tx_t *tx);
289 296
290 297 /*
291 298 * Manipulate entries where the name + value are the "same" (the name is
292 299 * a stringified version of the value).
293 300 */
294 301 int zap_add_int(objset_t *os, uint64_t obj, uint64_t value, dmu_tx_t *tx);
295 302 int zap_remove_int(objset_t *os, uint64_t obj, uint64_t value, dmu_tx_t *tx);
296 303 int zap_lookup_int(objset_t *os, uint64_t obj, uint64_t value);
297 304 int zap_increment_int(objset_t *os, uint64_t obj, uint64_t key, int64_t delta,
298 305 dmu_tx_t *tx);
299 306
300 307 /* Here the key is an int and the value is a different int. */
301 308 int zap_add_int_key(objset_t *os, uint64_t obj,
302 309 uint64_t key, uint64_t value, dmu_tx_t *tx);
303 310 int zap_update_int_key(objset_t *os, uint64_t obj,
304 311 uint64_t key, uint64_t value, dmu_tx_t *tx);
305 312 int zap_lookup_int_key(objset_t *os, uint64_t obj,
306 313 uint64_t key, uint64_t *valuep);
307 314
308 315 int zap_increment(objset_t *os, uint64_t obj, const char *name, int64_t delta,
309 316 dmu_tx_t *tx);
310 317
311 318 struct zap;
312 319 struct zap_leaf;
313 320 typedef struct zap_cursor {
314 321 /* This structure is opaque! */
315 322 objset_t *zc_objset;
316 323 struct zap *zc_zap;
317 324 struct zap_leaf *zc_leaf;
318 325 uint64_t zc_zapobj;
319 326 uint64_t zc_serialized;
320 327 uint64_t zc_hash;
321 328 uint32_t zc_cd;
322 329 } zap_cursor_t;
323 330
324 331 typedef struct {
325 332 int za_integer_length;
326 333 /*
327 334 * za_normalization_conflict will be set if there are additional
328 335 * entries with this normalized form (eg, "foo" and "Foo").
329 336 */
330 337 boolean_t za_normalization_conflict;
331 338 uint64_t za_num_integers;
332 339 uint64_t za_first_integer; /* no sign extension for <8byte ints */
333 340 char za_name[MAXNAMELEN];
334 341 } zap_attribute_t;
335 342
336 343 /*
337 344 * The interface for listing all the attributes of a zapobj can be
338 345 * thought of as cursor moving down a list of the attributes one by
339 346 * one. The cookie returned by the zap_cursor_serialize routine is
340 347 * persistent across system calls (and across reboot, even).
341 348 */
342 349
343 350 /*
344 351 * Initialize a zap cursor, pointing to the "first" attribute of the
345 352 * zapobj. You must _fini the cursor when you are done with it.
346 353 */
347 354 void zap_cursor_init(zap_cursor_t *zc, objset_t *ds, uint64_t zapobj);
348 355 void zap_cursor_fini(zap_cursor_t *zc);
349 356
350 357 /*
351 358 * Get the attribute currently pointed to by the cursor. Returns
352 359 * ENOENT if at the end of the attributes.
353 360 */
354 361 int zap_cursor_retrieve(zap_cursor_t *zc, zap_attribute_t *za);
355 362
356 363 /*
357 364 * Advance the cursor to the next attribute.
358 365 */
359 366 void zap_cursor_advance(zap_cursor_t *zc);
360 367
361 368 /*
362 369 * Get a persistent cookie pointing to the current position of the zap
363 370 * cursor. The low 4 bits in the cookie are always zero, and thus can
364 371 * be used as to differentiate a serialized cookie from a different type
365 372 * of value. The cookie will be less than 2^32 as long as there are
366 373 * fewer than 2^22 (4.2 million) entries in the zap object.
367 374 */
368 375 uint64_t zap_cursor_serialize(zap_cursor_t *zc);
369 376
370 377 /*
371 378 * Advance the cursor to the attribute having the given key.
372 379 */
373 380 int zap_cursor_move_to_key(zap_cursor_t *zc, const char *name, matchtype_t mt);
374 381
375 382 /*
376 383 * Initialize a zap cursor pointing to the position recorded by
377 384 * zap_cursor_serialize (in the "serialized" argument). You can also
378 385 * use a "serialized" argument of 0 to start at the beginning of the
379 386 * zapobj (ie. zap_cursor_init_serialized(..., 0) is equivalent to
380 387 * zap_cursor_init(...).)
381 388 */
382 389 void zap_cursor_init_serialized(zap_cursor_t *zc, objset_t *ds,
383 390 uint64_t zapobj, uint64_t serialized);
384 391
385 392
386 393 #define ZAP_HISTOGRAM_SIZE 10
387 394
388 395 typedef struct zap_stats {
389 396 /*
390 397 * Size of the pointer table (in number of entries).
391 398 * This is always a power of 2, or zero if it's a microzap.
392 399 * In general, it should be considerably greater than zs_num_leafs.
393 400 */
394 401 uint64_t zs_ptrtbl_len;
395 402
396 403 uint64_t zs_blocksize; /* size of zap blocks */
397 404
398 405 /*
399 406 * The number of blocks used. Note that some blocks may be
400 407 * wasted because old ptrtbl's and large name/value blocks are
401 408 * not reused. (Although their space is reclaimed, we don't
402 409 * reuse those offsets in the object.)
403 410 */
404 411 uint64_t zs_num_blocks;
405 412
406 413 /*
407 414 * Pointer table values from zap_ptrtbl in the zap_phys_t
408 415 */
409 416 uint64_t zs_ptrtbl_nextblk; /* next (larger) copy start block */
410 417 uint64_t zs_ptrtbl_blks_copied; /* number source blocks copied */
411 418 uint64_t zs_ptrtbl_zt_blk; /* starting block number */
412 419 uint64_t zs_ptrtbl_zt_numblks; /* number of blocks */
413 420 uint64_t zs_ptrtbl_zt_shift; /* bits to index it */
414 421
415 422 /*
416 423 * Values of the other members of the zap_phys_t
417 424 */
418 425 uint64_t zs_block_type; /* ZBT_HEADER */
419 426 uint64_t zs_magic; /* ZAP_MAGIC */
420 427 uint64_t zs_num_leafs; /* The number of leaf blocks */
421 428 uint64_t zs_num_entries; /* The number of zap entries */
422 429 uint64_t zs_salt; /* salt to stir into hash function */
423 430
424 431 /*
425 432 * Histograms. For all histograms, the last index
426 433 * (ZAP_HISTOGRAM_SIZE-1) includes any values which are greater
427 434 * than what can be represented. For example
428 435 * zs_leafs_with_n5_entries[ZAP_HISTOGRAM_SIZE-1] is the number
429 436 * of leafs with more than 45 entries.
430 437 */
431 438
432 439 /*
433 440 * zs_leafs_with_n_pointers[n] is the number of leafs with
434 441 * 2^n pointers to it.
435 442 */
436 443 uint64_t zs_leafs_with_2n_pointers[ZAP_HISTOGRAM_SIZE];
437 444
438 445 /*
439 446 * zs_leafs_with_n_entries[n] is the number of leafs with
440 447 * [n*5, (n+1)*5) entries. In the current implementation, there
441 448 * can be at most 55 entries in any block, but there may be
442 449 * fewer if the name or value is large, or the block is not
443 450 * completely full.
444 451 */
445 452 uint64_t zs_blocks_with_n5_entries[ZAP_HISTOGRAM_SIZE];
446 453
447 454 /*
448 455 * zs_leafs_n_tenths_full[n] is the number of leafs whose
449 456 * fullness is in the range [n/10, (n+1)/10).
450 457 */
451 458 uint64_t zs_blocks_n_tenths_full[ZAP_HISTOGRAM_SIZE];
452 459
453 460 /*
454 461 * zs_entries_using_n_chunks[n] is the number of entries which
455 462 * consume n 24-byte chunks. (Note, large names/values only use
456 463 * one chunk, but contribute to zs_num_blocks_large.)
457 464 */
458 465 uint64_t zs_entries_using_n_chunks[ZAP_HISTOGRAM_SIZE];
459 466
460 467 /*
461 468 * zs_buckets_with_n_entries[n] is the number of buckets (each
462 469 * leaf has 64 buckets) with n entries.
463 470 * zs_buckets_with_n_entries[1] should be very close to
464 471 * zs_num_entries.
465 472 */
466 473 uint64_t zs_buckets_with_n_entries[ZAP_HISTOGRAM_SIZE];
467 474 } zap_stats_t;
468 475
469 476 /*
470 477 * Get statistics about a ZAP object. Note: you need to be aware of the
471 478 * internal implementation of the ZAP to correctly interpret some of the
472 479 * statistics. This interface shouldn't be relied on unless you really
473 480 * know what you're doing.
474 481 */
475 482 int zap_get_stats(objset_t *ds, uint64_t zapobj, zap_stats_t *zs);
476 483
477 484 #ifdef __cplusplus
478 485 }
479 486 #endif
480 487
481 488 #endif /* _SYS_ZAP_H */
↓ open down ↓ |
276 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX