1 /* 2 * Copyright (C) 2006-2009 Red Hat, Inc. 3 * 4 * This file is released under the LGPL. 5 */ 6 7 #ifndef __DM_LOG_USERSPACE_H__ 8 #define __DM_LOG_USERSPACE_H__ 9 10 #include <linux/types.h> 11 #include <linux/dm-ioctl.h> /* For DM_UUID_LEN */ 12 13 /* 14 * The device-mapper userspace log module consists of a kernel component and 15 * a user-space component. The kernel component implements the API defined 16 * in dm-dirty-log.h. Its purpose is simply to pass the parameters and 17 * return values of those API functions between kernel and user-space. 18 * 19 * Below are defined the 'request_types' - DM_ULOG_CTR, DM_ULOG_DTR, etc. 20 * These request types represent the different functions in the device-mapper 21 * dirty log API. Each of these is described in more detail below. 22 * 23 * The user-space program must listen for requests from the kernel (representing 24 * the various API functions) and process them. 25 * 26 * User-space begins by setting up the communication link (error checking 27 * removed for clarity): 28 * fd = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); 29 * addr.nl_family = AF_NETLINK; 30 * addr.nl_groups = CN_IDX_DM; 31 * addr.nl_pid = 0; 32 * r = bind(fd, (struct sockaddr *) &addr, sizeof(addr)); 33 * opt = addr.nl_groups; 34 * setsockopt(fd, SOL_NETLINK, NETLINK_ADD_MEMBERSHIP, &opt, sizeof(opt)); 35 * 36 * User-space will then wait to receive requests form the kernel, which it 37 * will process as described below. The requests are received in the form, 38 * ((struct dm_ulog_request) + (additional data)). Depending on the request 39 * type, there may or may not be 'additional data'. In the descriptions below, 40 * you will see 'Payload-to-userspace' and 'Payload-to-kernel'. The 41 * 'Payload-to-userspace' is what the kernel sends in 'additional data' as 42 * necessary parameters to complete the request. The 'Payload-to-kernel' is 43 * the 'additional data' returned to the kernel that contains the necessary 44 * results of the request. The 'data_size' field in the dm_ulog_request 45 * structure denotes the availability and amount of payload data. 46 */ 47 48 /* 49 * DM_ULOG_CTR corresponds to (found in dm-dirty-log.h): 50 * int (*ctr)(struct dm_dirty_log *log, struct dm_target *ti, 51 * unsigned argc, char **argv); 52 * 53 * Payload-to-userspace: 54 * A single string containing all the argv arguments separated by ' 's 55 * Payload-to-kernel: 56 * A NUL-terminated string that is the name of the device that is used 57 * as the backing store for the log data. 'dm_get_device' will be called 58 * on this device. ('dm_put_device' will be called on this device 59 * automatically after calling DM_ULOG_DTR.) If there is no device needed 60 * for log data, 'data_size' in the dm_ulog_request struct should be 0. 61 * 62 * The UUID contained in the dm_ulog_request structure is the reference that 63 * will be used by all request types to a specific log. The constructor must 64 * record this association with the instance created. 65 * 66 * When the request has been processed, user-space must return the 67 * dm_ulog_request to the kernel - setting the 'error' field, filling the 68 * data field with the log device if necessary, and setting 'data_size' 69 * appropriately. 70 */ 71 #define DM_ULOG_CTR 1 72 73 /* 74 * DM_ULOG_DTR corresponds to (found in dm-dirty-log.h): 75 * void (*dtr)(struct dm_dirty_log *log); 76 * 77 * Payload-to-userspace: 78 * A single string containing all the argv arguments separated by ' 's 79 * Payload-to-kernel: 80 * None. ('data_size' in the dm_ulog_request struct should be 0.) 81 * 82 * The UUID contained in the dm_ulog_request structure is all that is 83 * necessary to identify the log instance being destroyed. There is no 84 * payload data. 85 * 86 * When the request has been processed, user-space must return the 87 * dm_ulog_request to the kernel - setting the 'error' field and clearing 88 * 'data_size' appropriately. 89 */ 90 #define DM_ULOG_DTR 2 91 92 /* 93 * DM_ULOG_PRESUSPEND corresponds to (found in dm-dirty-log.h): 94 * int (*presuspend)(struct dm_dirty_log *log); 95 * 96 * Payload-to-userspace: 97 * None. 98 * Payload-to-kernel: 99 * None. 100 * 101 * The UUID contained in the dm_ulog_request structure is all that is 102 * necessary to identify the log instance being presuspended. There is no 103 * payload data. 104 * 105 * When the request has been processed, user-space must return the 106 * dm_ulog_request to the kernel - setting the 'error' field and 107 * 'data_size' appropriately. 108 */ 109 #define DM_ULOG_PRESUSPEND 3 110 111 /* 112 * DM_ULOG_POSTSUSPEND corresponds to (found in dm-dirty-log.h): 113 * int (*postsuspend)(struct dm_dirty_log *log); 114 * 115 * Payload-to-userspace: 116 * None. 117 * Payload-to-kernel: 118 * None. 119 * 120 * The UUID contained in the dm_ulog_request structure is all that is 121 * necessary to identify the log instance being postsuspended. There is no 122 * payload data. 123 * 124 * When the request has been processed, user-space must return the 125 * dm_ulog_request to the kernel - setting the 'error' field and 126 * 'data_size' appropriately. 127 */ 128 #define DM_ULOG_POSTSUSPEND 4 129 130 /* 131 * DM_ULOG_RESUME corresponds to (found in dm-dirty-log.h): 132 * int (*resume)(struct dm_dirty_log *log); 133 * 134 * Payload-to-userspace: 135 * None. 136 * Payload-to-kernel: 137 * None. 138 * 139 * The UUID contained in the dm_ulog_request structure is all that is 140 * necessary to identify the log instance being resumed. There is no 141 * payload data. 142 * 143 * When the request has been processed, user-space must return the 144 * dm_ulog_request to the kernel - setting the 'error' field and 145 * 'data_size' appropriately. 146 */ 147 #define DM_ULOG_RESUME 5 148 149 /* 150 * DM_ULOG_GET_REGION_SIZE corresponds to (found in dm-dirty-log.h): 151 * __u32 (*get_region_size)(struct dm_dirty_log *log); 152 * 153 * Payload-to-userspace: 154 * None. 155 * Payload-to-kernel: 156 * __u64 - contains the region size 157 * 158 * The region size is something that was determined at constructor time. 159 * It is returned in the payload area and 'data_size' is set to 160 * reflect this. 161 * 162 * When the request has been processed, user-space must return the 163 * dm_ulog_request to the kernel - setting the 'error' field appropriately. 164 */ 165 #define DM_ULOG_GET_REGION_SIZE 6 166 167 /* 168 * DM_ULOG_IS_CLEAN corresponds to (found in dm-dirty-log.h): 169 * int (*is_clean)(struct dm_dirty_log *log, region_t region); 170 * 171 * Payload-to-userspace: 172 * __u64 - the region to get clean status on 173 * Payload-to-kernel: 174 * __s64 - 1 if clean, 0 otherwise 175 * 176 * Payload is sizeof(__u64) and contains the region for which the clean 177 * status is being made. 178 * 179 * When the request has been processed, user-space must return the 180 * dm_ulog_request to the kernel - filling the payload with 0 (not clean) or 181 * 1 (clean), setting 'data_size' and 'error' appropriately. 182 */ 183 #define DM_ULOG_IS_CLEAN 7 184 185 /* 186 * DM_ULOG_IN_SYNC corresponds to (found in dm-dirty-log.h): 187 * int (*in_sync)(struct dm_dirty_log *log, region_t region, 188 * int can_block); 189 * 190 * Payload-to-userspace: 191 * __u64 - the region to get sync status on 192 * Payload-to-kernel: 193 * __s64 - 1 if in-sync, 0 otherwise 194 * 195 * Exactly the same as 'is_clean' above, except this time asking "has the 196 * region been recovered?" vs. "is the region not being modified?" 197 */ 198 #define DM_ULOG_IN_SYNC 8 199 200 /* 201 * DM_ULOG_FLUSH corresponds to (found in dm-dirty-log.h): 202 * int (*flush)(struct dm_dirty_log *log); 203 * 204 * Payload-to-userspace: 205 * If the 'integrated_flush' directive is present in the constructor 206 * table, the payload is as same as DM_ULOG_MARK_REGION: 207 * __u64 [] - region(s) to mark 208 * else 209 * None 210 * Payload-to-kernel: 211 * None. 212 * 213 * If the 'integrated_flush' option was used during the creation of the 214 * log, mark region requests are carried as payload in the flush request. 215 * Piggybacking the mark requests in this way allows for fewer communications 216 * between kernel and userspace. 217 * 218 * When the request has been processed, user-space must return the 219 * dm_ulog_request to the kernel - setting the 'error' field and clearing 220 * 'data_size' appropriately. 221 */ 222 #define DM_ULOG_FLUSH 9 223 224 /* 225 * DM_ULOG_MARK_REGION corresponds to (found in dm-dirty-log.h): 226 * void (*mark_region)(struct dm_dirty_log *log, region_t region); 227 * 228 * Payload-to-userspace: 229 * __u64 [] - region(s) to mark 230 * Payload-to-kernel: 231 * None. 232 * 233 * Incoming payload contains the one or more regions to mark dirty. 234 * The number of regions contained in the payload can be determined from 235 * 'data_size/sizeof(__u64)'. 236 * 237 * When the request has been processed, user-space must return the 238 * dm_ulog_request to the kernel - setting the 'error' field and clearing 239 * 'data_size' appropriately. 240 */ 241 #define DM_ULOG_MARK_REGION 10 242 243 /* 244 * DM_ULOG_CLEAR_REGION corresponds to (found in dm-dirty-log.h): 245 * void (*clear_region)(struct dm_dirty_log *log, region_t region); 246 * 247 * Payload-to-userspace: 248 * __u64 [] - region(s) to clear 249 * Payload-to-kernel: 250 * None. 251 * 252 * Incoming payload contains the one or more regions to mark clean. 253 * The number of regions contained in the payload can be determined from 254 * 'data_size/sizeof(__u64)'. 255 * 256 * When the request has been processed, user-space must return the 257 * dm_ulog_request to the kernel - setting the 'error' field and clearing 258 * 'data_size' appropriately. 259 */ 260 #define DM_ULOG_CLEAR_REGION 11 261 262 /* 263 * DM_ULOG_GET_RESYNC_WORK corresponds to (found in dm-dirty-log.h): 264 * int (*get_resync_work)(struct dm_dirty_log *log, region_t *region); 265 * 266 * Payload-to-userspace: 267 * None. 268 * Payload-to-kernel: 269 * { 270 * __s64 i; -- 1 if recovery necessary, 0 otherwise 271 * __u64 r; -- The region to recover if i=1 272 * } 273 * 'data_size' should be set appropriately. 274 * 275 * When the request has been processed, user-space must return the 276 * dm_ulog_request to the kernel - setting the 'error' field appropriately. 277 */ 278 #define DM_ULOG_GET_RESYNC_WORK 12 279 280 /* 281 * DM_ULOG_SET_REGION_SYNC corresponds to (found in dm-dirty-log.h): 282 * void (*set_region_sync)(struct dm_dirty_log *log, 283 * region_t region, int in_sync); 284 * 285 * Payload-to-userspace: 286 * { 287 * __u64 - region to set sync state on 288 * __s64 - 0 if not-in-sync, 1 if in-sync 289 * } 290 * Payload-to-kernel: 291 * None. 292 * 293 * When the request has been processed, user-space must return the 294 * dm_ulog_request to the kernel - setting the 'error' field and clearing 295 * 'data_size' appropriately. 296 */ 297 #define DM_ULOG_SET_REGION_SYNC 13 298 299 /* 300 * DM_ULOG_GET_SYNC_COUNT corresponds to (found in dm-dirty-log.h): 301 * region_t (*get_sync_count)(struct dm_dirty_log *log); 302 * 303 * Payload-to-userspace: 304 * None. 305 * Payload-to-kernel: 306 * __u64 - the number of in-sync regions 307 * 308 * No incoming payload. Kernel-bound payload contains the number of 309 * regions that are in-sync (in a size_t). 310 * 311 * When the request has been processed, user-space must return the 312 * dm_ulog_request to the kernel - setting the 'error' field and 313 * 'data_size' appropriately. 314 */ 315 #define DM_ULOG_GET_SYNC_COUNT 14 316 317 /* 318 * DM_ULOG_STATUS_INFO corresponds to (found in dm-dirty-log.h): 319 * int (*status)(struct dm_dirty_log *log, STATUSTYPE_INFO, 320 * char *result, unsigned maxlen); 321 * 322 * Payload-to-userspace: 323 * None. 324 * Payload-to-kernel: 325 * Character string containing STATUSTYPE_INFO 326 * 327 * When the request has been processed, user-space must return the 328 * dm_ulog_request to the kernel - setting the 'error' field and 329 * 'data_size' appropriately. 330 */ 331 #define DM_ULOG_STATUS_INFO 15 332 333 /* 334 * DM_ULOG_STATUS_TABLE corresponds to (found in dm-dirty-log.h): 335 * int (*status)(struct dm_dirty_log *log, STATUSTYPE_TABLE, 336 * char *result, unsigned maxlen); 337 * 338 * Payload-to-userspace: 339 * None. 340 * Payload-to-kernel: 341 * Character string containing STATUSTYPE_TABLE 342 * 343 * When the request has been processed, user-space must return the 344 * dm_ulog_request to the kernel - setting the 'error' field and 345 * 'data_size' appropriately. 346 */ 347 #define DM_ULOG_STATUS_TABLE 16 348 349 /* 350 * DM_ULOG_IS_REMOTE_RECOVERING corresponds to (found in dm-dirty-log.h): 351 * int (*is_remote_recovering)(struct dm_dirty_log *log, region_t region); 352 * 353 * Payload-to-userspace: 354 * __u64 - region to determine recovery status on 355 * Payload-to-kernel: 356 * { 357 * __s64 is_recovering; -- 0 if no, 1 if yes 358 * __u64 in_sync_hint; -- lowest region still needing resync 359 * } 360 * 361 * When the request has been processed, user-space must return the 362 * dm_ulog_request to the kernel - setting the 'error' field and 363 * 'data_size' appropriately. 364 */ 365 #define DM_ULOG_IS_REMOTE_RECOVERING 17 366 367 /* 368 * (DM_ULOG_REQUEST_MASK & request_type) to get the request type 369 * 370 * Payload-to-userspace: 371 * A single string containing all the argv arguments separated by ' 's 372 * Payload-to-kernel: 373 * None. ('data_size' in the dm_ulog_request struct should be 0.) 374 * 375 * We are reserving 8 bits of the 32-bit 'request_type' field for the 376 * various request types above. The remaining 24-bits are currently 377 * set to zero and are reserved for future use and compatibility concerns. 378 * 379 * User-space should always use DM_ULOG_REQUEST_TYPE to acquire the 380 * request type from the 'request_type' field to maintain forward compatibility. 381 */ 382 #define DM_ULOG_REQUEST_MASK 0xFF 383 #define DM_ULOG_REQUEST_TYPE(request_type) \ 384 (DM_ULOG_REQUEST_MASK & (request_type)) 385 386 /* 387 * DM_ULOG_REQUEST_VERSION is incremented when there is a 388 * change to the way information is passed between kernel 389 * and userspace. This could be a structure change of 390 * dm_ulog_request or a change in the way requests are 391 * issued/handled. Changes are outlined here: 392 * version 1: Initial implementation 393 * version 2: DM_ULOG_CTR allowed to return a string containing a 394 * device name that is to be registered with DM via 395 * 'dm_get_device'. 396 * version 3: DM_ULOG_FLUSH is capable of carrying payload for marking 397 * regions. This "integrated flush" reduces the number of 398 * requests between the kernel and userspace by effectively 399 * merging 'mark' and 'flush' requests. A constructor table 400 * argument ('integrated_flush') is required to turn this 401 * feature on, so it is backwards compatible with older 402 * userspace versions. 403 */ 404 #define DM_ULOG_REQUEST_VERSION 3 405 406 struct dm_ulog_request { 407 /* 408 * The local unique identifier (luid) and the universally unique 409 * identifier (uuid) are used to tie a request to a specific 410 * mirror log. A single machine log could probably make due with 411 * just the 'luid', but a cluster-aware log must use the 'uuid' and 412 * the 'luid'. The uuid is what is required for node to node 413 * communication concerning a particular log, but the 'luid' helps 414 * differentiate between logs that are being swapped and have the 415 * same 'uuid'. (Think "live" and "inactive" device-mapper tables.) 416 */ 417 __u64 luid; 418 char uuid[DM_UUID_LEN]; 419 char padding[3]; /* Padding because DM_UUID_LEN = 129 */ 420 421 __u32 version; /* See DM_ULOG_REQUEST_VERSION */ 422 __s32 error; /* Used to report back processing errors */ 423 424 __u32 seq; /* Sequence number for request */ 425 __u32 request_type; /* DM_ULOG_* defined above */ 426 __u32 data_size; /* How much data (not including this struct) */ 427 428 char data[0]; 429 }; 430 431 #endif /* __DM_LOG_USERSPACE_H__ */ 432