Branch data Line data Source code
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 : : #include <linux/math64.h>
14 : : #include <linux/ratelimit.h>
15 : :
16 : : struct dm_dev;
17 : : struct dm_target;
18 : : struct dm_table;
19 : : struct mapped_device;
20 : : struct bio_vec;
21 : :
22 : : typedef enum { STATUSTYPE_INFO, STATUSTYPE_TABLE } status_type_t;
23 : :
24 : : union map_info {
25 : : void *ptr;
26 : : unsigned long long ll;
27 : : };
28 : :
29 : : /*
30 : : * In the constructor the target parameter will already have the
31 : : * table, type, begin and len fields filled in.
32 : : */
33 : : typedef int (*dm_ctr_fn) (struct dm_target *target,
34 : : unsigned int argc, char **argv);
35 : :
36 : : /*
37 : : * The destructor doesn't need to free the dm_target, just
38 : : * anything hidden ti->private.
39 : : */
40 : : typedef void (*dm_dtr_fn) (struct dm_target *ti);
41 : :
42 : : /*
43 : : * The map function must return:
44 : : * < 0: error
45 : : * = 0: The target will handle the io by resubmitting it later
46 : : * = 1: simple remap complete
47 : : * = 2: The target wants to push back the io
48 : : */
49 : : typedef int (*dm_map_fn) (struct dm_target *ti, struct bio *bio);
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 : : typedef int (*dm_request_endio_fn) (struct dm_target *ti,
64 : : struct request *clone, int error,
65 : : union map_info *map_context);
66 : :
67 : : typedef void (*dm_presuspend_fn) (struct dm_target *ti);
68 : : typedef void (*dm_postsuspend_fn) (struct dm_target *ti);
69 : : typedef int (*dm_preresume_fn) (struct dm_target *ti);
70 : : typedef void (*dm_resume_fn) (struct dm_target *ti);
71 : :
72 : : typedef void (*dm_status_fn) (struct dm_target *ti, status_type_t status_type,
73 : : unsigned status_flags, char *result, unsigned maxlen);
74 : :
75 : : typedef int (*dm_message_fn) (struct dm_target *ti, unsigned argc, char **argv);
76 : :
77 : : typedef int (*dm_ioctl_fn) (struct dm_target *ti, unsigned int cmd,
78 : : unsigned long arg);
79 : :
80 : : typedef int (*dm_merge_fn) (struct dm_target *ti, struct bvec_merge_data *bvm,
81 : : struct bio_vec *biovec, int max_size);
82 : :
83 : : /*
84 : : * These iteration functions are typically used to check (and combine)
85 : : * properties of underlying devices.
86 : : * E.g. Does at least one underlying device support flush?
87 : : * Does any underlying device not support WRITE_SAME?
88 : : *
89 : : * The callout function is called once for each contiguous section of
90 : : * an underlying device. State can be maintained in *data.
91 : : * Return non-zero to stop iterating through any further devices.
92 : : */
93 : : typedef int (*iterate_devices_callout_fn) (struct dm_target *ti,
94 : : struct dm_dev *dev,
95 : : sector_t start, sector_t len,
96 : : void *data);
97 : :
98 : : /*
99 : : * This function must iterate through each section of device used by the
100 : : * target until it encounters a non-zero return code, which it then returns.
101 : : * Returns zero if no callout returned non-zero.
102 : : */
103 : : typedef int (*dm_iterate_devices_fn) (struct dm_target *ti,
104 : : iterate_devices_callout_fn fn,
105 : : void *data);
106 : :
107 : : typedef void (*dm_io_hints_fn) (struct dm_target *ti,
108 : : struct queue_limits *limits);
109 : :
110 : : /*
111 : : * Returns:
112 : : * 0: The target can handle the next I/O immediately.
113 : : * 1: The target can't handle the next I/O immediately.
114 : : */
115 : : typedef int (*dm_busy_fn) (struct dm_target *ti);
116 : :
117 : : void dm_error(const char *message);
118 : :
119 : : /*
120 : : * Combine device limits.
121 : : */
122 : : int dm_set_device_limits(struct dm_target *ti, struct dm_dev *dev,
123 : : sector_t start, sector_t len, void *data);
124 : :
125 : : struct dm_dev {
126 : : struct block_device *bdev;
127 : : fmode_t mode;
128 : : char name[16];
129 : : };
130 : :
131 : : /*
132 : : * Constructors should call these functions to ensure destination devices
133 : : * are opened/closed correctly.
134 : : */
135 : : int dm_get_device(struct dm_target *ti, const char *path, fmode_t mode,
136 : : struct dm_dev **result);
137 : : void dm_put_device(struct dm_target *ti, struct dm_dev *d);
138 : :
139 : : /*
140 : : * Information about a target type
141 : : */
142 : :
143 : : struct target_type {
144 : : uint64_t features;
145 : : const char *name;
146 : : struct module *module;
147 : : unsigned version[3];
148 : : dm_ctr_fn ctr;
149 : : dm_dtr_fn dtr;
150 : : dm_map_fn map;
151 : : dm_map_request_fn map_rq;
152 : : dm_endio_fn end_io;
153 : : dm_request_endio_fn rq_end_io;
154 : : dm_presuspend_fn presuspend;
155 : : dm_postsuspend_fn postsuspend;
156 : : dm_preresume_fn preresume;
157 : : dm_resume_fn resume;
158 : : dm_status_fn status;
159 : : dm_message_fn message;
160 : : dm_ioctl_fn ioctl;
161 : : dm_merge_fn merge;
162 : : dm_busy_fn busy;
163 : : dm_iterate_devices_fn iterate_devices;
164 : : dm_io_hints_fn io_hints;
165 : :
166 : : /* For internal device-mapper use. */
167 : : struct list_head list;
168 : : };
169 : :
170 : : /*
171 : : * Target features
172 : : */
173 : :
174 : : /*
175 : : * Any table that contains an instance of this target must have only one.
176 : : */
177 : : #define DM_TARGET_SINGLETON 0x00000001
178 : : #define dm_target_needs_singleton(type) ((type)->features & DM_TARGET_SINGLETON)
179 : :
180 : : /*
181 : : * Indicates that a target does not support read-only devices.
182 : : */
183 : : #define DM_TARGET_ALWAYS_WRITEABLE 0x00000002
184 : : #define dm_target_always_writeable(type) \
185 : : ((type)->features & DM_TARGET_ALWAYS_WRITEABLE)
186 : :
187 : : /*
188 : : * Any device that contains a table with an instance of this target may never
189 : : * have tables containing any different target type.
190 : : */
191 : : #define DM_TARGET_IMMUTABLE 0x00000004
192 : : #define dm_target_is_immutable(type) ((type)->features & DM_TARGET_IMMUTABLE)
193 : :
194 : : /*
195 : : * Some targets need to be sent the same WRITE bio severals times so
196 : : * that they can send copies of it to different devices. This function
197 : : * examines any supplied bio and returns the number of copies of it the
198 : : * target requires.
199 : : */
200 : : typedef unsigned (*dm_num_write_bios_fn) (struct dm_target *ti, struct bio *bio);
201 : :
202 : : struct dm_target {
203 : : struct dm_table *table;
204 : : struct target_type *type;
205 : :
206 : : /* target limits */
207 : : sector_t begin;
208 : : sector_t len;
209 : :
210 : : /* If non-zero, maximum size of I/O submitted to a target. */
211 : : uint32_t max_io_len;
212 : :
213 : : /*
214 : : * A number of zero-length barrier bios that will be submitted
215 : : * to the target for the purpose of flushing cache.
216 : : *
217 : : * The bio number can be accessed with dm_bio_get_target_bio_nr.
218 : : * It is a responsibility of the target driver to remap these bios
219 : : * to the real underlying devices.
220 : : */
221 : : unsigned num_flush_bios;
222 : :
223 : : /*
224 : : * The number of discard bios that will be submitted to the target.
225 : : * The bio number can be accessed with dm_bio_get_target_bio_nr.
226 : : */
227 : : unsigned num_discard_bios;
228 : :
229 : : /*
230 : : * The number of WRITE SAME bios that will be submitted to the target.
231 : : * The bio number can be accessed with dm_bio_get_target_bio_nr.
232 : : */
233 : : unsigned num_write_same_bios;
234 : :
235 : : /*
236 : : * The minimum number of extra bytes allocated in each bio for the
237 : : * target to use. dm_per_bio_data returns the data location.
238 : : */
239 : : unsigned per_bio_data_size;
240 : :
241 : : /*
242 : : * If defined, this function is called to find out how many
243 : : * duplicate bios should be sent to the target when writing
244 : : * data.
245 : : */
246 : : dm_num_write_bios_fn num_write_bios;
247 : :
248 : : /* target specific data */
249 : : void *private;
250 : :
251 : : /* Used to provide an error string from the ctr */
252 : : char *error;
253 : :
254 : : /*
255 : : * Set if this target needs to receive flushes regardless of
256 : : * whether or not its underlying devices have support.
257 : : */
258 : : bool flush_supported:1;
259 : :
260 : : /*
261 : : * Set if this target needs to receive discards regardless of
262 : : * whether or not its underlying devices have support.
263 : : */
264 : : bool discards_supported:1;
265 : :
266 : : /*
267 : : * Set if the target required discard bios to be split
268 : : * on max_io_len boundary.
269 : : */
270 : : bool split_discard_bios:1;
271 : :
272 : : /*
273 : : * Set if this target does not return zeroes on discarded blocks.
274 : : */
275 : : bool discard_zeroes_data_unsupported:1;
276 : : };
277 : :
278 : : /* Each target can link one of these into the table */
279 : : struct dm_target_callbacks {
280 : : struct list_head list;
281 : : int (*congested_fn) (struct dm_target_callbacks *, int);
282 : : };
283 : :
284 : : /*
285 : : * For bio-based dm.
286 : : * One of these is allocated for each bio.
287 : : * This structure shouldn't be touched directly by target drivers.
288 : : * It is here so that we can inline dm_per_bio_data and
289 : : * dm_bio_from_per_bio_data
290 : : */
291 : : struct dm_target_io {
292 : : struct dm_io *io;
293 : : struct dm_target *ti;
294 : : union map_info info;
295 : : unsigned target_bio_nr;
296 : : struct bio clone;
297 : : };
298 : :
299 : : static inline void *dm_per_bio_data(struct bio *bio, size_t data_size)
300 : : {
301 : : return (char *)bio - offsetof(struct dm_target_io, clone) - data_size;
302 : : }
303 : :
304 : : static inline struct bio *dm_bio_from_per_bio_data(void *data, size_t data_size)
305 : : {
306 : : return (struct bio *)((char *)data + data_size + offsetof(struct dm_target_io, clone));
307 : : }
308 : :
309 : : static inline unsigned dm_bio_get_target_bio_nr(const struct bio *bio)
310 : : {
311 : 0 : return container_of(bio, struct dm_target_io, clone)->target_bio_nr;
312 : : }
313 : :
314 : : int dm_register_target(struct target_type *t);
315 : : void dm_unregister_target(struct target_type *t);
316 : :
317 : : /*
318 : : * Target argument parsing.
319 : : */
320 : : struct dm_arg_set {
321 : : unsigned argc;
322 : : char **argv;
323 : : };
324 : :
325 : : /*
326 : : * The minimum and maximum value of a numeric argument, together with
327 : : * the error message to use if the number is found to be outside that range.
328 : : */
329 : : struct dm_arg {
330 : : unsigned min;
331 : : unsigned max;
332 : : char *error;
333 : : };
334 : :
335 : : /*
336 : : * Validate the next argument, either returning it as *value or, if invalid,
337 : : * returning -EINVAL and setting *error.
338 : : */
339 : : int dm_read_arg(struct dm_arg *arg, struct dm_arg_set *arg_set,
340 : : unsigned *value, char **error);
341 : :
342 : : /*
343 : : * Process the next argument as the start of a group containing between
344 : : * arg->min and arg->max further arguments. Either return the size as
345 : : * *num_args or, if invalid, return -EINVAL and set *error.
346 : : */
347 : : int dm_read_arg_group(struct dm_arg *arg, struct dm_arg_set *arg_set,
348 : : unsigned *num_args, char **error);
349 : :
350 : : /*
351 : : * Return the current argument and shift to the next.
352 : : */
353 : : const char *dm_shift_arg(struct dm_arg_set *as);
354 : :
355 : : /*
356 : : * Move through num_args arguments.
357 : : */
358 : : void dm_consume_args(struct dm_arg_set *as, unsigned num_args);
359 : :
360 : : /*-----------------------------------------------------------------
361 : : * Functions for creating and manipulating mapped devices.
362 : : * Drop the reference with dm_put when you finish with the object.
363 : : *---------------------------------------------------------------*/
364 : :
365 : : /*
366 : : * DM_ANY_MINOR chooses the next available minor number.
367 : : */
368 : : #define DM_ANY_MINOR (-1)
369 : : int dm_create(int minor, struct mapped_device **md);
370 : :
371 : : /*
372 : : * Reference counting for md.
373 : : */
374 : : struct mapped_device *dm_get_md(dev_t dev);
375 : : void dm_get(struct mapped_device *md);
376 : : void dm_put(struct mapped_device *md);
377 : :
378 : : /*
379 : : * An arbitrary pointer may be stored alongside a mapped device.
380 : : */
381 : : void dm_set_mdptr(struct mapped_device *md, void *ptr);
382 : : void *dm_get_mdptr(struct mapped_device *md);
383 : :
384 : : /*
385 : : * A device can still be used while suspended, but I/O is deferred.
386 : : */
387 : : int dm_suspend(struct mapped_device *md, unsigned suspend_flags);
388 : : int dm_resume(struct mapped_device *md);
389 : :
390 : : /*
391 : : * Event functions.
392 : : */
393 : : uint32_t dm_get_event_nr(struct mapped_device *md);
394 : : int dm_wait_event(struct mapped_device *md, int event_nr);
395 : : uint32_t dm_next_uevent_seq(struct mapped_device *md);
396 : : void dm_uevent_add(struct mapped_device *md, struct list_head *elist);
397 : :
398 : : /*
399 : : * Info functions.
400 : : */
401 : : const char *dm_device_name(struct mapped_device *md);
402 : : int dm_copy_name_and_uuid(struct mapped_device *md, char *name, char *uuid);
403 : : struct gendisk *dm_disk(struct mapped_device *md);
404 : : int dm_suspended(struct dm_target *ti);
405 : : int dm_noflush_suspending(struct dm_target *ti);
406 : : union map_info *dm_get_mapinfo(struct bio *bio);
407 : : union map_info *dm_get_rq_mapinfo(struct request *rq);
408 : :
409 : : struct queue_limits *dm_get_queue_limits(struct mapped_device *md);
410 : :
411 : : /*
412 : : * Geometry functions.
413 : : */
414 : : int dm_get_geometry(struct mapped_device *md, struct hd_geometry *geo);
415 : : int dm_set_geometry(struct mapped_device *md, struct hd_geometry *geo);
416 : :
417 : : /*-----------------------------------------------------------------
418 : : * Functions for manipulating device-mapper tables.
419 : : *---------------------------------------------------------------*/
420 : :
421 : : /*
422 : : * First create an empty table.
423 : : */
424 : : int dm_table_create(struct dm_table **result, fmode_t mode,
425 : : unsigned num_targets, struct mapped_device *md);
426 : :
427 : : /*
428 : : * Then call this once for each target.
429 : : */
430 : : int dm_table_add_target(struct dm_table *t, const char *type,
431 : : sector_t start, sector_t len, char *params);
432 : :
433 : : /*
434 : : * Target_ctr should call this if it needs to add any callbacks.
435 : : */
436 : : void dm_table_add_target_callbacks(struct dm_table *t, struct dm_target_callbacks *cb);
437 : :
438 : : /*
439 : : * Finally call this to make the table ready for use.
440 : : */
441 : : int dm_table_complete(struct dm_table *t);
442 : :
443 : : /*
444 : : * Target may require that it is never sent I/O larger than len.
445 : : */
446 : : int __must_check dm_set_target_max_io_len(struct dm_target *ti, sector_t len);
447 : :
448 : : /*
449 : : * Table reference counting.
450 : : */
451 : : struct dm_table *dm_get_live_table(struct mapped_device *md, int *srcu_idx);
452 : : void dm_put_live_table(struct mapped_device *md, int srcu_idx);
453 : : void dm_sync_table(struct mapped_device *md);
454 : :
455 : : /*
456 : : * Queries
457 : : */
458 : : sector_t dm_table_get_size(struct dm_table *t);
459 : : unsigned int dm_table_get_num_targets(struct dm_table *t);
460 : : fmode_t dm_table_get_mode(struct dm_table *t);
461 : : struct mapped_device *dm_table_get_md(struct dm_table *t);
462 : :
463 : : /*
464 : : * Trigger an event.
465 : : */
466 : : void dm_table_event(struct dm_table *t);
467 : :
468 : : /*
469 : : * The device must be suspended before calling this method.
470 : : * Returns the previous table, which the caller must destroy.
471 : : */
472 : : struct dm_table *dm_swap_table(struct mapped_device *md,
473 : : struct dm_table *t);
474 : :
475 : : /*
476 : : * A wrapper around vmalloc.
477 : : */
478 : : void *dm_vcalloc(unsigned long nmemb, unsigned long elem_size);
479 : :
480 : : /*-----------------------------------------------------------------
481 : : * Macros.
482 : : *---------------------------------------------------------------*/
483 : : #define DM_NAME "device-mapper"
484 : :
485 : : #ifdef CONFIG_PRINTK
486 : : extern struct ratelimit_state dm_ratelimit_state;
487 : :
488 : : #define dm_ratelimit() __ratelimit(&dm_ratelimit_state)
489 : : #else
490 : : #define dm_ratelimit() 0
491 : : #endif
492 : :
493 : : #define DMCRIT(f, arg...) \
494 : : printk(KERN_CRIT DM_NAME ": " DM_MSG_PREFIX ": " f "\n", ## arg)
495 : :
496 : : #define DMERR(f, arg...) \
497 : : printk(KERN_ERR DM_NAME ": " DM_MSG_PREFIX ": " f "\n", ## arg)
498 : : #define DMERR_LIMIT(f, arg...) \
499 : : do { \
500 : : if (dm_ratelimit()) \
501 : : printk(KERN_ERR DM_NAME ": " DM_MSG_PREFIX ": " \
502 : : f "\n", ## arg); \
503 : : } while (0)
504 : :
505 : : #define DMWARN(f, arg...) \
506 : : printk(KERN_WARNING DM_NAME ": " DM_MSG_PREFIX ": " f "\n", ## arg)
507 : : #define DMWARN_LIMIT(f, arg...) \
508 : : do { \
509 : : if (dm_ratelimit()) \
510 : : printk(KERN_WARNING DM_NAME ": " DM_MSG_PREFIX ": " \
511 : : f "\n", ## arg); \
512 : : } while (0)
513 : :
514 : : #define DMINFO(f, arg...) \
515 : : printk(KERN_INFO DM_NAME ": " DM_MSG_PREFIX ": " f "\n", ## arg)
516 : : #define DMINFO_LIMIT(f, arg...) \
517 : : do { \
518 : : if (dm_ratelimit()) \
519 : : printk(KERN_INFO DM_NAME ": " DM_MSG_PREFIX ": " f \
520 : : "\n", ## arg); \
521 : : } while (0)
522 : :
523 : : #ifdef CONFIG_DM_DEBUG
524 : : # define DMDEBUG(f, arg...) \
525 : : printk(KERN_DEBUG DM_NAME ": " DM_MSG_PREFIX " DEBUG: " f "\n", ## arg)
526 : : # define DMDEBUG_LIMIT(f, arg...) \
527 : : do { \
528 : : if (dm_ratelimit()) \
529 : : printk(KERN_DEBUG DM_NAME ": " DM_MSG_PREFIX ": " f \
530 : : "\n", ## arg); \
531 : : } while (0)
532 : : #else
533 : : # define DMDEBUG(f, arg...) do {} while (0)
534 : : # define DMDEBUG_LIMIT(f, arg...) do {} while (0)
535 : : #endif
536 : :
537 : : #define DMEMIT(x...) sz += ((sz >= maxlen) ? \
538 : : 0 : scnprintf(result + sz, maxlen - sz, x))
539 : :
540 : : #define SECTOR_SHIFT 9
541 : :
542 : : /*
543 : : * Definitions of return values from target end_io function.
544 : : */
545 : : #define DM_ENDIO_INCOMPLETE 1
546 : : #define DM_ENDIO_REQUEUE 2
547 : :
548 : : /*
549 : : * Definitions of return values from target map function.
550 : : */
551 : : #define DM_MAPIO_SUBMITTED 0
552 : : #define DM_MAPIO_REMAPPED 1
553 : : #define DM_MAPIO_REQUEUE DM_ENDIO_REQUEUE
554 : :
555 : : #define dm_sector_div64(x, y)( \
556 : : { \
557 : : u64 _res; \
558 : : (x) = div64_u64_rem(x, y, &_res); \
559 : : _res; \
560 : : } \
561 : : )
562 : :
563 : : /*
564 : : * Ceiling(n / sz)
565 : : */
566 : : #define dm_div_up(n, sz) (((n) + (sz) - 1) / (sz))
567 : :
568 : : #define dm_sector_div_up(n, sz) ( \
569 : : { \
570 : : sector_t _r = ((n) + (sz) - 1); \
571 : : sector_div(_r, (sz)); \
572 : : _r; \
573 : : } \
574 : : )
575 : :
576 : : /*
577 : : * ceiling(n / size) * size
578 : : */
579 : : #define dm_round_up(n, sz) (dm_div_up((n), (sz)) * (sz))
580 : :
581 : : #define dm_array_too_big(fixed, obj, num) \
582 : : ((num) > (UINT_MAX - (fixed)) / (obj))
583 : :
584 : : /*
585 : : * Sector offset taken relative to the start of the target instead of
586 : : * relative to the start of the device.
587 : : */
588 : : #define dm_target_offset(ti, sector) ((sector) - (ti)->begin)
589 : :
590 : : static inline sector_t to_sector(unsigned long n)
591 : : {
592 : 0 : return (n >> SECTOR_SHIFT);
593 : : }
594 : :
595 : : static inline unsigned long to_bytes(sector_t n)
596 : : {
597 : 0 : return (n << SECTOR_SHIFT);
598 : : }
599 : :
600 : : /*-----------------------------------------------------------------
601 : : * Helper for block layer and dm core operations
602 : : *---------------------------------------------------------------*/
603 : : void dm_dispatch_request(struct request *rq);
604 : : void dm_requeue_unmapped_request(struct request *rq);
605 : : void dm_kill_unmapped_request(struct request *rq, int error);
606 : : int dm_underlying_device_busy(struct request_queue *q);
607 : :
608 : : #endif /* _LINUX_DEVICE_MAPPER_H */
|
