Commit | Line | Data |
---|---|---|
3bd94003 | 1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
c6b4fcba JT |
2 | /* |
3 | * Copyright (C) 2012 Red Hat. All rights reserved. | |
4 | * | |
5 | * This file is released under the GPL. | |
6 | */ | |
7 | ||
8 | #ifndef DM_CACHE_POLICY_H | |
9 | #define DM_CACHE_POLICY_H | |
10 | ||
11 | #include "dm-cache-block-types.h" | |
12 | ||
13 | #include <linux/device-mapper.h> | |
14 | ||
15 | /*----------------------------------------------------------------*/ | |
16 | ||
c6b4fcba JT |
17 | /* |
18 | * The cache policy makes the important decisions about which blocks get to | |
19 | * live on the faster cache device. | |
c6b4fcba JT |
20 | */ |
21 | enum policy_operation { | |
b29d4986 JT |
22 | POLICY_PROMOTE, |
23 | POLICY_DEMOTE, | |
24 | POLICY_WRITEBACK | |
fb4100ae JT |
25 | }; |
26 | ||
c6b4fcba JT |
27 | /* |
28 | * This is the instruction passed back to the core target. | |
29 | */ | |
b29d4986 | 30 | struct policy_work { |
c6b4fcba | 31 | enum policy_operation op; |
b29d4986 JT |
32 | dm_oblock_t oblock; |
33 | dm_cblock_t cblock; | |
c6b4fcba JT |
34 | }; |
35 | ||
c6b4fcba | 36 | /* |
b29d4986 JT |
37 | * The cache policy object. It is envisaged that this structure will be |
38 | * embedded in a bigger, policy specific structure (ie. use container_of()). | |
c6b4fcba JT |
39 | */ |
40 | struct dm_cache_policy { | |
c6b4fcba JT |
41 | /* |
42 | * Destroys this object. | |
43 | */ | |
44 | void (*destroy)(struct dm_cache_policy *p); | |
45 | ||
46 | /* | |
b29d4986 | 47 | * Find the location of a block. |
c6b4fcba | 48 | * |
b29d4986 | 49 | * Must not block. |
c6b4fcba | 50 | * |
b29d4986 JT |
51 | * Returns 0 if in cache (cblock will be set), -ENOENT if not, < 0 for |
52 | * other errors (-EWOULDBLOCK would be typical). data_dir should be | |
53 | * READ or WRITE. fast_copy should be set if migrating this block would | |
54 | * be 'cheap' somehow (eg, discarded data). background_queued will be set | |
55 | * if a migration has just been queued. | |
c6b4fcba | 56 | */ |
b29d4986 JT |
57 | int (*lookup)(struct dm_cache_policy *p, dm_oblock_t oblock, dm_cblock_t *cblock, |
58 | int data_dir, bool fast_copy, bool *background_queued); | |
c6b4fcba JT |
59 | |
60 | /* | |
b29d4986 JT |
61 | * Sometimes the core target can optimise a migration, eg, the |
62 | * block may be discarded, or the bio may cover an entire block. | |
63 | * In order to optimise it needs the migration immediately though | |
64 | * so it knows to do something different with the bio. | |
c6b4fcba | 65 | * |
b29d4986 JT |
66 | * This method is optional (policy-internal will fallback to using |
67 | * lookup). | |
c6b4fcba | 68 | */ |
b29d4986 JT |
69 | int (*lookup_with_work)(struct dm_cache_policy *p, |
70 | dm_oblock_t oblock, dm_cblock_t *cblock, | |
71 | int data_dir, bool fast_copy, | |
72 | struct policy_work **work); | |
c6b4fcba JT |
73 | |
74 | /* | |
b29d4986 JT |
75 | * Retrieves background work. Returns -ENODATA when there's no |
76 | * background work. | |
c6b4fcba | 77 | */ |
b29d4986 | 78 | int (*get_background_work)(struct dm_cache_policy *p, bool idle, |
255e2646 | 79 | struct policy_work **result); |
c6b4fcba | 80 | |
4e781b49 | 81 | /* |
b29d4986 JT |
82 | * You must pass in the same work pointer that you were given, not |
83 | * a copy. | |
4e781b49 | 84 | */ |
b29d4986 JT |
85 | void (*complete_background_work)(struct dm_cache_policy *p, |
86 | struct policy_work *work, | |
87 | bool success); | |
88 | ||
89 | void (*set_dirty)(struct dm_cache_policy *p, dm_cblock_t cblock); | |
90 | void (*clear_dirty)(struct dm_cache_policy *p, dm_cblock_t cblock); | |
c6b4fcba JT |
91 | |
92 | /* | |
b29d4986 JT |
93 | * Called when a cache target is first created. Used to load a |
94 | * mapping from the metadata device into the policy. | |
c6b4fcba | 95 | */ |
b29d4986 JT |
96 | int (*load_mapping)(struct dm_cache_policy *p, dm_oblock_t oblock, |
97 | dm_cblock_t cblock, bool dirty, | |
98 | uint32_t hint, bool hint_valid); | |
c6b4fcba | 99 | |
532906aa | 100 | /* |
b29d4986 JT |
101 | * Drops the mapping, irrespective of whether it's clean or dirty. |
102 | * Returns -ENODATA if cblock is not mapped. | |
532906aa | 103 | */ |
b29d4986 | 104 | int (*invalidate_mapping)(struct dm_cache_policy *p, dm_cblock_t cblock); |
c6b4fcba | 105 | |
532906aa | 106 | /* |
b29d4986 JT |
107 | * Gets the hint for a given cblock. Called in a single threaded |
108 | * context. So no locking required. | |
532906aa | 109 | */ |
b29d4986 | 110 | uint32_t (*get_hint)(struct dm_cache_policy *p, dm_cblock_t cblock); |
c6b4fcba JT |
111 | |
112 | /* | |
113 | * How full is the cache? | |
114 | */ | |
115 | dm_cblock_t (*residency)(struct dm_cache_policy *p); | |
116 | ||
117 | /* | |
118 | * Because of where we sit in the block layer, we can be asked to | |
119 | * map a lot of little bios that are all in the same block (no | |
120 | * queue merging has occurred). To stop the policy being fooled by | |
fba10109 | 121 | * these, the core target sends regular tick() calls to the policy. |
c6b4fcba | 122 | * The policy should only count an entry as hit once per tick. |
b29d4986 JT |
123 | * |
124 | * This method is optional. | |
c6b4fcba | 125 | */ |
fba10109 | 126 | void (*tick)(struct dm_cache_policy *p, bool can_block); |
c6b4fcba JT |
127 | |
128 | /* | |
129 | * Configuration. | |
130 | */ | |
028ae9f7 | 131 | int (*emit_config_values)(struct dm_cache_policy *p, char *result, |
86a3238c | 132 | unsigned int maxlen, ssize_t *sz_ptr); |
c6b4fcba JT |
133 | int (*set_config_value)(struct dm_cache_policy *p, |
134 | const char *key, const char *value); | |
135 | ||
b29d4986 JT |
136 | void (*allow_migrations)(struct dm_cache_policy *p, bool allow); |
137 | ||
c6b4fcba JT |
138 | /* |
139 | * Book keeping ptr for the policy register, not for general use. | |
140 | */ | |
141 | void *private; | |
142 | }; | |
143 | ||
144 | /*----------------------------------------------------------------*/ | |
145 | ||
146 | /* | |
147 | * We maintain a little register of the different policy types. | |
148 | */ | |
149 | #define CACHE_POLICY_NAME_SIZE 16 | |
4e7f506f | 150 | #define CACHE_POLICY_VERSION_SIZE 3 |
c6b4fcba JT |
151 | |
152 | struct dm_cache_policy_type { | |
153 | /* For use by the register code only. */ | |
154 | struct list_head list; | |
155 | ||
156 | /* | |
157 | * Policy writers should fill in these fields. The name field is | |
158 | * what gets passed on the target line to select your policy. | |
159 | */ | |
160 | char name[CACHE_POLICY_NAME_SIZE]; | |
86a3238c | 161 | unsigned int version[CACHE_POLICY_VERSION_SIZE]; |
c6b4fcba | 162 | |
2e68c4e6 MS |
163 | /* |
164 | * For use by an alias dm_cache_policy_type to point to the | |
165 | * real dm_cache_policy_type. | |
166 | */ | |
167 | struct dm_cache_policy_type *real; | |
168 | ||
c6b4fcba | 169 | /* |
48d1a964 | 170 | * Policies may store a hint for each cache block. |
c6b4fcba JT |
171 | * Currently the size of this hint must be 0 or 4 bytes but we |
172 | * expect to relax this in future. | |
173 | */ | |
174 | size_t hint_size; | |
175 | ||
176 | struct module *owner; | |
177 | struct dm_cache_policy *(*create)(dm_cblock_t cache_size, | |
178 | sector_t origin_size, | |
179 | sector_t block_size); | |
180 | }; | |
181 | ||
182 | int dm_cache_policy_register(struct dm_cache_policy_type *type); | |
183 | void dm_cache_policy_unregister(struct dm_cache_policy_type *type); | |
184 | ||
185 | /*----------------------------------------------------------------*/ | |
186 | ||
187 | #endif /* DM_CACHE_POLICY_H */ |