drivers/md/dm-cache-policy.h

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