188 lines · c
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_H9#define DM_CACHE_POLICY_H10 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 to19 * live on the faster cache device.20 */21enum policy_operation {22 POLICY_PROMOTE,23 POLICY_DEMOTE,24 POLICY_WRITEBACK25};26 27/*28 * This is the instruction passed back to the core target.29 */30struct 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 be38 * embedded in a bigger, policy specific structure (ie. use container_of()).39 */40struct 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 for52 * other errors (-EWOULDBLOCK would be typical). data_dir should be53 * READ or WRITE. fast_copy should be set if migrating this block would54 * be 'cheap' somehow (eg, discarded data). background_queued will be set55 * 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, the62 * block may be discarded, or the bio may cover an entire block.63 * In order to optimise it needs the migration immediately though64 * so it knows to do something different with the bio.65 *66 * This method is optional (policy-internal will fallback to using67 * 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 no76 * 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, not83 * 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 a94 * 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 threaded108 * 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 to119 * map a lot of little bios that are all in the same block (no120 * queue merging has occurred). To stop the policy being fooled by121 * 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 16150#define CACHE_POLICY_VERSION_SIZE 3151 152struct 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 is158 * 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 the165 * 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 we172 * 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 182int dm_cache_policy_register(struct dm_cache_policy_type *type);183void dm_cache_policy_unregister(struct dm_cache_policy_type *type);184 185/*----------------------------------------------------------------*/186 187#endif /* DM_CACHE_POLICY_H */188