include/linux/dm-bufio.h

   1 /*
   2  * Copyright (C) 2009-2011 Red Hat, Inc.
   3  *
   4  * Author: Mikulas Patocka <mpatocka@redhat.com>
   5  *
   6  * This file is released under the GPL.
   7  */
   8
   9 #ifndef _LINUX_DM_BUFIO_H
  10 #define _LINUX_DM_BUFIO_H
  11
  12 #include <linux/blkdev.h>
  13 #include <linux/types.h>
  14
  15 /*----------------------------------------------------------------*/
  16
  17 struct dm_bufio_client;
  18 struct dm_buffer;
  19
  20 /*
  21  * Flags for dm_bufio_client_create
  22  */
  23 #define DM_BUFIO_CLIENT_NO_SLEEP 0x1
  24
  25 /*
  26  * Create a buffered IO cache on a given device
  27  */
  28 struct dm_bufio_client *
  29 dm_bufio_client_create(struct block_device *bdev, unsigned block_size,
  30                        unsigned reserved_buffers, unsigned aux_size,
  31                        void (*alloc_callback)(struct dm_buffer *),
  32                        void (*write_callback)(struct dm_buffer *),
  33                        unsigned int flags);
  34
  35 /*
  36  * Release a buffered IO cache.
  37  */
  38 void dm_bufio_client_destroy(struct dm_bufio_client *c);
  39
  40 /*
  41  * Set the sector range.
  42  * When this function is called, there must be no I/O in progress on the bufio
  43  * client.
  44  */
  45 void dm_bufio_set_sector_offset(struct dm_bufio_client *c, sector_t start);
  46
  47 /*
  48  * WARNING: to avoid deadlocks, these conditions are observed:
  49  *
  50  * - At most one thread can hold at most "reserved_buffers" simultaneously.
  51  * - Each other threads can hold at most one buffer.
  52  * - Threads which call only dm_bufio_get can hold unlimited number of
  53  *   buffers.
  54  */
  55
  56 /*
  57  * Read a given block from disk. Returns pointer to data.  Returns a
  58  * pointer to dm_buffer that can be used to release the buffer or to make
  59  * it dirty.
  60  */
  61 void *dm_bufio_read(struct dm_bufio_client *c, sector_t block,
  62                     struct dm_buffer **bp);
  63
  64 /*
  65  * Like dm_bufio_read, but return buffer from cache, don't read
  66  * it. If the buffer is not in the cache, return NULL.
  67  */
  68 void *dm_bufio_get(struct dm_bufio_client *c, sector_t block,
  69                    struct dm_buffer **bp);
  70
  71 /*
  72  * Like dm_bufio_read, but don't read anything from the disk.  It is
  73  * expected that the caller initializes the buffer and marks it dirty.
  74  */
  75 void *dm_bufio_new(struct dm_bufio_client *c, sector_t block,
  76                    struct dm_buffer **bp);
  77
  78 /*
  79  * Prefetch the specified blocks to the cache.
  80  * The function starts to read the blocks and returns without waiting for
  81  * I/O to finish.
  82  */
  83 void dm_bufio_prefetch(struct dm_bufio_client *c,
  84                        sector_t block, unsigned n_blocks);
  85
  86 /*
  87  * Release a reference obtained with dm_bufio_{read,get,new}. The data
  88  * pointer and dm_buffer pointer is no longer valid after this call.
  89  */
  90 void dm_bufio_release(struct dm_buffer *b);
  91
  92 /*
  93  * Mark a buffer dirty. It should be called after the buffer is modified.
  94  *
  95  * In case of memory pressure, the buffer may be written after
  96  * dm_bufio_mark_buffer_dirty, but before dm_bufio_write_dirty_buffers.  So
  97  * dm_bufio_write_dirty_buffers guarantees that the buffer is on-disk but
  98  * the actual writing may occur earlier.
  99  */
 100 void dm_bufio_mark_buffer_dirty(struct dm_buffer *b);
 101
 102 /*
 103  * Mark a part of the buffer dirty.
 104  *
 105  * The specified part of the buffer is scheduled to be written. dm-bufio may
 106  * write the specified part of the buffer or it may write a larger superset.
 107  */
 108 void dm_bufio_mark_partial_buffer_dirty(struct dm_buffer *b,
 109                                         unsigned start, unsigned end);
 110
 111 /*
 112  * Initiate writing of dirty buffers, without waiting for completion.
 113  */
 114 void dm_bufio_write_dirty_buffers_async(struct dm_bufio_client *c);
 115
 116 /*
 117  * Write all dirty buffers. Guarantees that all dirty buffers created prior
 118  * to this call are on disk when this call exits.
 119  */
 120 int dm_bufio_write_dirty_buffers(struct dm_bufio_client *c);
 121
 122 /*
 123  * Send an empty write barrier to the device to flush hardware disk cache.
 124  */
 125 int dm_bufio_issue_flush(struct dm_bufio_client *c);
 126
 127 /*
 128  * Send a discard request to the underlying device.
 129  */
 130 int dm_bufio_issue_discard(struct dm_bufio_client *c, sector_t block, sector_t count);
 131
 132 /*
 133  * Like dm_bufio_release but also move the buffer to the new
 134  * block. dm_bufio_write_dirty_buffers is needed to commit the new block.
 135  */
 136 void dm_bufio_release_move(struct dm_buffer *b, sector_t new_block);
 137
 138 /*
 139  * Free the given buffer.
 140  * This is just a hint, if the buffer is in use or dirty, this function
 141  * does nothing.
 142  */
 143 void dm_bufio_forget(struct dm_bufio_client *c, sector_t block);
 144
 145 /*
 146  * Free the given range of buffers.
 147  * This is just a hint, if the buffer is in use or dirty, this function
 148  * does nothing.
 149  */
 150 void dm_bufio_forget_buffers(struct dm_bufio_client *c, sector_t block, sector_t n_blocks);
 151
 152 /*
 153  * Set the minimum number of buffers before cleanup happens.
 154  */
 155 void dm_bufio_set_minimum_buffers(struct dm_bufio_client *c, unsigned n);
 156
 157 unsigned dm_bufio_get_block_size(struct dm_bufio_client *c);
 158 sector_t dm_bufio_get_device_size(struct dm_bufio_client *c);
 159 struct dm_io_client *dm_bufio_get_dm_io_client(struct dm_bufio_client *c);
 160 sector_t dm_bufio_get_block_number(struct dm_buffer *b);
 161 void *dm_bufio_get_block_data(struct dm_buffer *b);
 162 void *dm_bufio_get_aux_data(struct dm_buffer *b);
 163 struct dm_bufio_client *dm_bufio_get_client(struct dm_buffer *b);
 164
 165 /*----------------------------------------------------------------*/
 166
 167 #endif