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