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
34struct dm_pool_metadata;
35struct dm_thin_device;
36
37/*
38 * Device identifier
39 */
40typedef uint64_t dm_thin_id;
41
42/*
43 * Reopens or creates a new, empty metadata volume.
44 */
45struct dm_pool_metadata *dm_pool_metadata_open(struct block_device *bdev,
46 sector_t data_block_size,
47 bool format_device);
48
49int 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 */
62int 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 */
70int 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 */
78int 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 */
85int 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 */
95int dm_pool_abort_metadata(struct dm_pool_metadata *pmd);
96
97/*
98 * Set/get userspace transaction id.
99 */
100int dm_pool_set_metadata_transaction_id(struct dm_pool_metadata *pmd,
101 uint64_t current_id,
102 uint64_t new_id);
103
104int 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 */
116int dm_pool_reserve_metadata_snap(struct dm_pool_metadata *pmd);
117int dm_pool_release_metadata_snap(struct dm_pool_metadata *pmd);
118
119int 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 */
129int dm_pool_open_thin_device(struct dm_pool_metadata *pmd, dm_thin_id dev,
130 struct dm_thin_device **td);
131
132int dm_pool_close_thin_device(struct dm_thin_device *td);
133
134dm_thin_id dm_thin_dev_id(struct dm_thin_device *td);
135
136struct 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 */
147int 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 */
154int 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 */
162int dm_pool_alloc_data_block(struct dm_pool_metadata *pmd, dm_block_t *result);
163
164/*
165 * Insert or remove block.
166 */
167int dm_thin_insert_block(struct dm_thin_device *td, dm_block_t block,
168 dm_block_t data_block);
169
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

source code of linux/drivers/md/dm-thin-metadata.h