drivers/md/dm-cache-policy.h

0001 /*
0002  * Copyright (C) 2012 Red Hat. All rights reserved.
0003  *
0004  * This file is released under the GPL.
0005  */
0006
0007 #ifndef DM_CACHE_POLICY_H
0008 #define DM_CACHE_POLICY_H
0009
0010 #include "dm-cache-block-types.h"
0011
0012 #include <linux/device-mapper.h>
0013
0014 /*----------------------------------------------------------------*/
0015
0016 /*
0017  * The cache policy makes the important decisions about which blocks get to
0018  * live on the faster cache device.
0019  */
0020 enum policy_operation {
0021     POLICY_PROMOTE,
0022     POLICY_DEMOTE,
0023     POLICY_WRITEBACK
0024 };
0025
0026 /*
0027  * This is the instruction passed back to the core target.
0028  */
0029 struct policy_work {
0030     enum policy_operation op;
0031     dm_oblock_t oblock;
0032     dm_cblock_t cblock;
0033 };
0034
0035 /*
0036  * The cache policy object.  It is envisaged that this structure will be
0037  * embedded in a bigger, policy specific structure (ie. use container_of()).
0038  */
0039 struct dm_cache_policy {
0040     /*
0041      * Destroys this object.
0042      */
0043     void (*destroy)(struct dm_cache_policy *p);
0044
0045     /*
0046      * Find the location of a block.
0047      *
0048      * Must not block.
0049      *
0050      * Returns 0 if in cache (cblock will be set), -ENOENT if not, < 0 for
0051      * other errors (-EWOULDBLOCK would be typical).  data_dir should be
0052      * READ or WRITE. fast_copy should be set if migrating this block would
0053      * be 'cheap' somehow (eg, discarded data). background_queued will be set
0054      * if a migration has just been queued.
0055      */
0056     int (*lookup)(struct dm_cache_policy *p, dm_oblock_t oblock, dm_cblock_t *cblock,
0057               int data_dir, bool fast_copy, bool *background_queued);
0058
0059     /*
0060      * Sometimes the core target can optimise a migration, eg, the
0061      * block may be discarded, or the bio may cover an entire block.
0062      * In order to optimise it needs the migration immediately though
0063      * so it knows to do something different with the bio.
0064      *
0065      * This method is optional (policy-internal will fallback to using
0066      * lookup).
0067      */
0068     int (*lookup_with_work)(struct dm_cache_policy *p,
0069                 dm_oblock_t oblock, dm_cblock_t *cblock,
0070                 int data_dir, bool fast_copy,
0071                 struct policy_work **work);
0072
0073     /*
0074      * Retrieves background work.  Returns -ENODATA when there's no
0075      * background work.
0076      */
0077     int (*get_background_work)(struct dm_cache_policy *p, bool idle,
0078                        struct policy_work **result);
0079
0080     /*
0081      * You must pass in the same work pointer that you were given, not
0082      * a copy.
0083      */
0084     void (*complete_background_work)(struct dm_cache_policy *p,
0085                      struct policy_work *work,
0086                      bool success);
0087
0088     void (*set_dirty)(struct dm_cache_policy *p, dm_cblock_t cblock);
0089     void (*clear_dirty)(struct dm_cache_policy *p, dm_cblock_t cblock);
0090
0091     /*
0092      * Called when a cache target is first created.  Used to load a
0093      * mapping from the metadata device into the policy.
0094      */
0095     int (*load_mapping)(struct dm_cache_policy *p, dm_oblock_t oblock,
0096                 dm_cblock_t cblock, bool dirty,
0097                 uint32_t hint, bool hint_valid);
0098
0099     /*
0100      * Drops the mapping, irrespective of whether it's clean or dirty.
0101      * Returns -ENODATA if cblock is not mapped.
0102      */
0103     int (*invalidate_mapping)(struct dm_cache_policy *p, dm_cblock_t cblock);
0104
0105     /*
0106      * Gets the hint for a given cblock.  Called in a single threaded
0107      * context.  So no locking required.
0108      */
0109     uint32_t (*get_hint)(struct dm_cache_policy *p, dm_cblock_t cblock);
0110
0111     /*
0112      * How full is the cache?
0113      */
0114     dm_cblock_t (*residency)(struct dm_cache_policy *p);
0115
0116     /*
0117      * Because of where we sit in the block layer, we can be asked to
0118      * map a lot of little bios that are all in the same block (no
0119      * queue merging has occurred).  To stop the policy being fooled by
0120      * these, the core target sends regular tick() calls to the policy.
0121      * The policy should only count an entry as hit once per tick.
0122      *
0123      * This method is optional.
0124      */
0125     void (*tick)(struct dm_cache_policy *p, bool can_block);
0126
0127     /*
0128      * Configuration.
0129      */
0130     int (*emit_config_values)(struct dm_cache_policy *p, char *result,
0131                   unsigned maxlen, ssize_t *sz_ptr);
0132     int (*set_config_value)(struct dm_cache_policy *p,
0133                 const char *key, const char *value);
0134
0135     void (*allow_migrations)(struct dm_cache_policy *p, bool allow);
0136
0137     /*
0138      * Book keeping ptr for the policy register, not for general use.
0139      */
0140     void *private;
0141 };
0142
0143 /*----------------------------------------------------------------*/
0144
0145 /*
0146  * We maintain a little register of the different policy types.
0147  */
0148 #define CACHE_POLICY_NAME_SIZE 16
0149 #define CACHE_POLICY_VERSION_SIZE 3
0150
0151 struct dm_cache_policy_type {
0152     /* For use by the register code only. */
0153     struct list_head list;
0154
0155     /*
0156      * Policy writers should fill in these fields.  The name field is
0157      * what gets passed on the target line to select your policy.
0158      */
0159     char name[CACHE_POLICY_NAME_SIZE];
0160     unsigned version[CACHE_POLICY_VERSION_SIZE];
0161
0162     /*
0163      * For use by an alias dm_cache_policy_type to point to the
0164      * real dm_cache_policy_type.
0165      */
0166     struct dm_cache_policy_type *real;
0167
0168     /*
0169      * Policies may store a hint for each each cache block.
0170      * Currently the size of this hint must be 0 or 4 bytes but we
0171      * expect to relax this in future.
0172      */
0173     size_t hint_size;
0174
0175     struct module *owner;
0176     struct dm_cache_policy *(*create)(dm_cblock_t cache_size,
0177                       sector_t origin_size,
0178                       sector_t block_size);
0179 };
0180
0181 int dm_cache_policy_register(struct dm_cache_policy_type *type);
0182 void dm_cache_policy_unregister(struct dm_cache_policy_type *type);
0183
0184 /*----------------------------------------------------------------*/
0185
0186 #endif  /* DM_CACHE_POLICY_H */