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