1===============
2Persistent data
3===============
4
5Introduction
6============
7
8The more-sophisticated device-mapper targets require complex metadata
9that is managed in kernel.  In late 2010 we were seeing that various
10different targets were rolling their own data structures, for example:
11
12- Mikulas Patocka's multisnap implementation
13- Heinz Mauelshagen's thin provisioning target
14- Another btree-based caching target posted to dm-devel
15- Another multi-snapshot target based on a design of Daniel Phillips
16
17Maintaining these data structures takes a lot of work, so if possible
18we'd like to reduce the number.
19
20The persistent-data library is an attempt to provide a re-usable
21framework for people who want to store metadata in device-mapper
22targets.  It's currently used by the thin-provisioning target and an
23upcoming hierarchical storage target.
24
25Overview
26========
27
28The main documentation is in the header files which can all be found
29under drivers/md/persistent-data.
30
31The block manager
32-----------------
33
34dm-block-manager.[hc]
35
36This provides access to the data on disk in fixed sized-blocks.  There
37is a read/write locking interface to prevent concurrent accesses, and
38keep data that is being used in the cache.
39
40Clients of persistent-data are unlikely to use this directly.
41
42The transaction manager
43-----------------------
44
45dm-transaction-manager.[hc]
46
47This restricts access to blocks and enforces copy-on-write semantics.
48The only way you can get hold of a writable block through the
49transaction manager is by shadowing an existing block (ie. doing
50copy-on-write) or allocating a fresh one.  Shadowing is elided within
51the same transaction so performance is reasonable.  The commit method
52ensures that all data is flushed before it writes the superblock.
53On power failure your metadata will be as it was when last committed.
54
55The Space Maps
56--------------
57
58dm-space-map.h
59dm-space-map-metadata.[hc]
60dm-space-map-disk.[hc]
61
62On-disk data structures that keep track of reference counts of blocks.
63Also acts as the allocator of new blocks.  Currently two
64implementations: a simpler one for managing blocks on a different
65device (eg. thinly-provisioned data blocks); and one for managing
66the metadata space.  The latter is complicated by the need to store
67its own data within the space it's managing.
68
69The data structures
70-------------------
71
72dm-btree.[hc]
73dm-btree-remove.c
74dm-btree-spine.c
75dm-btree-internal.h
76
77Currently there is only one data structure, a hierarchical btree.
78There are plans to add more.  For example, something with an
79array-like interface would see a lot of use.
80
81The btree is 'hierarchical' in that you can define it to be composed
82of nested btrees, and take multiple keys.  For example, the
83thin-provisioning target uses a btree with two levels of nesting.
84The first maps a device id to a mapping tree, and that in turn maps a
85virtual block to a physical block.
86
87Values stored in the btrees can have arbitrary size.  Keys are always
8864bits, although nesting allows you to use multiple keys.
89