1 /*
2 * Copyright (C) 2001 Sistina Software (UK) Limited.
3 * Copyright (C) 2004-2008 Red Hat, Inc. All rights reserved.
4 *
5 * This file is released under the LGPL.
6 */
7
8 #ifndef _LINUX_DEVICE_MAPPER_H
9 #define _LINUX_DEVICE_MAPPER_H
10
11 #include <linux/bio.h>
12 #include <linux/blkdev.h>
13
14 struct dm_dev;
15 struct dm_target;
16 struct dm_table;
17 struct mapped_device;
18 struct bio_vec;
19
20 typedef enum { STATUSTYPE_INFO, STATUSTYPE_TABLE } status_type_t;
21
22 union map_info {
23 void *ptr;
24 unsigned long long ll;
25 unsigned target_request_nr;
26 };
27
28 /*
29 * In the constructor the target parameter will already have the
30 * table, type, begin and len fields filled in.
31 */
32 typedef int (*dm_ctr_fn) (struct dm_target *target,
33 unsigned int argc, char **argv);
34
35 /*
36 * The destructor doesn't need to free the dm_target, just
37 * anything hidden ti->private.
38 */
39 typedef void (*dm_dtr_fn) (struct dm_target *ti);
40
41 /*
42 * The map function must return:
43 * < 0: error
44 * = 0: The target will handle the io by resubmitting it later
45 * = 1: simple remap complete
46 * = 2: The target wants to push back the io
47 */
48 typedef int (*dm_map_fn) (struct dm_target *ti, struct bio *bio,
49 union map_info *map_context);
50 typedef int (*dm_map_request_fn) (struct dm_target *ti, struct request *clone,
51 union map_info *map_context);
52
53 /*
54 * Returns:
55 * < 0 : error (currently ignored)
56 * 0 : ended successfully
57 * 1 : for some reason the io has still not completed (eg,
58 * multipath target might want to requeue a failed io).
59 * 2 : The target wants to push back the io
60 */
61 typedef int (*dm_endio_fn) (struct dm_target *ti,
62 struct bio *bio, int error,
63 union map_info *map_context);
64 typedef int (*dm_request_endio_fn) (struct dm_target *ti,
65 struct request *clone, int error,
66 union map_info *map_context);
67
68 typedef void (*dm_flush_fn) (struct dm_target *ti);
69 typedef void (*dm_presuspend_fn) (struct dm_target *ti);
70 typedef void (*dm_postsuspend_fn) (struct dm_target *ti);
71 typedef int (*dm_preresume_fn) (struct dm_target *ti);
72 typedef void (*dm_resume_fn) (struct dm_target *ti);
73
74 typedef int (*dm_status_fn) (struct dm_target *ti, status_type_t status_type,
75 char *result, unsigned int maxlen);
76
77 typedef int (*dm_message_fn) (struct dm_target *ti, unsigned argc, char **argv);
78
79 typedef int (*dm_ioctl_fn) (struct dm_target *ti, unsigned int cmd,
80 unsigned long arg);
81
82 typedef int (*dm_merge_fn) (struct dm_target *ti, struct bvec_merge_data *bvm,
83 struct bio_vec *biovec, int max_size);
84
85 typedef int (*iterate_devices_callout_fn) (struct dm_target *ti,
86 struct dm_dev *dev,
87 sector_t start, sector_t len,
88 void *data);
89
90 typedef int (*dm_iterate_devices_fn) (struct dm_target *ti,
91 iterate_devices_callout_fn fn,
92 void *data);
93
94 typedef void (*dm_io_hints_fn) (struct dm_target *ti,
95 struct queue_limits *limits);
96
97 /*
98 * Returns:
99 * 0: The target can handle the next I/O immediately.
100 * 1: The target can't handle the next I/O immediately.
101 */
102 typedef int (*dm_busy_fn) (struct dm_target *ti);
103
104 void dm_error(const char *message);
105
106 /*
107 * Combine device limits.
108 */
109 int dm_set_device_limits(struct dm_target *ti, struct dm_dev *dev,
110 sector_t start, sector_t len, void *data);
111
112 struct dm_dev {
113 struct block_device *bdev;
114 fmode_t mode;
115 char name[16];
116 };
117
118 /*
119 * Constructors should call these functions to ensure destination devices
120 * are opened/closed correctly.
121 */
122 int dm_get_device(struct dm_target *ti, const char *path, fmode_t mode,
123 struct dm_dev **result);
124 void dm_put_device(struct dm_target *ti, struct dm_dev *d);
125
126 /*
127 * Information about a target type
128 */
129
130 /*
131 * Target features
132 */
133
134 struct target_type {
135 uint64_t features;
136 const char *name;
137 struct module *module;
138 unsigned version[3];
139 dm_ctr_fn ctr;
140 dm_dtr_fn dtr;
141 dm_map_fn map;
142 dm_map_request_fn map_rq;
143 dm_endio_fn end_io;
144 dm_request_endio_fn rq_end_io;
145 dm_flush_fn flush;
146 dm_presuspend_fn presuspend;
147 dm_postsuspend_fn postsuspend;
148 dm_preresume_fn preresume;
149 dm_resume_fn resume;
150 dm_status_fn status;
151 dm_message_fn message;
152 dm_ioctl_fn ioctl;
153 dm_merge_fn merge;
154 dm_busy_fn busy;
155 dm_iterate_devices_fn iterate_devices;
156 dm_io_hints_fn io_hints;
157
158 /* For internal device-mapper use. */
159 struct list_head list;
160 };
161
162 struct dm_target {
163 struct dm_table *table;
164 struct target_type *type;
165
166 /* target limits */
167 sector_t begin;
168 sector_t len;
169
170 /* Always a power of 2 */
171 sector_t split_io;
172
173 /*
174 * A number of zero-length barrier requests that will be submitted
175 * to the target for the purpose of flushing cache.
176 *
177 * The request number will be placed in union map_info->target_request_nr.
178 * It is a responsibility of the target driver to remap these requests
179 * to the real underlying devices.
180 */
181 unsigned num_flush_requests;
182
183 /*
184 * The number of discard requests that will be submitted to the
185 * target. map_info->request_nr is used just like num_flush_requests.
186 */
187 unsigned num_discard_requests;
188
189 /* target specific data */
190 void *private;
191
192 /* Used to provide an error string from the ctr */
193 char *error;
194 };
195
196 /* Each target can link one of these into the table */
197 struct dm_target_callbacks {
198 struct list_head list;
199 int (*congested_fn) (struct dm_target_callbacks *, int);
200 };
201
202 int dm_register_target(struct target_type *t);
203 void dm_unregister_target(struct target_type *t);
204
205 /*-----------------------------------------------------------------
206 * Functions for creating and manipulating mapped devices.
207 * Drop the reference with dm_put when you finish with the object.
208 *---------------------------------------------------------------*/
209
210 /*
211 * DM_ANY_MINOR chooses the next available minor number.
212 */
213 #define DM_ANY_MINOR (-1)
214 int dm_create(int minor, struct mapped_device **md);
215
216 /*
217 * Reference counting for md.
218 */
219 struct mapped_device *dm_get_md(dev_t dev);
220 void dm_get(struct mapped_device *md);
221 void dm_put(struct mapped_device *md);
222
223 /*
224 * An arbitrary pointer may be stored alongside a mapped device.
225 */
226 void dm_set_mdptr(struct mapped_device *md, void *ptr);
227 void *dm_get_mdptr(struct mapped_device *md);
228
229 /*
230 * A device can still be used while suspended, but I/O is deferred.
231 */
232 int dm_suspend(struct mapped_device *md, unsigned suspend_flags);
233 int dm_resume(struct mapped_device *md);
234
235 /*
236 * Event functions.
237 */
238 uint32_t dm_get_event_nr(struct mapped_device *md);
239 int dm_wait_event(struct mapped_device *md, int event_nr);
240 uint32_t dm_next_uevent_seq(struct mapped_device *md);
241 void dm_uevent_add(struct mapped_device *md, struct list_head *elist);
242
243 /*
244 * Info functions.
245 */
246 const char *dm_device_name(struct mapped_device *md);
247 int dm_copy_name_and_uuid(struct mapped_device *md, char *name, char *uuid);
248 struct gendisk *dm_disk(struct mapped_device *md);
249 int dm_suspended(struct dm_target *ti);
250 int dm_noflush_suspending(struct dm_target *ti);
251 union map_info *dm_get_mapinfo(struct bio *bio);
252 union map_info *dm_get_rq_mapinfo(struct request *rq);
253
254 /*
255 * Geometry functions.
256 */
257 int dm_get_geometry(struct mapped_device *md, struct hd_geometry *geo);
258 int dm_set_geometry(struct mapped_device *md, struct hd_geometry *geo);
259
260
261 /*-----------------------------------------------------------------
262 * Functions for manipulating device-mapper tables.
263 *---------------------------------------------------------------*/
264
265 /*
266 * First create an empty table.
267 */
268 int dm_table_create(struct dm_table **result, fmode_t mode,
269 unsigned num_targets, struct mapped_device *md);
270
271 /*
272 * Then call this once for each target.
273 */
274 int dm_table_add_target(struct dm_table *t, const char *type,
275 sector_t start, sector_t len, char *params);
276
277 /*
278 * Target_ctr should call this if it needs to add any callbacks.
279 */
280 void dm_table_add_target_callbacks(struct dm_table *t, struct dm_target_callbacks *cb);
281
282 /*
283 * Finally call this to make the table ready for use.
284 */
285 int dm_table_complete(struct dm_table *t);
286
287 /*
288 * Table reference counting.
289 */
290 struct dm_table *dm_get_live_table(struct mapped_device *md);
291 void dm_table_get(struct dm_table *t);
292 void dm_table_put(struct dm_table *t);
293
294 /*
295 * Queries
296 */
297 sector_t dm_table_get_size(struct dm_table *t);
298 unsigned int dm_table_get_num_targets(struct dm_table *t);
299 fmode_t dm_table_get_mode(struct dm_table *t);
300 struct mapped_device *dm_table_get_md(struct dm_table *t);
301
302 /*
303 * Trigger an event.
304 */
305 void dm_table_event(struct dm_table *t);
306
307 /*
308 * The device must be suspended before calling this method.
309 * Returns the previous table, which the caller must destroy.
310 */
311 struct dm_table *dm_swap_table(struct mapped_device *md,
312 struct dm_table *t);
313
314 /*
315 * A wrapper around vmalloc.
316 */
317 void *dm_vcalloc(unsigned long nmemb, unsigned long elem_size);
318
319 /*-----------------------------------------------------------------
320 * Macros.
321 *---------------------------------------------------------------*/
322 #define DM_NAME "device-mapper"
323
324 #define DMCRIT(f, arg...) \
325 printk(KERN_CRIT DM_NAME ": " DM_MSG_PREFIX ": " f "\n", ## arg)
326
327 #define DMERR(f, arg...) \
328 printk(KERN_ERR DM_NAME ": " DM_MSG_PREFIX ": " f "\n", ## arg)
329 #define DMERR_LIMIT(f, arg...) \
330 do { \
331 if (printk_ratelimit()) \
332 printk(KERN_ERR DM_NAME ": " DM_MSG_PREFIX ": " \
333 f "\n", ## arg); \
334 } while (0)
335
336 #define DMWARN(f, arg...) \
337 printk(KERN_WARNING DM_NAME ": " DM_MSG_PREFIX ": " f "\n", ## arg)
338 #define DMWARN_LIMIT(f, arg...) \
339 do { \
340 if (printk_ratelimit()) \
341 printk(KERN_WARNING DM_NAME ": " DM_MSG_PREFIX ": " \
342 f "\n", ## arg); \
343 } while (0)
344
345 #define DMINFO(f, arg...) \
346 printk(KERN_INFO DM_NAME ": " DM_MSG_PREFIX ": " f "\n", ## arg)
347 #define DMINFO_LIMIT(f, arg...) \
348 do { \
349 if (printk_ratelimit()) \
350 printk(KERN_INFO DM_NAME ": " DM_MSG_PREFIX ": " f \
351 "\n", ## arg); \
352 } while (0)
353
354 #ifdef CONFIG_DM_DEBUG
355 # define DMDEBUG(f, arg...) \
356 printk(KERN_DEBUG DM_NAME ": " DM_MSG_PREFIX " DEBUG: " f "\n", ## arg)
357 # define DMDEBUG_LIMIT(f, arg...) \
358 do { \
359 if (printk_ratelimit()) \
360 printk(KERN_DEBUG DM_NAME ": " DM_MSG_PREFIX ": " f \
361 "\n", ## arg); \
362 } while (0)
363 #else
364 # define DMDEBUG(f, arg...) do {} while (0)
365 # define DMDEBUG_LIMIT(f, arg...) do {} while (0)
366 #endif
367
368 #define DMEMIT(x...) sz += ((sz >= maxlen) ? \
369 0 : scnprintf(result + sz, maxlen - sz, x))
370
371 #define SECTOR_SHIFT 9
372
373 /*
374 * Definitions of return values from target end_io function.
375 */
376 #define DM_ENDIO_INCOMPLETE 1
377 #define DM_ENDIO_REQUEUE 2
378
379 /*
380 * Definitions of return values from target map function.
381 */
382 #define DM_MAPIO_SUBMITTED 0
383 #define DM_MAPIO_REMAPPED 1
384 #define DM_MAPIO_REQUEUE DM_ENDIO_REQUEUE
385
386 /*
387 * Ceiling(n / sz)
388 */
389 #define dm_div_up(n, sz) (((n) + (sz) - 1) / (sz))
390
391 #define dm_sector_div_up(n, sz) ( \
392 { \
393 sector_t _r = ((n) + (sz) - 1); \
394 sector_div(_r, (sz)); \
395 _r; \
396 } \
397 )
398
399 /*
400 * ceiling(n / size) * size
401 */
402 #define dm_round_up(n, sz) (dm_div_up((n), (sz)) * (sz))
403
404 #define dm_array_too_big(fixed, obj, num) \
405 ((num) > (UINT_MAX - (fixed)) / (obj))
406
407 /*
408 * Sector offset taken relative to the start of the target instead of
409 * relative to the start of the device.
410 */
411 #define dm_target_offset(ti, sector) ((sector) - (ti)->begin)
412
to_sector(unsigned long n)413 static inline sector_t to_sector(unsigned long n)
414 {
415 return (n >> SECTOR_SHIFT);
416 }
417
to_bytes(sector_t n)418 static inline unsigned long to_bytes(sector_t n)
419 {
420 return (n << SECTOR_SHIFT);
421 }
422
423 /*-----------------------------------------------------------------
424 * Helper for block layer and dm core operations
425 *---------------------------------------------------------------*/
426 void dm_dispatch_request(struct request *rq);
427 void dm_requeue_unmapped_request(struct request *rq);
428 void dm_kill_unmapped_request(struct request *rq, int error);
429 int dm_underlying_device_busy(struct request_queue *q);
430
431 #endif /* _LINUX_DEVICE_MAPPER_H */
432