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