LXR linux/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 */
  27struct 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 */
  37int 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 */
  51int 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 */
  67struct 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 */
  74void 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 */
  94int dm_clone_metadata_pre_commit(struct dm_clone_metadata *cmd);
  95int 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 */
 114int dm_clone_reload_in_core_bitset(struct dm_clone_metadata *cmd);
 115
 116/*
 117 * Check whether dm-clone's metadata changed this transaction.
 118 */
 119bool 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 */
 125int 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 */
 137void dm_clone_metadata_set_read_only(struct dm_clone_metadata *cmd);
 138void 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 */
 143bool dm_clone_is_hydration_done(struct dm_clone_metadata *cmd);
 144
 145/*
 146 * Returns true if region @region_nr is hydrated.
 147 */
 148bool 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 */
 153bool 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 */
 159unsigned 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 */
 164unsigned 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 */
 170int 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 */
 175int dm_clone_get_metadata_dev_size(struct dm_clone_metadata *cmd, dm_block_t *result);
 176
 177#endif /* DM_CLONE_METADATA_H */
 178