xref: /linux/include/linux/dm-bufio.h (revision 07f0148aafe8c95a3a76cd59e9e75b4d78d1d31d) 
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
168