dm-clone-metadata.h 5.6 KB

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