1/* 2 * Copyright (c) 2001-2007 Apple Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * The contents of this file constitute Original Code as defined in and 7 * are subject to the Apple Public Source License Version 1.1 (the 8 * "License"). You may not use this file except in compliance with the 9 * License. Please obtain a copy of the License at 10 * http://www.apple.com/publicsource and read it before using this file. 11 * 12 * This Original Code and all software distributed under the License are 13 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER 14 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 15 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 16 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the 17 * License for the specific language governing rights and limitations 18 * under the License. 19 * 20 * @APPLE_LICENSE_HEADER_END@ 21 */ 22 23#ifndef _APPLERAIDUSERLIB_H 24#define _APPLERAIDUSERLIB_H 25 26#define kAppleRAIDUserClassName "AppleRAID" 27#define kAppleRAIDSetClassName "AppleRAIDSet" 28#define kAppleLogicalVolumeClassName "AppleLVMVolume" 29 30// extras in IOMedia object for raid sets 31#define kAppleRAIDIsRAIDKey "RAID" // CFBoolean - true 32#define kAppleLVMIsLogicalVolumeKey "LVM" // CFBoolean - true 33 34// header defines 35 36#define kAppleRAIDHeaderVersionKey "AppleRAID-HeaderVersion" // CFNumber 32bit "0xMMMMmmmm" 37#define kAppleRAIDLevelNameKey "AppleRAID-LevelName" // CFString 38#define kAppleRAIDSetNameKey "AppleRAID-SetName" // CFString 39#define kAppleRAIDSetUUIDKey "AppleRAID-SetUUID" // CFString 40#define kAppleRAIDSequenceNumberKey "AppleRAID-SequenceNumber" // CFNumber 32bit 41#define kAppleRAIDChunkSizeKey "AppleRAID-ChunkSize" // CFNumber 64bit 42 43#define kAppleRAIDMembersKey "AppleRAID-Members" // CFArray of member UUIDs CFStrings 44 // (also used to determine member count) 45#define kAppleRAIDSparesKey "AppleRAID-Spares" // CFArray of spare UUIDs CFStrings 46 47// capabilities 48#define kAppleRAIDSetAutoRebuildKey "AppleRAID-AutoRebuild" // CFBoolean 49#define kAppleRAIDSetContentHintKey "AppleRAID-ContentHint" // CFString 50 51#define kAppleRAIDNoMediaExport "RAIDNoMedia" // CFString - for LVG 52#define kAppleRAIDNoFileSystem "RAIDNoFS" // CFString - for stacked raid sets 53 54#define kAppleRAIDSetQuickRebuildKey "AppleRAID-QuickRebuild" // CFBoolean (faked, not in header) 55#define kAppleRAIDSetTimeoutKey "AppleRAID-SetTimeout" // CFNumber 32bit 56#define kAppleRAIDPrimaryMetaDataUsedKey "AppleRAID-MetaData1Used" // CFNumber 64bit (freespace, lvg toc) 57 58#define kAppleRAIDCanAddMembersKey "AppleRAID-CanAddMembers" // CFBoolean 59#define kAppleRAIDCanAddSparesKey "AppleRAID-CanAddSpares" // CFBoolean 60#define kAppleRAIDSizesCanVaryKey "AppleRAID-SizesCanVary" // CFBoolean - true for concat, lvg 61#define kAppleRAIDRemovalAllowedKey "AppleRAID-RemovalAllowed" // CFString 62 63#define kAppleRAIDRemovalNone "None" // stripe 64#define kAppleRAIDRemovalLastMember "Last" // concat 65#define kAppleRAIDRemovalAnyOneMember "AnyOne" // raid v 66#define kAppleRAIDRemovalAnyMember "Any" // mirror 67 68#define kAppleRAIDCanBeConvertedToKey "AppleRAID-CanBeConvertedTo" // CFBoolean 69 70#define kAppleRAIDLVGExtentsKey "AppleRAID-LVGExtents" // CFNumber 64bit (faked, lvg only) 71#define kAppleRAIDLVGVolumeCountKey "AppleRAID-LVGVolumeCount" // CFNumber 32bit (faked, lvg only) 72#define kAppleRAIDLVGFreeSpaceKey "AppleRAID-LVGFreeSpace" // CFNumber 64bit (faked, lvg only) 73 74// member defines (varies per member) 75 76#define kAppleRAIDMemberTypeKey "AppleRAID-MemberType" // CFStrings 77#define kAppleRAIDMemberUUIDKey "AppleRAID-MemberUUID" // CFString 78#define kAppleRAIDMemberIndexKey "AppleRAID-MemberIndex" // CFNumber 32bit 79#define kAppleRAIDChunkCountKey "AppleRAID-ChunkCount" // CFNumber 64bit 80#define kAppleRAIDMemberStartKey "AppleRAID-MemberStart" // CFNumber 64bit (faked, lvg only) 81#define kAppleRAIDSecondaryMetaDataSizeKey "AppleRAID-MetaData2Size" // CFNumber 64bit (lve data, varies per member) 82 83// logical volume defines 84 85#define kAppleLVMVolumeVersionKey "AppleLVM-Version" // CFNumber 32bit "0xMMMMmmmm" 86#define kAppleLVMVolumeUUIDKey "AppleLVM-VolumeUUID" // CFString 87#define kAppleLVMGroupUUIDKey "AppleLVM-GroupUUID" // CFString 88//#define kAppleLVMSnapShotUUIDKey "AppleLVM-SnapUUID" // CFString 89//#define kAppleLVMBitMapUUIDKey "AppleLVM-BitMapUUID" // CFString 90#define kAppleLVMParentUUIDKey "AppleLVM-ParentUUID" // CFString 91#define kAppleLVMVolumeSequenceKey "AppleLVM-Sequence" // CFNumber 32bit 92#define kAppleLVMVolumeSizeKey "AppleLVM-VolumeSize" // CFNumber 64bit (faked) 93#define kAppleLVMVolumeExtentCountKey "AppleLVM-ExtentCount" // CFNumber 64bit 94#define kAppleLVMVolumeTypeKey "AppleLVM-Type" // CFString 95#define kAppleLVMVolumeTypeConcat "concat" 96#define kAppleLVMVolumeTypeStripe "stripe" 97#define kAppleLVMVolumeTypeMirror "mirror" 98#define kAppleLVMVolumeTypeSnapRO "snap ro" // AppleLVMSnapShotVolume only 99#define kAppleLVMVolumeTypeSnapRW "snap rw" // AppleLVMSnapShotVolume only 100#define kAppleLVMVolumeTypeBitMap "bitmap" // internal use only 101#define kAppleLVMVolumeTypeMaster "master" // internal use only 102#define kAppleLVMVolumeLocationKey "AppleLVM-Location" // CFString 103#define kAppleLVMVolumeLocationFast "fast" 104#define kAppleLVMVolumeLocationMedium "medium" 105#define kAppleLVMVolumeLocationSlow "slow" 106#define kAppleLVMVolumeContentHintKey "AppleLVM-ContentHint" // CFString 107#define kAppleLVMVolumeStatusKey "AppleLVM-Status" // CFString 108#define kAppleLVMVolumeNameKey "AppleLVM-Name" // CFString 109 110// XXXSNAP remaining free space for snap 111 112// status defines 113 114#define kAppleRAIDStatusKey "AppleRAID-SetStatus" 115#define kAppleRAIDMemberStatusKey "AppleRAID-MemberStatus" 116 117#define kAppleRAIDStatusOffline "Offline" 118#define kAppleRAIDStatusDegraded "Degraded" 119#define kAppleRAIDStatusOnline "Online" 120 121#define kAppleRAIDStatusMissing "Missing" // member only 122#define kAppleRAIDStatusFailed "Failed" // member only 123#define kAppleRAIDStatusSpare "Standby" // member only 124#define kAppleRAIDStatusRebuilding "Rebuilding" // member only 125 126#define kAppleRAIDRebuildStatus "AppleRAID-Rebuild-Progress" // CFNumber 64bit (bytes completed) 127 128// dummy string for deleted members 129#define kAppleRAIDDeletedUUID "00000000-0000-0000-0000-000000000000" 130#define kAppleRAIDMissingUUID "FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF" 131 132enum { 133 kAppleRAIDDummySpareIndex = 9999 134}; 135 136// Get List of Sets Flags 137enum { 138 kAppleRAIDOfflineSets = 0x00000001, 139 kAppleRAIDDegradedSets = 0x00000002, 140 kAppleRAIDOnlineSets = 0x00000004, 141 kAppleRAIDState = 0x000000ff, 142 143 kAppleRAIDVisibleSets = 0x00000100, 144 kAppleRAIDInternalSets = 0x00000200, 145 kAppleRAIDVisibility = 0x00000f00, 146 147 kAppleRAIDRunning = 0x00000106, // usable user visible sets 148 149 kAppleRAIDAllSets = 0xffffffff 150}; 151 152#ifndef KERNEL 153 154// CFString that contains the set's UUID string 155typedef CFStringRef AppleRAIDSetRef; 156 157// CFString that contains the member's UUID string 158typedef CFStringRef AppleRAIDMemberRef; 159 160 161// ******************************************************************************************** 162// ******************************************************************************************** 163 164#define kAppleRAIDNotificationSetDiscovered "AppleRAIDNotificationSetDiscovered" 165#define kAppleRAIDNotificationSetChanged "AppleRAIDNotificationSetChanged" 166#define kAppleRAIDNotificationSetTerminated "AppleRAIDNotificationSetTerminated" 167 168#define kAppleLVMNotificationVolumeDiscovered "AppleLVMNotificationVolumeDiscovered" 169#define kAppleLVMNotificationVolumeChanged "AppleLVMNotificationVolumeChanged" 170#define kAppleLVMNotificationVolumeTerminated "AppleLVMNotificationVolumeTerminated" 171 172CF_EXPORT 173kern_return_t AppleRAIDEnableNotifications(void); 174 175CF_EXPORT 176kern_return_t AppleRAIDDisableNotifications(void); 177 178 179// ******************************************************************************************** 180// ******************************************************************************************** 181 182 183/*! 184 @function AppleRAIDGetListOfSets 185 @discussion Returns a "filtered" list of the RAID sets on system, as a CFArray of AppleRAIDSetRefs. 186 @param filter - Used to determine which types RAID sets to return. 187*/ 188CF_EXPORT 189CFMutableArrayRef AppleRAIDGetListOfSets(UInt32 filter); 190 191 192/*! 193 @function AppleRAIDGetSetProperties 194 @discussion Returns CFMutableDictionaryRef - a dict with information on this set - type of set, ... 195 @param setRef A handle for finding the RAID set. 196*/ 197CF_EXPORT 198CFMutableDictionaryRef AppleRAIDGetSetProperties(AppleRAIDSetRef setRef); 199 200 201/*! 202 @function AppleRAIDGetMemberProperties 203 @discussion Returns CFMutableDictionaryRef - a dict with information on this member of the set 204 Mostly useful for find out the member's status, like online, offline, missing, spare, % rebuild. 205 @param memberRef A handle for finding the RAID set's member. 206*/ 207CF_EXPORT 208CFMutableDictionaryRef AppleRAIDGetMemberProperties(AppleRAIDMemberRef memberRef); 209 210 211// ******************************************************************************************** 212 213/*! 214 @function AppleRAIDGetUsableSize 215 @discussion Returns the amount of space available to for use after RAID headers have been added. 216 The primary use would be for converting a regular volume into a mirrored or JBOD volume. 217 The returned value is the size the current filesystem needs to be shrunk to in order to fit. 218 @param partitionSize - size of the partition in bytes 219 @param chunkSize - size of the chunkSize in bytes. 220 @param options - options that this set will support that require additional disk space 221*/ 222CF_EXPORT 223UInt64 AppleRAIDGetUsableSize(UInt64 partitionSize, UInt64 chunkSize, UInt32 options); 224 225// XXX use raid type strings here instead? there is no mirror with quickrebuild string 226 227#define kAppleRAIDUsableSizeOptionNone 0x0 228#define kAppleRAIDUsableSizeOptionQuickRebuild 0x1 229#define kAppleRAIDUsableSizeOptionLVG 0x2 // for enable 230 231/*! 232 @function AppleRAIDGetSetDescriptions 233 @discussion Returns an array of dictionaries. Each dictionary contains an list of capabilites for that raid type: 234 235 - raid type name 236 - features: supports spares, members can vary in size 237 - "tradeoffs", speed, space efficency, ... 238 - allowable ranges for settings: chunk 239 - list of what types it can be convert to (later) 240*/ 241CF_EXPORT 242CFMutableArrayRef AppleRAIDGetSetDescriptions(void); 243 244 245/*! 246 @function AppleRAIDCreateSet 247 @discussion Returns an AppleRAIDSetInfo dict, picks the set's UUID, sets up default values for set. 248 This just creates the dictionary representing the RAID to be created, nothing sent to kernel. 249 @param raidType Get valid types from AppleRAIDGetSetDescriptions(). 250 @param setName The RAID set name in UTF-8 format. 251*/ 252CF_EXPORT 253CFMutableDictionaryRef AppleRAIDCreateSet(CFStringRef raidType, CFStringRef setName); 254 255 256/*! 257 @function AppleRAIDAddMember 258 @discussion Returns a handle to the RAID member on success. The disk partition is not changed. 259 This can be used both for creating new sets and adding to current sets. 260 @param setInfo The dictionary returned from either GetSetProperties or CreateSet. 261 @param partitionName Path to disk partition or raid set. 262 @param memberType - kAppleRAIDMembersKey, kAppleRAIDSparesKey 263*/ 264CF_EXPORT 265AppleRAIDMemberRef AppleRAIDAddMember(CFMutableDictionaryRef setInfo, CFStringRef partitionName, CFStringRef memberType); 266 267 268/*! 269 @function AppleRAIDRemoveMember 270 @discussion Removes a member from a live RAID volume. The disk partition is not changed. 271 This call can be used both for removing set members and spares. 272 @param setInfo The dictionary returned from either GetSetProperties. 273 @param memberRef The member or spare to be removed. 274*/ 275CF_EXPORT 276bool AppleRAIDRemoveMember(CFMutableDictionaryRef setInfo, AppleRAIDMemberRef memberRef); 277 278 279/*! 280 @function AppleRAIDModifySet 281 @discussion Modifies the RAID set dictionary while doing some sanity checks. Returns true on success. 282 @param setInfo The dictionary returned from either GetSetProperties or CreateSet. 283 @param key Must a key that is specified by AppleRAIDGetSetDescriptions() 284 @param value Must be valid for this key as specified by AppleRAIDGetSetDescriptions and IOCFSerialize-able. 285*/ 286CF_EXPORT 287bool AppleRAIDModifySet(CFMutableDictionaryRef setInfo, CFStringRef key, void * value); 288 289 290/*! 291 @function AppleRAIDUpdateSet 292 @discussion Writes out updated RAID headers. If notifications are enabled, 293 there will be a notification for each new member and the update is complete 294 @param setInfo The dictionary returned from either GetSetProperties or CreateSet. 295*/ 296CF_EXPORT 297AppleRAIDSetRef AppleRAIDUpdateSet(CFMutableDictionaryRef setInfo); 298 299 300/*! 301 @function AppleRAIDDestroySet 302 @discussion Shutdown a raid set and zero out it's headers. 303 @param setRef The handle for the RAID set. 304*/ 305CF_EXPORT 306bool AppleRAIDDestroySet(AppleRAIDSetRef setRef); 307 308 309// ******************************************************************************************** 310 311/*! 312 @function AppleRAIDRemoveHeaders 313 @discussion Cleans a disk partition of any old raid headers. 314 @param partitionName Path to disk partition or raid set. 315*/ 316CF_EXPORT 317bool AppleRAIDRemoveHeaders(CFStringRef partitionName); 318 319 320/*! 321 @function AppleRAIDDumpHeader 322 @discussion Returns a CFData object for the raw header data. 323 This is intended for internal diagnostic use only. 324 @param partitionName Path to disk partition or raid set. 325*/ 326CF_EXPORT 327CFDataRef AppleRAIDDumpHeader(CFStringRef partitionName); 328 329 330// ******************************************************************************************** 331// ******************************************************************************************** 332// 333// L V M 334// 335// ******************************************************************************************** 336// ******************************************************************************************** 337 338 339// CFString that contains the Logical Volume's UUID string 340typedef CFStringRef AppleLVMVolumeRef; 341 342 343 344// ******************************************************************************************** 345// Logical Volume state 346// ******************************************************************************************** 347 348/*! 349 @function AppleLVMGetVolumesForGroup 350 @discussion Returns the list of logical volumes contained (whole or partial) in the 351 the specied logical volume group's member. If the member is not specified this function 352 returns all logical volumes in the logical volume group. This call should work if the 353 member is missing, allowing volumes on a dead disk to be removed. 354 @param setRef The handle for the logical volume group returned from AppleRAIDCreateSet(). 355 @param memberRef A member from the logical volume group or nil. 356*/ 357CF_EXPORT 358CFMutableArrayRef AppleLVMGetVolumesForGroup(AppleRAIDSetRef setRef, AppleRAIDMemberRef member); 359 360/*! 361 @function AppleLVMGetVolumeProperties 362 @discussion Returns a dictionary of properties for this logical volume. 363 364 - size of logical volume 365 - location of logical volume 366 - snapshot of (UUID of snapshoted volume) 367 - ... 368 369 @param volRef The handle to the logical volume. 370*/ 371CF_EXPORT 372CFMutableDictionaryRef AppleLVMGetVolumeProperties(AppleLVMVolumeRef volRef); 373 374/*! 375 @function AppleLVMGetVolumeExtents 376 @discussion Returns an C array of extents for this logical volume. 377 @param volRef The handle to the logical volume. 378*/ 379CF_EXPORT 380CFDataRef AppleLVMGetVolumeExtents(AppleLVMVolumeRef volRef); 381 382/*! 383 @function AppleLVMGetVolumeDescription(void); 384 @discussion Returns a dictionary contains an list of supported keys 385 for each type of logical volume. 386 387 - content hint 388 - location of logical volume (fast, average, slow) 389*/ 390CF_EXPORT 391CFMutableArrayRef AppleLVMGetVolumeDescription(void); 392 393 394// ******************************************************************************************** 395// Logical Volume creation and deletion 396// ******************************************************************************************** 397 398 399/*! 400 @function AppleLVMCreateVolume 401 @discussion Creates a new logical volume dictionary for an existing logical volume group. 402 It does not write any information to disk, use AppleLVMUpdateVolume() for that. 403 Returns a dictionary for the new logical volume on success. 404 @param setRef The handle for the logical volume group returned from AppleRAIDCreateSet(). 405 @param volumeType Type of logical volume, concat, mirror, stripe, ... 406 @param volumeSize Requested size for the new logical volume. Will be rounded up to the nearest volume allocation multiple. 407 @param volumeLocation Where on the disk, fast section, slow section, .. 408*/ 409CF_EXPORT 410CFMutableDictionaryRef AppleLVMCreateVolume(AppleRAIDSetRef setRef, CFStringRef volumeType, UInt64 volumeSize, CFStringRef volumeLocation); 411 412 413/*! 414 @function AppleLVMModifyVolume 415 @discussion Modifies the properties of a logical volume while doing some sanity checks. Returns true on success. 416 @param volumeProperties The dictionary for the logical volume, either from AppleLVMCreateVolume() or AppleLVMGetVolumeProperties(), 417 @param key Must a key that is specified by AppleLVMGetVolumeDescriptions() 418 @param value Must be valid for this key as specified by AppleLVMGetVolumeDescriptions and IOCFSerialize-able. 419*/ 420CF_EXPORT 421bool AppleLVMModifyVolume(CFMutableDictionaryRef volumeProperties, CFStringRef key, void * value); 422 423 424/*! 425 @function AppleLVMUpdateVolume 426 @discussion Write logical volume while doing some sanity checks. 427 Returns the handle to the new or updated logical volume. 428 @param volumeProperties The dictionary for the logical volume, either from AppleLVMCreateVolume() or AppleLVMGetVolumeProperties(), 429*/ 430CF_EXPORT 431AppleLVMVolumeRef AppleLVMUpdateVolume(CFMutableDictionaryRef volumeProperties); 432 433 434/*! 435 @function AppleLVMDestroyVolume 436 @discussion Destroys a logical volume and frees up the space it was using. 437 This call is supported on logical volumes that are missing. 438 @param volRef The handle to the logical volume. 439*/ 440CF_EXPORT 441bool AppleLVMDestroyVolume(AppleLVMVolumeRef volRef); 442 443 444// ******************************************************************************************** 445// Logical Volume level manipulations 446// ******************************************************************************************** 447 448 449/*! 450 @function AppleLVMResizeVolume 451 @discussion Used to resize a volume up or down in size. May cause a logical volume to start 452 spaning logical volume group members or stop spanning them if reducing the size. The size 453 returned will be rounded up to the nearest allocation multiple. 454 @param volumeProperties The dictionary for the logical volume, either from AppleLVMCreateVolume() or AppleLVMGetVolumeProperties(), 455 @param size The new size for the volume. 456*/ 457CF_EXPORT 458UInt64 AppleLVMResizeVolume(CFMutableDictionaryRef volumeProperties, UInt64 size); 459 460 461/*! 462 @function AppleLVMSnapShotVolume 463 @discussion Returns a new logical volume that is a snapshot of the specified volume. 464 Snapshots of snapshots are allowed. If the changes to the original volume are larger than 465 than the snapshot can track then the snapshot will fail. As will any snapshots of it. 466 @param volumeProperties The dictionary for the logical volume from AppleLVMGetVolumeProperties(), 467 @param type The handle to the original logical volume. 468 @param snapshotSize The maximum size of the snapshot. 469*/ 470CF_EXPORT 471CFMutableDictionaryRef AppleLVMSnapShotVolume(CFMutableDictionaryRef volumeProperties, CFStringRef type, UInt64 snapshotSize); 472 473 474/*! 475 @function AppleLVMMigrateVolume 476 @discussion Used to do a live move of a logical volume from one disk member to another disk member or 477 from one location to another location on the same member. 478 @param volRef The handle to the logical volume. 479 @param toRef A member from the logical volume group (can be same as fromRef) 480 @param volumeLocation Where on the disk, fast section, slow section, .. 481*/ 482CF_EXPORT 483bool AppleLVMMigrateVolume(AppleLVMVolumeRef volRef, AppleRAIDMemberRef toRef, CFStringRef volumeLocation); 484 485 486// ******************************************************************************************** 487// Logical Group Member level manipulations 488// ******************************************************************************************** 489 490/*! 491 @function AppleLVMRemoveMember 492 @discussion Used to remove a member disk from a logical volume group. Works for members 493 that do or do not have logical volumes on them. If the member is not empty, a new logical 494 volume group will be created if possible. The logical volumes on the member must be closed (unmounted). 495 @param volRef The handle to the logical volume. 496 @param memberRef A member from the logical volume group. 497*/ 498CF_EXPORT 499AppleLVMVolumeRef AppleLVMRemoveMember(AppleLVMVolumeRef volRef, AppleRAIDMemberRef memberRef); 500 501 502/*! 503 @function AppleLVMMergeGroups 504 @discussion Used to merge two logical volume groups together into one. The logical volume 505 is deleted the it's volumes are added to the other. The logical volumes on the donor 506 must be closed (unmounted). 507 @param setRef A handle for the logical volume group being added to. 508 @param donorSetRef The handle for the logical volume group being added. 509*/ 510CF_EXPORT 511AppleLVMVolumeRef AppleLVMMergeGroups(AppleRAIDSetRef setRef, AppleRAIDSetRef donorSetRef); 512 513 514#endif !KERNEL 515 516#endif _APPLERAIDUSERLIB_H 517