xref: /illumos-gate/usr/src/uts/common/fs/zfs/zfeature.c (revision eb633035c80613ec93d62f90482837adaaf21a0a)
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 /*
23  * Copyright (c) 2011, 2015 by Delphix. All rights reserved.
24  */
25 
26 #include <sys/zfs_context.h>
27 #include <sys/zfeature.h>
28 #include <sys/dmu.h>
29 #include <sys/nvpair.h>
30 #include <sys/zap.h>
31 #include <sys/dmu_tx.h>
32 #include "zfeature_common.h"
33 #include <sys/spa_impl.h>
34 
35 /*
36  * ZFS Feature Flags
37  * -----------------
38  *
39  * ZFS feature flags are used to provide fine-grained versioning to the ZFS
40  * on-disk format. Once enabled on a pool feature flags replace the old
41  * spa_version() number.
42  *
43  * Each new on-disk format change will be given a uniquely identifying string
44  * guid rather than a version number. This avoids the problem of different
45  * organizations creating new on-disk formats with the same version number. To
46  * keep feature guids unique they should consist of the reverse dns name of the
47  * organization which implemented the feature and a short name for the feature,
48  * separated by a colon (e.g. com.delphix:async_destroy).
49  *
50  * Reference Counts
51  * ----------------
52  *
53  * Within each pool features can be in one of three states: disabled, enabled,
54  * or active. These states are differentiated by a reference count stored on
55  * disk for each feature:
56  *
57  *   1) If there is no reference count stored on disk the feature is disabled.
58  *   2) If the reference count is 0 a system administrator has enabled the
59  *      feature, but the feature has not been used yet, so no on-disk
60  *      format changes have been made.
61  *   3) If the reference count is greater than 0 the feature is active.
62  *      The format changes required by the feature are currently on disk.
63  *      Note that if the feature's format changes are reversed the feature
64  *      may choose to set its reference count back to 0.
65  *
66  * Feature flags makes no differentiation between non-zero reference counts
67  * for an active feature (e.g. a reference count of 1 means the same thing as a
68  * reference count of 27834721), but feature implementations may choose to use
69  * the reference count to store meaningful information. For example, a new RAID
70  * implementation might set the reference count to the number of vdevs using
71  * it. If all those disks are removed from the pool the feature goes back to
72  * having a reference count of 0.
73  *
74  * It is the responsibility of the individual features to maintain a non-zero
75  * reference count as long as the feature's format changes are present on disk.
76  *
77  * Dependencies
78  * ------------
79  *
80  * Each feature may depend on other features. The only effect of this
81  * relationship is that when a feature is enabled all of its dependencies are
82  * automatically enabled as well. Any future work to support disabling of
83  * features would need to ensure that features cannot be disabled if other
84  * enabled features depend on them.
85  *
86  * On-disk Format
87  * --------------
88  *
89  * When feature flags are enabled spa_version() is set to SPA_VERSION_FEATURES
90  * (5000). In order for this to work the pool is automatically upgraded to
91  * SPA_VERSION_BEFORE_FEATURES (28) first, so all pre-feature flags on disk
92  * format changes will be in use.
93  *
94  * Information about features is stored in 3 ZAP objects in the pool's MOS.
95  * These objects are linked to by the following names in the pool directory
96  * object:
97  *
98  * 1) features_for_read: feature guid -> reference count
99  *    Features needed to open the pool for reading.
100  * 2) features_for_write: feature guid -> reference count
101  *    Features needed to open the pool for writing.
102  * 3) feature_descriptions: feature guid -> descriptive string
103  *    A human readable string.
104  *
105  * All enabled features appear in either features_for_read or
106  * features_for_write, but not both.
107  *
108  * To open a pool in read-only mode only the features listed in
109  * features_for_read need to be supported.
110  *
111  * To open the pool in read-write mode features in both features_for_read and
112  * features_for_write need to be supported.
113  *
114  * Some features may be required to read the ZAP objects containing feature
115  * information. To allow software to check for compatibility with these features
116  * before the pool is opened their names must be stored in the label in a
117  * new "features_for_read" entry (note that features that are only required
118  * to write to a pool never need to be stored in the label since the
119  * features_for_write ZAP object can be read before the pool is written to).
120  * To save space in the label features must be explicitly marked as needing to
121  * be written to the label. Also, reference counts are not stored in the label,
122  * instead any feature whose reference count drops to 0 is removed from the
123  * label.
124  *
125  * Adding New Features
126  * -------------------
127  *
128  * Features must be registered in zpool_feature_init() function in
129  * zfeature_common.c using the zfeature_register() function. This function
130  * has arguments to specify if the feature should be stored in the
131  * features_for_read or features_for_write ZAP object and if it needs to be
132  * written to the label when active.
133  *
134  * Once a feature is registered it will appear as a "feature@<feature name>"
135  * property which can be set by an administrator. Feature implementors should
136  * use the spa_feature_is_enabled() and spa_feature_is_active() functions to
137  * query the state of a feature and the spa_feature_incr() and
138  * spa_feature_decr() functions to change an enabled feature's reference count.
139  * Reference counts may only be updated in the syncing context.
140  *
141  * Features may not perform enable-time initialization. Instead, any such
142  * initialization should occur when the feature is first used. This design
143  * enforces that on-disk changes be made only when features are used. Code
144  * should only check if a feature is enabled using spa_feature_is_enabled(),
145  * not by relying on any feature specific metadata existing. If a feature is
146  * enabled, but the feature's metadata is not on disk yet then it should be
147  * created as needed.
148  *
149  * As an example, consider the com.delphix:async_destroy feature. This feature
150  * relies on the existence of a bptree in the MOS that store blocks for
151  * asynchronous freeing. This bptree is not created when async_destroy is
152  * enabled. Instead, when a dataset is destroyed spa_feature_is_enabled() is
153  * called to check if async_destroy is enabled. If it is and the bptree object
154  * does not exist yet, the bptree object is created as part of the dataset
155  * destroy and async_destroy's reference count is incremented to indicate it
156  * has made an on-disk format change. Later, after the destroyed dataset's
157  * blocks have all been asynchronously freed there is no longer any use for the
158  * bptree object, so it is destroyed and async_destroy's reference count is
159  * decremented back to 0 to indicate that it has undone its on-disk format
160  * changes.
161  */
162 
163 typedef enum {
164 	FEATURE_ACTION_INCR,
165 	FEATURE_ACTION_DECR,
166 } feature_action_t;
167 
168 /*
169  * Checks that the active features in the pool are supported by
170  * this software.  Adds each unsupported feature (name -> description) to
171  * the supplied nvlist.
172  */
173 boolean_t
spa_features_check(spa_t * spa,boolean_t for_write,nvlist_t * unsup_feat,nvlist_t * enabled_feat)174 spa_features_check(spa_t *spa, boolean_t for_write,
175     nvlist_t *unsup_feat, nvlist_t *enabled_feat)
176 {
177 	objset_t *os = spa->spa_meta_objset;
178 	boolean_t supported;
179 	zap_cursor_t zc;
180 	zap_attribute_t za;
181 	uint64_t obj = for_write ?
182 	    spa->spa_feat_for_write_obj : spa->spa_feat_for_read_obj;
183 
184 	supported = B_TRUE;
185 	for (zap_cursor_init(&zc, os, obj);
186 	    zap_cursor_retrieve(&zc, &za) == 0;
187 	    zap_cursor_advance(&zc)) {
188 		ASSERT(za.za_integer_length == sizeof (uint64_t) &&
189 		    za.za_num_integers == 1);
190 
191 		if (NULL != enabled_feat) {
192 			fnvlist_add_uint64(enabled_feat, za.za_name,
193 			    za.za_first_integer);
194 		}
195 
196 		if (za.za_first_integer != 0 &&
197 		    !zfeature_is_supported(za.za_name)) {
198 			supported = B_FALSE;
199 
200 			if (NULL != unsup_feat) {
201 				char *desc = "";
202 				char buf[MAXPATHLEN];
203 
204 				if (zap_lookup(os, spa->spa_feat_desc_obj,
205 				    za.za_name, 1, sizeof (buf), buf) == 0)
206 					desc = buf;
207 
208 				VERIFY(nvlist_add_string(unsup_feat, za.za_name,
209 				    desc) == 0);
210 			}
211 		}
212 	}
213 	zap_cursor_fini(&zc);
214 
215 	return (supported);
216 }
217 
218 /*
219  * Use an in-memory cache of feature refcounts for quick retrieval.
220  *
221  * Note: well-designed features will not need to use this; they should
222  * use spa_feature_is_enabled() and spa_feature_is_active() instead.
223  * However, this is non-static for zdb and zhack.
224  */
225 int
feature_get_refcount(spa_t * spa,zfeature_info_t * feature,uint64_t * res)226 feature_get_refcount(spa_t *spa, zfeature_info_t *feature, uint64_t *res)
227 {
228 	ASSERT(VALID_FEATURE_FID(feature->fi_feature));
229 	if (spa->spa_feat_refcount_cache[feature->fi_feature] ==
230 	    SPA_FEATURE_DISABLED) {
231 		return (SET_ERROR(ENOTSUP));
232 	}
233 	*res = spa->spa_feat_refcount_cache[feature->fi_feature];
234 	return (0);
235 }
236 
237 /*
238  * Note: well-designed features will not need to use this; they should
239  * use spa_feature_is_enabled() and spa_feature_is_active() instead.
240  * However, this is non-static for zdb and zhack.
241  */
242 int
feature_get_refcount_from_disk(spa_t * spa,zfeature_info_t * feature,uint64_t * res)243 feature_get_refcount_from_disk(spa_t *spa, zfeature_info_t *feature,
244     uint64_t *res)
245 {
246 	int err;
247 	uint64_t refcount;
248 	uint64_t zapobj = (feature->fi_flags & ZFEATURE_FLAG_READONLY_COMPAT) ?
249 	    spa->spa_feat_for_write_obj : spa->spa_feat_for_read_obj;
250 
251 	/*
252 	 * If the pool is currently being created, the feature objects may not
253 	 * have been allocated yet.  Act as though all features are disabled.
254 	 */
255 	if (zapobj == 0)
256 		return (SET_ERROR(ENOTSUP));
257 
258 	err = zap_lookup(spa->spa_meta_objset, zapobj,
259 	    feature->fi_guid, sizeof (uint64_t), 1, &refcount);
260 	if (err != 0) {
261 		if (err == ENOENT)
262 			return (SET_ERROR(ENOTSUP));
263 		else
264 			return (err);
265 	}
266 	*res = refcount;
267 	return (0);
268 }
269 
270 
271 static int
feature_get_enabled_txg(spa_t * spa,zfeature_info_t * feature,uint64_t * res)272 feature_get_enabled_txg(spa_t *spa, zfeature_info_t *feature, uint64_t *res)
273 {
274 	uint64_t enabled_txg_obj = spa->spa_feat_enabled_txg_obj;
275 
276 	ASSERT(zfeature_depends_on(feature->fi_feature,
277 	    SPA_FEATURE_ENABLED_TXG));
278 
279 	if (!spa_feature_is_enabled(spa, feature->fi_feature)) {
280 		return (SET_ERROR(ENOTSUP));
281 	}
282 
283 	ASSERT(enabled_txg_obj != 0);
284 
285 	VERIFY0(zap_lookup(spa->spa_meta_objset, spa->spa_feat_enabled_txg_obj,
286 	    feature->fi_guid, sizeof (uint64_t), 1, res));
287 
288 	return (0);
289 }
290 
291 /*
292  * This function is non-static for zhack; it should otherwise not be used
293  * outside this file.
294  */
295 void
feature_sync(spa_t * spa,zfeature_info_t * feature,uint64_t refcount,dmu_tx_t * tx)296 feature_sync(spa_t *spa, zfeature_info_t *feature, uint64_t refcount,
297     dmu_tx_t *tx)
298 {
299 	ASSERT(VALID_FEATURE_OR_NONE(feature->fi_feature));
300 	uint64_t zapobj = (feature->fi_flags & ZFEATURE_FLAG_READONLY_COMPAT) ?
301 	    spa->spa_feat_for_write_obj : spa->spa_feat_for_read_obj;
302 
303 	VERIFY0(zap_update(spa->spa_meta_objset, zapobj, feature->fi_guid,
304 	    sizeof (uint64_t), 1, &refcount, tx));
305 
306 	/*
307 	 * feature_sync is called directly from zhack, allowing the
308 	 * creation of arbitrary features whose fi_feature field may
309 	 * be greater than SPA_FEATURES. When called from zhack, the
310 	 * zfeature_info_t object's fi_feature field will be set to
311 	 * SPA_FEATURE_NONE.
312 	 */
313 	if (feature->fi_feature != SPA_FEATURE_NONE) {
314 		uint64_t *refcount_cache =
315 		    &spa->spa_feat_refcount_cache[feature->fi_feature];
316 		VERIFY3U(*refcount_cache, ==,
317 		    atomic_swap_64(refcount_cache, refcount));
318 	}
319 
320 	if (refcount == 0)
321 		spa_deactivate_mos_feature(spa, feature->fi_guid);
322 	else if (feature->fi_flags & ZFEATURE_FLAG_MOS)
323 		spa_activate_mos_feature(spa, feature->fi_guid, tx);
324 }
325 
326 /*
327  * This function is non-static for zhack; it should otherwise not be used
328  * outside this file.
329  */
330 void
feature_enable_sync(spa_t * spa,zfeature_info_t * feature,dmu_tx_t * tx)331 feature_enable_sync(spa_t *spa, zfeature_info_t *feature, dmu_tx_t *tx)
332 {
333 	uint64_t initial_refcount =
334 	    (feature->fi_flags & ZFEATURE_FLAG_ACTIVATE_ON_ENABLE) ? 1 : 0;
335 	uint64_t zapobj = (feature->fi_flags & ZFEATURE_FLAG_READONLY_COMPAT) ?
336 	    spa->spa_feat_for_write_obj : spa->spa_feat_for_read_obj;
337 
338 	ASSERT(0 != zapobj);
339 	ASSERT(zfeature_is_valid_guid(feature->fi_guid));
340 	ASSERT3U(spa_version(spa), >=, SPA_VERSION_FEATURES);
341 
342 	/*
343 	 * If the feature is already enabled, ignore the request.
344 	 */
345 	if (zap_contains(spa->spa_meta_objset, zapobj, feature->fi_guid) == 0)
346 		return;
347 
348 	for (int i = 0; feature->fi_depends[i] != SPA_FEATURE_NONE; i++)
349 		spa_feature_enable(spa, feature->fi_depends[i], tx);
350 
351 	VERIFY0(zap_update(spa->spa_meta_objset, spa->spa_feat_desc_obj,
352 	    feature->fi_guid, 1, strlen(feature->fi_desc) + 1,
353 	    feature->fi_desc, tx));
354 
355 	feature_sync(spa, feature, initial_refcount, tx);
356 
357 	if (spa_feature_is_enabled(spa, SPA_FEATURE_ENABLED_TXG)) {
358 		uint64_t enabling_txg = dmu_tx_get_txg(tx);
359 
360 		if (spa->spa_feat_enabled_txg_obj == 0ULL) {
361 			spa->spa_feat_enabled_txg_obj =
362 			    zap_create_link(spa->spa_meta_objset,
363 			    DMU_OTN_ZAP_METADATA, DMU_POOL_DIRECTORY_OBJECT,
364 			    DMU_POOL_FEATURE_ENABLED_TXG, tx);
365 		}
366 		spa_feature_incr(spa, SPA_FEATURE_ENABLED_TXG, tx);
367 
368 		VERIFY0(zap_add(spa->spa_meta_objset,
369 		    spa->spa_feat_enabled_txg_obj, feature->fi_guid,
370 		    sizeof (uint64_t), 1, &enabling_txg, tx));
371 	}
372 
373 	/*
374 	 * Errata #4 is mostly a problem with encrypted datasets, but it
375 	 * is also a problem where the old encryption feature did not
376 	 * depend on the bookmark_v2 feature. If the pool does not have
377 	 * any encrypted datasets we can resolve this issue simply by
378 	 * enabling this dependency.
379 	 */
380 	if (spa->spa_errata == ZPOOL_ERRATA_ZOL_8308_ENCRYPTION &&
381 	    spa_feature_is_enabled(spa, SPA_FEATURE_ENCRYPTION) &&
382 	    !spa_feature_is_active(spa, SPA_FEATURE_ENCRYPTION) &&
383 	    feature->fi_feature == SPA_FEATURE_BOOKMARK_V2)
384 		spa->spa_errata = 0;
385 }
386 
387 static void
feature_do_action(spa_t * spa,spa_feature_t fid,feature_action_t action,dmu_tx_t * tx)388 feature_do_action(spa_t *spa, spa_feature_t fid, feature_action_t action,
389     dmu_tx_t *tx)
390 {
391 	uint64_t refcount;
392 	zfeature_info_t *feature = &spa_feature_table[fid];
393 	uint64_t zapobj = (feature->fi_flags & ZFEATURE_FLAG_READONLY_COMPAT) ?
394 	    spa->spa_feat_for_write_obj : spa->spa_feat_for_read_obj;
395 
396 	ASSERT(VALID_FEATURE_FID(fid));
397 	ASSERT(0 != zapobj);
398 	ASSERT(zfeature_is_valid_guid(feature->fi_guid));
399 
400 	ASSERT(dmu_tx_is_syncing(tx));
401 	ASSERT3U(spa_version(spa), >=, SPA_VERSION_FEATURES);
402 
403 	VERIFY3U(feature_get_refcount(spa, feature, &refcount), !=, ENOTSUP);
404 
405 	switch (action) {
406 	case FEATURE_ACTION_INCR:
407 		VERIFY3U(refcount, !=, UINT64_MAX);
408 		refcount++;
409 		break;
410 	case FEATURE_ACTION_DECR:
411 		VERIFY3U(refcount, !=, 0);
412 		refcount--;
413 		break;
414 	default:
415 		ASSERT(0);
416 		break;
417 	}
418 
419 	feature_sync(spa, feature, refcount, tx);
420 }
421 
422 void
spa_feature_create_zap_objects(spa_t * spa,dmu_tx_t * tx)423 spa_feature_create_zap_objects(spa_t *spa, dmu_tx_t *tx)
424 {
425 	/*
426 	 * We create feature flags ZAP objects in two instances: during pool
427 	 * creation and during pool upgrade.
428 	 */
429 	ASSERT((!spa->spa_sync_on && tx->tx_txg == TXG_INITIAL) ||
430 	    dsl_pool_sync_context(spa_get_dsl(spa)));
431 
432 	spa->spa_feat_for_read_obj = zap_create_link(spa->spa_meta_objset,
433 	    DMU_OTN_ZAP_METADATA, DMU_POOL_DIRECTORY_OBJECT,
434 	    DMU_POOL_FEATURES_FOR_READ, tx);
435 	spa->spa_feat_for_write_obj = zap_create_link(spa->spa_meta_objset,
436 	    DMU_OTN_ZAP_METADATA, DMU_POOL_DIRECTORY_OBJECT,
437 	    DMU_POOL_FEATURES_FOR_WRITE, tx);
438 	spa->spa_feat_desc_obj = zap_create_link(spa->spa_meta_objset,
439 	    DMU_OTN_ZAP_METADATA, DMU_POOL_DIRECTORY_OBJECT,
440 	    DMU_POOL_FEATURE_DESCRIPTIONS, tx);
441 }
442 
443 /*
444  * Enable any required dependencies, then enable the requested feature.
445  */
446 void
spa_feature_enable(spa_t * spa,spa_feature_t fid,dmu_tx_t * tx)447 spa_feature_enable(spa_t *spa, spa_feature_t fid, dmu_tx_t *tx)
448 {
449 	ASSERT3U(spa_version(spa), >=, SPA_VERSION_FEATURES);
450 	ASSERT(VALID_FEATURE_FID(fid));
451 	feature_enable_sync(spa, &spa_feature_table[fid], tx);
452 }
453 
454 void
spa_feature_incr(spa_t * spa,spa_feature_t fid,dmu_tx_t * tx)455 spa_feature_incr(spa_t *spa, spa_feature_t fid, dmu_tx_t *tx)
456 {
457 	feature_do_action(spa, fid, FEATURE_ACTION_INCR, tx);
458 }
459 
460 void
spa_feature_decr(spa_t * spa,spa_feature_t fid,dmu_tx_t * tx)461 spa_feature_decr(spa_t *spa, spa_feature_t fid, dmu_tx_t *tx)
462 {
463 	feature_do_action(spa, fid, FEATURE_ACTION_DECR, tx);
464 }
465 
466 boolean_t
spa_feature_is_enabled(spa_t * spa,spa_feature_t fid)467 spa_feature_is_enabled(spa_t *spa, spa_feature_t fid)
468 {
469 	int err;
470 	uint64_t refcount;
471 
472 	ASSERT(VALID_FEATURE_FID(fid));
473 	if (spa_version(spa) < SPA_VERSION_FEATURES)
474 		return (B_FALSE);
475 
476 	err = feature_get_refcount(spa, &spa_feature_table[fid], &refcount);
477 	ASSERT(err == 0 || err == ENOTSUP);
478 	return (err == 0);
479 }
480 
481 boolean_t
spa_feature_is_active(spa_t * spa,spa_feature_t fid)482 spa_feature_is_active(spa_t *spa, spa_feature_t fid)
483 {
484 	int err;
485 	uint64_t refcount;
486 
487 	ASSERT(VALID_FEATURE_FID(fid));
488 	if (spa_version(spa) < SPA_VERSION_FEATURES)
489 		return (B_FALSE);
490 
491 	err = feature_get_refcount(spa, &spa_feature_table[fid], &refcount);
492 	ASSERT(err == 0 || err == ENOTSUP);
493 	return (err == 0 && refcount > 0);
494 }
495 
496 /*
497  * For the feature specified by fid (which must depend on
498  * SPA_FEATURE_ENABLED_TXG), return the TXG at which it was enabled in the
499  * OUT txg argument.
500  *
501  * Returns B_TRUE if the feature is enabled, in which case txg will be filled
502  * with the transaction group in which the specified feature was enabled.
503  * Returns B_FALSE otherwise (i.e. if the feature is not enabled).
504  */
505 boolean_t
spa_feature_enabled_txg(spa_t * spa,spa_feature_t fid,uint64_t * txg)506 spa_feature_enabled_txg(spa_t *spa, spa_feature_t fid, uint64_t *txg)
507 {
508 	int err;
509 
510 	ASSERT(VALID_FEATURE_FID(fid));
511 	if (spa_version(spa) < SPA_VERSION_FEATURES)
512 		return (B_FALSE);
513 
514 	err = feature_get_enabled_txg(spa, &spa_feature_table[fid], txg);
515 	ASSERT(err == 0 || err == ENOTSUP);
516 
517 	return (err == 0);
518 }
519