uapi/linux/dm-log-userspace.h

1 /* SPDX-License-Identifier: LGPL-2.0+ WITH Linux-syscall-note */
3  * Copyright (C) 2006-2009 Red Hat, Inc.
12 #include <linux/dm-ioctl.h> /* For DM_UUID_LEN */
15  * The device-mapper userspace log module consists of a kernel component and
16  * a user-space component.  The kernel component implements the API defined
17  * in dm-dirty-log.h.  Its purpose is simply to pass the parameters and
18  * return values of those API functions between kernel and user-space.
20  * Below are defined the 'request_types' - DM_ULOG_CTR, DM_ULOG_DTR, etc.
21  * These request types represent the different functions in the device-mapper
22  * dirty log API.  Each of these is described in more detail below.
24  * The user-space program must listen for requests from the kernel (representing
27  * User-space begins by setting up the communication link (error checking
37  * User-space will then wait to receive requests form the kernel, which it
38  * will process as described below.  The requests are received in the form,
40  * type, there may or may not be 'additional data'.  In the descriptions below,
41  * you will see 'Payload-to-userspace' and 'Payload-to-kernel'.  The
42  * 'Payload-to-userspace' is what the kernel sends in 'additional data' as
43  * necessary parameters to complete the request.  The 'Payload-to-kernel' is
44  * the 'additional data' returned to the kernel that contains the necessary
45  * results of the request.  The 'data_size' field in the dm_ulog_request
50  * DM_ULOG_CTR corresponds to (found in dm-dirty-log.h):
54  * Payload-to-userspace:
56  * Payload-to-kernel:
57  *	A NUL-terminated string that is the name of the device that is used
61  *	for log data, 'data_size' in the dm_ulog_request struct should be 0.
63  * The UUID contained in the dm_ulog_request structure is the reference that
67  * When the request has been processed, user-space must return the
68  * dm_ulog_request to the kernel - setting the 'error' field, filling the
75  * DM_ULOG_DTR corresponds to (found in dm-dirty-log.h):
78  * Payload-to-userspace:
80  * Payload-to-kernel:
81  *	None.  ('data_size' in the dm_ulog_request struct should be 0.)
83  * The UUID contained in the dm_ulog_request structure is all that is
87  * When the request has been processed, user-space must return the
88  * dm_ulog_request to the kernel - setting the 'error' field and clearing
94  * DM_ULOG_PRESUSPEND corresponds to (found in dm-dirty-log.h):
97  * Payload-to-userspace:
99  * Payload-to-kernel:
102  * The UUID contained in the dm_ulog_request structure is all that is
106  * When the request has been processed, user-space must return the
107  * dm_ulog_request to the kernel - setting the 'error' field and
113  * DM_ULOG_POSTSUSPEND corresponds to (found in dm-dirty-log.h):
116  * Payload-to-userspace:
118  * Payload-to-kernel:
121  * The UUID contained in the dm_ulog_request structure is all that is
125  * When the request has been processed, user-space must return the
126  * dm_ulog_request to the kernel - setting the 'error' field and
132  * DM_ULOG_RESUME corresponds to (found in dm-dirty-log.h):
135  * Payload-to-userspace:
137  * Payload-to-kernel:
140  * The UUID contained in the dm_ulog_request structure is all that is
144  * When the request has been processed, user-space must return the
145  * dm_ulog_request to the kernel - setting the 'error' field and
151  * DM_ULOG_GET_REGION_SIZE corresponds to (found in dm-dirty-log.h):
154  * Payload-to-userspace:
156  * Payload-to-kernel:
157  *	__u64 - contains the region size
160  * It is returned in the payload area and 'data_size' is set to
163  * When the request has been processed, user-space must return the
164  * dm_ulog_request to the kernel - setting the 'error' field appropriately.
169  * DM_ULOG_IS_CLEAN corresponds to (found in dm-dirty-log.h):
172  * Payload-to-userspace:
173  *	__u64 - the region to get clean status on
174  * Payload-to-kernel:
175  *	__s64  - 1 if clean, 0 otherwise
180  * When the request has been processed, user-space must return the
181  * dm_ulog_request to the kernel - filling the payload with 0 (not clean) or
187  * DM_ULOG_IN_SYNC corresponds to (found in dm-dirty-log.h):
191  * Payload-to-userspace:
192  *	__u64 - the region to get sync status on
193  * Payload-to-kernel:
194  *	__s64 - 1 if in-sync, 0 otherwise
202  * DM_ULOG_FLUSH corresponds to (found in dm-dirty-log.h):
205  * Payload-to-userspace:
206  *	If the 'integrated_flush' directive is present in the constructor
208  *		__u64 [] - region(s) to mark
211  * Payload-to-kernel:
215  * log, mark region requests are carried as payload in the flush request.
216  * Piggybacking the mark requests in this way allows for fewer communications
217  * between kernel and userspace.
219  * When the request has been processed, user-space must return the
220  * dm_ulog_request to the kernel - setting the 'error' field and clearing
226  * DM_ULOG_MARK_REGION corresponds to (found in dm-dirty-log.h):
229  * Payload-to-userspace:
230  *	__u64 [] - region(s) to mark
231  * Payload-to-kernel:
235  * The number of regions contained in the payload can be determined from
238  * When the request has been processed, user-space must return the
239  * dm_ulog_request to the kernel - setting the 'error' field and clearing
245  * DM_ULOG_CLEAR_REGION corresponds to (found in dm-dirty-log.h):
248  * Payload-to-userspace:
249  *	__u64 [] - region(s) to clear
250  * Payload-to-kernel:
254  * The number of regions contained in the payload can be determined from
257  * When the request has been processed, user-space must return the
258  * dm_ulog_request to the kernel - setting the 'error' field and clearing
264  * DM_ULOG_GET_RESYNC_WORK corresponds to (found in dm-dirty-log.h):
267  * Payload-to-userspace:
269  * Payload-to-kernel:
271  *		__s64 i; -- 1 if recovery necessary, 0 otherwise
272  *		__u64 r; -- The region to recover if i=1
276  * When the request has been processed, user-space must return the
277  * dm_ulog_request to the kernel - setting the 'error' field appropriately.
282  * DM_ULOG_SET_REGION_SYNC corresponds to (found in dm-dirty-log.h):
286  * Payload-to-userspace:
288  *		__u64 - region to set sync state on
289  *		__s64  - 0 if not-in-sync, 1 if in-sync
291  * Payload-to-kernel:
294  * When the request has been processed, user-space must return the
295  * dm_ulog_request to the kernel - setting the 'error' field and clearing
301  * DM_ULOG_GET_SYNC_COUNT corresponds to (found in dm-dirty-log.h):
304  * Payload-to-userspace:
306  * Payload-to-kernel:
307  *	__u64 - the number of in-sync regions
309  * No incoming payload.  Kernel-bound payload contains the number of
310  * regions that are in-sync (in a size_t).
312  * When the request has been processed, user-space must return the
313  * dm_ulog_request to the kernel - setting the 'error' field and
319  * DM_ULOG_STATUS_INFO corresponds to (found in dm-dirty-log.h):
323  * Payload-to-userspace:
325  * Payload-to-kernel:
328  * When the request has been processed, user-space must return the
329  * dm_ulog_request to the kernel - setting the 'error' field and
335  * DM_ULOG_STATUS_TABLE corresponds to (found in dm-dirty-log.h):
339  * Payload-to-userspace:
341  * Payload-to-kernel:
344  * When the request has been processed, user-space must return the
345  * dm_ulog_request to the kernel - setting the 'error' field and
351  * DM_ULOG_IS_REMOTE_RECOVERING corresponds to (found in dm-dirty-log.h):
354  * Payload-to-userspace:
355  *	__u64 - region to determine recovery status on
356  * Payload-to-kernel:
358  *		__s64 is_recovering;  -- 0 if no, 1 if yes
359  *		__u64 in_sync_hint;  -- lowest region still needing resync
362  * When the request has been processed, user-space must return the
363  * dm_ulog_request to the kernel - setting the 'error' field and
371  * Payload-to-userspace:
373  * Payload-to-kernel:
374  *	None.  ('data_size' in the dm_ulog_request struct should be 0.)
376  * We are reserving 8 bits of the 32-bit 'request_type' field for the
377  * various request types above.  The remaining 24-bits are currently
380  * User-space should always use DM_ULOG_REQUEST_TYPE to acquire the
389  * change to the way information is passed between kernel
391  * dm_ulog_request or a change in the way requests are
399  *		    requests between the kernel and userspace by effectively
412 	 * just the 'luid', but a cluster-aware log must use the 'uuid' and
416 	 * same 'uuid'.  (Think "live" and "inactive" device-mapper tables.)