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