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, so it's safe to call it from interrupt context.
 48 */
 49int 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 */
 65struct 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 */
 72void dm_clone_metadata_close(struct dm_clone_metadata *cmd);
 73
 74/*
 75 * Commit dm-clone metadata to disk.
 76 */
 77int dm_clone_metadata_commit(struct dm_clone_metadata *cmd);
 78
 79/*
 80 * Reload the in core copy of the on-disk bitmap.
 81 *
 82 * This should be used after aborting a metadata transaction and setting the
 83 * metadata to read-only, to invalidate the in-core cache and make it match the
 84 * on-disk metadata.
 85 *
 86 * WARNING: It must not be called concurrently with either
 87 * dm_clone_set_region_hydrated() or dm_clone_cond_set_range(), as it updates
 88 * the region bitmap without taking the relevant spinlock. We don't take the
 89 * spinlock because dm_clone_reload_in_core_bitset() does I/O, so it may block.
 90 *
 91 * But, it's safe to use it after calling dm_clone_metadata_set_read_only(),
 92 * because the latter sets the metadata to read-only mode. Both
 93 * dm_clone_set_region_hydrated() and dm_clone_cond_set_range() refuse to touch
 94 * the region bitmap, after calling dm_clone_metadata_set_read_only().
 95 */
 96int dm_clone_reload_in_core_bitset(struct dm_clone_metadata *cmd);
 97
 98/*
 99 * Check whether dm-clone's metadata changed this transaction.
100 */
101bool dm_clone_changed_this_transaction(struct dm_clone_metadata *cmd);
102
103/*
104 * Abort current metadata transaction and rollback metadata to the last
105 * committed transaction.
106 */
107int dm_clone_metadata_abort(struct dm_clone_metadata *cmd);
108
109/*
110 * Switches metadata to a read only mode. Once read-only mode has been entered
111 * the following functions will return -EPERM:
112 *
113 *   dm_clone_metadata_commit()
114 *   dm_clone_set_region_hydrated()
115 *   dm_clone_cond_set_range()
116 *   dm_clone_metadata_abort()
117 */
118void dm_clone_metadata_set_read_only(struct dm_clone_metadata *cmd);
119void dm_clone_metadata_set_read_write(struct dm_clone_metadata *cmd);
120
121/*
122 * Returns true if the hydration of the destination device is finished.
123 */
124bool dm_clone_is_hydration_done(struct dm_clone_metadata *cmd);
125
126/*
127 * Returns true if region @region_nr is hydrated.
128 */
129bool dm_clone_is_region_hydrated(struct dm_clone_metadata *cmd, unsigned long region_nr);
130
131/*
132 * Returns true if all the regions in the range are hydrated.
133 */
134bool dm_clone_is_range_hydrated(struct dm_clone_metadata *cmd,
135				unsigned long start, unsigned long nr_regions);
136
137/*
138 * Returns the number of hydrated regions.
139 */
140unsigned long dm_clone_nr_of_hydrated_regions(struct dm_clone_metadata *cmd);
141
142/*
143 * Returns the first unhydrated region with region_nr >= @start
144 */
145unsigned long dm_clone_find_next_unhydrated_region(struct dm_clone_metadata *cmd,
146						   unsigned long start);
147
148/*
149 * Get the number of free metadata blocks.
150 */
151int dm_clone_get_free_metadata_block_count(struct dm_clone_metadata *cmd, dm_block_t *result);
152
153/*
154 * Get the total number of metadata blocks.
155 */
156int dm_clone_get_metadata_dev_size(struct dm_clone_metadata *cmd, dm_block_t *result);
157
158#endif /* DM_CLONE_METADATA_H */