155 lines · c
1/* SPDX-License-Identifier: GPL-2.0-only */2/*3 * Copyright (C) 2011 Red Hat, Inc.4 *5 * This file is released under the GPL.6 */7 8#ifndef _LINUX_DM_TRANSACTION_MANAGER_H9#define _LINUX_DM_TRANSACTION_MANAGER_H10 11#include "dm-block-manager.h"12 13struct dm_transaction_manager;14struct dm_space_map;15 16/*----------------------------------------------------------------*/17 18/*19 * This manages the scope of a transaction. It also enforces immutability20 * of the on-disk data structures by limiting access to writeable blocks.21 *22 * Clients should not fiddle with the block manager directly.23 */24 25void dm_tm_destroy(struct dm_transaction_manager *tm);26 27/*28 * The non-blocking version of a transaction manager is intended for use in29 * fast path code that needs to do lookups e.g. a dm mapping function.30 * You create the non-blocking variant from a normal tm. The interface is31 * the same, except that most functions will just return -EWOULDBLOCK.32 * Methods that return void yet may block should not be called on a clone33 * viz. dm_tm_inc, dm_tm_dec. Call dm_tm_destroy() as you would with a normal34 * tm when you've finished with it. You may not destroy the original prior35 * to clones.36 */37struct dm_transaction_manager *dm_tm_create_non_blocking_clone(struct dm_transaction_manager *real);38 39/*40 * We use a 2-phase commit here.41 *42 * i) Make all changes for the transaction *except* for the superblock.43 * Then call dm_tm_pre_commit() to flush them to disk.44 *45 * ii) Lock your superblock. Update. Then call dm_tm_commit() which will46 * unlock the superblock and flush it. No other blocks should be updated47 * during this period. Care should be taken to never unlock a partially48 * updated superblock; perform any operations that could fail *before* you49 * take the superblock lock.50 */51int dm_tm_pre_commit(struct dm_transaction_manager *tm);52int dm_tm_commit(struct dm_transaction_manager *tm, struct dm_block *superblock);53 54/*55 * These methods are the only way to get hold of a writeable block.56 */57 58/*59 * dm_tm_new_block() is pretty self-explanatory. Make sure you do actually60 * write to the whole of @data before you unlock, otherwise you could get61 * a data leak. (The other option is for tm_new_block() to zero new blocks62 * before handing them out, which will be redundant in most, if not all,63 * cases).64 * Zeroes the new block and returns with write lock held.65 */66int dm_tm_new_block(struct dm_transaction_manager *tm,67 const struct dm_block_validator *v,68 struct dm_block **result);69 70/*71 * dm_tm_shadow_block() allocates a new block and copies the data from @orig72 * to it. It then decrements the reference count on original block. Use73 * this to update the contents of a block in a data structure, don't74 * confuse this with a clone - you shouldn't access the orig block after75 * this operation. Because the tm knows the scope of the transaction it76 * can optimise requests for a shadow of a shadow to a no-op. Don't forget77 * to unlock when you've finished with the shadow.78 *79 * The @inc_children flag is used to tell the caller whether it needs to80 * adjust reference counts for children. (Data in the block may refer to81 * other blocks.)82 *83 * Shadowing implicitly drops a reference on @orig so you must not have84 * it locked when you call this.85 */86int dm_tm_shadow_block(struct dm_transaction_manager *tm, dm_block_t orig,87 const struct dm_block_validator *v,88 struct dm_block **result, int *inc_children);89 90/*91 * Read access. You can lock any block you want. If there's a write lock92 * on it outstanding then it'll block.93 */94int dm_tm_read_lock(struct dm_transaction_manager *tm, dm_block_t b,95 const struct dm_block_validator *v,96 struct dm_block **result);97 98void dm_tm_unlock(struct dm_transaction_manager *tm, struct dm_block *b);99 100/*101 * Functions for altering the reference count of a block directly.102 */103void dm_tm_inc(struct dm_transaction_manager *tm, dm_block_t b);104void dm_tm_inc_range(struct dm_transaction_manager *tm, dm_block_t b, dm_block_t e);105void dm_tm_dec(struct dm_transaction_manager *tm, dm_block_t b);106void dm_tm_dec_range(struct dm_transaction_manager *tm, dm_block_t b, dm_block_t e);107 108/*109 * Builds up runs of adjacent blocks, and then calls the given fn110 * (typically dm_tm_inc/dec). Very useful when you have to perform111 * the same tm operation on all values in a btree leaf.112 */113typedef void (*dm_tm_run_fn)(struct dm_transaction_manager *, dm_block_t, dm_block_t);114void dm_tm_with_runs(struct dm_transaction_manager *tm,115 const __le64 *value_le, unsigned int count, dm_tm_run_fn fn);116 117int dm_tm_ref(struct dm_transaction_manager *tm, dm_block_t b, uint32_t *result);118 119/*120 * Finds out if a given block is shared (ie. has a reference count higher121 * than one).122 */123int dm_tm_block_is_shared(struct dm_transaction_manager *tm, dm_block_t b,124 int *result);125 126struct dm_block_manager *dm_tm_get_bm(struct dm_transaction_manager *tm);127 128/*129 * If you're using a non-blocking clone the tm will build up a list of130 * requested blocks that weren't in core. This call will request those131 * blocks to be prefetched.132 */133void dm_tm_issue_prefetches(struct dm_transaction_manager *tm);134 135/*136 * A little utility that ties the knot by producing a transaction manager137 * that has a space map managed by the transaction manager...138 *139 * Returns a tm that has an open transaction to write the new disk sm.140 * Caller should store the new sm root and commit.141 *142 * The superblock location is passed so the metadata space map knows it143 * shouldn't be used.144 */145int dm_tm_create_with_sm(struct dm_block_manager *bm, dm_block_t sb_location,146 struct dm_transaction_manager **tm,147 struct dm_space_map **sm);148 149int dm_tm_open_with_sm(struct dm_block_manager *bm, dm_block_t sb_location,150 void *sm_root, size_t root_len,151 struct dm_transaction_manager **tm,152 struct dm_space_map **sm);153 154#endif /* _LINUX_DM_TRANSACTION_MANAGER_H */155