13241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber/* 23241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * Copyright (C) 2011 Red Hat, Inc. 33241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * 43241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * This file is released under the GPL. 53241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber */ 63241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 73241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber#ifndef _LINUX_DM_TRANSACTION_MANAGER_H 83241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber#define _LINUX_DM_TRANSACTION_MANAGER_H 93241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 103241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber#include "dm-block-manager.h" 113241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 123241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberstruct dm_transaction_manager; 133241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberstruct dm_space_map; 143241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 153241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber/*----------------------------------------------------------------*/ 163241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 173241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber/* 183241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * This manages the scope of a transaction. It also enforces immutability 193241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * of the on-disk data structures by limiting access to writeable blocks. 203241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * 213241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * Clients should not fiddle with the block manager directly. 223241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber */ 233241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 243241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornbervoid dm_tm_destroy(struct dm_transaction_manager *tm); 253241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 263241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber/* 273241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * The non-blocking version of a transaction manager is intended for use in 283241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * fast path code that needs to do lookups e.g. a dm mapping function. 293241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * You create the non-blocking variant from a normal tm. The interface is 303241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * the same, except that most functions will just return -EWOULDBLOCK. 313241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * Methods that return void yet may block should not be called on a clone 323241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * viz. dm_tm_inc, dm_tm_dec. Call dm_tm_destroy() as you would with a normal 333241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * tm when you've finished with it. You may not destroy the original prior 343241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * to clones. 353241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber */ 363241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberstruct dm_transaction_manager *dm_tm_create_non_blocking_clone(struct dm_transaction_manager *real); 373241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 383241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber/* 393241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * We use a 2-phase commit here. 403241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * 413241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * i) In the first phase the block manager is told to start flushing, and 423241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * the changes to the space map are written to disk. You should interrogate 433241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * your particular space map to get detail of its root node etc. to be 443241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * included in your superblock. 453241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * 463241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * ii) @root will be committed last. You shouldn't use more than the 473241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * first 512 bytes of @root if you wish the transaction to survive a power 483241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * failure. You *must* have a write lock held on @root for both stage (i) 493241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * and (ii). The commit will drop the write lock. 503241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber */ 513241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberint dm_tm_pre_commit(struct dm_transaction_manager *tm); 523241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberint dm_tm_commit(struct dm_transaction_manager *tm, struct dm_block *root); 533241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 543241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber/* 553241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * These methods are the only way to get hold of a writeable block. 563241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber */ 573241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 583241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber/* 593241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * dm_tm_new_block() is pretty self-explanatory. Make sure you do actually 603241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * write to the whole of @data before you unlock, otherwise you could get 613241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * a data leak. (The other option is for tm_new_block() to zero new blocks 623241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * before handing them out, which will be redundant in most, if not all, 633241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * cases). 643241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * Zeroes the new block and returns with write lock held. 653241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber */ 663241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberint dm_tm_new_block(struct dm_transaction_manager *tm, 673241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber struct dm_block_validator *v, 683241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber struct dm_block **result); 693241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 703241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber/* 713241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * dm_tm_shadow_block() allocates a new block and copies the data from @orig 723241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * to it. It then decrements the reference count on original block. Use 733241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * this to update the contents of a block in a data structure, don't 743241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * confuse this with a clone - you shouldn't access the orig block after 753241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * this operation. Because the tm knows the scope of the transaction it 763241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * can optimise requests for a shadow of a shadow to a no-op. Don't forget 773241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * to unlock when you've finished with the shadow. 783241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * 793241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * The @inc_children flag is used to tell the caller whether it needs to 803241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * adjust reference counts for children. (Data in the block may refer to 813241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * other blocks.) 823241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * 833241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * Shadowing implicitly drops a reference on @orig so you must not have 843241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * it locked when you call this. 853241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber */ 863241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberint dm_tm_shadow_block(struct dm_transaction_manager *tm, dm_block_t orig, 873241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber struct dm_block_validator *v, 883241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber struct dm_block **result, int *inc_children); 893241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 903241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber/* 913241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * Read access. You can lock any block you want. If there's a write lock 923241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * on it outstanding then it'll block. 933241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber */ 943241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberint dm_tm_read_lock(struct dm_transaction_manager *tm, dm_block_t b, 953241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber struct dm_block_validator *v, 963241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber struct dm_block **result); 973241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 983241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberint dm_tm_unlock(struct dm_transaction_manager *tm, struct dm_block *b); 993241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 1003241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber/* 1013241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * Functions for altering the reference count of a block directly. 1023241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber */ 1033241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornbervoid dm_tm_inc(struct dm_transaction_manager *tm, dm_block_t b); 1043241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 1053241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornbervoid dm_tm_dec(struct dm_transaction_manager *tm, dm_block_t b); 1063241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 1073241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberint dm_tm_ref(struct dm_transaction_manager *tm, dm_block_t b, 1083241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber uint32_t *result); 1093241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 1103241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberstruct dm_block_manager *dm_tm_get_bm(struct dm_transaction_manager *tm); 1113241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 1123241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber/* 1133241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * A little utility that ties the knot by producing a transaction manager 1143241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * that has a space map managed by the transaction manager... 1153241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * 1163241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * Returns a tm that has an open transaction to write the new disk sm. 1173241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber * Caller should store the new sm root and commit. 1183241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber */ 1193241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberint dm_tm_create_with_sm(struct dm_block_manager *bm, dm_block_t sb_location, 1203241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber struct dm_block_validator *sb_validator, 1213241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber struct dm_transaction_manager **tm, 1223241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber struct dm_space_map **sm, struct dm_block **sblock); 1233241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 1243241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornberint dm_tm_open_with_sm(struct dm_block_manager *bm, dm_block_t sb_location, 1253241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber struct dm_block_validator *sb_validator, 1263241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber size_t root_offset, size_t root_max_len, 1273241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber struct dm_transaction_manager **tm, 1283241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber struct dm_space_map **sm, struct dm_block **sblock); 1293241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber 1303241b1d3e0aaafbfcd320f4d71ade629728cc4f4Joe Thornber#endif /* _LINUX_DM_TRANSACTION_MANAGER_H */ 131