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  */
  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 */