device-mapper.h 11.2 KB
Newer Older
L
Linus Torvalds 已提交
1 2
/*
 * Copyright (C) 2001 Sistina Software (UK) Limited.
A
Alasdair G Kergon 已提交
3
 * Copyright (C) 2004-2008 Red Hat, Inc. All rights reserved.
L
Linus Torvalds 已提交
4 5 6 7 8 9 10
 *
 * This file is released under the LGPL.
 */

#ifndef _LINUX_DEVICE_MAPPER_H
#define _LINUX_DEVICE_MAPPER_H

H
Heinz Mauelshagen 已提交
11
#include <linux/bio.h>
M
Milan Broz 已提交
12
#include <linux/blkdev.h>
H
Heinz Mauelshagen 已提交
13

14
struct dm_dev;
L
Linus Torvalds 已提交
15 16
struct dm_target;
struct dm_table;
A
Alasdair G Kergon 已提交
17
struct mapped_device;
M
Milan Broz 已提交
18
struct bio_vec;
L
Linus Torvalds 已提交
19 20 21 22 23 24

typedef enum { STATUSTYPE_INFO, STATUSTYPE_TABLE } status_type_t;

union map_info {
	void *ptr;
	unsigned long long ll;
25
	unsigned target_request_nr;
L
Linus Torvalds 已提交
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
};

/*
 * In the constructor the target parameter will already have the
 * table, type, begin and len fields filled in.
 */
typedef int (*dm_ctr_fn) (struct dm_target *target,
			  unsigned int argc, char **argv);

/*
 * The destructor doesn't need to free the dm_target, just
 * anything hidden ti->private.
 */
typedef void (*dm_dtr_fn) (struct dm_target *ti);

/*
 * The map function must return:
 * < 0: error
 * = 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
L
Linus Torvalds 已提交
47 48 49
 */
typedef int (*dm_map_fn) (struct dm_target *ti, struct bio *bio,
			  union map_info *map_context);
50 51
typedef int (*dm_map_request_fn) (struct dm_target *ti, struct request *clone,
				  union map_info *map_context);
L
Linus Torvalds 已提交
52 53 54 55 56 57 58

/*
 * Returns:
 * < 0 : error (currently ignored)
 * 0   : ended successfully
 * 1   : for some reason the io has still not completed (eg,
 *       multipath target might want to requeue a failed io).
59
 * 2   : The target wants to push back the io
L
Linus Torvalds 已提交
60 61 62 63
 */
typedef int (*dm_endio_fn) (struct dm_target *ti,
			    struct bio *bio, int error,
			    union map_info *map_context);
64 65 66
typedef int (*dm_request_endio_fn) (struct dm_target *ti,
				    struct request *clone, int error,
				    union map_info *map_context);
L
Linus Torvalds 已提交
67

B
Bryn Reeves 已提交
68
typedef void (*dm_flush_fn) (struct dm_target *ti);
L
Linus Torvalds 已提交
69 70
typedef void (*dm_presuspend_fn) (struct dm_target *ti);
typedef void (*dm_postsuspend_fn) (struct dm_target *ti);
71
typedef int (*dm_preresume_fn) (struct dm_target *ti);
L
Linus Torvalds 已提交
72 73 74 75 76 77 78
typedef void (*dm_resume_fn) (struct dm_target *ti);

typedef int (*dm_status_fn) (struct dm_target *ti, status_type_t status_type,
			     char *result, unsigned int maxlen);

typedef int (*dm_message_fn) (struct dm_target *ti, unsigned argc, char **argv);

79
typedef int (*dm_ioctl_fn) (struct dm_target *ti, unsigned int cmd,
80 81
			    unsigned long arg);

M
Milan Broz 已提交
82 83 84
typedef int (*dm_merge_fn) (struct dm_target *ti, struct bvec_merge_data *bvm,
			    struct bio_vec *biovec, int max_size);

85 86
typedef int (*iterate_devices_callout_fn) (struct dm_target *ti,
					   struct dm_dev *dev,
87
					   sector_t start, sector_t len,
88 89 90 91 92 93
					   void *data);

typedef int (*dm_iterate_devices_fn) (struct dm_target *ti,
				      iterate_devices_callout_fn fn,
				      void *data);

94 95 96
typedef void (*dm_io_hints_fn) (struct dm_target *ti,
				struct queue_limits *limits);

97 98 99 100 101 102 103
/*
 * Returns:
 *    0: The target can handle the next I/O immediately.
 *    1: The target can't handle the next I/O immediately.
 */
typedef int (*dm_busy_fn) (struct dm_target *ti);

L
Linus Torvalds 已提交
104 105
void dm_error(const char *message);

106 107 108
/*
 * Combine device limits.
 */
109
int dm_set_device_limits(struct dm_target *ti, struct dm_dev *dev,
110
			 sector_t start, sector_t len, void *data);
111

M
Mikulas Patocka 已提交
112 113
struct dm_dev {
	struct block_device *bdev;
114
	fmode_t mode;
M
Mikulas Patocka 已提交
115 116 117
	char name[16];
};

L
Linus Torvalds 已提交
118 119 120 121
/*
 * Constructors should call these functions to ensure destination devices
 * are opened/closed correctly.
 */
122 123
int dm_get_device(struct dm_target *ti, const char *path, fmode_t mode,
						 struct dm_dev **result);
L
Linus Torvalds 已提交
124 125 126 127 128
void dm_put_device(struct dm_target *ti, struct dm_dev *d);

/*
 * Information about a target type
 */
129 130 131 132 133

/*
 * Target features
 */

L
Linus Torvalds 已提交
134
struct target_type {
135
	uint64_t features;
L
Linus Torvalds 已提交
136 137
	const char *name;
	struct module *module;
A
Alasdair G Kergon 已提交
138
	unsigned version[3];
L
Linus Torvalds 已提交
139 140 141
	dm_ctr_fn ctr;
	dm_dtr_fn dtr;
	dm_map_fn map;
142
	dm_map_request_fn map_rq;
L
Linus Torvalds 已提交
143
	dm_endio_fn end_io;
144
	dm_request_endio_fn rq_end_io;
B
Bryn Reeves 已提交
145
	dm_flush_fn flush;
L
Linus Torvalds 已提交
146 147
	dm_presuspend_fn presuspend;
	dm_postsuspend_fn postsuspend;
148
	dm_preresume_fn preresume;
L
Linus Torvalds 已提交
149 150 151
	dm_resume_fn resume;
	dm_status_fn status;
	dm_message_fn message;
152
	dm_ioctl_fn ioctl;
M
Milan Broz 已提交
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 159

	/* For internal device-mapper use. */
	struct list_head list;
L
Linus Torvalds 已提交
160 161 162 163 164 165 166 167 168 169 170 171 172
};

struct dm_target {
	struct dm_table *table;
	struct target_type *type;

	/* target limits */
	sector_t begin;
	sector_t len;

	/* Always a power of 2 */
	sector_t split_io;

173 174 175 176
	/*
	 * A number of zero-length barrier requests that will be submitted
	 * to the target for the purpose of flushing cache.
	 *
177
	 * The request number will be placed in union map_info->target_request_nr.
178 179 180 181 182
	 * It is a responsibility of the target driver to remap these requests
	 * to the real underlying devices.
	 */
	unsigned num_flush_requests;

M
Mike Snitzer 已提交
183 184 185 186 187 188
	/*
	 * The number of discard requests that will be submitted to the
	 * target.  map_info->request_nr is used just like num_flush_requests.
	 */
	unsigned num_discard_requests;

L
Linus Torvalds 已提交
189 190 191 192 193 194 195 196
	/* target specific data */
	void *private;

	/* Used to provide an error string from the ctr */
	char *error;
};

int dm_register_target(struct target_type *t);
197
void dm_unregister_target(struct target_type *t);
A
Alasdair G Kergon 已提交
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225

/*-----------------------------------------------------------------
 * Functions for creating and manipulating mapped devices.
 * Drop the reference with dm_put when you finish with the object.
 *---------------------------------------------------------------*/

/*
 * DM_ANY_MINOR chooses the next available minor number.
 */
#define DM_ANY_MINOR (-1)
int dm_create(int minor, struct mapped_device **md);

/*
 * Reference counting for md.
 */
struct mapped_device *dm_get_md(dev_t dev);
void dm_get(struct mapped_device *md);
void dm_put(struct mapped_device *md);

/*
 * An arbitrary pointer may be stored alongside a mapped device.
 */
void dm_set_mdptr(struct mapped_device *md, void *ptr);
void *dm_get_mdptr(struct mapped_device *md);

/*
 * A device can still be used while suspended, but I/O is deferred.
 */
226
int dm_suspend(struct mapped_device *md, unsigned suspend_flags);
A
Alasdair G Kergon 已提交
227 228 229 230 231 232 233
int dm_resume(struct mapped_device *md);

/*
 * Event functions.
 */
uint32_t dm_get_event_nr(struct mapped_device *md);
int dm_wait_event(struct mapped_device *md, int event_nr);
M
Mike Anderson 已提交
234 235
uint32_t dm_next_uevent_seq(struct mapped_device *md);
void dm_uevent_add(struct mapped_device *md, struct list_head *elist);
A
Alasdair G Kergon 已提交
236 237 238 239

/*
 * Info functions.
 */
240
const char *dm_device_name(struct mapped_device *md);
M
Mike Anderson 已提交
241
int dm_copy_name_and_uuid(struct mapped_device *md, char *name, char *uuid);
A
Alasdair G Kergon 已提交
242
struct gendisk *dm_disk(struct mapped_device *md);
243
int dm_suspended(struct dm_target *ti);
244
int dm_noflush_suspending(struct dm_target *ti);
M
Mikulas Patocka 已提交
245
union map_info *dm_get_mapinfo(struct bio *bio);
246
union map_info *dm_get_rq_mapinfo(struct request *rq);
A
Alasdair G Kergon 已提交
247 248 249 250 251 252 253 254 255 256 257 258 259 260 261

/*
 * Geometry functions.
 */
int dm_get_geometry(struct mapped_device *md, struct hd_geometry *geo);
int dm_set_geometry(struct mapped_device *md, struct hd_geometry *geo);


/*-----------------------------------------------------------------
 * Functions for manipulating device-mapper tables.
 *---------------------------------------------------------------*/

/*
 * First create an empty table.
 */
262
int dm_table_create(struct dm_table **result, fmode_t mode,
A
Alasdair G Kergon 已提交
263 264 265 266 267 268 269 270 271 272 273 274 275
		    unsigned num_targets, struct mapped_device *md);

/*
 * Then call this once for each target.
 */
int dm_table_add_target(struct dm_table *t, const char *type,
			sector_t start, sector_t len, char *params);

/*
 * Finally call this to make the table ready for use.
 */
int dm_table_complete(struct dm_table *t);

M
Mikulas Patocka 已提交
276 277 278 279 280
/*
 * Unplug all devices in a table.
 */
void dm_table_unplug_all(struct dm_table *t);

A
Alasdair G Kergon 已提交
281 282 283
/*
 * Table reference counting.
 */
284
struct dm_table *dm_get_live_table(struct mapped_device *md);
A
Alasdair G Kergon 已提交
285 286 287 288 289 290 291 292
void dm_table_get(struct dm_table *t);
void dm_table_put(struct dm_table *t);

/*
 * Queries
 */
sector_t dm_table_get_size(struct dm_table *t);
unsigned int dm_table_get_num_targets(struct dm_table *t);
293
fmode_t dm_table_get_mode(struct dm_table *t);
A
Alasdair G Kergon 已提交
294 295 296 297 298 299 300 301 302
struct mapped_device *dm_table_get_md(struct dm_table *t);

/*
 * Trigger an event.
 */
void dm_table_event(struct dm_table *t);

/*
 * The device must be suspended before calling this method.
303
 * Returns the previous table, which the caller must destroy.
A
Alasdair G Kergon 已提交
304
 */
305 306
struct dm_table *dm_swap_table(struct mapped_device *md,
			       struct dm_table *t);
A
Alasdair G Kergon 已提交
307

M
Mikulas Patocka 已提交
308 309 310 311 312
/*
 * A wrapper around vmalloc.
 */
void *dm_vcalloc(unsigned long nmemb, unsigned long elem_size);

A
Alasdair G Kergon 已提交
313 314 315 316 317
/*-----------------------------------------------------------------
 * Macros.
 *---------------------------------------------------------------*/
#define DM_NAME "device-mapper"

318 319 320
#define DMCRIT(f, arg...) \
	printk(KERN_CRIT DM_NAME ": " DM_MSG_PREFIX ": " f "\n", ## arg)

A
Alasdair G Kergon 已提交
321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397
#define DMERR(f, arg...) \
	printk(KERN_ERR DM_NAME ": " DM_MSG_PREFIX ": " f "\n", ## arg)
#define DMERR_LIMIT(f, arg...) \
	do { \
		if (printk_ratelimit())	\
			printk(KERN_ERR DM_NAME ": " DM_MSG_PREFIX ": " \
			       f "\n", ## arg); \
	} while (0)

#define DMWARN(f, arg...) \
	printk(KERN_WARNING DM_NAME ": " DM_MSG_PREFIX ": " f "\n", ## arg)
#define DMWARN_LIMIT(f, arg...) \
	do { \
		if (printk_ratelimit())	\
			printk(KERN_WARNING DM_NAME ": " DM_MSG_PREFIX ": " \
			       f "\n", ## arg); \
	} while (0)

#define DMINFO(f, arg...) \
	printk(KERN_INFO DM_NAME ": " DM_MSG_PREFIX ": " f "\n", ## arg)
#define DMINFO_LIMIT(f, arg...) \
	do { \
		if (printk_ratelimit())	\
			printk(KERN_INFO DM_NAME ": " DM_MSG_PREFIX ": " f \
			       "\n", ## arg); \
	} while (0)

#ifdef CONFIG_DM_DEBUG
#  define DMDEBUG(f, arg...) \
	printk(KERN_DEBUG DM_NAME ": " DM_MSG_PREFIX " DEBUG: " f "\n", ## arg)
#  define DMDEBUG_LIMIT(f, arg...) \
	do { \
		if (printk_ratelimit())	\
			printk(KERN_DEBUG DM_NAME ": " DM_MSG_PREFIX ": " f \
			       "\n", ## arg); \
	} while (0)
#else
#  define DMDEBUG(f, arg...) do {} while (0)
#  define DMDEBUG_LIMIT(f, arg...) do {} while (0)
#endif

#define DMEMIT(x...) sz += ((sz >= maxlen) ? \
			  0 : scnprintf(result + sz, maxlen - sz, x))

#define SECTOR_SHIFT 9

/*
 * Definitions of return values from target end_io function.
 */
#define DM_ENDIO_INCOMPLETE	1
#define DM_ENDIO_REQUEUE	2

/*
 * Definitions of return values from target map function.
 */
#define DM_MAPIO_SUBMITTED	0
#define DM_MAPIO_REMAPPED	1
#define DM_MAPIO_REQUEUE	DM_ENDIO_REQUEUE

/*
 * Ceiling(n / sz)
 */
#define dm_div_up(n, sz) (((n) + (sz) - 1) / (sz))

#define dm_sector_div_up(n, sz) ( \
{ \
	sector_t _r = ((n) + (sz) - 1); \
	sector_div(_r, (sz)); \
	_r; \
} \
)

/*
 * ceiling(n / size) * size
 */
#define dm_round_up(n, sz) (dm_div_up((n), (sz)) * (sz))

M
Mikulas Patocka 已提交
398 399 400
#define dm_array_too_big(fixed, obj, num) \
	((num) > (UINT_MAX - (fixed)) / (obj))

401 402 403 404 405 406
/*
 * Sector offset taken relative to the start of the target instead of
 * relative to the start of the device.
 */
#define dm_target_offset(ti, sector) ((sector) - (ti)->begin)

A
Alasdair G Kergon 已提交
407 408 409 410 411 412 413 414 415 416
static inline sector_t to_sector(unsigned long n)
{
	return (n >> SECTOR_SHIFT);
}

static inline unsigned long to_bytes(sector_t n)
{
	return (n << SECTOR_SHIFT);
}

417 418 419 420 421 422 423 424
/*-----------------------------------------------------------------
 * Helper for block layer and dm core operations
 *---------------------------------------------------------------*/
void dm_dispatch_request(struct request *rq);
void dm_requeue_unmapped_request(struct request *rq);
void dm_kill_unmapped_request(struct request *rq, int error);
int dm_underlying_device_busy(struct request_queue *q);

A
Alasdair G Kergon 已提交
425
#endif	/* _LINUX_DEVICE_MAPPER_H */