Root/drivers/md/dm-cache-policy.h

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 * This is the instruction passed back to the core target.
74 */
75struct policy_result {
76    enum policy_operation op;
77    dm_oblock_t old_oblock; /* POLICY_REPLACE */
78    dm_cblock_t cblock; /* POLICY_HIT, POLICY_NEW, POLICY_REPLACE */
79};
80
81typedef int (*policy_walk_fn)(void *context, dm_cblock_t cblock,
82                  dm_oblock_t oblock, uint32_t hint);
83
84/*
85 * The cache policy object. Just a bunch of methods. It is envisaged that
86 * this structure will be embedded in a bigger, policy specific structure
87 * (ie. use container_of()).
88 */
89struct dm_cache_policy {
90
91    /*
92     * FIXME: make it clear which methods are optional, and which may
93     * block.
94     */
95
96    /*
97     * Destroys this object.
98     */
99    void (*destroy)(struct dm_cache_policy *p);
100
101    /*
102     * See large comment above.
103     *
104     * oblock - the origin block we're interested in.
105     *
106     * can_block - indicates whether the current thread is allowed to
107     * block. -EWOULDBLOCK returned if it can't and would.
108     *
109     * can_migrate - gives permission for POLICY_NEW or POLICY_REPLACE
110     * instructions. If denied and the policy would have
111     * returned one of these instructions it should
112     * return -EWOULDBLOCK.
113     *
114     * discarded_oblock - indicates whether the whole origin block is
115     * in a discarded state (FIXME: better to tell the
116     * policy about this sooner, so it can recycle that
117     * cache block if it wants.)
118     * bio - the bio that triggered this call.
119     * result - gets filled in with the instruction.
120     *
121     * May only return 0, or -EWOULDBLOCK (if !can_migrate)
122     */
123    int (*map)(struct dm_cache_policy *p, dm_oblock_t oblock,
124           bool can_block, bool can_migrate, bool discarded_oblock,
125           struct bio *bio, struct policy_result *result);
126
127    /*
128     * Sometimes we want to see if a block is in the cache, without
129     * triggering any update of stats. (ie. it's not a real hit).
130     *
131     * Must not block.
132     *
133     * Returns 1 iff in cache, 0 iff not, < 0 on error (-EWOULDBLOCK
134     * would be typical).
135     */
136    int (*lookup)(struct dm_cache_policy *p, dm_oblock_t oblock, dm_cblock_t *cblock);
137
138    /*
139     * oblock must be a mapped block. Must not block.
140     */
141    void (*set_dirty)(struct dm_cache_policy *p, dm_oblock_t oblock);
142    void (*clear_dirty)(struct dm_cache_policy *p, dm_oblock_t oblock);
143
144    /*
145     * Called when a cache target is first created. Used to load a
146     * mapping from the metadata device into the policy.
147     */
148    int (*load_mapping)(struct dm_cache_policy *p, dm_oblock_t oblock,
149                dm_cblock_t cblock, uint32_t hint, bool hint_valid);
150
151    int (*walk_mappings)(struct dm_cache_policy *p, policy_walk_fn fn,
152                 void *context);
153
154    /*
155     * Override functions used on the error paths of the core target.
156     * They must succeed.
157     */
158    void (*remove_mapping)(struct dm_cache_policy *p, dm_oblock_t oblock);
159    void (*force_mapping)(struct dm_cache_policy *p, dm_oblock_t current_oblock,
160                  dm_oblock_t new_oblock);
161
162    int (*writeback_work)(struct dm_cache_policy *p, dm_oblock_t *oblock, dm_cblock_t *cblock);
163
164
165    /*
166     * How full is the cache?
167     */
168    dm_cblock_t (*residency)(struct dm_cache_policy *p);
169
170    /*
171     * Because of where we sit in the block layer, we can be asked to
172     * map a lot of little bios that are all in the same block (no
173     * queue merging has occurred). To stop the policy being fooled by
174     * these the core target sends regular tick() calls to the policy.
175     * The policy should only count an entry as hit once per tick.
176     */
177    void (*tick)(struct dm_cache_policy *p);
178
179    /*
180     * Configuration.
181     */
182    int (*emit_config_values)(struct dm_cache_policy *p,
183                  char *result, unsigned maxlen);
184    int (*set_config_value)(struct dm_cache_policy *p,
185                const char *key, const char *value);
186
187    /*
188     * Book keeping ptr for the policy register, not for general use.
189     */
190    void *private;
191};
192
193/*----------------------------------------------------------------*/
194
195/*
196 * We maintain a little register of the different policy types.
197 */
198#define CACHE_POLICY_NAME_SIZE 16
199#define CACHE_POLICY_VERSION_SIZE 3
200
201struct dm_cache_policy_type {
202    /* For use by the register code only. */
203    struct list_head list;
204
205    /*
206     * Policy writers should fill in these fields. The name field is
207     * what gets passed on the target line to select your policy.
208     */
209    char name[CACHE_POLICY_NAME_SIZE];
210    unsigned version[CACHE_POLICY_VERSION_SIZE];
211
212    /*
213     * Policies may store a hint for each each cache block.
214     * Currently the size of this hint must be 0 or 4 bytes but we
215     * expect to relax this in future.
216     */
217    size_t hint_size;
218
219    struct module *owner;
220    struct dm_cache_policy *(*create)(dm_cblock_t cache_size,
221                      sector_t origin_size,
222                      sector_t block_size);
223};
224
225int dm_cache_policy_register(struct dm_cache_policy_type *type);
226void dm_cache_policy_unregister(struct dm_cache_policy_type *type);
227
228/*----------------------------------------------------------------*/
229
230#endif /* DM_CACHE_POLICY_H */
231

Archive Download this file



interactive