drivers/md/dm-clone-metadata.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * Copyright (C) 2019 Arrikto, Inc. All Rights Reserved.
0004  */
0005
0006 #ifndef DM_CLONE_METADATA_H
0007 #define DM_CLONE_METADATA_H
0008
0009 #include "persistent-data/dm-block-manager.h"
0010 #include "persistent-data/dm-space-map-metadata.h"
0011
0012 #define DM_CLONE_METADATA_BLOCK_SIZE DM_SM_METADATA_BLOCK_SIZE
0013
0014 /*
0015  * The metadata device is currently limited in size.
0016  */
0017 #define DM_CLONE_METADATA_MAX_SECTORS DM_SM_METADATA_MAX_SECTORS
0018
0019 /*
0020  * A metadata device larger than 16GB triggers a warning.
0021  */
0022 #define DM_CLONE_METADATA_MAX_SECTORS_WARNING (16 * (1024 * 1024 * 1024 >> SECTOR_SHIFT))
0023
0024 #define SPACE_MAP_ROOT_SIZE 128
0025
0026 /* dm-clone metadata */
0027 struct dm_clone_metadata;
0028
0029 /*
0030  * Set region status to hydrated.
0031  *
0032  * @cmd: The dm-clone metadata
0033  * @region_nr: The region number
0034  *
0035  * This function doesn't block, so it's safe to call it from interrupt context.
0036  */
0037 int dm_clone_set_region_hydrated(struct dm_clone_metadata *cmd, unsigned long region_nr);
0038
0039 /*
0040  * Set status of all regions in the provided range to hydrated, if not already
0041  * hydrated.
0042  *
0043  * @cmd: The dm-clone metadata
0044  * @start: Starting region number
0045  * @nr_regions: Number of regions in the range
0046  *
0047  * This function doesn't block, but since it uses spin_lock_irq()/spin_unlock_irq()
0048  * it's NOT safe to call it from any context where interrupts are disabled, e.g.,
0049  * from interrupt context.
0050  */
0051 int dm_clone_cond_set_range(struct dm_clone_metadata *cmd, unsigned long start,
0052                 unsigned long nr_regions);
0053
0054 /*
0055  * Read existing or create fresh metadata.
0056  *
0057  * @bdev: The device storing the metadata
0058  * @target_size: The target size
0059  * @region_size: The region size
0060  *
0061  * @returns: The dm-clone metadata
0062  *
0063  * This function reads the superblock of @bdev and checks if it's all zeroes.
0064  * If it is, it formats @bdev and creates fresh metadata. If it isn't, it
0065  * validates the metadata stored in @bdev.
0066  */
0067 struct dm_clone_metadata *dm_clone_metadata_open(struct block_device *bdev,
0068                          sector_t target_size,
0069                          sector_t region_size);
0070
0071 /*
0072  * Free the resources related to metadata management.
0073  */
0074 void dm_clone_metadata_close(struct dm_clone_metadata *cmd);
0075
0076 /*
0077  * Commit dm-clone metadata to disk.
0078  *
0079  * We use a two phase commit:
0080  *
0081  * 1. dm_clone_metadata_pre_commit(): Prepare the current transaction for
0082  *    committing. After this is called, all subsequent metadata updates, done
0083  *    through either dm_clone_set_region_hydrated() or
0084  *    dm_clone_cond_set_range(), will be part of the **next** transaction.
0085  *
0086  * 2. dm_clone_metadata_commit(): Actually commit the current transaction to
0087  *    disk and start a new transaction.
0088  *
0089  * This allows dm-clone to flush the destination device after step (1) to
0090  * ensure that all freshly hydrated regions, for which we are updating the
0091  * metadata, are properly written to non-volatile storage and won't be lost in
0092  * case of a crash.
0093  */
0094 int dm_clone_metadata_pre_commit(struct dm_clone_metadata *cmd);
0095 int dm_clone_metadata_commit(struct dm_clone_metadata *cmd);
0096
0097 /*
0098  * Reload the in core copy of the on-disk bitmap.
0099  *
0100  * This should be used after aborting a metadata transaction and setting the
0101  * metadata to read-only, to invalidate the in-core cache and make it match the
0102  * on-disk metadata.
0103  *
0104  * WARNING: It must not be called concurrently with either
0105  * dm_clone_set_region_hydrated() or dm_clone_cond_set_range(), as it updates
0106  * the region bitmap without taking the relevant spinlock. We don't take the
0107  * spinlock because dm_clone_reload_in_core_bitset() does I/O, so it may block.
0108  *
0109  * But, it's safe to use it after calling dm_clone_metadata_set_read_only(),
0110  * because the latter sets the metadata to read-only mode. Both
0111  * dm_clone_set_region_hydrated() and dm_clone_cond_set_range() refuse to touch
0112  * the region bitmap, after calling dm_clone_metadata_set_read_only().
0113  */
0114 int dm_clone_reload_in_core_bitset(struct dm_clone_metadata *cmd);
0115
0116 /*
0117  * Check whether dm-clone's metadata changed this transaction.
0118  */
0119 bool dm_clone_changed_this_transaction(struct dm_clone_metadata *cmd);
0120
0121 /*
0122  * Abort current metadata transaction and rollback metadata to the last
0123  * committed transaction.
0124  */
0125 int dm_clone_metadata_abort(struct dm_clone_metadata *cmd);
0126
0127 /*
0128  * Switches metadata to a read only mode. Once read-only mode has been entered
0129  * the following functions will return -EPERM:
0130  *
0131  *   dm_clone_metadata_pre_commit()
0132  *   dm_clone_metadata_commit()
0133  *   dm_clone_set_region_hydrated()
0134  *   dm_clone_cond_set_range()
0135  *   dm_clone_metadata_abort()
0136  */
0137 void dm_clone_metadata_set_read_only(struct dm_clone_metadata *cmd);
0138 void dm_clone_metadata_set_read_write(struct dm_clone_metadata *cmd);
0139
0140 /*
0141  * Returns true if the hydration of the destination device is finished.
0142  */
0143 bool dm_clone_is_hydration_done(struct dm_clone_metadata *cmd);
0144
0145 /*
0146  * Returns true if region @region_nr is hydrated.
0147  */
0148 bool dm_clone_is_region_hydrated(struct dm_clone_metadata *cmd, unsigned long region_nr);
0149
0150 /*
0151  * Returns true if all the regions in the range are hydrated.
0152  */
0153 bool dm_clone_is_range_hydrated(struct dm_clone_metadata *cmd,
0154                 unsigned long start, unsigned long nr_regions);
0155
0156 /*
0157  * Returns the number of hydrated regions.
0158  */
0159 unsigned int dm_clone_nr_of_hydrated_regions(struct dm_clone_metadata *cmd);
0160
0161 /*
0162  * Returns the first unhydrated region with region_nr >= @start
0163  */
0164 unsigned long dm_clone_find_next_unhydrated_region(struct dm_clone_metadata *cmd,
0165                            unsigned long start);
0166
0167 /*
0168  * Get the number of free metadata blocks.
0169  */
0170 int dm_clone_get_free_metadata_block_count(struct dm_clone_metadata *cmd, dm_block_t *result);
0171
0172 /*
0173  * Get the total number of metadata blocks.
0174  */
0175 int dm_clone_get_metadata_dev_size(struct dm_clone_metadata *cmd, dm_block_t *result);
0176
0177 #endif /* DM_CLONE_METADATA_H */