1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
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 | |
17 | /* |
18 | * The cache policy makes the important decisions about which blocks get to |
19 | * live on the faster cache device. |
20 | */ |
21 | enum policy_operation { |
22 | POLICY_PROMOTE, |
23 | POLICY_DEMOTE, |
24 | POLICY_WRITEBACK |
25 | }; |
26 | |
27 | /* |
28 | * This is the instruction passed back to the core target. |
29 | */ |
30 | struct policy_work { |
31 | enum policy_operation op; |
32 | dm_oblock_t oblock; |
33 | dm_cblock_t cblock; |
34 | }; |
35 | |
36 | /* |
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()). |
39 | */ |
40 | struct dm_cache_policy { |
41 | /* |
42 | * Destroys this object. |
43 | */ |
44 | void (*destroy)(struct dm_cache_policy *p); |
45 | |
46 | /* |
47 | * Find the location of a block. |
48 | * |
49 | * Must not block. |
50 | * |
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. |
56 | */ |
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); |
59 | |
60 | /* |
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. |
65 | * |
66 | * This method is optional (policy-internal will fallback to using |
67 | * lookup). |
68 | */ |
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); |
73 | |
74 | /* |
75 | * Retrieves background work. Returns -ENODATA when there's no |
76 | * background work. |
77 | */ |
78 | int (*get_background_work)(struct dm_cache_policy *p, bool idle, |
79 | struct policy_work **result); |
80 | |
81 | /* |
82 | * You must pass in the same work pointer that you were given, not |
83 | * a copy. |
84 | */ |
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); |
91 | |
92 | /* |
93 | * Called when a cache target is first created. Used to load a |
94 | * mapping from the metadata device into the policy. |
95 | */ |
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); |
99 | |
100 | /* |
101 | * Drops the mapping, irrespective of whether it's clean or dirty. |
102 | * Returns -ENODATA if cblock is not mapped. |
103 | */ |
104 | int (*invalidate_mapping)(struct dm_cache_policy *p, dm_cblock_t cblock); |
105 | |
106 | /* |
107 | * Gets the hint for a given cblock. Called in a single threaded |
108 | * context. So no locking required. |
109 | */ |
110 | uint32_t (*get_hint)(struct dm_cache_policy *p, dm_cblock_t cblock); |
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 |
121 | * these, the core target sends regular tick() calls to the policy. |
122 | * The policy should only count an entry as hit once per tick. |
123 | * |
124 | * This method is optional. |
125 | */ |
126 | void (*tick)(struct dm_cache_policy *p, bool can_block); |
127 | |
128 | /* |
129 | * Configuration. |
130 | */ |
131 | int (*emit_config_values)(struct dm_cache_policy *p, char *result, |
132 | unsigned int maxlen, ssize_t *sz_ptr); |
133 | int (*set_config_value)(struct dm_cache_policy *p, |
134 | const char *key, const char *value); |
135 | |
136 | void (*allow_migrations)(struct dm_cache_policy *p, bool allow); |
137 | |
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 |
150 | #define CACHE_POLICY_VERSION_SIZE 3 |
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]; |
161 | unsigned int version[CACHE_POLICY_VERSION_SIZE]; |
162 | |
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 | |
169 | /* |
170 | * Policies may store a hint for each cache block. |
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 */ |
188 | |