xref: /illumos-gate/usr/src/uts/common/fs/zfs/zfeature.c (revision 53089ab7c84db6fb76c16ca50076c147cda11757)
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 }
415