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) 2012 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_ENABLE, 165 FEATURE_ACTION_INCR, 166 FEATURE_ACTION_DECR, 167 } feature_action_t; 168 169 /* 170 * Checks that the features active in the specified object are supported by 171 * this software. Adds each unsupported feature (name -> description) to 172 * the supplied nvlist. 173 */ 174 boolean_t 175 feature_is_supported(objset_t *os, uint64_t obj, uint64_t desc_obj, 176 nvlist_t *unsup_feat, nvlist_t *enabled_feat) 177 { 178 boolean_t supported; 179 zap_cursor_t zc; 180 zap_attribute_t za; 181 182 supported = B_TRUE; 183 for (zap_cursor_init(&zc, os, obj); 184 zap_cursor_retrieve(&zc, &za) == 0; 185 zap_cursor_advance(&zc)) { 186 ASSERT(za.za_integer_length == sizeof (uint64_t) && 187 za.za_num_integers == 1); 188 189 if (NULL != enabled_feat) { 190 fnvlist_add_uint64(enabled_feat, za.za_name, 191 za.za_first_integer); 192 } 193 194 if (za.za_first_integer != 0 && 195 !zfeature_is_supported(za.za_name)) { 196 supported = B_FALSE; 197 198 if (NULL != unsup_feat) { 199 char *desc = ""; 200 char buf[MAXPATHLEN]; 201 202 if (zap_lookup(os, desc_obj, za.za_name, 203 1, sizeof (buf), buf) == 0) 204 desc = buf; 205 206 VERIFY(nvlist_add_string(unsup_feat, za.za_name, 207 desc) == 0); 208 } 209 } 210 } 211 zap_cursor_fini(&zc); 212 213 return (supported); 214 } 215 216 static int 217 feature_get_refcount(objset_t *os, uint64_t read_obj, uint64_t write_obj, 218 zfeature_info_t *feature, uint64_t *res) 219 { 220 int err; 221 uint64_t refcount; 222 uint64_t zapobj = feature->fi_can_readonly ? write_obj : read_obj; 223 224 ASSERT(0 != zapobj); 225 226 err = zap_lookup(os, zapobj, feature->fi_guid, sizeof (uint64_t), 1, 227 &refcount); 228 if (err != 0) { 229 if (err == ENOENT) 230 return (ENOTSUP); 231 else 232 return (err); 233 } 234 *res = refcount; 235 return (0); 236 } 237 238 static int 239 feature_do_action(objset_t *os, uint64_t read_obj, uint64_t write_obj, 240 uint64_t desc_obj, zfeature_info_t *feature, feature_action_t action, 241 dmu_tx_t *tx) 242 { 243 int error; 244 uint64_t refcount; 245 uint64_t zapobj = feature->fi_can_readonly ? write_obj : read_obj; 246 247 ASSERT(0 != zapobj); 248 ASSERT(zfeature_is_valid_guid(feature->fi_guid)); 249 250 error = zap_lookup(os, zapobj, feature->fi_guid, 251 sizeof (uint64_t), 1, &refcount); 252 253 /* 254 * If we can't ascertain the status of the specified feature, an I/O 255 * error occurred. 256 */ 257 if (error != 0 && error != ENOENT) 258 return (error); 259 260 switch (action) { 261 case FEATURE_ACTION_ENABLE: 262 /* 263 * If the feature is already enabled, ignore the request. 264 */ 265 if (error == 0) 266 return (0); 267 refcount = 0; 268 break; 269 case FEATURE_ACTION_INCR: 270 if (error == ENOENT) 271 return (ENOTSUP); 272 if (refcount == UINT64_MAX) 273 return (EOVERFLOW); 274 refcount++; 275 break; 276 case FEATURE_ACTION_DECR: 277 if (error == ENOENT) 278 return (ENOTSUP); 279 if (refcount == 0) 280 return (EOVERFLOW); 281 refcount--; 282 break; 283 default: 284 ASSERT(0); 285 break; 286 } 287 288 if (action == FEATURE_ACTION_ENABLE) { 289 int i; 290 291 for (i = 0; feature->fi_depends[i] != NULL; i++) { 292 zfeature_info_t *dep = feature->fi_depends[i]; 293 294 error = feature_do_action(os, read_obj, write_obj, 295 desc_obj, dep, FEATURE_ACTION_ENABLE, tx); 296 if (error != 0) 297 return (error); 298 } 299 } 300 301 error = zap_update(os, zapobj, feature->fi_guid, 302 sizeof (uint64_t), 1, &refcount, tx); 303 if (error != 0) 304 return (error); 305 306 if (action == FEATURE_ACTION_ENABLE) { 307 error = zap_update(os, desc_obj, 308 feature->fi_guid, 1, strlen(feature->fi_desc) + 1, 309 feature->fi_desc, tx); 310 if (error != 0) 311 return (error); 312 } 313 314 if (action == FEATURE_ACTION_INCR && refcount == 1 && feature->fi_mos) { 315 spa_activate_mos_feature(dmu_objset_spa(os), feature->fi_guid); 316 } 317 318 if (action == FEATURE_ACTION_DECR && refcount == 0) { 319 spa_deactivate_mos_feature(dmu_objset_spa(os), 320 feature->fi_guid); 321 } 322 323 return (0); 324 } 325 326 void 327 spa_feature_create_zap_objects(spa_t *spa, dmu_tx_t *tx) 328 { 329 /* 330 * We create feature flags ZAP objects in two instances: during pool 331 * creation and during pool upgrade. 332 */ 333 ASSERT(dsl_pool_sync_context(spa_get_dsl(spa)) || (!spa->spa_sync_on && 334 tx->tx_txg == TXG_INITIAL)); 335 336 spa->spa_feat_for_read_obj = zap_create_link(spa->spa_meta_objset, 337 DMU_OTN_ZAP_METADATA, DMU_POOL_DIRECTORY_OBJECT, 338 DMU_POOL_FEATURES_FOR_READ, tx); 339 spa->spa_feat_for_write_obj = zap_create_link(spa->spa_meta_objset, 340 DMU_OTN_ZAP_METADATA, DMU_POOL_DIRECTORY_OBJECT, 341 DMU_POOL_FEATURES_FOR_WRITE, tx); 342 spa->spa_feat_desc_obj = zap_create_link(spa->spa_meta_objset, 343 DMU_OTN_ZAP_METADATA, DMU_POOL_DIRECTORY_OBJECT, 344 DMU_POOL_FEATURE_DESCRIPTIONS, tx); 345 } 346 347 /* 348 * Enable any required dependencies, then enable the requested feature. 349 */ 350 void 351 spa_feature_enable(spa_t *spa, zfeature_info_t *feature, dmu_tx_t *tx) 352 { 353 ASSERT3U(spa_version(spa), >=, SPA_VERSION_FEATURES); 354 VERIFY3U(0, ==, feature_do_action(spa->spa_meta_objset, 355 spa->spa_feat_for_read_obj, spa->spa_feat_for_write_obj, 356 spa->spa_feat_desc_obj, feature, FEATURE_ACTION_ENABLE, tx)); 357 } 358 359 /* 360 * If the specified feature has not yet been enabled, this function returns 361 * ENOTSUP; otherwise, this function increments the feature's refcount (or 362 * returns EOVERFLOW if the refcount cannot be incremented). This function must 363 * be called from syncing context. 364 */ 365 void 366 spa_feature_incr(spa_t *spa, zfeature_info_t *feature, dmu_tx_t *tx) 367 { 368 ASSERT3U(spa_version(spa), >=, SPA_VERSION_FEATURES); 369 VERIFY3U(0, ==, feature_do_action(spa->spa_meta_objset, 370 spa->spa_feat_for_read_obj, spa->spa_feat_for_write_obj, 371 spa->spa_feat_desc_obj, feature, FEATURE_ACTION_INCR, tx)); 372 } 373 374 /* 375 * If the specified feature has not yet been enabled, this function returns 376 * ENOTSUP; otherwise, this function decrements the feature's refcount (or 377 * returns EOVERFLOW if the refcount is already 0). This function must 378 * be called from syncing context. 379 */ 380 void 381 spa_feature_decr(spa_t *spa, zfeature_info_t *feature, dmu_tx_t *tx) 382 { 383 ASSERT3U(spa_version(spa), >=, SPA_VERSION_FEATURES); 384 VERIFY3U(0, ==, feature_do_action(spa->spa_meta_objset, 385 spa->spa_feat_for_read_obj, spa->spa_feat_for_write_obj, 386 spa->spa_feat_desc_obj, feature, FEATURE_ACTION_DECR, tx)); 387 } 388 389 boolean_t 390 spa_feature_is_enabled(spa_t *spa, zfeature_info_t *feature) 391 { 392 int err; 393 uint64_t refcount; 394 395 if (spa_version(spa) < SPA_VERSION_FEATURES) 396 return (B_FALSE); 397 398 err = feature_get_refcount(spa->spa_meta_objset, 399 spa->spa_feat_for_read_obj, spa->spa_feat_for_write_obj, 400 feature, &refcount); 401 ASSERT(err == 0 || err == ENOTSUP); 402 return (err == 0); 403 } 404 405 boolean_t 406 spa_feature_is_active(spa_t *spa, zfeature_info_t *feature) 407 { 408 int err; 409 uint64_t refcount; 410 411 if (spa_version(spa) < SPA_VERSION_FEATURES) 412 return (B_FALSE); 413 414 err = feature_get_refcount(spa->spa_meta_objset, 415 spa->spa_feat_for_read_obj, spa->spa_feat_for_write_obj, 416 feature, &refcount); 417 ASSERT(err == 0 || err == ENOTSUP); 418 return (err == 0 && refcount > 0); 419 } 420