dm: document iterate_devices

Document iterate_devices in device-mapper.h. Signed-off-by: Alasdair G Kergon <agk@redhat.com>

dm: document iterate_devices
Document iterate_devices in device-mapper.h. Signed-off-by: Alasdair G Kergon <agk@redhat.com>
Alasdair G Kergon
1 parent 88a488f624
Showing 1 changed file with 15 additions and 0 deletions Side-by-side Diff
include/linux/device-mapper.h
@@ -79,11 +79,26 @@
 typedef int (*dm_merge_fn) (struct dm_target *ti, struct bvec_merge_data *bvm,
 			    struct bio_vec *biovec, int max_size);
  
+/*
+ * These iteration functions are typically used to check (and combine)
+ * properties of underlying devices.
+ * E.g. Does at least one underlying device support flush?
+ *      Does any underlying device not support WRITE_SAME?
+ *
+ * The callout function is called once for each contiguous section of
+ * an underlying device.  State can be maintained in *data.
+ * Return non-zero to stop iterating through any further devices.
+ */
 typedef int (*iterate_devices_callout_fn) (struct dm_target *ti,
 					   struct dm_dev *dev,
 					   sector_t start, sector_t len,
 					   void *data);
  
+/*
+ * This function must iterate through each section of device used by the
+ * target until it encounters a non-zero return code, which it then returns.
+ * Returns zero if no callout returned non-zero.
+ */
 typedef int (*dm_iterate_devices_fn) (struct dm_target *ti,
 				      iterate_devices_callout_fn fn,
 				      void *data);
...	...	@@ -79,11 +79,26 @@
79	79	typedef int (dm_merge_fn) (struct dm_target ti, struct bvec_merge_data *bvm,
80	80	struct bio_vec *biovec, int max_size);
81	81
	82	+/*
	83	+ * These iteration functions are typically used to check (and combine)
	84	+ * properties of underlying devices.
	85	+ * E.g. Does at least one underlying device support flush?
	86	+ * Does any underlying device not support WRITE_SAME?
	87	+ *
	88	+ * The callout function is called once for each contiguous section of
	89	+ * an underlying device. State can be maintained in *data.
	90	+ * Return non-zero to stop iterating through any further devices.
	91	+ */
82	92	typedef int (iterate_devices_callout_fn) (struct dm_target ti,
83	93	struct dm_dev *dev,
84	94	sector_t start, sector_t len,
85	95	void *data);
86	96
	97	+/*
	98	+ * This function must iterate through each section of device used by the
	99	+ * target until it encounters a non-zero return code, which it then returns.
	100	+ * Returns zero if no callout returned non-zero.
	101	+ */
87	102	typedef int (dm_iterate_devices_fn) (struct dm_target ti,
88	103	iterate_devices_callout_fn fn,
89	104	void *data);