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, so it's safe to call it from interrupt context. 48 */ 49 int dm_clone_cond_set_range(struct dm_clone_metadata *cmd, unsigned long start, 50 unsigned long nr_regions); 51 52 /* 53 * Read existing or create fresh metadata. 54 * 55 * @bdev: The device storing the metadata 56 * @target_size: The target size 57 * @region_size: The region size 58 * 59 * @returns: The dm-clone metadata 60 * 61 * This function reads the superblock of @bdev and checks if it's all zeroes. 62 * If it is, it formats @bdev and creates fresh metadata. If it isn't, it 63 * validates the metadata stored in @bdev. 64 */ 65 struct dm_clone_metadata *dm_clone_metadata_open(struct block_device *bdev, 66 sector_t target_size, 67 sector_t region_size); 68 69 /* 70 * Free the resources related to metadata management. 71 */ 72 void dm_clone_metadata_close(struct dm_clone_metadata *cmd); 73 74 /* 75 * Commit dm-clone metadata to disk. 76 * 77 * We use a two phase commit: 78 * 79 * 1. dm_clone_metadata_pre_commit(): Prepare the current transaction for 80 * committing. After this is called, all subsequent metadata updates, done 81 * through either dm_clone_set_region_hydrated() or 82 * dm_clone_cond_set_range(), will be part of the **next** transaction. 83 * 84 * 2. dm_clone_metadata_commit(): Actually commit the current transaction to 85 * disk and start a new transaction. 86 * 87 * This allows dm-clone to flush the destination device after step (1) to 88 * ensure that all freshly hydrated regions, for which we are updating the 89 * metadata, are properly written to non-volatile storage and won't be lost in 90 * case of a crash. 91 */ 92 int dm_clone_metadata_pre_commit(struct dm_clone_metadata *cmd); 93 int dm_clone_metadata_commit(struct dm_clone_metadata *cmd); 94 95 /* 96 * Reload the in core copy of the on-disk bitmap. 97 * 98 * This should be used after aborting a metadata transaction and setting the 99 * metadata to read-only, to invalidate the in-core cache and make it match the 100 * on-disk metadata. 101 * 102 * WARNING: It must not be called concurrently with either 103 * dm_clone_set_region_hydrated() or dm_clone_cond_set_range(), as it updates 104 * the region bitmap without taking the relevant spinlock. We don't take the 105 * spinlock because dm_clone_reload_in_core_bitset() does I/O, so it may block. 106 * 107 * But, it's safe to use it after calling dm_clone_metadata_set_read_only(), 108 * because the latter sets the metadata to read-only mode. Both 109 * dm_clone_set_region_hydrated() and dm_clone_cond_set_range() refuse to touch 110 * the region bitmap, after calling dm_clone_metadata_set_read_only(). 111 */ 112 int dm_clone_reload_in_core_bitset(struct dm_clone_metadata *cmd); 113 114 /* 115 * Check whether dm-clone's metadata changed this transaction. 116 */ 117 bool dm_clone_changed_this_transaction(struct dm_clone_metadata *cmd); 118 119 /* 120 * Abort current metadata transaction and rollback metadata to the last 121 * committed transaction. 122 */ 123 int dm_clone_metadata_abort(struct dm_clone_metadata *cmd); 124 125 /* 126 * Switches metadata to a read only mode. Once read-only mode has been entered 127 * the following functions will return -EPERM: 128 * 129 * dm_clone_metadata_pre_commit() 130 * dm_clone_metadata_commit() 131 * dm_clone_set_region_hydrated() 132 * dm_clone_cond_set_range() 133 * dm_clone_metadata_abort() 134 */ 135 void dm_clone_metadata_set_read_only(struct dm_clone_metadata *cmd); 136 void dm_clone_metadata_set_read_write(struct dm_clone_metadata *cmd); 137 138 /* 139 * Returns true if the hydration of the destination device is finished. 140 */ 141 bool dm_clone_is_hydration_done(struct dm_clone_metadata *cmd); 142 143 /* 144 * Returns true if region @region_nr is hydrated. 145 */ 146 bool dm_clone_is_region_hydrated(struct dm_clone_metadata *cmd, unsigned long region_nr); 147 148 /* 149 * Returns true if all the regions in the range are hydrated. 150 */ 151 bool dm_clone_is_range_hydrated(struct dm_clone_metadata *cmd, 152 unsigned long start, unsigned long nr_regions); 153 154 /* 155 * Returns the number of hydrated regions. 156 */ 157 unsigned long dm_clone_nr_of_hydrated_regions(struct dm_clone_metadata *cmd); 158 159 /* 160 * Returns the first unhydrated region with region_nr >= @start 161 */ 162 unsigned long dm_clone_find_next_unhydrated_region(struct dm_clone_metadata *cmd, 163 unsigned long start); 164 165 /* 166 * Get the number of free metadata blocks. 167 */ 168 int dm_clone_get_free_metadata_block_count(struct dm_clone_metadata *cmd, dm_block_t *result); 169 170 /* 171 * Get the total number of metadata blocks. 172 */ 173 int dm_clone_get_metadata_dev_size(struct dm_clone_metadata *cmd, dm_block_t *result); 174 175 #endif /* DM_CLONE_METADATA_H */ 176