iokit/IOKit/storage/IOMedia.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, 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 /*!
  24  * @header IOMedia
  25  * @abstract
  26  * This header contains the IOMedia class definition.
  27  */
  28
  29 #ifndef _IOMEDIA_H
  30 #define _IOMEDIA_H
  31
  32 /*!
  33  * @defined kIOMediaClass
  34  * @abstract
  35  * kIOMediaClass is the name of the IOMedia class.
  36  * @discussion
  37  * kIOMediaClass is the name of the IOMedia class.
  38  */
  39
  40 #define kIOMediaClass "IOMedia"
  41
  42 /*!
  43  * @defined kIOMediaContentKey
  44  * @abstract
  45  * kIOMediaContentKey is a property of IOMedia objects.  It has an OSString
  46  * value.
  47  * @discussion
  48  * The kIOMediaContentKey property contains a description of the media's
  49  * contents.  The description is the same as the hint at the time of the object's
  50  * creation, but it is possible that the description be overrided by a client
  51  * (which has probed the media and identified the content correctly) of the media
  52  * object.  It is more accurate than the hint for this reason.  The string is
  53  * formed in the likeness of Apple's "Apple_HFS" strings.
  54  */
  55
  56 #define kIOMediaContentKey "Content"
  57 #define kIOMediaContent "Content" ///d:deprecated
  58
  59 /*!
  60  * @defined kIOMediaContentHintKey
  61  * @abstract
  62  * kIOMediaContentHintKey is a property of IOMedia objects.  It has an OSString
  63  * value.
  64  * @discussion
  65  * The kIOMediaContentHintKey property contains a hint of the media's contents.
  66  * The hint is set at the time of the object's creation, should the creator have
  67  * a clue as to what it may contain.  The hint string does not change for the
  68  * lifetime of the object and is formed in the likeness of Apple's "Apple_HFS"
  69  * strings.
  70  */
  71
  72 #define kIOMediaContentHintKey "Content Hint"
  73
  74 /*!
  75  * @defined kIOMediaEjectableKey
  76  * @abstract
  77  * kIOMediaEjectableKey is a property of IOMedia objects.  It has an OSBoolean
  78  * value.
  79  * @discussion
  80  * The kIOMediaEjectableKey property describes whether the media is ejectable.
  81  */
  82
  83 #define kIOMediaEjectableKey "Ejectable"
  84 #define kIOMediaEjectable "Ejectable" ///d:deprecated
  85
  86 /*!
  87  * @defined kIOMediaLeafKey
  88  * @abstract
  89  * kIOMediaLeafKey is a property of IOMedia objects.  It has an OSBoolean value.
  90  * @discussion
  91  * The kIOMediaLeafKey property describes whether the media is a leaf, that is,
  92  * it is the deepest media object in this branch of the I/O Kit registry.
  93  */
  94
  95 #define kIOMediaLeafKey "Leaf"
  96 #define kIOMediaLeaf "Leaf" ///d:deprecated
  97
  98 /*!
  99  * @defined kIOMediaPreferredBlockSizeKey
 100  * @abstract
 101  * kIOMediaPreferredBlockSizeKey is a property of IOMedia objects.  It has an
 102  * OSNumber value.
 103  * @discussion
 104  * The kIOMediaPreferredBlockSizeKey property describes the media's natural block
 105  * size in bytes.  This information is useful to clients that want to optimize
 106  * access to the media.
 107  */
 108
 109 #define kIOMediaPreferredBlockSizeKey "Preferred Block Size"
 110
 111 /*!
 112  * @defined kIOMediaSizeKey
 113  * @abstract
 114  * kIOMediaSizeKey is a property of IOMedia objects.  It has an OSNumber value.
 115  * @discussion
 116  * The kIOMediaSizeKey property describes the total length of the media in bytes.
 117  */
 118
 119 #define kIOMediaSizeKey "Size"
 120 #define kIOMediaSize "Size" ///d:deprecated
 121
 122 /*!
 123  * @defined kIOMediaWholeKey
 124  * @abstract
 125  * kIOMediaWholeKey is a property of IOMedia objects.  It has an OSBoolean value.
 126  * @discussion
 127  * The kIOMediaWholeKey property describes whether the media is whole, that is,
 128  * it represents the whole disk (the physical disk, or a virtual replica
 129  * thereof).
 130  */
 131
 132 #define kIOMediaWholeKey "Whole"
 133
 134 /*!
 135  * @defined kIOMediaWritableKey
 136  * @abstract
 137  * kIOMediaWritableKey is a property of IOMedia objects.  It has an OSBoolean
 138  * value.
 139  * @discussion
 140  * The kIOMediaWritableKey property describes whether the media is writable.
 141  */
 142
 143 #define kIOMediaWritableKey "Writable"
 144 #define kIOMediaWritable "Writable" ///d:deprecated
 145
 146 /*!
 147  * @defined kIOMediaContentMaskKey
 148  * @abstract
 149  * kIOMediaContentMaskKey is a property of IOMedia clients.  It has an OSString
 150  * value.
 151  * @discussion
 152  * The kIOMediaContentMaskKey property must exist in all IOMedia clients that
 153  * drive new content (that is, produce new media objects).  When the client
 154  * matches against the provider media, the value of the client's
 155  * kIOMediaContentMaskKey property is used to replace the provider's
 156  * kIOMediaContentKey property.
 157  */
 158
 159 #define kIOMediaContentMaskKey "Content Mask"
 160
 161 /*
 162  * Kernel
 163  */
 164
 165 #if defined(KERNEL) && defined(__cplusplus)
 166
 167 #include <IOKit/storage/IOStorage.h>
 168
 169 /*!
 170  * @class IOMedia
 171  * @abstract
 172  * The IOMedia class is a random-access disk device abstraction.
 173  * @discussion
 174  * The IOMedia class is a random-access disk device abstraction.   It provides a
 175  * consistent interface for both real and virtual disk devices, for subdivisions
 176  * of disks such as partitions, for supersets of disks such as RAID volumes, and
 177  * so on.   It extends the IOStorage class by implementing the appropriate open,
 178  * close, read, write, and matching semantics for media objects.  The properties
 179  * it has reflect the properties of real disk devices,  such as ejectability and
 180  * writability.
 181  *
 182  * The read and write interfaces support byte-level access to the storage space,
 183  * with the appropriate deblocking handled by the block storage driver, however,
 184  * a typical client will want to get the natural block size in order to optimize
 185  * access to the real disk device.  A read or write is accepted so long as the
 186  * client's access is valid, the media is formatted and the transfer is within
 187  * the bounds of the media.  An optional non-zero base (offset) is then applied
 188  * before the read or write is passed to provider object.
 189  *
 190  * An open is accepted so long as no more than one writer is active at any time.
 191  */
 192
 193 class IOMedia : public IOStorage
 194 {
 195     OSDeclareDefaultStructors(IOMedia)
 196
 197 protected:
 198
 199     struct ExpansionData { /* */ };
 200     ExpansionData * _expansionData;
 201
 202     bool            _isEjectable;
 203     bool            _isWhole;
 204     bool            _isWritable;
 205
 206     UInt64          _mediaBase;  /* (relative to the storage object below us) */
 207     UInt64          _mediaSize;
 208
 209     IOStorageAccess _openLevel;
 210     OSSet *         _openReaders;
 211     IOService *     _openReaderWriter;
 212
 213     UInt64          _preferredBlockSize;
 214
 215     /*
 216      * Free all of this object's outstanding resources.
 217      */
 218
 219     virtual void free();
 220
 221     /*!
 222      * @function handleOpen
 223      * @discussion
 224      * The handleOpen method grants or denies permission to access this object
 225      * to an interested client.  The argument is an IOStorageAccess value that
 226      * specifies the level of access desired -- reader or reader-writer.
 227      *
 228      * This method can be invoked to upgrade or downgrade the access level for
 229      * an existing client as well.  The previous access level will prevail for
 230      * upgrades that fail, of course.   A downgrade should never fail.  If the
 231      * new access level should be the same as the old for a given client, this
 232      * method will do nothing and return success.  In all cases, one, singular
 233      * close-per-client is expected for all opens-per-client received.
 234      *
 235      * This implementation replaces the IOService definition of handleOpen().
 236      * @param client
 237      * Client requesting the open.
 238      * @param options
 239      * Options for the open.  Set to zero.
 240      * @param access
 241      * Access level for the open.  Set to kIOStorageAccessReader or
 242      * kIOStorageAccessReaderWriter.
 243      * @result
 244      * Returns true if the open was successful, false otherwise.
 245      */
 246
 247     virtual bool handleOpen(IOService *  client,
 248                             IOOptionBits options,
 249                             void *       access);
 250
 251     /*!
 252      * @function handleIsOpen
 253      * @discussion
 254      * The handleIsOpen method determines whether the specified client, or any
 255      * client if none is specificed, presently has an open on this object.
 256      *
 257      * This implementation replaces the IOService definition of handleIsOpen().
 258      * @param client
 259      * Client to check the open state of.  Set to zero to check the open state
 260      * of all clients.
 261      * @result
 262      * Returns true if the client was (or clients were) open, false otherwise.
 263      */
 264
 265     virtual bool handleIsOpen(const IOService * client) const;
 266
 267     /*!
 268      * @function handleClose
 269      * @discussion
 270      * The handleClose method closes the client's access to this object.
 271      *
 272      * This implementation replaces the IOService definition of handleClose().
 273      * @param client
 274      * Client requesting the close.
 275      * @param options
 276      * Options for the close.  Set to zero.
 277      */
 278
 279     virtual void handleClose(IOService * client, IOOptionBits options);
 280
 281 public:
 282
 283 ///m:2333367:workaround:commented:start
 284 //  using read;
 285 //  using write;
 286 ///m:2333367:workaround:commented:stop
 287
 288     /*!
 289      * @function init
 290      * @discussion
 291      * Initialize this object's minimal state.
 292      * @param base
 293      * Media offset, in bytes.
 294      * @param size
 295      * Media size, in bytes.
 296      * @param preferredBlockSize
 297      * Natural block size, in bytes.
 298      * @param isEjectable
 299      * Indicates whether the media is ejectable.
 300      * @param isWhole
 301      * Indicated whether the media represents the whole disk.
 302      * @param isWritable
 303      * Indicates whether the media is writable.
 304      * @param contentHint
 305      * Hint of media's contents (optional).  See getContentHint().
 306      * @param properties
 307      * Substitute property table for this object (optional).
 308      * @result
 309      * Returns true on success, false otherwise.
 310      */
 311
 312     virtual bool init(UInt64         base,
 313                       UInt64         size,
 314                       UInt64         preferredBlockSize,
 315                       bool           isEjectable,
 316                       bool           isWhole,
 317                       bool           isWritable,
 318                       const char *   contentHint = 0,
 319                       OSDictionary * properties  = 0);
 320
 321     /*
 322      * This method is called for each client interested in the services we
 323      * provide.  The superclass links us as a parent to this client in the
 324      * I/O Kit registry on success.
 325      */
 326
 327     virtual bool attachToChild(IORegistryEntry *       client,
 328                                const IORegistryPlane * plane);
 329
 330     /*
 331      * This method is called for each client that loses interest in the
 332      * services we provide.  The superclass unlinks us from this client
 333      * in the I/O Kit registry on success.
 334      */
 335
 336     virtual void detachFromChild(IORegistryEntry *       client,
 337                                  const IORegistryPlane * plane);
 338
 339     /*
 340      * Compare the properties in the supplied table to this object's properties.
 341      */
 342
 343     virtual bool matchPropertyTable(OSDictionary * table, SInt32 * score);
 344
 345     /*!
 346      * @function read
 347      * @discussion
 348      * Read data from the storage object at the specified byte offset into the
 349      * specified buffer, asynchronously.   When the read completes, the caller
 350      * will be notified via the specified completion action.
 351      *
 352      * The buffer will be retained for the duration of the read.
 353      * @param client
 354      * Client requesting the read.
 355      * @param byteStart
 356      * Starting byte offset for the data transfer.
 357      * @param buffer
 358      * Buffer for the data transfer.  The size of the buffer implies the size of
 359      * the data transfer.
 360      * @param completion
 361      * Completion routine to call once the data transfer is complete.
 362      */
 363
 364     virtual void read(IOService *          client,
 365                       UInt64               byteStart,
 366                       IOMemoryDescriptor * buffer,
 367                       IOStorageCompletion  completion);
 368
 369     /*!
 370      * @function write
 371      * @discussion
 372      * Write data into the storage object at the specified byte offset from the
 373      * specified buffer, asynchronously.   When the write completes, the caller
 374      * will be notified via the specified completion action.
 375      *
 376      * The buffer will be retained for the duration of the write.
 377      * @param client
 378      * Client requesting the write.
 379      * @param byteStart
 380      * Starting byte offset for the data transfer.
 381      * @param buffer
 382      * Buffer for the data transfer.  The size of the buffer implies the size of
 383      * the data transfer.
 384      * @param completion
 385      * Completion routine to call once the data transfer is complete.
 386      */
 387
 388     virtual void write(IOService *          client,
 389                        UInt64               byteStart,
 390                        IOMemoryDescriptor * buffer,
 391                        IOStorageCompletion  completion);
 392
 393     virtual IOReturn synchronizeCache(IOService * client);
 394
 395     /*!
 396      * @function getPreferredBlockSize
 397      * @discussion
 398      * Ask the media object for its natural block size.  This information
 399      * is useful to clients that want to optimize access to the media.
 400      * @result
 401      * Natural block size, in bytes.
 402      */
 403
 404     virtual UInt64 getPreferredBlockSize() const;
 405
 406     /*!
 407      * @function getSize
 408      * @discussion
 409      * Ask the media object for its total length in bytes.
 410      * @result
 411      * Media size, in bytes.
 412      */
 413
 414     virtual UInt64 getSize() const;
 415
 416     /*!
 417      * @function getBase
 418      * @discussion
 419      * Ask the media object for its byte offset relative to its provider media
 420      * object below it in the storage hierarchy.
 421      * Media offset, in bytes.
 422      */
 423
 424     virtual UInt64 getBase() const;
 425
 426     /*!
 427      * @function isEjectable
 428      * @discussion
 429      * Ask the media object whether it is ejectable.
 430      * @result
 431      * Returns true if the media is ejectable, false otherwise.
 432      */
 433
 434     virtual bool isEjectable() const;
 435
 436     /*!
 437      * @function isFormatted
 438      * @discussion
 439      * Ask the media object whether it is formatted.
 440      * @result
 441      * Returns true if the media is formatted, false otherwise.
 442      */
 443
 444     virtual bool isFormatted() const;
 445
 446     /*!
 447      * @function isWhole
 448      * @discussion
 449      * Ask the media object whether it represents the whole disk.
 450      * @result
 451      * Returns true if the media represents the whole disk, false otherwise.
 452      */
 453
 454     virtual bool isWhole() const;
 455
 456     /*!
 457      * @function isWritable
 458      * @discussion
 459      * Ask the media object whether it is writable.
 460      * @result
 461      * Returns true if the media is writable, false otherwise.
 462      */
 463
 464     virtual bool isWritable() const;
 465
 466     /*!
 467      * @function getContent
 468      * @discussion
 469      * Ask the media object for a description of its contents.  The description
 470      * is the same as the hint at the time of the object's creation,  but it is
 471      * possible that the description be overrided by a client (which has probed
 472      * the media and identified the content correctly) of the media object.  It
 473      * is more accurate than the hint for this reason.  The string is formed in
 474      * the likeness of Apple's "Apple_HFS" strings.
 475      *
 476      * The content description can be overrided by any client that matches onto
 477      * this media object with a match category of kIOStorageCategory.  The media
 478      * object checks for a kIOMediaContentMaskKey property in the client, and if
 479      * it finds one, it copies it into kIOMediaContentKey property.
 480      * @result
 481      * Description of media's contents.
 482      */
 483
 484     virtual const char * getContent() const;
 485
 486     /*!
 487      * @function getContentHint
 488      * @discussion
 489      * Ask the media object for a hint of its contents.  The hint is set at the
 490      * time of the object's creation, should the creator have a clue as to what
 491      * it may contain.  The hint string does not change for the lifetime of the
 492      * object and is also formed in the likeness of Apple's "Apple_HFS" strings.
 493      * @result
 494      * Hint of media's contents.
 495      */
 496
 497     virtual const char * getContentHint() const;
 498
 499     /*
 500      * Obtain this object's provider.  We override the superclass's method to
 501      * return a more specific subclass of OSObject -- IOStorage.  This method
 502      * serves simply as a convenience to subclass developers.
 503      */
 504
 505     virtual IOStorage * getProvider() const;
 506
 507     OSMetaClassDeclareReservedUnused(IOMedia,  0);
 508     OSMetaClassDeclareReservedUnused(IOMedia,  1);
 509     OSMetaClassDeclareReservedUnused(IOMedia,  2);
 510     OSMetaClassDeclareReservedUnused(IOMedia,  3);
 511     OSMetaClassDeclareReservedUnused(IOMedia,  4);
 512     OSMetaClassDeclareReservedUnused(IOMedia,  5);
 513     OSMetaClassDeclareReservedUnused(IOMedia,  6);
 514     OSMetaClassDeclareReservedUnused(IOMedia,  7);
 515     OSMetaClassDeclareReservedUnused(IOMedia,  8);
 516     OSMetaClassDeclareReservedUnused(IOMedia,  9);
 517     OSMetaClassDeclareReservedUnused(IOMedia, 10);
 518     OSMetaClassDeclareReservedUnused(IOMedia, 11);
 519     OSMetaClassDeclareReservedUnused(IOMedia, 12);
 520     OSMetaClassDeclareReservedUnused(IOMedia, 13);
 521     OSMetaClassDeclareReservedUnused(IOMedia, 14);
 522     OSMetaClassDeclareReservedUnused(IOMedia, 15);
 523 };
 524
 525 #endif /* defined(KERNEL) && defined(__cplusplus) */
 526
 527 #endif /* !_IOMEDIA_H */