266 lines
8.2 KiB
C
266 lines
8.2 KiB
C
/*
|
|
* Copyright (C) 2012 Red Hat. All rights reserved.
|
|
*
|
|
* This file is released under the GPL.
|
|
*/
|
|
|
|
#ifndef DM_CACHE_POLICY_H
|
|
#define DM_CACHE_POLICY_H
|
|
|
|
#include "dm-cache-block-types.h"
|
|
|
|
#include <linux/device-mapper.h>
|
|
|
|
/*----------------------------------------------------------------*/
|
|
|
|
/* FIXME: make it clear which methods are optional. Get debug policy to
|
|
* double check this at start.
|
|
*/
|
|
|
|
/*
|
|
* The cache policy makes the important decisions about which blocks get to
|
|
* live on the faster cache device.
|
|
*
|
|
* When the core target has to remap a bio it calls the 'map' method of the
|
|
* policy. This returns an instruction telling the core target what to do.
|
|
*
|
|
* POLICY_HIT:
|
|
* That block is in the cache. Remap to the cache and carry on.
|
|
*
|
|
* POLICY_MISS:
|
|
* This block is on the origin device. Remap and carry on.
|
|
*
|
|
* POLICY_NEW:
|
|
* This block is currently on the origin device, but the policy wants to
|
|
* move it. The core should:
|
|
*
|
|
* - hold any further io to this origin block
|
|
* - copy the origin to the given cache block
|
|
* - release all the held blocks
|
|
* - remap the original block to the cache
|
|
*
|
|
* POLICY_REPLACE:
|
|
* This block is currently on the origin device. The policy wants to
|
|
* move it to the cache, with the added complication that the destination
|
|
* cache block needs a writeback first. The core should:
|
|
*
|
|
* - hold any further io to this origin block
|
|
* - hold any further io to the origin block that's being written back
|
|
* - writeback
|
|
* - copy new block to cache
|
|
* - release held blocks
|
|
* - remap bio to cache and reissue.
|
|
*
|
|
* Should the core run into trouble while processing a POLICY_NEW or
|
|
* POLICY_REPLACE instruction it will roll back the policies mapping using
|
|
* remove_mapping() or force_mapping(). These methods must not fail. This
|
|
* approach avoids having transactional semantics in the policy (ie, the
|
|
* core informing the policy when a migration is complete), and hence makes
|
|
* it easier to write new policies.
|
|
*
|
|
* In general policy methods should never block, except in the case of the
|
|
* map function when can_migrate is set. So be careful to implement using
|
|
* bounded, preallocated memory.
|
|
*/
|
|
enum policy_operation {
|
|
POLICY_HIT,
|
|
POLICY_MISS,
|
|
POLICY_NEW,
|
|
POLICY_REPLACE
|
|
};
|
|
|
|
/*
|
|
* When issuing a POLICY_REPLACE the policy needs to make a callback to
|
|
* lock the block being demoted. This doesn't need to occur during a
|
|
* writeback operation since the block remains in the cache.
|
|
*/
|
|
struct policy_locker;
|
|
typedef int (*policy_lock_fn)(struct policy_locker *l, dm_oblock_t oblock);
|
|
|
|
struct policy_locker {
|
|
policy_lock_fn fn;
|
|
};
|
|
|
|
/*
|
|
* This is the instruction passed back to the core target.
|
|
*/
|
|
struct policy_result {
|
|
enum policy_operation op;
|
|
dm_oblock_t old_oblock; /* POLICY_REPLACE */
|
|
dm_cblock_t cblock; /* POLICY_HIT, POLICY_NEW, POLICY_REPLACE */
|
|
};
|
|
|
|
/*
|
|
* The cache policy object. Just a bunch of methods. It is envisaged that
|
|
* this structure will be embedded in a bigger, policy specific structure
|
|
* (ie. use container_of()).
|
|
*/
|
|
struct dm_cache_policy {
|
|
|
|
/*
|
|
* FIXME: make it clear which methods are optional, and which may
|
|
* block.
|
|
*/
|
|
|
|
/*
|
|
* Destroys this object.
|
|
*/
|
|
void (*destroy)(struct dm_cache_policy *p);
|
|
|
|
/*
|
|
* See large comment above.
|
|
*
|
|
* oblock - the origin block we're interested in.
|
|
*
|
|
* can_block - indicates whether the current thread is allowed to
|
|
* block. -EWOULDBLOCK returned if it can't and would.
|
|
*
|
|
* can_migrate - gives permission for POLICY_NEW or POLICY_REPLACE
|
|
* instructions. If denied and the policy would have
|
|
* returned one of these instructions it should
|
|
* return -EWOULDBLOCK.
|
|
*
|
|
* discarded_oblock - indicates whether the whole origin block is
|
|
* in a discarded state (FIXME: better to tell the
|
|
* policy about this sooner, so it can recycle that
|
|
* cache block if it wants.)
|
|
* bio - the bio that triggered this call.
|
|
* result - gets filled in with the instruction.
|
|
*
|
|
* May only return 0, or -EWOULDBLOCK (if !can_migrate)
|
|
*/
|
|
int (*map)(struct dm_cache_policy *p, dm_oblock_t oblock,
|
|
bool can_block, bool can_migrate, bool discarded_oblock,
|
|
struct bio *bio, struct policy_locker *locker,
|
|
struct policy_result *result);
|
|
|
|
/*
|
|
* Sometimes we want to see if a block is in the cache, without
|
|
* triggering any update of stats. (ie. it's not a real hit).
|
|
*
|
|
* Must not block.
|
|
*
|
|
* Returns 0 if in cache, -ENOENT if not, < 0 for other errors
|
|
* (-EWOULDBLOCK would be typical).
|
|
*/
|
|
int (*lookup)(struct dm_cache_policy *p, dm_oblock_t oblock, dm_cblock_t *cblock);
|
|
|
|
void (*set_dirty)(struct dm_cache_policy *p, dm_oblock_t oblock);
|
|
void (*clear_dirty)(struct dm_cache_policy *p, dm_oblock_t oblock);
|
|
|
|
/*
|
|
* Called when a cache target is first created. Used to load a
|
|
* mapping from the metadata device into the policy.
|
|
*/
|
|
int (*load_mapping)(struct dm_cache_policy *p, dm_oblock_t oblock,
|
|
dm_cblock_t cblock, uint32_t hint, bool hint_valid);
|
|
|
|
/*
|
|
* Gets the hint for a given cblock. Called in a single threaded
|
|
* context. So no locking required.
|
|
*/
|
|
uint32_t (*get_hint)(struct dm_cache_policy *p, dm_cblock_t cblock);
|
|
|
|
/*
|
|
* Override functions used on the error paths of the core target.
|
|
* They must succeed.
|
|
*/
|
|
void (*remove_mapping)(struct dm_cache_policy *p, dm_oblock_t oblock);
|
|
void (*force_mapping)(struct dm_cache_policy *p, dm_oblock_t current_oblock,
|
|
dm_oblock_t new_oblock);
|
|
|
|
/*
|
|
* This is called via the invalidate_cblocks message. It is
|
|
* possible the particular cblock has already been removed due to a
|
|
* write io in passthrough mode. In which case this should return
|
|
* -ENODATA.
|
|
*/
|
|
int (*remove_cblock)(struct dm_cache_policy *p, dm_cblock_t cblock);
|
|
|
|
/*
|
|
* Provide a dirty block to be written back by the core target. If
|
|
* critical_only is set then the policy should only provide work if
|
|
* it urgently needs it.
|
|
*
|
|
* Returns:
|
|
*
|
|
* 0 and @cblock,@oblock: block to write back provided
|
|
*
|
|
* -ENODATA: no dirty blocks available
|
|
*/
|
|
int (*writeback_work)(struct dm_cache_policy *p, dm_oblock_t *oblock, dm_cblock_t *cblock,
|
|
bool critical_only);
|
|
|
|
/*
|
|
* How full is the cache?
|
|
*/
|
|
dm_cblock_t (*residency)(struct dm_cache_policy *p);
|
|
|
|
/*
|
|
* Because of where we sit in the block layer, we can be asked to
|
|
* map a lot of little bios that are all in the same block (no
|
|
* queue merging has occurred). To stop the policy being fooled by
|
|
* these, the core target sends regular tick() calls to the policy.
|
|
* The policy should only count an entry as hit once per tick.
|
|
*/
|
|
void (*tick)(struct dm_cache_policy *p, bool can_block);
|
|
|
|
/*
|
|
* Configuration.
|
|
*/
|
|
int (*emit_config_values)(struct dm_cache_policy *p, char *result,
|
|
unsigned maxlen, ssize_t *sz_ptr);
|
|
int (*set_config_value)(struct dm_cache_policy *p,
|
|
const char *key, const char *value);
|
|
|
|
/*
|
|
* Book keeping ptr for the policy register, not for general use.
|
|
*/
|
|
void *private;
|
|
};
|
|
|
|
/*----------------------------------------------------------------*/
|
|
|
|
/*
|
|
* We maintain a little register of the different policy types.
|
|
*/
|
|
#define CACHE_POLICY_NAME_SIZE 16
|
|
#define CACHE_POLICY_VERSION_SIZE 3
|
|
|
|
struct dm_cache_policy_type {
|
|
/* For use by the register code only. */
|
|
struct list_head list;
|
|
|
|
/*
|
|
* Policy writers should fill in these fields. The name field is
|
|
* what gets passed on the target line to select your policy.
|
|
*/
|
|
char name[CACHE_POLICY_NAME_SIZE];
|
|
unsigned version[CACHE_POLICY_VERSION_SIZE];
|
|
|
|
/*
|
|
* For use by an alias dm_cache_policy_type to point to the
|
|
* real dm_cache_policy_type.
|
|
*/
|
|
struct dm_cache_policy_type *real;
|
|
|
|
/*
|
|
* Policies may store a hint for each each cache block.
|
|
* Currently the size of this hint must be 0 or 4 bytes but we
|
|
* expect to relax this in future.
|
|
*/
|
|
size_t hint_size;
|
|
|
|
struct module *owner;
|
|
struct dm_cache_policy *(*create)(dm_cblock_t cache_size,
|
|
sector_t origin_size,
|
|
sector_t block_size);
|
|
};
|
|
|
|
int dm_cache_policy_register(struct dm_cache_policy_type *type);
|
|
void dm_cache_policy_unregister(struct dm_cache_policy_type *type);
|
|
|
|
/*----------------------------------------------------------------*/
|
|
|
|
#endif /* DM_CACHE_POLICY_H */
|