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