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 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 */ 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