lib/evms/common.h

   1 /*
   2  *
   3  *   Copyright (c) International Business Machines  Corp., 2001
   4  *
   5  *   This program is free software;  you can redistribute it and/or modify
   6  *   it under the terms of the GNU General Public License as published by
   7  *   the Free Software Foundation; either version 2 of the License, or
   8  *   (at your option) any later version.
   9  *
  10  *   This program is distributed in the hope that it will be useful,
  11  *   but WITHOUT ANY WARRANTY;  without even the implied warranty of
  12  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
  13  *   the GNU General Public License for more details.
  14  *
  15  *   You should have received a copy of the GNU General Public License
  16  *   along with this program;  if not, write to the Free Software
  17  *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  18  *
  19  * Module: common.h
  20  */
  21
  22 #ifndef EVMS_COMMON_H_INCLUDED
  23 #define EVMS_COMMON_H_INCLUDED 1
  24
  25 #include <stdlib.h>
  26 #include <stdint.h>
  27 #include <sys/types.h>
  28
  29 /* version info */
  30 #define EVMS_MAJOR_VERSION              1
  31 #define EVMS_MINOR_VERSION              2
  32 #define EVMS_PATCHLEVEL_VERSION         0
  33
  34 #define EVMS_MAJOR                      117
  35
  36 #define MAX_EVMS_VOLUMES                256     /* There are 256 minors */
  37 #define EVMS_VOLUME_NAME_SIZE           127
  38
  39 #define IBM_OEM_ID                      8112    // could be anything, but used
  40
  41 // I=8, B=1, M=12
  42 // this one going away as well.
  43 #define EVMS_OEM_IBM                    IBM_OEM_ID
  44
  45 #define EVMS_INITIAL_CRC                0xFFFFFFFF
  46 #define EVMS_MAGIC_CRC                  0x31415926
  47
  48 #define EVMS_VSECTOR_SIZE               512
  49 #define EVMS_VSECTOR_SIZE_SHIFT         9
  50
  51 #define DEV_PATH                        "/dev"
  52 #define EVMS_DIR_NAME                   "evms"
  53 #define EVMS_DEV_NAME                   "block_device"
  54 #define EVMS_DEV_NODE_PATH              DEV_PATH "/" EVMS_DIR_NAME "/"
  55 #define EVMS_DEVICE_NAME                DEV_PATH "/" EVMS_DIR_NAME "/" EVMS_DEV_NAME
  56
  57 /* EVMS will always use 64-bit fields */
  58 typedef u_int64_t evms_sector_t;
  59
  60 /* EVMS specific device handle type definition */
  61 typedef u_int64_t evms_dev_handle_t;
  62
  63 typedef struct evms_version {
  64     /* major changes when incompatible differences are introduced */
  65     u_int32_t major;
  66     /* minor changes when additions are made */
  67     u_int32_t minor;
  68     /* patchlevel changes when bugs are fixed */
  69     u_int32_t patchlevel;
  70 } evms_version_t;
  71
  72 typedef enum evms_plugin_code {
  73     EVMS_NO_PLUGIN,                                     // 0
  74     EVMS_DEVICE_MANAGER,                                // 1
  75     EVMS_SEGMENT_MANAGER,                               // 2
  76     EVMS_REGION_MANAGER,                                // 3
  77     EVMS_FEATURE,                                       // 4
  78     EVMS_ASSOCIATIVE_FEATURE,                           // 5
  79     EVMS_FILESYSTEM_INTERFACE_MODULE,                   // 6
  80     EVMS_CLUSTER_MANAGER_INTERFACE_MODULE,              // 7
  81     EVMS_DISTRIBUTED_LOCK_MANAGER_INTERFACE_MODULE      // 8
  82 } evms_plugin_code_t;
  83
  84 #define SetPluginID(oem, type, id) ((oem << 16) | (type << 12) | id)
  85 #define GetPluginOEM(pluginid) (pluginid >> 16)
  86 #define GetPluginType(pluginid) ((pluginid >> 12) & 0xf)
  87 #define GetPluginID(pluginid) (pluginid & 0xfff)
  88
  89 /* bit definitions for the flags field in
  90  * the EVMS LOGICAL NODE (kernel) and
  91  * the EVMS LOGICAL VOLUME (user) structures.
  92  */
  93 #define EVMS_FLAGS_WIDTH                32
  94 #define EVMS_VOLUME_FLAG                (1<<0)
  95 #define EVMS_VOLUME_PARTIAL_FLAG        (1<<1)
  96 #define EVMS_VOLUME_PARTIAL             (1<<1)
  97 #define EVMS_VOLUME_SET_READ_ONLY       (1<<2)
  98 #define EVMS_VOLUME_READ_ONLY           (1<<2)
  99
 100 /* queued flags bits */
 101 #define EVMS_REQUESTED_DELETE           (1<<5)
 102 #define EVMS_REQUESTED_QUIESCE          (1<<6)
 103 #define EVMS_REQUESTED_VFS_QUIESCE      (1<<7)
 104
 105 /* this bit indicates corruption */
 106 #define EVMS_VOLUME_CORRUPT             (1<<8)
 107
 108 /* these bits define the source of the corruption */
 109 #define EVMS_VOLUME_SOFT_DELETED        (1<<9)
 110 #define EVMS_DEVICE_UNAVAILABLE         (1<<10)
 111
 112 /* these bits are used for moving objects. */
 113 #define EVMS_MOVE_PARENT                (1<<11)
 114
 115 /* these bits define volume status */
 116 #define EVMS_MEDIA_CHANGED              (1<<20)
 117 #define EVMS_DEVICE_UNPLUGGED           (1<<21)
 118
 119 /* these bits used for removable status */
 120 #define EVMS_DEVICE_MEDIA_PRESENT       (1<<24)
 121 #define EVMS_DEVICE_PRESENT             (1<<25)
 122 #define EVMS_DEVICE_LOCKABLE            (1<<26)
 123 #define EVMS_DEVICE_REMOVABLE           (1<<27)
 124
 125 /* version info for evms_feature_header_t */
 126 #define EVMS_FEATURE_HEADER_MAJOR       3
 127 #define EVMS_FEATURE_HEADER_MINOR       0
 128 #define EVMS_FEATURE_HEADER_PATCHLEVEL  0
 129
 130 /* version info for evms_feature_header_t that has fields for move*/
 131 #define EVMS_MOVE_FEATURE_HEADER_MAJOR       3
 132 #define EVMS_MOVE_FEATURE_HEADER_MINOR       1
 133 #define EVMS_MOVE_FEATURE_HEADER_PATCHLEVEL  0
 134
 135 /* bit definitions of FEATURE HEADER bits in the FLAGS field  */
 136 #define EVMS_FEATURE_ACTIVE             (1<<0)
 137 #define EVMS_FEATURE_VOLUME_COMPLETE    (1<<1)
 138
 139 /* bit definitions for VOLUME bits in the FLAGS field */
 140 #define EVMS_VOLUME_DATA_OBJECT         (1<<16)
 141 #define EVMS_VOLUME_DATA_STOP           (1<<17)
 142
 143 #define EVMS_FEATURE_HEADER_SIGNATURE   0x54414546  // "FEAT"
 144 typedef struct evms_feature_header {
 145 /*  0*/
 146     u_int32_t signature;
 147 /*  4*/ u_int32_t crc;
 148 /*  8*/ evms_version_t version;
 149     /* structure version */
 150 /* 20*/ evms_version_t engine_version;
 151     /* version of the Engine that */
 152     /* wrote this feature header  */
 153 /* 32*/ u_int32_t flags;
 154 /* 36*/ u_int32_t feature_id;
 155 /* 40*/ u_int64_t sequence_number;
 156 /* 48*/ u_int64_t alignment_padding;
 157     //required: starting lsn to 1st copy of feature's metadata.
 158 /* 56*/ evms_sector_t feature_data1_start_lsn;
 159 /* 64*/ evms_sector_t feature_data1_size;
 160     //in 512 byte units
 161     //optional: starting lsn to 2nd copy of feature's metadata.
 162     //          if unused set size field to 0.
 163 /* 72*/ evms_sector_t feature_data2_start_lsn;
 164 /* 80*/ evms_sector_t feature_data2_size;
 165     //in 512 byte units
 166 /* 88*/ u_int64_t volume_serial_number;
 167 /* 96*/ u_int32_t volume_system_id;
 168     /* the minor is stored here */
 169 /*100*/ u_int32_t object_depth;
 170     /* depth of object in the volume tree */
 171 /*104*/ char object_name[EVMS_VOLUME_NAME_SIZE + 1];
 172 /*232*/ char volume_name[EVMS_VOLUME_NAME_SIZE + 1];
 173 /*360*/ u_int32_t move_source;
 174     /* version 3.1.0 feature header */
 175 /*364*/ u_int32_t move_target;
 176     /* version 3.1.0 feature header */
 177 /*368*/ unsigned char pad[144];
 178 /*512*/
 179 } evms_feature_header_t;
 180
 181 /* EVMS specific error codes */
 182 #define EVMS_FEATURE_FATAL_ERROR        257
 183 #define EVMS_VOLUME_FATAL_ERROR         258
 184
 185 #define EVMS_FEATURE_INCOMPLETE_ERROR   259
 186
 187 /* Defines for storage object names */
 188 #define EVMS_NAME_SIZE                  EVMS_VOLUME_NAME_SIZE
 189
 190 /* Defines for the flags in the storage_object_t structure */
 191 #define SOFLAG_DIRTY                    (1<<0)
 192 #define SOFLAG_NEW                      (1<<1)
 193 #define SOFLAG_READ_ONLY                (1<<2)
 194 #define SOFLAG_FEATURE_HEADER_DIRTY     (1<<3)
 195 #define SOFLAG_MUST_BE_TOP              (1<<4)
 196 #define SOFLAG_IO_ERROR                 (1<<5)
 197 #define SOFLAG_CORRUPT                  (1<<6)
 198 #define SOFLAG_BIOS_READABLE            (1<<7)
 199 #define SOFLAG_MUST_BE_VOLUME           (1<<8)
 200 #define SOFLAG_NOT_CLAIMED              (1<<9)
 201 #define SOFLAG_HAS_STOP_DATA            (1<<10)
 202
 203 /* Defines for flags in the storage_container_t structure */
 204 #define SCFLAG_DIRTY                    (1<<0)
 205 #define SCFLAG_NEW                      (1<<1)
 206
 207 /* Defines for the flags in the logical_volume_t structure */
 208 #define VOLFLAG_DIRTY                   (1<<0)
 209 #define VOLFLAG_NEW                     (1<<1)
 210 #define VOLFLAG_READ_ONLY               (1<<2)
 211 #define VOLFLAG_NEEDS_DEV_NODE          (1<<3)
 212 #define VOLFLAG_COMPATIBILITY           (1<<4)
 213 #define VOLFLAG_FOREIGN                 (1<<5)
 214 #define VOLFLAG_MKFS                    (1<<6)
 215 #define VOLFLAG_UNMKFS                  (1<<7)
 216 #define VOLFLAG_FSCK                    (1<<8)
 217 #define VOLFLAG_DEFRAG                  (1<<9)
 218 #define VOLFLAG_EXPAND_FS               (1<<10)
 219 #define VOLFLAG_SHRINK_FS               (1<<11)
 220 #define VOLFLAG_SYNC_FS                 (1<<12)
 221 #define VOLFLAG_PROBE_FS                (1<<13)
 222 #define VOLFLAG_IS_EXTERNAL_LOG         (1<<14)
 223 #define VOLFLAG_HAS_EXTERNAL_LOG        (1<<15)
 224
 225 /* A BOOLEAN variable is one which is either TRUE or FALSE. */
 226 #ifndef BOOLEAN_DEFINED
 227   #define BOOLEAN_DEFINED 1
 228 typedef unsigned char BOOLEAN;
 229 #endif
 230
 231 #ifndef TRUE
 232   #define TRUE  1
 233 #endif
 234 #ifndef FALSE
 235   #define FALSE 0
 236 #endif
 237
 238 /*
 239  * Logical Sector Number: This is a physical sector address on a system drive.
 240  */
 241 typedef u_int64_t       lsn_t;
 242
 243 /*
 244  * Logical Block Address: This is a sector address on a volume which will be
 245  * translated to a Logical Sector Number.
 246  */
 247 typedef u_int64_t       lba_t;
 248
 249 /*
 250  * A sector_count_t is a count of sectors.  It is mainly used to hold the size
 251  * of a disk, segment, region, etc.
 252  */
 253 typedef u_int64_t       sector_count_t;
 254
 255 /*
 256  * A module_handle_t variable is one which holds a handle (or descriptor)
 257  * referencing a loaded module.
 258  */
 259 typedef void          * module_handle_t;
 260
 261 /*
 262  * The standard data type for Engine handles
 263  */
 264 typedef u_int32_t       engine_handle_t;
 265
 266 /*
 267  * An object_handle_t holds a handle for an EVMS Engine object.
 268  */
 269 typedef engine_handle_t object_handle_t;
 270
 271 /*
 272  * A plugin_handle_t holds a handle for an EVMS Engine plug-in.
 273  */
 274 typedef engine_handle_t plugin_handle_t;
 275
 276 /*
 277  * A plugin_ID_t holds a unique ID for a plug-in.
 278  */
 279 typedef u_int32_t       plugin_id_t;
 280
 281 /*
 282  * A plugin_type_t holds the type field of a plug-in's ID.
 283  */
 284 typedef u_int8_t        plugin_type_t;
 285
 286 /*
 287  * The various modes in which the Engine can be
 288  */
 289 typedef enum {
 290     ENGINE_CLOSED = 0,
 291     ENGINE_READONLY,
 292     ENGINE_READWRITE
 293 } engine_mode_t;
 294
 295 /*
 296  * The geometry of a disk, segment, region, etc.
 297  */
 298 typedef struct geometry_s {
 299     u_int64_t   cylinders;
 300     u_int32_t   heads;
 301     u_int32_t   sectors_per_track;
 302     u_int32_t   bytes_per_sector;
 303     u_int64_t   boot_cylinder_limit;
 304     u_int64_t   block_size;
 305 } geometry_t;
 306
 307
 308 /*
 309  * Definitions and structures for progress indicators.
 310  */
 311 typedef enum {
 312     DISPLAY_PERCENT = 0,    /* Display the progress as a percentage.      */
 313     /* This is the default display mode.          */
 314     DISPLAY_COUNT,          /* Display the progress as a count.           */
 315     INDETERMINATE           /* Progress cannot be measured with a count   */
 316     /* of items.  Progress is simply "working".   */
 317 } progress_type_t;
 318
 319 typedef struct progress_s {
 320     /*
 321      * The plug-in MUST set id to zero on the first call.  An id of zero
 322      * tells the UI to start a new progress indicator.  The UI MUST set the
 323      * id field to a nonzero number that is unique from any other progress
 324      * indicators that may be in effect.
 325      */
 326     uint            id;
 327
 328     /* Short title for the progress indicator */
 329     char          * title;
 330
 331     /* Longer description of the task that is in progress */
 332     char          * description;
 333
 334     /* Type of progress indicator */
 335     progress_type_t type;
 336
 337     /*
 338      * Current number of items completed.  The plug-in should set count to
 339      * zero on the first call.
 340      */
 341     uint            count;
 342
 343     /*
 344      * Total number of items to be completed.  The UI uses count/total_count
 345      * to calculate the percent complete.  On the plug-in's last call to
 346      * update the progress it MUST set count >= total_count.  When the UI
 347      * gets a call for progress and count >= total_count, it knows it is the
 348      * last call and closes the progress indicator.
 349      */
 350     uint            total_count;
 351
 352     /*
 353      * The plug-in may provide an estimate of how many seconds it will take
 354      * to complete the operation, but it is not required.  If the plug-in is
 355      * not providing a time estimate it MUST set remaining_seconds to zero.
 356      *
 357      * The plug-in may update remaining_seconds on subsequent calls for
 358      * progress.  If the plug-in does not provide a time estimate, the UI
 359      * may provide one based on the time elapsed between the calls to update
 360      * the progress and the numbers in the count and total_count fields.
 361      */
 362     uint            remaining_seconds;
 363
 364     /*
 365      * A place for the plug-in to store any data relating to this progress
 366      * indicator.
 367      */
 368     void          * plugin_private_data;
 369
 370     /*
 371      * A place for the UI to store any data relating to this progress
 372      * indicator.
 373      */
 374     void          * ui_private_data;
 375 } progress_t;
 376
 377 /*
 378  * The data types which a storage object can be.
 379  */
 380 typedef enum {
 381     META_DATA_TYPE  = (1<<0),
 382     DATA_TYPE       = (1<<1),
 383     FREE_SPACE_TYPE = (1<<2)
 384 } data_type_t;
 385
 386 /*
 387  * The types of structures the Engine exports
 388  */
 389 typedef enum {
 390     PLUGIN      = (1<<0),
 391     DISK        = (1<<1),
 392     SEGMENT     = (1<<2),
 393     REGION      = (1<<3),
 394     EVMS_OBJECT = (1<<4),
 395     CONTAINER   = (1<<5),
 396     VOLUME      = (1<<6)
 397 } object_type_t;
 398
 399 /*
 400  * Flags that can be used for filtering plug-ins on the evms_get_plugin_list API
 401  */
 402 typedef enum {
 403     SUPPORTS_CONTAINERS = (1<<0)
 404 } plugin_search_flags_t;
 405
 406 /*
 407  * Flags that can be used for filtering objects on the evms_get_object_list API
 408  */
 409 typedef enum {
 410     TOPMOST =           (1<<0),
 411     NOT_MUST_BE_TOP =   (1<<1),
 412     WRITEABLE =         (1<<2)
 413 } object_search_flags_t;
 414
 415 #define VALID_INPUT_OBJECT      (TOPMOST | NOT_MUST_BE_TOP | WRITEABLE)
 416
 417 /*
 418  * Debug levels
 419  * These levels should be kept in sync with the debug levels defined for the
 420  * EVMS kernel in linux/evms/evms.h.
 421  */
 422 typedef enum {
 423     /*
 424      * Use CRITICAL for messages that indicate that the health of the
 425      * system/Engine is in jeopardy.  Something _really_ bad happened,
 426      * such as failure to allocate memory or control structures are
 427      * corrupted.
 428      */
 429     CRITICAL = 0,
 430
 431     /*
 432      * Use SERIOUS for messages that something bad has happened, but not
 433      * as bad a CRITICAL.
 434      */
 435     SERIOUS = 1,
 436
 437     /*
 438      * Use ERROR for messages that indicate the user caused an error,
 439      * such as passing a bad parameter.  The message should help the
 440      * user correct the problem.
 441      */
 442     ERROR = 2,
 443
 444     /*
 445      * Use WARNING for messages that indicate that something is not quite
 446      * right and the user should know about it.  You may or may not be able
 447      * to work around the problem.
 448      */
 449     WARNING = 3,
 450
 451     /*
 452      * Use DEFAULT for informational messages that do not indicate problems,
 453      * or that a problem occurred but there was a work-around.  DEFAULT
 454      * messages should be things that the user would usually want to know
 455      * during any run of the Engine, such as how many volumes were discovered
 456      * on the system, and not necessarily what a developer would want to know
 457      * (use DETAILS or DEBUG for that).  Since DEFAULT is the default debug
 458      * level, be careful not to put DEFAULT messages in loops or frequently
 459      * executed code as they will bloat the log file.
 460      */
 461     DEFAULT = 5,
 462
 463     /*
 464      * Use DETAILS to provide more detailed information about the system.
 465      * The message may provide additional information about the progress of
 466      * the system.  It may contain more information about a DEFAULT message
 467      * or more information about an error condition.
 468      */
 469     DETAILS = 6,
 470
 471     /*
 472      * Use DEBUG for messages that would help debug a problem, such as
 473      * tracing code paths or dumping the contents of variables.
 474      */
 475     DEBUG = 7,
 476
 477     /*
 478      * Use EXTRA to provided more information than your standard debug
 479      * messages provide.
 480      */
 481
 482     EXTRA = 8,
 483
 484     /*
 485      * Use ENTRY_EXIT to trace entries and exits from functions.
 486      */
 487     ENTRY_EXIT = 9,
 488
 489     /*
 490      * Use EVERYTHING for all manner of verbose output.  Feel free to bloat
 491      * the log file with any messages that would help you debug a problem.
 492      */
 493     EVERYTHING = 10
 494
 495 } debug_level_t;
 496
 497
 498 /*
 499  * Handy macros for finding the min and max of two numbers.
 500  */
 501 #ifndef min
 502     #define min(a,b) (((a)<(b))?(a):(b))
 503 #endif
 504 #ifndef max
 505     #define max(a,b) (((a)>(b))?(a):(b))
 506 #endif
 507
 508
 509 #endif
 510