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