xref: /illumos-gate/usr/src/uts/common/fs/zfs/sys/zap.h (revision 8248818d5849649ef734d62da097e90222a23763)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 /*
22  * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
23  * Use is subject to license terms.
24  */
25 
26 #ifndef	_SYS_ZAP_H
27 #define	_SYS_ZAP_H
28 
29 #pragma ident	"%Z%%M%	%I%	%E% SMI"
30 
31 /*
32  * ZAP - ZFS Attribute Processor
33  *
34  * The ZAP is a module which sits on top of the DMU (Data Managemnt
35  * Unit) and implements a higher-level storage primitive using DMU
36  * objects.  Its primary consumer is the ZPL (ZFS Posix Layer).
37  *
38  * A "zapobj" is a DMU object which the ZAP uses to stores attributes.
39  * Users should use only zap routines to access a zapobj - they should
40  * not access the DMU object directly using DMU routines.
41  *
42  * The attributes stored in a zapobj are name-value pairs.  The name is
43  * a zero-terminated string of up to ZAP_MAXNAMELEN bytes (including
44  * terminating NULL).  The value is an array of integers, which may be
45  * 1, 2, 4, or 8 bytes long.  The total space used by the array (number
46  * of integers * integer length) can be up to ZAP_MAXVALUELEN bytes.
47  * Note that an 8-byte integer value can be used to store the location
48  * (object number) of another dmu object (which may be itself a zapobj).
49  * Note that you can use a zero-length attribute to store a single bit
50  * of information - the attribute is present or not.
51  *
52  * The ZAP routines are thread-safe.  However, you must observe the
53  * DMU's restriction that a transaction may not be operated on
54  * concurrently.
55  *
56  * Any of the routines that return an int may return an I/O error (EIO
57  * or ECHECKSUM).
58  *
59  *
60  * Implementation / Performance Notes:
61  *
62  * The ZAP is intended to operate most efficiently on attributes with
63  * short (49 bytes or less) names and single 8-byte values, for which
64  * the microzap will be used.  The ZAP should be efficient enough so
65  * that the user does not need to cache these attributes.
66  *
67  * The ZAP's locking scheme makes its routines thread-safe.  Operations
68  * on different zapobjs will be processed concurrently.  Operations on
69  * the same zapobj which only read data will be processed concurrently.
70  * Operations on the same zapobj which modify data will be processed
71  * concurrently when there are many attributes in the zapobj (because
72  * the ZAP uses per-block locking - more than 128 * (number of cpus)
73  * small attributes will suffice).
74  */
75 
76 /*
77  * We're using zero-terminated byte strings (ie. ASCII or UTF-8 C
78  * strings) for the names of attributes, rather than a byte string
79  * bounded by an explicit length.  If some day we want to support names
80  * in character sets which have embedded zeros (eg. UTF-16, UTF-32),
81  * we'll have to add routines for using length-bounded strings.
82  */
83 
84 #include <sys/dmu.h>
85 
86 #ifdef	__cplusplus
87 extern "C" {
88 #endif
89 
90 #define	ZAP_MAXNAMELEN 256
91 #define	ZAP_MAXVALUELEN 1024
92 
93 /*
94  * Create a new zapobj with no attributes and return its object number.
95  */
96 uint64_t zap_create(objset_t *ds, dmu_object_type_t ot,
97     dmu_object_type_t bonustype, int bonuslen, dmu_tx_t *tx);
98 
99 /*
100  * Create a new zapobj with no attributes from the given (unallocated)
101  * object number.
102  */
103 int zap_create_claim(objset_t *ds, uint64_t obj, dmu_object_type_t ot,
104     dmu_object_type_t bonustype, int bonuslen, dmu_tx_t *tx);
105 
106 /*
107  * The zapobj passed in must be a valid ZAP object for all of the
108  * following routines.
109  */
110 
111 /*
112  * Destroy this zapobj and all its attributes.
113  *
114  * Frees the object number using dmu_object_free.
115  */
116 int zap_destroy(objset_t *ds, uint64_t zapobj, dmu_tx_t *tx);
117 
118 /*
119  * Manipulate attributes.
120  *
121  * 'integer_size' is in bytes, and must be 1, 2, 4, or 8.
122  */
123 
124 /*
125  * Retrieve the contents of the attribute with the given name.
126  *
127  * If the requested attribute does not exist, the call will fail and
128  * return ENOENT.
129  *
130  * If 'integer_size' is smaller than the attribute's integer size, the
131  * call will fail and return EINVAL.
132  *
133  * If 'integer_size' is equal to or larger than the attribute's integer
134  * size, the call will succeed and return 0.  * When converting to a
135  * larger integer size, the integers will be treated as unsigned (ie. no
136  * sign-extension will be performed).
137  *
138  * 'num_integers' is the length (in integers) of 'buf'.
139  *
140  * If the attribute is longer than the buffer, as many integers as will
141  * fit will be transferred to 'buf'.  If the entire attribute was not
142  * transferred, the call will return EOVERFLOW.
143  */
144 int zap_lookup(objset_t *ds, uint64_t zapobj, const char *name,
145     uint64_t integer_size, uint64_t num_integers, void *buf);
146 
147 /*
148  * Create an attribute with the given name and value.
149  *
150  * If an attribute with the given name already exists, the call will
151  * fail and return EEXIST.
152  */
153 int zap_add(objset_t *ds, uint64_t zapobj, const char *name,
154     int integer_size, uint64_t num_integers,
155     const void *val, dmu_tx_t *tx);
156 
157 /*
158  * Set the attribute with the given name to the given value.  If an
159  * attribute with the given name does not exist, it will be created.  If
160  * an attribute with the given name already exists, the previous value
161  * will be overwritten.  The integer_size may be different from the
162  * existing attribute's integer size, in which case the attribute's
163  * integer size will be updated to the new value.
164  */
165 int zap_update(objset_t *ds, uint64_t zapobj, const char *name,
166     int integer_size, uint64_t num_integers, const void *val, dmu_tx_t *tx);
167 
168 /*
169  * Get the length (in integers) and the integer size of the specified
170  * attribute.
171  *
172  * If the requested attribute does not exist, the call will fail and
173  * return ENOENT.
174  */
175 int zap_length(objset_t *ds, uint64_t zapobj, const char *name,
176     uint64_t *integer_size, uint64_t *num_integers);
177 
178 /*
179  * Remove the specified attribute.
180  *
181  * If the specified attribute does not exist, the call will fail and
182  * return ENOENT.
183  */
184 int zap_remove(objset_t *ds, uint64_t zapobj, const char *name, dmu_tx_t *tx);
185 
186 /*
187  * Returns (in *count) the number of attributes in the specified zap
188  * object.
189  */
190 int zap_count(objset_t *ds, uint64_t zapobj, uint64_t *count);
191 
192 
193 /*
194  * Returns (in name) the name of the entry whose value
195  * (za_first_integer) is value, or ENOENT if not found.  The string
196  * pointed to by name must be at least 256 bytes long.
197  */
198 int zap_value_search(objset_t *os, uint64_t zapobj, uint64_t value, char *name);
199 
200 struct zap;
201 struct zap_leaf;
202 typedef struct zap_cursor {
203 	/* This structure is opaque! */
204 	objset_t *zc_objset;
205 	struct zap *zc_zap;
206 	struct zap_leaf *zc_leaf;
207 	uint64_t zc_zapobj;
208 	uint64_t zc_hash;
209 	uint32_t zc_cd;
210 } zap_cursor_t;
211 
212 typedef struct {
213 	int za_integer_length;
214 	uint64_t za_num_integers;
215 	uint64_t za_first_integer;	/* no sign extension for <8byte ints */
216 	char za_name[MAXNAMELEN];
217 } zap_attribute_t;
218 
219 /*
220  * The interface for listing all the attributes of a zapobj can be
221  * thought of as cursor moving down a list of the attributes one by
222  * one.  The cookie returned by the zap_cursor_serialize routine is
223  * persistent across system calls (and across reboot, even).
224  */
225 
226 /*
227  * Initialize a zap cursor, pointing to the "first" attribute of the
228  * zapobj.  You must _fini the cursor when you are done with it.
229  */
230 void zap_cursor_init(zap_cursor_t *zc, objset_t *ds, uint64_t zapobj);
231 void zap_cursor_fini(zap_cursor_t *zc);
232 
233 /*
234  * Get the attribute currently pointed to by the cursor.  Returns
235  * ENOENT if at the end of the attributes.
236  */
237 int zap_cursor_retrieve(zap_cursor_t *zc, zap_attribute_t *za);
238 
239 /*
240  * Advance the cursor to the next attribute.
241  */
242 void zap_cursor_advance(zap_cursor_t *zc);
243 
244 /*
245  * Get a persistent cookie pointing to the current position of the zap
246  * cursor.  The low 4 bits in the cookie are always zero, and thus can
247  * be used as to differentiate a serialized cookie from a different type
248  * of value.  The cookie will be less than 2^32 as long as there are
249  * fewer than 2^22 (4.2 million) entries in the zap object.
250  */
251 uint64_t zap_cursor_serialize(zap_cursor_t *zc);
252 
253 /*
254  * Initialize a zap cursor pointing to the position recorded by
255  * zap_cursor_serialize (in the "serialized" argument).  You can also
256  * use a "serialized" argument of 0 to start at the beginning of the
257  * zapobj (ie.  zap_cursor_init_serialized(..., 0) is equivalent to
258  * zap_cursor_init(...).)
259  */
260 void zap_cursor_init_serialized(zap_cursor_t *zc, objset_t *ds,
261     uint64_t zapobj, uint64_t serialized);
262 
263 
264 #define	ZAP_HISTOGRAM_SIZE 10
265 
266 typedef struct zap_stats {
267 	/*
268 	 * Size of the pointer table (in number of entries).
269 	 * This is always a power of 2, or zero if it's a microzap.
270 	 * In general, it should be considerably greater than zs_num_leafs.
271 	 */
272 	uint64_t zs_ptrtbl_len;
273 
274 	uint64_t zs_blocksize;		/* size of zap blocks */
275 
276 	/*
277 	 * The number of blocks used.  Note that some blocks may be
278 	 * wasted because old ptrtbl's and large name/value blocks are
279 	 * not reused.  (Although their space is reclaimed, we don't
280 	 * reuse those offsets in the object.)
281 	 */
282 	uint64_t zs_num_blocks;
283 
284 	/*
285 	 * Pointer table values from zap_ptrtbl in the zap_phys_t
286 	 */
287 	uint64_t zs_ptrtbl_nextblk;	  /* next (larger) copy start block */
288 	uint64_t zs_ptrtbl_blks_copied;   /* number source blocks copied */
289 	uint64_t zs_ptrtbl_zt_blk;	  /* starting block number */
290 	uint64_t zs_ptrtbl_zt_numblks;    /* number of blocks */
291 	uint64_t zs_ptrtbl_zt_shift;	  /* bits to index it */
292 
293 	/*
294 	 * Values of the other members of the zap_phys_t
295 	 */
296 	uint64_t zs_block_type;		/* ZBT_HEADER */
297 	uint64_t zs_magic;		/* ZAP_MAGIC */
298 	uint64_t zs_num_leafs;		/* The number of leaf blocks */
299 	uint64_t zs_num_entries;	/* The number of zap entries */
300 	uint64_t zs_salt;		/* salt to stir into hash function */
301 
302 	/*
303 	 * Histograms.  For all histograms, the last index
304 	 * (ZAP_HISTOGRAM_SIZE-1) includes any values which are greater
305 	 * than what can be represented.  For example
306 	 * zs_leafs_with_n5_entries[ZAP_HISTOGRAM_SIZE-1] is the number
307 	 * of leafs with more than 45 entries.
308 	 */
309 
310 	/*
311 	 * zs_leafs_with_n_pointers[n] is the number of leafs with
312 	 * 2^n pointers to it.
313 	 */
314 	uint64_t zs_leafs_with_2n_pointers[ZAP_HISTOGRAM_SIZE];
315 
316 	/*
317 	 * zs_leafs_with_n_entries[n] is the number of leafs with
318 	 * [n*5, (n+1)*5) entries.  In the current implementation, there
319 	 * can be at most 55 entries in any block, but there may be
320 	 * fewer if the name or value is large, or the block is not
321 	 * completely full.
322 	 */
323 	uint64_t zs_blocks_with_n5_entries[ZAP_HISTOGRAM_SIZE];
324 
325 	/*
326 	 * zs_leafs_n_tenths_full[n] is the number of leafs whose
327 	 * fullness is in the range [n/10, (n+1)/10).
328 	 */
329 	uint64_t zs_blocks_n_tenths_full[ZAP_HISTOGRAM_SIZE];
330 
331 	/*
332 	 * zs_entries_using_n_chunks[n] is the number of entries which
333 	 * consume n 24-byte chunks.  (Note, large names/values only use
334 	 * one chunk, but contribute to zs_num_blocks_large.)
335 	 */
336 	uint64_t zs_entries_using_n_chunks[ZAP_HISTOGRAM_SIZE];
337 
338 	/*
339 	 * zs_buckets_with_n_entries[n] is the number of buckets (each
340 	 * leaf has 64 buckets) with n entries.
341 	 * zs_buckets_with_n_entries[1] should be very close to
342 	 * zs_num_entries.
343 	 */
344 	uint64_t zs_buckets_with_n_entries[ZAP_HISTOGRAM_SIZE];
345 } zap_stats_t;
346 
347 /*
348  * Get statistics about a ZAP object.  Note: you need to be aware of the
349  * internal implementation of the ZAP to correctly interpret some of the
350  * statistics.  This interface shouldn't be relied on unless you really
351  * know what you're doing.
352  */
353 int zap_get_stats(objset_t *ds, uint64_t zapobj, zap_stats_t *zs);
354 
355 #ifdef	__cplusplus
356 }
357 #endif
358 
359 #endif	/* _SYS_ZAP_H */
360