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 DM_BUFIO_H
10#define DM_BUFIO_H
11
12#include <linux/blkdev.h>
13#include <linux/types.h>
14
15/*----------------------------------------------------------------*/
16
17struct dm_bufio_client;
18struct dm_buffer;
19
20/*
21 * Create a buffered IO cache on a given device
22 */
23struct dm_bufio_client *
24dm_bufio_client_create(struct block_device *bdev, unsigned block_size,
25		       unsigned reserved_buffers, unsigned aux_size,
26		       void (*alloc_callback)(struct dm_buffer *),
27		       void (*write_callback)(struct dm_buffer *));
28
29/*
30 * Release a buffered IO cache.
31 */
32void dm_bufio_client_destroy(struct dm_bufio_client *c);
33
34/*
35 * WARNING: to avoid deadlocks, these conditions are observed:
36 *
37 * - At most one thread can hold at most "reserved_buffers" simultaneously.
38 * - Each other threads can hold at most one buffer.
39 * - Threads which call only dm_bufio_get can hold unlimited number of
40 *   buffers.
41 */
42
43/*
44 * Read a given block from disk. Returns pointer to data.  Returns a
45 * pointer to dm_buffer that can be used to release the buffer or to make
46 * it dirty.
47 */
48void *dm_bufio_read(struct dm_bufio_client *c, sector_t block,
49		    struct dm_buffer **bp);
50
51/*
52 * Like dm_bufio_read, but return buffer from cache, don't read
53 * it. If the buffer is not in the cache, return NULL.
54 */
55void *dm_bufio_get(struct dm_bufio_client *c, sector_t block,
56		   struct dm_buffer **bp);
57
58/*
59 * Like dm_bufio_read, but don't read anything from the disk.  It is
60 * expected that the caller initializes the buffer and marks it dirty.
61 */
62void *dm_bufio_new(struct dm_bufio_client *c, sector_t block,
63		   struct dm_buffer **bp);
64
65/*
66 * Prefetch the specified blocks to the cache.
67 * The function starts to read the blocks and returns without waiting for
68 * I/O to finish.
69 */
70void dm_bufio_prefetch(struct dm_bufio_client *c,
71		       sector_t block, unsigned n_blocks);
72
73/*
74 * Release a reference obtained with dm_bufio_{read,get,new}. The data
75 * pointer and dm_buffer pointer is no longer valid after this call.
76 */
77void dm_bufio_release(struct dm_buffer *b);
78
79/*
80 * Mark a buffer dirty. It should be called after the buffer is modified.
81 *
82 * In case of memory pressure, the buffer may be written after
83 * dm_bufio_mark_buffer_dirty, but before dm_bufio_write_dirty_buffers.  So
84 * dm_bufio_write_dirty_buffers guarantees that the buffer is on-disk but
85 * the actual writing may occur earlier.
86 */
87void dm_bufio_mark_buffer_dirty(struct dm_buffer *b);
88
89/*
90 * Initiate writing of dirty buffers, without waiting for completion.
91 */
92void dm_bufio_write_dirty_buffers_async(struct dm_bufio_client *c);
93
94/*
95 * Write all dirty buffers. Guarantees that all dirty buffers created prior
96 * to this call are on disk when this call exits.
97 */
98int dm_bufio_write_dirty_buffers(struct dm_bufio_client *c);
99
100/*
101 * Send an empty write barrier to the device to flush hardware disk cache.
102 */
103int dm_bufio_issue_flush(struct dm_bufio_client *c);
104
105/*
106 * Like dm_bufio_release but also move the buffer to the new
107 * block. dm_bufio_write_dirty_buffers is needed to commit the new block.
108 */
109void dm_bufio_release_move(struct dm_buffer *b, sector_t new_block);
110
111/*
112 * Free the given buffer.
113 * This is just a hint, if the buffer is in use or dirty, this function
114 * does nothing.
115 */
116void dm_bufio_forget(struct dm_bufio_client *c, sector_t block);
117
118/*
119 * Set the minimum number of buffers before cleanup happens.
120 */
121void dm_bufio_set_minimum_buffers(struct dm_bufio_client *c, unsigned n);
122
123unsigned dm_bufio_get_block_size(struct dm_bufio_client *c);
124sector_t dm_bufio_get_device_size(struct dm_bufio_client *c);
125sector_t dm_bufio_get_block_number(struct dm_buffer *b);
126void *dm_bufio_get_block_data(struct dm_buffer *b);
127void *dm_bufio_get_aux_data(struct dm_buffer *b);
128struct dm_bufio_client *dm_bufio_get_client(struct dm_buffer *b);
129
130/*----------------------------------------------------------------*/
131
132#endif
133