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