1*4882a593Smuzhiyun /* 2*4882a593Smuzhiyun * Copyright (C) 2011 Red Hat, Inc. 3*4882a593Smuzhiyun * 4*4882a593Smuzhiyun * This file is released under the GPL. 5*4882a593Smuzhiyun */ 6*4882a593Smuzhiyun 7*4882a593Smuzhiyun #ifndef _LINUX_DM_TRANSACTION_MANAGER_H 8*4882a593Smuzhiyun #define _LINUX_DM_TRANSACTION_MANAGER_H 9*4882a593Smuzhiyun 10*4882a593Smuzhiyun #include "dm-block-manager.h" 11*4882a593Smuzhiyun 12*4882a593Smuzhiyun struct dm_transaction_manager; 13*4882a593Smuzhiyun struct dm_space_map; 14*4882a593Smuzhiyun 15*4882a593Smuzhiyun /*----------------------------------------------------------------*/ 16*4882a593Smuzhiyun 17*4882a593Smuzhiyun /* 18*4882a593Smuzhiyun * This manages the scope of a transaction. It also enforces immutability 19*4882a593Smuzhiyun * of the on-disk data structures by limiting access to writeable blocks. 20*4882a593Smuzhiyun * 21*4882a593Smuzhiyun * Clients should not fiddle with the block manager directly. 22*4882a593Smuzhiyun */ 23*4882a593Smuzhiyun 24*4882a593Smuzhiyun void dm_tm_destroy(struct dm_transaction_manager *tm); 25*4882a593Smuzhiyun 26*4882a593Smuzhiyun /* 27*4882a593Smuzhiyun * The non-blocking version of a transaction manager is intended for use in 28*4882a593Smuzhiyun * fast path code that needs to do lookups e.g. a dm mapping function. 29*4882a593Smuzhiyun * You create the non-blocking variant from a normal tm. The interface is 30*4882a593Smuzhiyun * the same, except that most functions will just return -EWOULDBLOCK. 31*4882a593Smuzhiyun * Methods that return void yet may block should not be called on a clone 32*4882a593Smuzhiyun * viz. dm_tm_inc, dm_tm_dec. Call dm_tm_destroy() as you would with a normal 33*4882a593Smuzhiyun * tm when you've finished with it. You may not destroy the original prior 34*4882a593Smuzhiyun * to clones. 35*4882a593Smuzhiyun */ 36*4882a593Smuzhiyun struct dm_transaction_manager *dm_tm_create_non_blocking_clone(struct dm_transaction_manager *real); 37*4882a593Smuzhiyun 38*4882a593Smuzhiyun /* 39*4882a593Smuzhiyun * We use a 2-phase commit here. 40*4882a593Smuzhiyun * 41*4882a593Smuzhiyun * i) Make all changes for the transaction *except* for the superblock. 42*4882a593Smuzhiyun * Then call dm_tm_pre_commit() to flush them to disk. 43*4882a593Smuzhiyun * 44*4882a593Smuzhiyun * ii) Lock your superblock. Update. Then call dm_tm_commit() which will 45*4882a593Smuzhiyun * unlock the superblock and flush it. No other blocks should be updated 46*4882a593Smuzhiyun * during this period. Care should be taken to never unlock a partially 47*4882a593Smuzhiyun * updated superblock; perform any operations that could fail *before* you 48*4882a593Smuzhiyun * take the superblock lock. 49*4882a593Smuzhiyun */ 50*4882a593Smuzhiyun int dm_tm_pre_commit(struct dm_transaction_manager *tm); 51*4882a593Smuzhiyun int dm_tm_commit(struct dm_transaction_manager *tm, struct dm_block *superblock); 52*4882a593Smuzhiyun 53*4882a593Smuzhiyun /* 54*4882a593Smuzhiyun * These methods are the only way to get hold of a writeable block. 55*4882a593Smuzhiyun */ 56*4882a593Smuzhiyun 57*4882a593Smuzhiyun /* 58*4882a593Smuzhiyun * dm_tm_new_block() is pretty self-explanatory. Make sure you do actually 59*4882a593Smuzhiyun * write to the whole of @data before you unlock, otherwise you could get 60*4882a593Smuzhiyun * a data leak. (The other option is for tm_new_block() to zero new blocks 61*4882a593Smuzhiyun * before handing them out, which will be redundant in most, if not all, 62*4882a593Smuzhiyun * cases). 63*4882a593Smuzhiyun * Zeroes the new block and returns with write lock held. 64*4882a593Smuzhiyun */ 65*4882a593Smuzhiyun int dm_tm_new_block(struct dm_transaction_manager *tm, 66*4882a593Smuzhiyun struct dm_block_validator *v, 67*4882a593Smuzhiyun struct dm_block **result); 68*4882a593Smuzhiyun 69*4882a593Smuzhiyun /* 70*4882a593Smuzhiyun * dm_tm_shadow_block() allocates a new block and copies the data from @orig 71*4882a593Smuzhiyun * to it. It then decrements the reference count on original block. Use 72*4882a593Smuzhiyun * this to update the contents of a block in a data structure, don't 73*4882a593Smuzhiyun * confuse this with a clone - you shouldn't access the orig block after 74*4882a593Smuzhiyun * this operation. Because the tm knows the scope of the transaction it 75*4882a593Smuzhiyun * can optimise requests for a shadow of a shadow to a no-op. Don't forget 76*4882a593Smuzhiyun * to unlock when you've finished with the shadow. 77*4882a593Smuzhiyun * 78*4882a593Smuzhiyun * The @inc_children flag is used to tell the caller whether it needs to 79*4882a593Smuzhiyun * adjust reference counts for children. (Data in the block may refer to 80*4882a593Smuzhiyun * other blocks.) 81*4882a593Smuzhiyun * 82*4882a593Smuzhiyun * Shadowing implicitly drops a reference on @orig so you must not have 83*4882a593Smuzhiyun * it locked when you call this. 84*4882a593Smuzhiyun */ 85*4882a593Smuzhiyun int dm_tm_shadow_block(struct dm_transaction_manager *tm, dm_block_t orig, 86*4882a593Smuzhiyun struct dm_block_validator *v, 87*4882a593Smuzhiyun struct dm_block **result, int *inc_children); 88*4882a593Smuzhiyun 89*4882a593Smuzhiyun /* 90*4882a593Smuzhiyun * Read access. You can lock any block you want. If there's a write lock 91*4882a593Smuzhiyun * on it outstanding then it'll block. 92*4882a593Smuzhiyun */ 93*4882a593Smuzhiyun int dm_tm_read_lock(struct dm_transaction_manager *tm, dm_block_t b, 94*4882a593Smuzhiyun struct dm_block_validator *v, 95*4882a593Smuzhiyun struct dm_block **result); 96*4882a593Smuzhiyun 97*4882a593Smuzhiyun void dm_tm_unlock(struct dm_transaction_manager *tm, struct dm_block *b); 98*4882a593Smuzhiyun 99*4882a593Smuzhiyun /* 100*4882a593Smuzhiyun * Functions for altering the reference count of a block directly. 101*4882a593Smuzhiyun */ 102*4882a593Smuzhiyun void dm_tm_inc(struct dm_transaction_manager *tm, dm_block_t b); 103*4882a593Smuzhiyun 104*4882a593Smuzhiyun void dm_tm_dec(struct dm_transaction_manager *tm, dm_block_t b); 105*4882a593Smuzhiyun 106*4882a593Smuzhiyun int dm_tm_ref(struct dm_transaction_manager *tm, dm_block_t b, 107*4882a593Smuzhiyun uint32_t *result); 108*4882a593Smuzhiyun 109*4882a593Smuzhiyun struct dm_block_manager *dm_tm_get_bm(struct dm_transaction_manager *tm); 110*4882a593Smuzhiyun 111*4882a593Smuzhiyun /* 112*4882a593Smuzhiyun * If you're using a non-blocking clone the tm will build up a list of 113*4882a593Smuzhiyun * requested blocks that weren't in core. This call will request those 114*4882a593Smuzhiyun * blocks to be prefetched. 115*4882a593Smuzhiyun */ 116*4882a593Smuzhiyun void dm_tm_issue_prefetches(struct dm_transaction_manager *tm); 117*4882a593Smuzhiyun 118*4882a593Smuzhiyun /* 119*4882a593Smuzhiyun * A little utility that ties the knot by producing a transaction manager 120*4882a593Smuzhiyun * that has a space map managed by the transaction manager... 121*4882a593Smuzhiyun * 122*4882a593Smuzhiyun * Returns a tm that has an open transaction to write the new disk sm. 123*4882a593Smuzhiyun * Caller should store the new sm root and commit. 124*4882a593Smuzhiyun * 125*4882a593Smuzhiyun * The superblock location is passed so the metadata space map knows it 126*4882a593Smuzhiyun * shouldn't be used. 127*4882a593Smuzhiyun */ 128*4882a593Smuzhiyun int dm_tm_create_with_sm(struct dm_block_manager *bm, dm_block_t sb_location, 129*4882a593Smuzhiyun struct dm_transaction_manager **tm, 130*4882a593Smuzhiyun struct dm_space_map **sm); 131*4882a593Smuzhiyun 132*4882a593Smuzhiyun int dm_tm_open_with_sm(struct dm_block_manager *bm, dm_block_t sb_location, 133*4882a593Smuzhiyun void *sm_root, size_t root_len, 134*4882a593Smuzhiyun struct dm_transaction_manager **tm, 135*4882a593Smuzhiyun struct dm_space_map **sm); 136*4882a593Smuzhiyun 137*4882a593Smuzhiyun #endif /* _LINUX_DM_TRANSACTION_MANAGER_H */ 138