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 /*
  17  * The cache policy makes the important decisions about which blocks get to
  18  * live on the faster cache device.
  19  */
  20 enum 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  */
  29 struct 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  */
  39 struct 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
 151 struct 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
 181 int dm_cache_policy_register(struct dm_cache_policy_type *type);
 182 void dm_cache_policy_unregister(struct dm_cache_policy_type *type);
 183
 184 /*----------------------------------------------------------------*/
 185
 186 #endif  /* DM_CACHE_POLICY_H */