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 */ 65 enum 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 */ 77 struct policy_locker; 78 typedef int (*policy_lock_fn)(struct policy_locker *l, dm_oblock_t oblock); 79 80 struct policy_locker { 81 policy_lock_fn fn; 82 }; 83 84 /* 85 * This is the instruction passed back to the core target. 86 */ 87 struct 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 93 typedef 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 */ 101 struct 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. If 182 * critical_only is set then the policy should only provide work if 183 * it urgently needs it. 184 * 185 * Returns: 186 * 187 * 0 and @cblock,@oblock: block to write back provided 188 * 189 * -ENODATA: no dirty blocks available 190 */ 191 int (*writeback_work)(struct dm_cache_policy *p, dm_oblock_t *oblock, dm_cblock_t *cblock, 192 bool critical_only); 193 194 /* 195 * How full is the cache? 196 */ 197 dm_cblock_t (*residency)(struct dm_cache_policy *p); 198 199 /* 200 * Because of where we sit in the block layer, we can be asked to 201 * map a lot of little bios that are all in the same block (no 202 * queue merging has occurred). To stop the policy being fooled by 203 * these, the core target sends regular tick() calls to the policy. 204 * The policy should only count an entry as hit once per tick. 205 */ 206 void (*tick)(struct dm_cache_policy *p, bool can_block); 207 208 /* 209 * Configuration. 210 */ 211 int (*emit_config_values)(struct dm_cache_policy *p, char *result, 212 unsigned maxlen, ssize_t *sz_ptr); 213 int (*set_config_value)(struct dm_cache_policy *p, 214 const char *key, const char *value); 215 216 /* 217 * Book keeping ptr for the policy register, not for general use. 218 */ 219 void *private; 220 }; 221 222 /*----------------------------------------------------------------*/ 223 224 /* 225 * We maintain a little register of the different policy types. 226 */ 227 #define CACHE_POLICY_NAME_SIZE 16 228 #define CACHE_POLICY_VERSION_SIZE 3 229 230 struct dm_cache_policy_type { 231 /* For use by the register code only. */ 232 struct list_head list; 233 234 /* 235 * Policy writers should fill in these fields. The name field is 236 * what gets passed on the target line to select your policy. 237 */ 238 char name[CACHE_POLICY_NAME_SIZE]; 239 unsigned version[CACHE_POLICY_VERSION_SIZE]; 240 241 /* 242 * For use by an alias dm_cache_policy_type to point to the 243 * real dm_cache_policy_type. 244 */ 245 struct dm_cache_policy_type *real; 246 247 /* 248 * Policies may store a hint for each each cache block. 249 * Currently the size of this hint must be 0 or 4 bytes but we 250 * expect to relax this in future. 251 */ 252 size_t hint_size; 253 254 struct module *owner; 255 struct dm_cache_policy *(*create)(dm_cblock_t cache_size, 256 sector_t origin_size, 257 sector_t block_size); 258 }; 259 260 int dm_cache_policy_register(struct dm_cache_policy_type *type); 261 void dm_cache_policy_unregister(struct dm_cache_policy_type *type); 262 263 /*----------------------------------------------------------------*/ 264 265 #endif /* DM_CACHE_POLICY_H */ 266