iokit/IOKit/storage/IOBlockStorageDevice.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  * IOBlockStorageDevice.h
  24  *
  25  * This class is the protocol for generic block storage functionality, independent
  26  * of the physical connection protocol (e.g. SCSI, ATA, USB).
  27  *
  28  * A subclass implements relay methods that translate our requests into
  29  * calls to a protocol- and device-specific provider.
  30  */
  31
  32 /*!     @language embedded-c++ */
  33
  34 #ifndef _IOBLOCKSTORAGEDEVICE_H
  35 #define _IOBLOCKSTORAGEDEVICE_H
  36
  37 #include <IOKit/IOMessage.h>
  38 #include <IOKit/IOTypes.h>
  39 #include <IOKit/IOService.h>
  40 #include <IOKit/storage/IOMedia.h>
  41
  42 /*!
  43  * @defined kIOMessageMediaStateHasChanged
  44  * The message ID which indicates that the media state has changed.  The message
  45  * is passed to all clients of the IOBlockStorageDevice via the message() method.
  46  * The argument that is passed along with this message is an IOMediaState value.
  47  *
  48  * Devices that aren't capable of detecting media state changes indicate this in
  49  * the reportPollRequirements() method.
  50  */
  51 #define kIOMessageMediaStateHasChanged iokit_family_msg(sub_iokit_block_storage, 1)
  52
  53 /* Property used for matching, so the generic driver gets the nub it wants. */
  54 /*!
  55  * @defined kIOBlockStorageDeviceTypeKey
  56  * The name of the property tested for nub type matching by the generic block
  57  * storage driver.
  58  */
  59 #define kIOBlockStorageDeviceTypeKey    "device-type"
  60 /*!
  61  * @defined kIOBlockStorageDeviceTypeGeneric
  62  * A character string used for nub matching.
  63  */
  64 #define kIOBlockStorageDeviceTypeGeneric        "Generic"
  65
  66 class IOMemoryDescriptor;
  67
  68 /*!
  69  * @class
  70  * IOBlockStorageDevice : public IOService
  71  * @abstract
  72  * "Impedance-matcher" class to connect Generic device driver to Transport Driver.
  73  * @discussion
  74  * The IOBlockStorageDevice class exports the generic block storage protocol,
  75  * forwarding all requests to its provider (the Transport Driver).
  76  * Though the nub does no actual processing of requests, it is necessary
  77  * in a C++ environment. The Transport Driver can be of any type, as
  78  * long as it inherits from IOService. Because Transport Drivers needn't
  79  * derive from a type known to IOBlockStorageDriver, it isn't possible for
  80  * IOBlockStorageDriver to include the appropriate header file to allow direct
  81  * communication with the Transport Driver. Thus we achieve polymorphism by
  82  * having the Transport Driver instantiate a subclass of IOBlockStorageDevice.
  83  * A typical implementation for a concrete subclass of IOBlockStorageDevice
  84  * simply relays all methods to its provider (the Transport Driver).
  85  *
  86  * All pure-virtual functions must be implemented by the Transport Driver, which
  87  * is responsible for instantiating the Nub.
  88  */
  89
  90 class IOBlockStorageDevice : public IOService {
  91
  92     OSDeclareAbstractStructors(IOBlockStorageDevice)
  93
  94 protected:
  95
  96     struct ExpansionData { /* */ };
  97     ExpansionData * _expansionData;
  98
  99 public:
 100
 101     /* Overrides from IORegistryEntry */
 102
 103     /*!
 104      * @function init
 105      * @discussion
 106      * This function is overridden so that IOBlockStorageDevice can set a
 107      * property, used by IOBlockStorageDriver for matching. Since the concrete
 108      * subclass of IOBlockStorageDevice can be of any class type, the property
 109      * is used for matching.
 110      *
 111      * This function is usually not overridden by developers.
 112      */
 113     virtual bool        init(OSDictionary * properties);
 114
 115     /* --- A subclass must implement the the following methods: --- */
 116
 117     /*!
 118      * @function doAsyncReadWrite
 119      * @abstract
 120      * Start an asynchronous read or write operation.
 121      * @param buffer
 122      * An IOMemoryDescriptor describing the data-transfer buffer. The data direction
 123      * is contained in the IOMemoryDescriptor. Responsiblity for releasing the descriptor
 124      * rests with the caller.
 125      * @param block
 126      * The starting block number of the data transfer.
 127      * @param nblks
 128      * The integral number of blocks to be transferred.
 129      * @param completion
 130      * The completion routine to call once the data transfer is complete.
 131      */
 132
 133     virtual IOReturn    doAsyncReadWrite(IOMemoryDescriptor *buffer,
 134                                             UInt32 block,UInt32 nblks,
 135                                             IOStorageCompletion completion)     = 0;
 136
 137     /*!
 138      * @function doSyncReadWrite
 139      * @abstract
 140      * Perform a synchronous read or write operation.
 141      * @param buffer
 142      * An IOMemoryDescriptor describing the data-transfer buffer. The data direction
 143      * is contained in the IOMemoryDescriptor. Responsiblity for releasing the descriptor
 144      * rests with the caller.
 145      * @param block
 146      * The starting block number of the data transfer.
 147      * @param nblks
 148      * The integral number of blocks to be transferred.
 149      */
 150     virtual IOReturn    doSyncReadWrite(IOMemoryDescriptor *buffer,
 151                                      UInt32 block,UInt32 nblks)                 = 0;
 152
 153     /*!
 154      * @function doEjectMedia
 155      * @abstract
 156      * Eject the media.
 157      */
 158     virtual IOReturn    doEjectMedia(void)                                      = 0;
 159
 160     /*!
 161      * @function doFormatMedia
 162      * @abstract
 163      * Format the media to the specified byte capacity.
 164      * @discussion
 165      * The specified byte capacity must be one supported by the device.
 166      * Supported capacities can be obtained by calling doGetFormatCapacities.
 167      * @param byteCapacity
 168      * The byte capacity to which the device is to be formatted, if possible.
 169      */
 170     virtual IOReturn    doFormatMedia(UInt64 byteCapacity)                      = 0;
 171
 172     /*!
 173      * @function doGetFormatCapacities
 174      * @abstract
 175      * Return the allowable formatting byte capacities.
 176      * @discussion
 177      * This function returns the supported byte capacities for the device.
 178      * @param capacities
 179      * Pointer for returning the list of capacities.
 180      * @param capacitiesMaxCount
 181      * The number of capacity values returned in "capacities."
 182      */
 183     virtual UInt32      doGetFormatCapacities(UInt64 * capacities,
 184                                             UInt32   capacitiesMaxCount) const  = 0;
 185
 186     /*!
 187      * @function doLockUnlockMedia
 188      * @abstract
 189      * Lock or unlock the (removable) media in the drive.
 190      * @discussion
 191      * This method should only be called if the media is known to be removable.
 192      * @param doLock
 193      * True to lock the media, False to unlock.
 194      */
 195     virtual IOReturn    doLockUnlockMedia(bool doLock)                          = 0;
 196
 197     /*!
 198      * @function doSynchronizeCache
 199      * @abstract
 200      * Force data blocks in the hardware's buffer to be flushed to the media.
 201      * @discussion
 202      * This method should only be called if the media is writable.
 203      */
 204     virtual IOReturn    doSynchronizeCache(void)                                = 0;
 205
 206     /*!
 207      * @function getVendorString
 208      * @abstract
 209      * Return Vendor Name string for the device.
 210      * @result
 211      * A pointer to a static character string.
 212      */
 213     virtual char *      getVendorString(void)                                   = 0;
 214
 215     /*!
 216      * @function getProductString
 217      * @abstract
 218      * Return Product Name string for the device.
 219      * @result
 220      * A pointer to a static character string.
 221      */
 222     virtual char *      getProductString(void)                                  = 0;
 223
 224     /*!
 225      * @function getRevisionString
 226      * @abstract
 227      * Return Product Revision string for the device.
 228      * @result
 229      * A pointer to a static character string.
 230      */
 231     virtual char *      getRevisionString(void)                                 = 0;
 232
 233     /*!
 234      * @function getAdditionalDeviceInfoString
 235      * @abstract
 236      * Return additional informational string for the device.
 237      * @result
 238      * A pointer to a static character string.
 239      */
 240     virtual char *      getAdditionalDeviceInfoString(void)                     = 0;
 241
 242     /*!
 243      * @function reportBlockSize
 244      * @abstract
 245      * Report the block size for the device, in bytes.
 246      * @param blockSize
 247      * Pointer to returned block size value.
 248      */
 249     virtual IOReturn    reportBlockSize(UInt64 *blockSize)                      = 0;
 250
 251     /*!
 252      * @function reportEjectability
 253      * @abstract
 254      * Report if the media is ejectable under software control.
 255      * @discussion
 256      * This method should only be called if the media is known to be removable.
 257      * @param isEjectable
 258      * Pointer to returned result. True indicates the media is ejectable, False indicates
 259      * the media cannot be ejected under software control.
 260      */
 261     virtual IOReturn    reportEjectability(bool *isEjectable)                   = 0;
 262
 263     /*!
 264      * @function reportLockability
 265      * @abstract
 266      * Report if the media is lockable under software control.
 267      * @discussion
 268      * This method should only be called if the media is known to be removable.
 269      * @param isLockable
 270      * Pointer to returned result. True indicates the media can be locked in place; False
 271      * indicates the media cannot be locked by software.
 272      */
 273     virtual IOReturn    reportLockability(bool *isLockable)                     = 0;
 274
 275     /*!
 276      * @function reportMaxReadTransfer
 277      * @abstract
 278      * Report the maximum allowed byte transfer for read operations.
 279      * @discussion
 280      * Some devices impose a maximum data transfer size. Because this limit
 281      * may be determined by the size of a block-count field in a command, the limit may
 282      * depend on the block size of the transfer.
 283      * @param blockSize
 284      * The block size desired for the transfer.
 285      * @param max
 286      * Pointer to returned result.
 287      */
 288     virtual IOReturn    reportMaxReadTransfer (UInt64 blockSize,UInt64 *max)    = 0;
 289
 290     /*!
 291      * @function reportMaxWriteTransfer
 292      * @abstract
 293      * Report the maximum allowed byte transfer for write operations.
 294      * @discussion
 295      * Some devices impose a maximum data transfer size. Because this limit
 296      * may be determined by the size of a block-count field in a command, the limit may
 297      * depend on the block size of the transfer.
 298      * @param blockSize
 299      * The block size desired for the transfer.
 300      * @param max
 301      * Pointer to returned result.
 302      */
 303     virtual IOReturn    reportMaxWriteTransfer(UInt64 blockSize,UInt64 *max)    = 0;
 304
 305     /*!
 306      * @function reportMaxValidBlock
 307      * @abstract
 308      * Report the highest valid block for the device.
 309      * @param maxBlock
 310      * Pointer to returned result
 311      */
 312     virtual IOReturn    reportMaxValidBlock(UInt64 *maxBlock)                   = 0;
 313
 314     /*!
 315      * @function reportMediaState
 316      * @abstract
 317      * Report the device's media state.
 318      * @discussion
 319      * This method reports whether we have media in the drive or not, and
 320      * whether the state has changed from the previously reported state.
 321      *
 322      * A result of kIOReturnSuccess is always returned if the test for media is successful,
 323      * regardless of media presence. The mediaPresent result should be used to determine
 324      * whether media is present or not. A return other than kIOReturnSuccess indicates that
 325      * the Transport Driver was unable to interrogate the device. In this error case, the
 326      * outputs mediaState and changedState will *not* be stored.
 327      * @param mediaPresent Pointer to returned media state. True indicates media is present
 328      * in the device; False indicates no media is present.
 329      * @param changedState Pointer to returned result. True indicates a change of state since
 330      * prior calls, False indicates that the state has not changed.
 331      */
 332     virtual IOReturn    reportMediaState(bool *mediaPresent,bool *changedState) = 0;
 333
 334     /*!
 335      * @function reportPollRequirements
 336      * @abstract
 337      * Report if it's necessary to poll for media insertion, and if polling is expensive.
 338      * @discussion
 339      * This method reports whether the device must be polled to detect media
 340      * insertion, and whether a poll is expensive to perform.
 341      *
 342      * The term "expensive" typically implies a device that must be spun-up to detect media,
 343      * as on a PC floppy. Most devices can detect media inexpensively.
 344      * @param pollRequired
 345      * Pointer to returned result. True indicates that polling is required; False indicates
 346      * that polling is not required to detect media.
 347      * @param pollIsExpensive
 348      * Pointer to returned result. True indicates that the polling operation is expensive;
 349      * False indicates that the polling operation is cheap.
 350      */
 351     virtual IOReturn    reportPollRequirements(bool *pollRequired,
 352                                             bool *pollIsExpensive)              = 0;
 353
 354     /*!
 355      * @function reportRemovability
 356      * @abstract
 357      * Report whether the media is removable or not.
 358      * @discussion
 359      * This method reports whether the media is removable, but it does not
 360      * provide detailed information regarding software eject or lock/unlock capability.
 361      * @param isRemovable
 362      * Pointer to returned result. True indicates that the media is removable; False
 363      * indicates the media is not removable.
 364      */
 365     virtual IOReturn    reportRemovability(bool *isRemovable)                   = 0;
 366
 367     /*!
 368      * @function reportWriteProtection
 369      * @abstract
 370      * Report whether the media is write-protected or not.
 371      * @param isWriteProtected
 372      * Pointer to returned result. True indicates that the media is write-protected (it
 373      * cannot be written); False indicates that the media is not write-protected (it
 374      * is permissible to write).
 375      */
 376     virtual IOReturn    reportWriteProtection(bool *isWriteProtected)           = 0;
 377
 378     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice,  0);
 379     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice,  1);
 380     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice,  2);
 381     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice,  3);
 382     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice,  4);
 383     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice,  5);
 384     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice,  6);
 385     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice,  7);
 386     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice,  8);
 387     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice,  9);
 388     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 10);
 389     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 11);
 390     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 12);
 391     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 13);
 392     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 14);
 393     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 15);
 394     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 16);
 395     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 17);
 396     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 18);
 397     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 19);
 398     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 20);
 399     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 21);
 400     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 22);
 401     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 23);
 402     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 24);
 403     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 25);
 404     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 26);
 405     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 27);
 406     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 28);
 407     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 29);
 408     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 30);
 409     OSMetaClassDeclareReservedUnused(IOBlockStorageDevice, 31);
 410 };
 411 #endif