Commit | Line | Data |
---|---|---|
f2836352 JT |
1 | Guidance for writing policies |
2 | ============================= | |
3 | ||
4 | Try to keep transactionality out of it. The core is careful to | |
5 | avoid asking about anything that is migrating. This is a pain, but | |
6 | makes it easier to write the policies. | |
7 | ||
8 | Mappings are loaded into the policy at construction time. | |
9 | ||
10 | Every bio that is mapped by the target is referred to the policy. | |
11 | The policy can return a simple HIT or MISS or issue a migration. | |
12 | ||
13 | Currently there's no way for the policy to issue background work, | |
14 | e.g. to start writing back dirty blocks that are going to be evicte | |
15 | soon. | |
16 | ||
17 | Because we map bios, rather than requests it's easy for the policy | |
18 | to get fooled by many small bios. For this reason the core target | |
19 | issues periodic ticks to the policy. It's suggested that the policy | |
20 | doesn't update states (eg, hit counts) for a block more than once | |
21 | for each tick. The core ticks by watching bios complete, and so | |
22 | trying to see when the io scheduler has let the ios run. | |
23 | ||
24 | ||
25 | Overview of supplied cache replacement policies | |
26 | =============================================== | |
27 | ||
28 | multiqueue | |
29 | ---------- | |
30 | ||
31 | This policy is the default. | |
32 | ||
01911c19 JT |
33 | The multiqueue policy has three sets of 16 queues: one set for entries |
34 | waiting for the cache and another two for those in the cache (a set for | |
35 | clean entries and a set for dirty entries). | |
36 | ||
f2836352 JT |
37 | Cache entries in the queues are aged based on logical time. Entry into |
38 | the cache is based on variable thresholds and queue selection is based | |
39 | on hit count on entry. The policy aims to take different cache miss | |
40 | costs into account and to adjust to varying load patterns automatically. | |
41 | ||
42 | Message and constructor argument pairs are: | |
78e03d69 JT |
43 | 'sequential_threshold <#nr_sequential_ios>' |
44 | 'random_threshold <#nr_random_ios>' | |
45 | 'read_promote_adjustment <value>' | |
46 | 'write_promote_adjustment <value>' | |
47 | 'discard_promote_adjustment <value>' | |
f2836352 JT |
48 | |
49 | The sequential threshold indicates the number of contiguous I/Os | |
50 | required before a stream is treated as sequential. The random threshold | |
51 | is the number of intervening non-contiguous I/Os that must be seen | |
52 | before the stream is treated as random again. | |
53 | ||
54 | The sequential and random thresholds default to 512 and 4 respectively. | |
55 | ||
56 | Large, sequential ios are probably better left on the origin device | |
57 | since spindles tend to have good bandwidth. The io_tracker counts | |
58 | contiguous I/Os to try to spot when the io is in one of these sequential | |
59 | modes. | |
60 | ||
78e03d69 JT |
61 | Internally the mq policy maintains a promotion threshold variable. If |
62 | the hit count of a block not in the cache goes above this threshold it | |
63 | gets promoted to the cache. The read, write and discard promote adjustment | |
64 | tunables allow you to tweak the promotion threshold by adding a small | |
65 | value based on the io type. They default to 4, 8 and 1 respectively. | |
66 | If you're trying to quickly warm a new cache device you may wish to | |
67 | reduce these to encourage promotion. Remember to switch them back to | |
68 | their defaults after the cache fills though. | |
69 | ||
8735a813 HM |
70 | cleaner |
71 | ------- | |
72 | ||
73 | The cleaner writes back all dirty blocks in a cache to decommission it. | |
74 | ||
f2836352 JT |
75 | Examples |
76 | ======== | |
77 | ||
78 | The syntax for a table is: | |
79 | cache <metadata dev> <cache dev> <origin dev> <block size> | |
80 | <#feature_args> [<feature arg>]* | |
81 | <policy> <#policy_args> [<policy arg>]* | |
82 | ||
83 | The syntax to send a message using the dmsetup command is: | |
84 | dmsetup message <mapped device> 0 sequential_threshold 1024 | |
85 | dmsetup message <mapped device> 0 random_threshold 8 | |
86 | ||
87 | Using dmsetup: | |
88 | dmsetup create blah --table "0 268435456 cache /dev/sdb /dev/sdc \ | |
89 | /dev/sdd 512 0 mq 4 sequential_threshold 1024 random_threshold 8" | |
90 | creates a 128GB large mapped device named 'blah' with the | |
91 | sequential threshold set to 1024 and the random_threshold set to 8. |