1/*
2 * Copyright (C) 2010-2011 Red Hat, Inc.
3 *
4 * This file is released under the GPL.
5 */
6
7#ifndef DM_THIN_METADATA_H
8#define DM_THIN_METADATA_H
9
10#include "persistent-data/dm-block-manager.h"
11#include "persistent-data/dm-space-map.h"
12#include "persistent-data/dm-space-map-metadata.h"
13
14#define THIN_METADATA_BLOCK_SIZE DM_SM_METADATA_BLOCK_SIZE
15
16/*
17 * The metadata device is currently limited in size.
18 */
19#define THIN_METADATA_MAX_SECTORS DM_SM_METADATA_MAX_SECTORS
20
21/*
22 * A metadata device larger than 16GB triggers a warning.
23 */
24#define THIN_METADATA_MAX_SECTORS_WARNING (16 * (1024 * 1024 * 1024 >> SECTOR_SHIFT))
25
26/*----------------------------------------------------------------*/
27
28/*
29 * Thin metadata superblock flags.
30 */
31#define THIN_METADATA_NEEDS_CHECK_FLAG (1 << 0)
32
33struct dm_pool_metadata;
34struct dm_thin_device;
35
36/*
37 * Device identifier
38 */
39typedef uint64_t dm_thin_id;
40
41/*
42 * Reopens or creates a new, empty metadata volume.
43 */
44struct dm_pool_metadata *dm_pool_metadata_open(struct block_device *bdev,
45					       sector_t data_block_size,
46					       bool format_device);
47
48int dm_pool_metadata_close(struct dm_pool_metadata *pmd);
49
50/*
51 * Compat feature flags.  Any incompat flags beyond the ones
52 * specified below will prevent use of the thin metadata.
53 */
54#define THIN_FEATURE_COMPAT_SUPP	  0UL
55#define THIN_FEATURE_COMPAT_RO_SUPP	  0UL
56#define THIN_FEATURE_INCOMPAT_SUPP	  0UL
57
58/*
59 * Device creation/deletion.
60 */
61int dm_pool_create_thin(struct dm_pool_metadata *pmd, dm_thin_id dev);
62
63/*
64 * An internal snapshot.
65 *
66 * You can only snapshot a quiesced origin i.e. one that is either
67 * suspended or not instanced at all.
68 */
69int dm_pool_create_snap(struct dm_pool_metadata *pmd, dm_thin_id dev,
70			dm_thin_id origin);
71
72/*
73 * Deletes a virtual device from the metadata.  It _is_ safe to call this
74 * when that device is open.  Operations on that device will just start
75 * failing.  You still need to call close() on the device.
76 */
77int dm_pool_delete_thin_device(struct dm_pool_metadata *pmd,
78			       dm_thin_id dev);
79
80/*
81 * Commits _all_ metadata changes: device creation, deletion, mapping
82 * updates.
83 */
84int dm_pool_commit_metadata(struct dm_pool_metadata *pmd);
85
86/*
87 * Discards all uncommitted changes.  Rereads the superblock, rolling back
88 * to the last good transaction.  Thin devices remain open.
89 * dm_thin_aborted_changes() tells you if they had uncommitted changes.
90 *
91 * If this call fails it's only useful to call dm_pool_metadata_close().
92 * All other methods will fail with -EINVAL.
93 */
94int dm_pool_abort_metadata(struct dm_pool_metadata *pmd);
95
96/*
97 * Set/get userspace transaction id.
98 */
99int dm_pool_set_metadata_transaction_id(struct dm_pool_metadata *pmd,
100					uint64_t current_id,
101					uint64_t new_id);
102
103int dm_pool_get_metadata_transaction_id(struct dm_pool_metadata *pmd,
104					uint64_t *result);
105
106/*
107 * Hold/get root for userspace transaction.
108 *
109 * The metadata snapshot is a copy of the current superblock (minus the
110 * space maps).  Userland can access the data structures for READ
111 * operations only.  A small performance hit is incurred by providing this
112 * copy of the metadata to userland due to extra copy-on-write operations
113 * on the metadata nodes.  Release this as soon as you finish with it.
114 */
115int dm_pool_reserve_metadata_snap(struct dm_pool_metadata *pmd);
116int dm_pool_release_metadata_snap(struct dm_pool_metadata *pmd);
117
118int dm_pool_get_metadata_snap(struct dm_pool_metadata *pmd,
119			      dm_block_t *result);
120
121/*
122 * Actions on a single virtual device.
123 */
124
125/*
126 * Opening the same device more than once will fail with -EBUSY.
127 */
128int dm_pool_open_thin_device(struct dm_pool_metadata *pmd, dm_thin_id dev,
129			     struct dm_thin_device **td);
130
131int dm_pool_close_thin_device(struct dm_thin_device *td);
132
133dm_thin_id dm_thin_dev_id(struct dm_thin_device *td);
134
135struct dm_thin_lookup_result {
136	dm_block_t block;
137	bool shared:1;
138};
139
140/*
141 * Returns:
142 *   -EWOULDBLOCK iff @can_issue_io is set and would issue IO
143 *   -ENODATA iff that mapping is not present.
144 *   0 success
145 */
146int dm_thin_find_block(struct dm_thin_device *td, dm_block_t block,
147		       int can_issue_io, struct dm_thin_lookup_result *result);
148
149/*
150 * Retrieve the next run of contiguously mapped blocks.  Useful for working
151 * out where to break up IO.  Returns 0 on success, < 0 on error.
152 */
153int dm_thin_find_mapped_range(struct dm_thin_device *td,
154			      dm_block_t begin, dm_block_t end,
155			      dm_block_t *thin_begin, dm_block_t *thin_end,
156			      dm_block_t *pool_begin, bool *maybe_shared);
157
158/*
159 * Obtain an unused block.
160 */
161int dm_pool_alloc_data_block(struct dm_pool_metadata *pmd, dm_block_t *result);
162
163/*
164 * Insert or remove block.
165 */
166int dm_thin_insert_block(struct dm_thin_device *td, dm_block_t block,
167			 dm_block_t data_block);
168
169int dm_thin_remove_block(struct dm_thin_device *td, dm_block_t block);
170int dm_thin_remove_range(struct dm_thin_device *td,
171			 dm_block_t begin, dm_block_t end);
172
173/*
174 * Queries.
175 */
176bool dm_thin_changed_this_transaction(struct dm_thin_device *td);
177
178bool dm_pool_changed_this_transaction(struct dm_pool_metadata *pmd);
179
180bool dm_thin_aborted_changes(struct dm_thin_device *td);
181
182int dm_thin_get_highest_mapped_block(struct dm_thin_device *td,
183				     dm_block_t *highest_mapped);
184
185int dm_thin_get_mapped_count(struct dm_thin_device *td, dm_block_t *result);
186
187int dm_pool_get_free_block_count(struct dm_pool_metadata *pmd,
188				 dm_block_t *result);
189
190int dm_pool_get_free_metadata_block_count(struct dm_pool_metadata *pmd,
191					  dm_block_t *result);
192
193int dm_pool_get_metadata_dev_size(struct dm_pool_metadata *pmd,
194				  dm_block_t *result);
195
196int dm_pool_get_data_dev_size(struct dm_pool_metadata *pmd, dm_block_t *result);
197
198int dm_pool_block_is_shared(struct dm_pool_metadata *pmd, dm_block_t b, bool *result);
199
200int dm_pool_inc_data_range(struct dm_pool_metadata *pmd, dm_block_t b, dm_block_t e);
201int dm_pool_dec_data_range(struct dm_pool_metadata *pmd, dm_block_t b, dm_block_t e);
202
203/*
204 * Returns -ENOSPC if the new size is too small and already allocated
205 * blocks would be lost.
206 */
207int dm_pool_resize_data_dev(struct dm_pool_metadata *pmd, dm_block_t new_size);
208int dm_pool_resize_metadata_dev(struct dm_pool_metadata *pmd, dm_block_t new_size);
209
210/*
211 * Flicks the underlying block manager into read only mode, so you know
212 * that nothing is changing.
213 */
214void dm_pool_metadata_read_only(struct dm_pool_metadata *pmd);
215void dm_pool_metadata_read_write(struct dm_pool_metadata *pmd);
216
217int dm_pool_register_metadata_threshold(struct dm_pool_metadata *pmd,
218					dm_block_t threshold,
219					dm_sm_threshold_fn fn,
220					void *context);
221
222/*
223 * Updates the superblock immediately.
224 */
225int dm_pool_metadata_set_needs_check(struct dm_pool_metadata *pmd);
226bool dm_pool_metadata_needs_check(struct dm_pool_metadata *pmd);
227
228/*
229 * Issue any prefetches that may be useful.
230 */
231void dm_pool_issue_prefetches(struct dm_pool_metadata *pmd);
232
233/* Pre-commit callback */
234typedef int (*dm_pool_pre_commit_fn)(void *context);
235
236void dm_pool_register_pre_commit_callback(struct dm_pool_metadata *pmd,
237					  dm_pool_pre_commit_fn fn,
238					  void *context);
239
240/*----------------------------------------------------------------*/
241
242#endif
243