1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3  * Copyright (C) 2019 Arrikto, Inc. All Rights Reserved.
4  */
5 
6 #ifndef DM_CLONE_METADATA_H
7 #define DM_CLONE_METADATA_H
8 
9 #include "persistent-data/dm-block-manager.h"
10 #include "persistent-data/dm-space-map-metadata.h"
11 
12 #define DM_CLONE_METADATA_BLOCK_SIZE DM_SM_METADATA_BLOCK_SIZE
13 
14 /*
15  * The metadata device is currently limited in size.
16  */
17 #define DM_CLONE_METADATA_MAX_SECTORS DM_SM_METADATA_MAX_SECTORS
18 
19 /*
20  * A metadata device larger than 16GB triggers a warning.
21  */
22 #define DM_CLONE_METADATA_MAX_SECTORS_WARNING (16 * (1024 * 1024 * 1024 >> SECTOR_SHIFT))
23 
24 #define SPACE_MAP_ROOT_SIZE 128
25 
26 /* dm-clone metadata */
27 struct dm_clone_metadata;
28 
29 /*
30  * Set region status to hydrated.
31  *
32  * @cmd: The dm-clone metadata
33  * @region_nr: The region number
34  *
35  * This function doesn't block, so it's safe to call it from interrupt context.
36  */
37 int dm_clone_set_region_hydrated(struct dm_clone_metadata *cmd, unsigned long region_nr);
38 
39 /*
40  * Set status of all regions in the provided range to hydrated, if not already
41  * hydrated.
42  *
43  * @cmd: The dm-clone metadata
44  * @start: Starting region number
45  * @nr_regions: Number of regions in the range
46  *
47  * This function doesn't block, but since it uses spin_lock_irq()/spin_unlock_irq()
48  * it's NOT safe to call it from any context where interrupts are disabled, e.g.,
49  * from interrupt context.
50  */
51 int dm_clone_cond_set_range(struct dm_clone_metadata *cmd, unsigned long start,
52 			    unsigned long nr_regions);
53 
54 /*
55  * Read existing or create fresh metadata.
56  *
57  * @bdev: The device storing the metadata
58  * @target_size: The target size
59  * @region_size: The region size
60  *
61  * @returns: The dm-clone metadata
62  *
63  * This function reads the superblock of @bdev and checks if it's all zeroes.
64  * If it is, it formats @bdev and creates fresh metadata. If it isn't, it
65  * validates the metadata stored in @bdev.
66  */
67 struct dm_clone_metadata *dm_clone_metadata_open(struct block_device *bdev,
68 						 sector_t target_size,
69 						 sector_t region_size);
70 
71 /*
72  * Free the resources related to metadata management.
73  */
74 void dm_clone_metadata_close(struct dm_clone_metadata *cmd);
75 
76 /*
77  * Commit dm-clone metadata to disk.
78  *
79  * We use a two phase commit:
80  *
81  * 1. dm_clone_metadata_pre_commit(): Prepare the current transaction for
82  *    committing. After this is called, all subsequent metadata updates, done
83  *    through either dm_clone_set_region_hydrated() or
84  *    dm_clone_cond_set_range(), will be part of the **next** transaction.
85  *
86  * 2. dm_clone_metadata_commit(): Actually commit the current transaction to
87  *    disk and start a new transaction.
88  *
89  * This allows dm-clone to flush the destination device after step (1) to
90  * ensure that all freshly hydrated regions, for which we are updating the
91  * metadata, are properly written to non-volatile storage and won't be lost in
92  * case of a crash.
93  */
94 int dm_clone_metadata_pre_commit(struct dm_clone_metadata *cmd);
95 int dm_clone_metadata_commit(struct dm_clone_metadata *cmd);
96 
97 /*
98  * Reload the in core copy of the on-disk bitmap.
99  *
100  * This should be used after aborting a metadata transaction and setting the
101  * metadata to read-only, to invalidate the in-core cache and make it match the
102  * on-disk metadata.
103  *
104  * WARNING: It must not be called concurrently with either
105  * dm_clone_set_region_hydrated() or dm_clone_cond_set_range(), as it updates
106  * the region bitmap without taking the relevant spinlock. We don't take the
107  * spinlock because dm_clone_reload_in_core_bitset() does I/O, so it may block.
108  *
109  * But, it's safe to use it after calling dm_clone_metadata_set_read_only(),
110  * because the latter sets the metadata to read-only mode. Both
111  * dm_clone_set_region_hydrated() and dm_clone_cond_set_range() refuse to touch
112  * the region bitmap, after calling dm_clone_metadata_set_read_only().
113  */
114 int dm_clone_reload_in_core_bitset(struct dm_clone_metadata *cmd);
115 
116 /*
117  * Check whether dm-clone's metadata changed this transaction.
118  */
119 bool dm_clone_changed_this_transaction(struct dm_clone_metadata *cmd);
120 
121 /*
122  * Abort current metadata transaction and rollback metadata to the last
123  * committed transaction.
124  */
125 int dm_clone_metadata_abort(struct dm_clone_metadata *cmd);
126 
127 /*
128  * Switches metadata to a read only mode. Once read-only mode has been entered
129  * the following functions will return -EPERM:
130  *
131  *   dm_clone_metadata_pre_commit()
132  *   dm_clone_metadata_commit()
133  *   dm_clone_set_region_hydrated()
134  *   dm_clone_cond_set_range()
135  *   dm_clone_metadata_abort()
136  */
137 void dm_clone_metadata_set_read_only(struct dm_clone_metadata *cmd);
138 void dm_clone_metadata_set_read_write(struct dm_clone_metadata *cmd);
139 
140 /*
141  * Returns true if the hydration of the destination device is finished.
142  */
143 bool dm_clone_is_hydration_done(struct dm_clone_metadata *cmd);
144 
145 /*
146  * Returns true if region @region_nr is hydrated.
147  */
148 bool dm_clone_is_region_hydrated(struct dm_clone_metadata *cmd, unsigned long region_nr);
149 
150 /*
151  * Returns true if all the regions in the range are hydrated.
152  */
153 bool dm_clone_is_range_hydrated(struct dm_clone_metadata *cmd,
154 				unsigned long start, unsigned long nr_regions);
155 
156 /*
157  * Returns the number of hydrated regions.
158  */
159 unsigned long dm_clone_nr_of_hydrated_regions(struct dm_clone_metadata *cmd);
160 
161 /*
162  * Returns the first unhydrated region with region_nr >= @start
163  */
164 unsigned long dm_clone_find_next_unhydrated_region(struct dm_clone_metadata *cmd,
165 						   unsigned long start);
166 
167 /*
168  * Get the number of free metadata blocks.
169  */
170 int dm_clone_get_free_metadata_block_count(struct dm_clone_metadata *cmd, dm_block_t *result);
171 
172 /*
173  * Get the total number of metadata blocks.
174  */
175 int dm_clone_get_metadata_dev_size(struct dm_clone_metadata *cmd, dm_block_t *result);
176 
177 #endif /* DM_CLONE_METADATA_H */
178