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 */
 21enum 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 */
 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 be
 38 * 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 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
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 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
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 */