1/*
2 * Copyright (C) 2012 Red Hat. All rights reserved.
3 *
4 * This file is released under the GPL.
5 */
6
7#ifndef DM_CACHE_POLICY_H
8#define DM_CACHE_POLICY_H
9
10#include "dm-cache-block-types.h"
11
12#include <linux/device-mapper.h>
13
14/*----------------------------------------------------------------*/
15
16/* FIXME: make it clear which methods are optional.  Get debug policy to
17 * double check this at start.
18 */
19
20/*
21 * The cache policy makes the important decisions about which blocks get to
22 * live on the faster cache device.
23 *
24 * When the core target has to remap a bio it calls the 'map' method of the
25 * policy.  This returns an instruction telling the core target what to do.
26 *
27 * POLICY_HIT:
28 *   That block is in the cache.  Remap to the cache and carry on.
29 *
30 * POLICY_MISS:
31 *   This block is on the origin device.  Remap and carry on.
32 *
33 * POLICY_NEW:
34 *   This block is currently on the origin device, but the policy wants to
35 *   move it.  The core should:
36 *
37 *   - hold any further io to this origin block
38 *   - copy the origin to the given cache block
39 *   - release all the held blocks
40 *   - remap the original block to the cache
41 *
42 * POLICY_REPLACE:
43 *   This block is currently on the origin device.  The policy wants to
44 *   move it to the cache, with the added complication that the destination
45 *   cache block needs a writeback first.  The core should:
46 *
47 *   - hold any further io to this origin block
48 *   - hold any further io to the origin block that's being written back
49 *   - writeback
50 *   - copy new block to cache
51 *   - release held blocks
52 *   - remap bio to cache and reissue.
53 *
54 * Should the core run into trouble while processing a POLICY_NEW or
55 * POLICY_REPLACE instruction it will roll back the policies mapping using
56 * remove_mapping() or force_mapping().  These methods must not fail.  This
57 * approach avoids having transactional semantics in the policy (ie, the
58 * core informing the policy when a migration is complete), and hence makes
59 * it easier to write new policies.
60 *
61 * In general policy methods should never block, except in the case of the
62 * map function when can_migrate is set.  So be careful to implement using
63 * bounded, preallocated memory.
64 */
65enum policy_operation {
66	POLICY_HIT,
67	POLICY_MISS,
68	POLICY_NEW,
69	POLICY_REPLACE
70};
71
72/*
73 * When issuing a POLICY_REPLACE the policy needs to make a callback to
74 * lock the block being demoted.  This doesn't need to occur during a
75 * writeback operation since the block remains in the cache.
76 */
77struct policy_locker;
78typedef int (*policy_lock_fn)(struct policy_locker *l, dm_oblock_t oblock);
79
80struct policy_locker {
81	policy_lock_fn fn;
82};
83
84/*
85 * This is the instruction passed back to the core target.
86 */
87struct policy_result {
88	enum policy_operation op;
89	dm_oblock_t old_oblock;	/* POLICY_REPLACE */
90	dm_cblock_t cblock;	/* POLICY_HIT, POLICY_NEW, POLICY_REPLACE */
91};
92
93typedef int (*policy_walk_fn)(void *context, dm_cblock_t cblock,
94			      dm_oblock_t oblock, uint32_t hint);
95
96/*
97 * The cache policy object.  Just a bunch of methods.  It is envisaged that
98 * this structure will be embedded in a bigger, policy specific structure
99 * (ie. use container_of()).
100 */
101struct dm_cache_policy {
102
103	/*
104	 * FIXME: make it clear which methods are optional, and which may
105	 * block.
106	 */
107
108	/*
109	 * Destroys this object.
110	 */
111	void (*destroy)(struct dm_cache_policy *p);
112
113	/*
114	 * See large comment above.
115	 *
116	 * oblock      - the origin block we're interested in.
117	 *
118	 * can_block - indicates whether the current thread is allowed to
119	 *             block.  -EWOULDBLOCK returned if it can't and would.
120	 *
121	 * can_migrate - gives permission for POLICY_NEW or POLICY_REPLACE
122	 *               instructions.  If denied and the policy would have
123	 *               returned one of these instructions it should
124	 *               return -EWOULDBLOCK.
125	 *
126	 * discarded_oblock - indicates whether the whole origin block is
127	 *               in a discarded state (FIXME: better to tell the
128	 *               policy about this sooner, so it can recycle that
129	 *               cache block if it wants.)
130	 * bio         - the bio that triggered this call.
131	 * result      - gets filled in with the instruction.
132	 *
133	 * May only return 0, or -EWOULDBLOCK (if !can_migrate)
134	 */
135	int (*map)(struct dm_cache_policy *p, dm_oblock_t oblock,
136		   bool can_block, bool can_migrate, bool discarded_oblock,
137		   struct bio *bio, struct policy_locker *locker,
138		   struct policy_result *result);
139
140	/*
141	 * Sometimes we want to see if a block is in the cache, without
142	 * triggering any update of stats.  (ie. it's not a real hit).
143	 *
144	 * Must not block.
145	 *
146	 * Returns 0 if in cache, -ENOENT if not, < 0 for other errors
147	 * (-EWOULDBLOCK would be typical).
148	 */
149	int (*lookup)(struct dm_cache_policy *p, dm_oblock_t oblock, dm_cblock_t *cblock);
150
151	void (*set_dirty)(struct dm_cache_policy *p, dm_oblock_t oblock);
152	void (*clear_dirty)(struct dm_cache_policy *p, dm_oblock_t oblock);
153
154	/*
155	 * Called when a cache target is first created.  Used to load a
156	 * mapping from the metadata device into the policy.
157	 */
158	int (*load_mapping)(struct dm_cache_policy *p, dm_oblock_t oblock,
159			    dm_cblock_t cblock, uint32_t hint, bool hint_valid);
160
161	int (*walk_mappings)(struct dm_cache_policy *p, policy_walk_fn fn,
162			     void *context);
163
164	/*
165	 * Override functions used on the error paths of the core target.
166	 * They must succeed.
167	 */
168	void (*remove_mapping)(struct dm_cache_policy *p, dm_oblock_t oblock);
169	void (*force_mapping)(struct dm_cache_policy *p, dm_oblock_t current_oblock,
170			      dm_oblock_t new_oblock);
171
172	/*
173	 * This is called via the invalidate_cblocks message.  It is
174	 * possible the particular cblock has already been removed due to a
175	 * write io in passthrough mode.  In which case this should return
176	 * -ENODATA.
177	 */
178	int (*remove_cblock)(struct dm_cache_policy *p, dm_cblock_t cblock);
179
180	/*
181	 * Provide a dirty block to be written back by the core target.
182	 *
183	 * Returns:
184	 *
185	 * 0 and @cblock,@oblock: block to write back provided
186	 *
187	 * -ENODATA: no dirty blocks available
188	 */
189	int (*writeback_work)(struct dm_cache_policy *p, dm_oblock_t *oblock, dm_cblock_t *cblock);
190
191	/*
192	 * How full is the cache?
193	 */
194	dm_cblock_t (*residency)(struct dm_cache_policy *p);
195
196	/*
197	 * Because of where we sit in the block layer, we can be asked to
198	 * map a lot of little bios that are all in the same block (no
199	 * queue merging has occurred).  To stop the policy being fooled by
200	 * these the core target sends regular tick() calls to the policy.
201	 * The policy should only count an entry as hit once per tick.
202	 */
203	void (*tick)(struct dm_cache_policy *p);
204
205	/*
206	 * Configuration.
207	 */
208	int (*emit_config_values)(struct dm_cache_policy *p,
209				  char *result, unsigned maxlen);
210	int (*set_config_value)(struct dm_cache_policy *p,
211				const char *key, const char *value);
212
213	/*
214	 * Book keeping ptr for the policy register, not for general use.
215	 */
216	void *private;
217};
218
219/*----------------------------------------------------------------*/
220
221/*
222 * We maintain a little register of the different policy types.
223 */
224#define CACHE_POLICY_NAME_SIZE 16
225#define CACHE_POLICY_VERSION_SIZE 3
226
227struct dm_cache_policy_type {
228	/* For use by the register code only. */
229	struct list_head list;
230
231	/*
232	 * Policy writers should fill in these fields.  The name field is
233	 * what gets passed on the target line to select your policy.
234	 */
235	char name[CACHE_POLICY_NAME_SIZE];
236	unsigned version[CACHE_POLICY_VERSION_SIZE];
237
238	/*
239	 * For use by an alias dm_cache_policy_type to point to the
240	 * real dm_cache_policy_type.
241	 */
242	struct dm_cache_policy_type *real;
243
244	/*
245	 * Policies may store a hint for each each cache block.
246	 * Currently the size of this hint must be 0 or 4 bytes but we
247	 * expect to relax this in future.
248	 */
249	size_t hint_size;
250
251	struct module *owner;
252	struct dm_cache_policy *(*create)(dm_cblock_t cache_size,
253					  sector_t origin_size,
254					  sector_t block_size);
255};
256
257int dm_cache_policy_register(struct dm_cache_policy_type *type);
258void dm_cache_policy_unregister(struct dm_cache_policy_type *type);
259
260/*----------------------------------------------------------------*/
261
262#endif	/* DM_CACHE_POLICY_H */
263