Loading...
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 */
27struct 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 */
37int 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 */
51int 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 */
67struct 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 */
74void 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 */
94int dm_clone_metadata_pre_commit(struct dm_clone_metadata *cmd);
95int 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 */
114int dm_clone_reload_in_core_bitset(struct dm_clone_metadata *cmd);
115
116/*
117 * Check whether dm-clone's metadata changed this transaction.
118 */
119bool 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 */
125int 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 */
137void dm_clone_metadata_set_read_only(struct dm_clone_metadata *cmd);
138void 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 */
143bool dm_clone_is_hydration_done(struct dm_clone_metadata *cmd);
144
145/*
146 * Returns true if region @region_nr is hydrated.
147 */
148bool 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 */
153bool 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 */
159unsigned int dm_clone_nr_of_hydrated_regions(struct dm_clone_metadata *cmd);
160
161/*
162 * Returns the first unhydrated region with region_nr >= @start
163 */
164unsigned 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 */
170int 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 */
175int dm_clone_get_metadata_dev_size(struct dm_clone_metadata *cmd, dm_block_t *result);
176
177#endif /* DM_CLONE_METADATA_H */
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 */
27struct 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 */
37int 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 */
51int 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 */
67struct 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 */
74void 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 */
94int dm_clone_metadata_pre_commit(struct dm_clone_metadata *cmd);
95int 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 */
114int dm_clone_reload_in_core_bitset(struct dm_clone_metadata *cmd);
115
116/*
117 * Check whether dm-clone's metadata changed this transaction.
118 */
119bool 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 */
125int 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 */
137void dm_clone_metadata_set_read_only(struct dm_clone_metadata *cmd);
138void 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 */
143bool dm_clone_is_hydration_done(struct dm_clone_metadata *cmd);
144
145/*
146 * Returns true if region @region_nr is hydrated.
147 */
148bool 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 */
153bool 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 */
159unsigned int dm_clone_nr_of_hydrated_regions(struct dm_clone_metadata *cmd);
160
161/*
162 * Returns the first unhydrated region with region_nr >= @start
163 */
164unsigned 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 */
170int 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 */
175int dm_clone_get_metadata_dev_size(struct dm_clone_metadata *cmd, dm_block_t *result);
176
177#endif /* DM_CLONE_METADATA_H */