iokit/IOKit/storage/scsi/IOSCSIHDDrive.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  * IOSCSIHDDrive.h
  24  *
  25  * This class implements SCSI hard disk functionality.
  26  *
  27  * Subclasses may modify the operations to handle device-specific variations.
  28  */
  29
  30 #ifndef _IOSCSIHDDRIVE_H
  31 #define _IOSCSIHDDRIVE_H
  32
  33 #include <IOKit/IOTypes.h>
  34 #include <IOKit/scsi/IOSCSIDeviceInterface.h>
  35 #include <IOKit/storage/scsi/IOBasicSCSI.h>
  36
  37 /* SCSI (inquiry) device type. */
  38
  39 enum {
  40     kIOSCSIDeviceTypeDirectAccess  = 0x00
  41 };
  42
  43 /* SCSI commands. */
  44
  45 enum {
  46     kIOSCSICommandTestUnitReady    = 0x00,
  47     kIOSCSICommandFormatUnit       = 0x04,
  48     kIOSCSICommandStartStopUnit    = 0x1b,
  49     kIOSCSICommandPreventAllow     = 0x1e,
  50     kIOSCSICommandSynchronizeCache = 0x35,
  51     kIOSCSICommandModeSelect       = 0x55,
  52     kIOSCSICommandModeSense        = 0x5a,
  53     kIOSCSICommandRead             = 0xa8,
  54     kIOSCSICommandWrite            = 0xaa
  55 };
  56
  57 struct IOFormatcdb {
  58     UInt8       opcode;                 /* 0x12 */
  59     UInt8       lunbits;                /* lun and control bits */
  60     UInt8       vendor;
  61     UInt8       interleave_msb;
  62     UInt8       interleave_lsb;
  63     UInt8       ctlbyte;
  64 };
  65
  66 struct IOPrevAllowcdb {
  67     UInt8       opcode;
  68     UInt8       lunbits;
  69     UInt8       reserved1;
  70     UInt8       reserved2;
  71     UInt8       prevent;
  72     UInt8       ctlbyte;
  73 };
  74
  75 struct IOStartStopcdb {
  76     UInt8       opcode;
  77     UInt8       lunImmed;
  78     UInt8       reserved1;
  79     UInt8       reserved2;
  80
  81     /* Control bits: */
  82                                         /* Power Conditions */
  83 static const UInt8      P_NOCHANGE      = 0x00; /*  0 - no change */
  84 static const UInt8      P_ACTIVE        = 0x10; /*  1 - change to Active */
  85 static const UInt8      P_IDLE          = 0x20; /*  2 - change to Idle */
  86 static const UInt8      P_STANDBY       = 0x30; /*  3 - change to Standby */
  87 static const UInt8      P_RESERVED4     = 0x40; /*  4 - reserved */
  88 static const UInt8      P_SLEEP         = 0x50; /*  5 - change to Sleep */
  89 static const UInt8      P_RESERVED6     = 0x60; /*  6 - reserved */
  90 static const UInt8      P_LUNCONTROL    = 0x70; /*  7 - give pwr ctl to LUN */
  91 static const UInt8      P_RESERVED8     = 0x80; /*  8 - reserved */
  92 static const UInt8      P_RESERVED9     = 0x90; /*  9 - reserved */
  93 static const UInt8      P_TIDLEZERO     = 0xa0; /*  a - force Idle Cond Timer = 0 */
  94 static const UInt8      P_TSTDBYZERO    = 0xb0; /*  b - force Stby Cond Timer = 0 */
  95
  96 static const UInt8      C_LOEJ          = 0x02; /* load on start/eject on stop */
  97 static const UInt8      C_SPINUP        = 0x01;
  98 static const UInt8      C_SPINDOWN      = 0x00;
  99
 100     UInt8       controls;
 101     UInt8       ctlbyte;
 102 };
 103
 104 struct IOSyncCachecdb {
 105     UInt8       opcode;
 106     UInt8       lunbits;
 107     UInt8       lba_3;                  /* msb */
 108     UInt8       lba_2;
 109     UInt8       lba_1;
 110     UInt8       lba_0;                  /* lsb */
 111     UInt8       reserved;
 112     UInt8       nblks_msb;
 113     UInt8       nblks_lsb;
 114     UInt8       ctlbyte;
 115 };
 116
 117 /*!
 118  * @enum Power States
 119  * @discussion
 120  * We define and understand three basic, generic power states. A subclass may change
 121  * the power management logic, but all power-management routines should be examined
 122  * if anything is changed. The only routines that deal directly with these values
 123  * are directly related to power management. All other functions merely ask for and
 124  * pass along power state values.
 125  * @constant kAllOff
 126  * The power state for an all-off condition.
 127  * @constant kElectronicsOn
 128  * The power state for the electronics on, but the media off.
 129  * @constant kAllOn
 130  * The power state for the electronics and media on.
 131  * @constant kNumberOfPowerStates
 132  * The maximum enum value.
 133  */
 134 enum {                                  /* electronics          mechanical      */
 135     kAllOff             = 0,            /*      OFF             OFF             */
 136     kElectronicsOn      = 1,            /*       ON             OFF             */
 137     kAllOn              = 2,            /*       ON              ON             */
 138
 139     kNumberOfPowerStates = 3
 140 };
 141
 142 /*!
 143  * @class
 144  * IOSCSIHDDrive : public IOBasicSCSI
 145  * @abstract
 146  * SCSI Hard Disk driver.
 147  * @discussion
 148  * IOSCSIHDDrive derives from IOBasicSCSI and adds all functionality
 149  * needed to support removable or fixed hard disk drives.
 150  */
 151
 152 class IOSCSIHDDrive : public IOBasicSCSI {
 153
 154     OSDeclareDefaultStructors(IOSCSIHDDrive)
 155
 156 public:
 157
 158     /* Overrides from IOService: */
 159
 160     virtual bool        init(OSDictionary * properties);
 161
 162     /*!
 163      * @function start
 164      * @abstract
 165      * Start the driver.
 166      * @discussion
 167      * We override IOBasicSCSI::start so we can initialize Power Management,
 168      * then we call createNub to create an IOSCSIHDDriveNub.
 169      */
 170     virtual bool        start(IOService * provider);
 171
 172     /* Overrides from IOBasicSCSI: */
 173
 174     /*!
 175      * @function deviceTypeMatches
 176      * @abstract
 177      * Determine if device type matches expected type.
 178      * @discussion
 179      * We implement this function so we can return a match
 180      * on the hard disk device type.
 181      */
 182     virtual bool        deviceTypeMatches(UInt8 inqBuf[],UInt32 inqLen,SInt32 *score);
 183
 184     /*!
 185      * @function constructDeviceProperties
 186      * @abstract
 187      * Construct a set of properties about the device.
 188      * @discussion
 189      * This function creates a set of properties reflecting information
 190      * about the device.
 191      *
 192      * This function is presently not used.
 193      * @result
 194      * A pointer to an OSDictionary containing the properties. The caller
 195      * is responsible for releasing the OSDictionary.
 196      */
 197     virtual OSDictionary *constructDeviceProperties(void);
 198
 199     /*!
 200      * @function RWCompletion
 201      * @abstract
 202      * Asynchronous read/write completion routine.
 203      * @discussion
 204      * We implement this function in this class. It is called from the base
 205      * class when an IO operation completes.
 206      */
 207     virtual void        RWCompletion(struct context *cx);
 208
 209     /* End of IOBasicSCSI overrides */
 210
 211     /* Additional API added to IOBasicSCSI: */
 212
 213     /*!
 214      * @function doAsyncReadWrite
 215      * @abstract
 216      * Start an asynchronous read or write operation.
 217      * @discussion
 218      * See IOBlockStorageDevice for details.
 219      */
 220     virtual IOReturn    doAsyncReadWrite(IOMemoryDescriptor *buffer,
 221                                             UInt32 block,UInt32 nblks,
 222                                             IOStorageCompletion completion);
 223
 224     /*!
 225      * @function doSyncReadWrite
 226      * @abstract
 227      * Perform a synchronous read or write operation.
 228      * @discussion
 229      * See IOBlockStorageDevice for details.
 230      */
 231     virtual IOReturn    doSyncReadWrite(IOMemoryDescriptor *buffer,UInt32 block,UInt32 nblks);
 232
 233     /*!
 234      * @function doEjectMedia
 235      * @abstract
 236      * Eject the media.
 237      * @discussion
 238      * See IOBlockStorageDevice for details.
 239      */
 240     virtual IOReturn    doEjectMedia(void);
 241
 242     /*!
 243      * @function doFormatMedia
 244      * @abstract
 245      * Format the media to the specified byte capacity.
 246      * @discussion
 247      * The default implementation calls standardFormatMedia.
 248      * See IOBlockStorageDevice for details.
 249      */
 250     virtual IOReturn    doFormatMedia(UInt64 byteCapacity);
 251
 252     /*!
 253      * @function doGetFormatCapacities
 254      * @abstract
 255      * Return the allowable formatting byte capacities.
 256      * @discussion
 257      * The default implementation of this method returns a value of block
 258      * size * max block, and a capacities count of 1.
 259      * See IOBlockStorageDevice for details.
 260      */
 261     virtual UInt32      doGetFormatCapacities(UInt64 * capacities,
 262                                             UInt32   capacitiesMaxCount) const;
 263
 264     /*!
 265      * @function doLockUnlockMedia
 266      * @abstract
 267      * Lock or unlock the (removable) media in the drive.
 268      * @discussion
 269      * This method issues a standard SCSI Prevent/Allow command to lock
 270      * or unlock the media in the drive.
 271      * See IOBlockStorageDevice for details.
 272      */
 273     virtual IOReturn    doLockUnlockMedia(bool doLock);
 274
 275     /*!
 276      * @function doSynchronizeCache
 277      * @abstract
 278      * Force data blocks in the drive's buffer to be flushed to the media.
 279      * @discussion
 280      * This method issues a SCSI Synchronize Cache command, to ensure that
 281      * all blocks in the device cache are written to the media.
 282      * See IOBlockStorageDevice for details.
 283      */
 284     virtual IOReturn    doSynchronizeCache(void);
 285
 286     /*!
 287      * @function reportMediaState
 288      * @abstract
 289      * Report the device's media state.
 290      * @discussion
 291      * This method reports whether media is present or not, and also
 292      * whether the media state has changed since the last call to
 293      * reportMediaState.  The default implementation issues a SCSI Test
 294      * Unit Ready command: depending on the result of that command, the
 295      * following cases are reported:
 296      *
 297      * 1. TUR status == good completion: we report media present and return
 298      * kIOReturnSuccess.
 299      *
 300      * 2. TUR status != good completion, but good autosense returned:
 301      *
 302      * 2a: sense key says not ready: we report media not present
 303      * and return kIOReturnSuccess.
 304      *
 305      * 2b: sense key is anything else: we report media not present
 306      * and return kIOReturnIOError.
 307      *
 308      * 3. TUR status != good completion, and no autosense data: we do not
 309      * set mediaPresent or changedState, and we return whatever result
 310      * came back from the SCSI operation.
 311      */
 312     virtual IOReturn    reportMediaState(bool *mediaPresent,bool *changed);
 313
 314     /* --- end of additional API --- */
 315
 316 protected:
 317
 318     /*!
 319      * @function createFormatCdb
 320      * @abstract
 321      * Create a SCSI CDB for a format operation.
 322      * @discussion
 323      * Override this to control the cdb created for a format operation.
 324      * The default implementation creates a 6-byte format command with
 325      * no data buffer, disconnect allowed, 8-byte autosense, and a 15-minute timeout.
 326      *
 327      * See also: allocateFormatBuffer, deleteFormatBuffer, composeFormatBuffer.
 328      * @param byteCapacity
 329      * The requested byte capacity to which the media should be formatted. This value
 330      * should have been previously validated, otherwise the device may return an error.
 331      * @param cdb
 332      * A pointer to the CDB bytes.
 333      * @param cdbLength
 334      * The length of the CDB in bytes.
 335      * @param block
 336      * The device block to be written.
 337      * @param nblks
 338      * The number of blocks to be transferred.
 339      * @param maxAutoSenseLength
 340      * The maximum size of the autosense data, in bytes. A value of zero
 341      * will disable autosense.
 342      * @param timeoutSeconds
 343      * The command timeout in seconds.
 344      * @result
 345      * The IOSCSICommandOptions returned will be used to issue the command.
 346      */
 347     virtual UInt32      createFormatCdb(
 348                             UInt64 byteCapacity,        /* in  */
 349                             UInt8 *cdb,                 /* in  */
 350                             UInt32 *cdbLength,          /* out */
 351                             UInt8 buf[],                /* in  */
 352                             UInt32 bufLen,              /* in  */
 353                             UInt32 *maxAutoSenseLength, /* out */
 354                             UInt32 *timeoutSeconds);    /* out */
 355
 356
 357     /*!
 358      * @function allocateFormatBuffer
 359      * @abstract
 360      * Create a data buffer to be used for formatting the media.
 361      * @discussion
 362      * If a format buffer is to be used, then "allocateFormatBuffer" and
 363      * deleteFormatBuffer" must be overridden to manage the buffer. The
 364      * buffer must be prepared for IO upon return from allocateFormatBuffer.
 365      * The default implementations of these methods don't allocate a buffer.
 366      * @param buf
 367      * A pointer for the returned buffer pointer.
 368      * @param buflen
 369      * The desired length of the buffer, in bytes.
 370      */
 371     virtual IOReturn    allocateFormatBuffer(UInt8 **buf,UInt32 *buflen);
 372
 373     /*!
 374      * @function deleteFormatBuffer
 375      * @abstract
 376      * Delete the data buffer to be used for formatting the media.
 377      * @discussion
 378      * If a format buffer is to be used, then "allocateFormatBuffer" and
 379      * deleteFormatBuffer" must be overridden to manage the buffer.
 380      * The default implementation of this method does nothing.
 381      * @param buf
 382      * A pointer to the buffer to delete.
 383      * @param buflen
 384      * The size of the buffer, in bytes.
 385      */
 386     virtual void        deleteFormatBuffer(UInt8 *buf,UInt32 buflen);
 387
 388     /*!
 389      * @function composeFormatBuffer
 390      * @abstract
 391      * Compose the data in the buffer used for the format command.
 392      * @discussion
 393      * This method will be called to compose the data in the format buffer.
 394      *
 395      * The default implementation of this method does nothing.
 396      * @param buf
 397      * A pointer to the format data buffer.
 398      * @param buflen
 399      * The size of the format data buffer, in bytes.
 400      * @result
 401      * The return value should be the desired values for the "CmpLst" and Defect
 402      * List Format bits in the CDB. The default implementation returns zero.
 403      */
 404     virtual UInt8       composeFormatBuffer(UInt8 *buf,UInt32 buflen);
 405
 406     /* Override these methods to save and restore the state of the device electronics
 407      * when power is turned off and on. The defaults do nothing and return kIOReturnSuccess.
 408      */
 409
 410     /*!
 411      * @function restoreElectronicsState
 412      * @abstract
 413      * Restore the state of the device electronics when powering-up.
 414      * @discussion
 415      * This method is called just after the device transitions from a powered-off state.
 416      *
 417      * The default implementation of this method does nothing and returns kIOReturnSuccess.
 418      */
 419     virtual IOReturn    restoreElectronicsState(void);
 420
 421     /*!
 422      * @function saveElectronicsState
 423      * @abstract
 424      * Save the state of the device electronics when powering-down.
 425      * @discussion
 426      * This method is called just before the device transitions to a powered-off state.
 427      *
 428      * The default implementation of this method does nothing and returns kIOReturnSuccess.
 429      */
 430     virtual IOReturn    saveElectronicsState(void);
 431
 432     /*!
 433      * @function initialPowerStateForDomainState
 434      * @abstract
 435      * Return the initial power state for the device.
 436      * @discussion
 437      * This method is called to obtain the initial power state for the device,
 438      * by calling getInitialPowerState.
 439      * @param domainState
 440      * Power domain state flags.
 441      * @result
 442      * The return value must be a valid power state value.
 443      */
 444     virtual unsigned long initialPowerStateForDomainState ( IOPMPowerFlags domainState );
 445
 446     /*!
 447      * @function maxCapabilityForDomainState
 448      * @abstract
 449      * Return the maximum power level obtainable for the given state.
 450      * @discussion
 451      * This method is called to obtain the maximum power level obtainable for the
 452      * given state.
 453      * @param domainState
 454      * Power domain state flags.
 455      * @result
 456      * The return value must be a valid power state value.
 457      */
 458     virtual unsigned long  maxCapabilityForDomainState ( IOPMPowerFlags domainState );
 459
 460     /*!
 461      * @function powerStateForDomainState
 462      * Return the maximum power level obtainable for the given state.
 463      * @discussion
 464      * This method is called to obtain the maximum power level obtainable for the
 465      * given state.
 466      * @param domainState
 467      * Power domain state flags.
 468      * @result
 469      * The return value must be a valid power state value.
 470      */
 471     virtual unsigned long powerStateForDomainState ( IOPMPowerFlags domainState );
 472
 473     /*!
 474      * @function powerStateDidChangeTo
 475      * @abstract
 476      * React to a change in power state.
 477      * @discussion
 478      * This method is called when the power state changes. We call restoreElectronicsState
 479      * if necessary, then call dequeueCommands if we have changed to a state that has power.
 480      * @param stateOrdinal
 481      * The power level to which we have changed.
 482      */
 483     virtual IOReturn powerStateDidChangeTo ( unsigned long, unsigned long stateOrdinal, IOService* );
 484
 485     /*!
 486      * @function powerStateWillChangeTo
 487      * @abstract
 488      * Prepare for a power state change.
 489      * @discussion
 490      * This method is called when the power state will change. If we are powering-up from kAllOff,
 491      * we schedule a call to restoreElectronicsState. If, instead, we are powering-down from an "on" state,
 492      * we schedule a call to saveElectronicsState.
 493      * @param stateOrdinal
 494      * The power level to which we will change.
 495      */
 496     virtual IOReturn powerStateWillChangeTo ( unsigned long, unsigned long stateOrdinal, IOService* );
 497
 498     /*!
 499      * @function setPowerState
 500      * @abstract
 501      * Set the power state to the specified state.
 502      * @discussion
 503      * This method is called to cause a change in power state. We handle changes to and from
 504      * kAllOn and kElectronicsOn, which are done by spinning up and down the media.
 505      * @param powerStateOrdinal
 506      * The power level to which we must change.
 507      */
 508     virtual IOReturn setPowerState ( unsigned long powerStateOrdinal, IOService* );
 509
 510     /*!
 511      * @function powerTickle
 512      * Check for the device power state currently being in the desired state.
 513      * @discussion
 514      * This method simply "tickles"
 515      * the Power Management subsystem to ensure that the device transitions to the desired
 516      * state if necessary.
 517      */
 518     virtual bool        powerTickle(UInt32 desiredState);
 519
 520     /* Override this method to report the initial device power state when its domain is
 521      * powered up. The default implementation assumes the drive spins up.
 522      */
 523
 524     /*!
 525      * @function getInitialPowerState
 526      * @abstract
 527      * Report the initial power state of the device.
 528      * @discussion
 529      * The default implementation of this method returns kAllOn, assuming that the
 530      * drive spindle spins up initially.
 531      * @result
 532      * The return value must be a valid power state value.
 533      */
 534     virtual unsigned long getInitialPowerState(void);   /* default = kAllOn */
 535
 536     /* Override these to change power level required to do various commands. */
 537
 538     /*!
 539      * @function getEjectPowerState
 540      * @abstract
 541      * Return the required device power level to determine eject the media.
 542      * @discussion
 543      * The default implementation of this method returns kElectronicsOn.
 544      * @result
 545      * The return value must be a valid power state value.
 546      */
 547     virtual UInt32      getEjectPowerState(void);               /* default = kElectronicsOn */
 548
 549     /*!
 550      * @function getExecuteCDBPowerState
 551      * @abstract
 552      * @discussion
 553      * @param
 554      * @result
 555      * The return value must be a valid power state value.
 556      */
 557     virtual UInt32      getExecuteCDBPowerState(void);          /* default = kAllOn */
 558
 559     /*!
 560      * @function getFormatMediaPowerState
 561      * @abstract
 562      * Return the required device power level to execute a client CDB.
 563      * @discussion
 564      * The default implementation of this method returns kAllOn.
 565      * @result
 566      * The return value must be a valid power state value.
 567      */
 568     virtual UInt32      getFormatMediaPowerState(void);         /* default = kAllOn */
 569
 570     /*!
 571      * @function getInquiryPowerState
 572      * @abstract
 573      * Return the required device power level to execute an Inquiry command.
 574      * @discussion
 575      * The default implementation of this method returns kElectronicsOn.
 576      * @result
 577      * The return value must be a valid power state value.
 578      */
 579     virtual UInt32      getInquiryPowerState(void);             /* default = kElectronicsOn */
 580
 581     /*!
 582      * @function getLockUnlockMediaPowerState
 583      * @abstract
 584      * Return the required device power level to lock or unlock the media.
 585      * @discussion
 586      * The default implementation of this method returns kElectronicsOn.
 587      * @result
 588      * The return value must be a valid power state value.
 589      */
 590     virtual UInt32      getLockUnlockMediaPowerState(void);     /* default = kElectronicsOn */
 591
 592     /*!
 593      * @function getReadCapacityPowerState
 594      * @abstract
 595      * Return the required device power level to execute a Read-Capacity command.
 596      * @discussion
 597      * The default implementation of this method returns kElectronicsOn.
 598      * @result
 599      * The return value must be a valid power state value.
 600      */
 601     virtual UInt32      getReadCapacityPowerState(void);        /* default = kElectronicsOn */
 602
 603     /*!
 604      * @function getReadWritePowerState
 605      * @abstract
 606      * Return the required device power level to execute a Read or Write command.
 607      * @discussion
 608      * The default implementation of this method returns kAllOn.
 609      * @result
 610      * The return value must be a valid power state value.
 611      */
 612     virtual UInt32      getReadWritePowerState(void);           /* default = kAllOn */
 613
 614     /*!
 615      * @function getReportWriteProtectionPowerState
 616      * @abstract
 617      * Return the required device power level to report media write protection.
 618      * @discussion
 619      * The default implementation of this method returns kElectronicsOn.
 620      * @result
 621      * The return value must be a valid power state value.
 622      */
 623     virtual UInt32      getReportWriteProtectionPowerState(void); /* default = kElectronicsOn */
 624
 625     /*!
 626      * @function getStartPowerState
 627      * @abstract
 628      * Return the required device power level to start (spin up) the media.
 629      * @discussion
 630      * The default implementation of this method returns kElectronicsOn.
 631      * @result
 632      * The return value must be a valid power state value.
 633      */
 634     virtual UInt32      getStartPowerState(void);               /* default = kElectronicsOn */
 635
 636     /*!
 637      * @function getStopPowerState
 638      * @abstract
 639      * Return the required device power level to stop (spin down) the media.
 640      * @discussion
 641      * The default implementation of this method returns kAllOn.
 642      * @result
 643      * The return value must be a valid power state value.
 644      */
 645     virtual UInt32      getStopPowerState(void);                /* default = kAllOn */
 646
 647     /*!
 648      * @function getSynchronizeCachePowerState
 649      * @abstract
 650      * Return the required device power level to issue a Synchronize-Cache command.
 651      * @discussion
 652      * The default implementation of this method returns kAllOn.
 653      * @result
 654      * The return value must be a valid power state value.
 655      */
 656     virtual UInt32      getSynchronizeCachePowerState(void);    /* default = kAllOn */
 657
 658     /*!
 659      * @function getTestUnitReadyPowerState
 660      * @abstract
 661      * Return the required device power level to issue a Test Unit Ready command.
 662      * @discussion
 663      * The default implementation of this method returns kElectronicsOn.
 664      * @result
 665      * The return value must be a valid power state value.
 666      */
 667     virtual UInt32      getTestUnitReadyPowerState(void);       /* default = kElectronicsOn */
 668
 669     /*
 670      * @group
 671      * Internally used methods.
 672      */
 673
 674     /*!
 675      * @function createNub
 676      * @abstract
 677      * Create, init, attach, and register the device nub.
 678      * @discussion
 679      * This method calls instantiateNub, then init, attach, and register.
 680      * @result
 681      * A pointer to the nub or NULL if something failed.
 682      */
 683     virtual IOService * createNub(void);
 684
 685     /*!
 686      * @function getDeviceTypeName
 687      * @abstract
 688      * Return a character string for the device type.
 689      * @discussion
 690      * The default implementation of this method returns
 691      * kIOBlockStorageDeviceTypeGeneric.
 692      */
 693     virtual const char * getDeviceTypeName(void);
 694
 695     /*!
 696      * @function instantiateNub
 697      * @abstract
 698      * Create the device nub.
 699      * @discussion
 700      * A subclass will override this method to change the type of nub created.
 701      * A CD driver, for example, will instantiate an IOSCSICDDriveNub instead
 702      * of the default implementation's IOSCSIHDDriveNub.
 703      */
 704     virtual IOService * instantiateNub(void);
 705
 706     /*!
 707      * @function doStart
 708      * @abstract
 709      * Start (spin up) the media.
 710      * @discussion
 711      * This method calls doStartStop.
 712      */
 713     virtual IOReturn    doStart(void);
 714
 715     /*!
 716      * @function doStartStop
 717      * @abstract
 718      * Perform the actual spin up/down command.
 719      * @discussion
 720      * This method issues a SCSI Start Stop Unit command to start or stop
 721      * the device. Because the powerCondition value is only for use with
 722      * SCSI-3 devices, the current implementation ignores powerCondition.
 723      * @param start
 724      * True to start (spin-up) the media; False to stop (spin-down) the media.
 725      * @param loadEject
 726      * True to eject; False to not eject. This parameter is applicable only to a stop
 727      * operation.
 728      * @param powerCondition
 729      * The power condition to which the drive should transition. This is a SCSI-3
 730      * capability; it is presently unused.
 731      */
 732     virtual IOReturn    doStartStop(bool start,bool loadEject,UInt8 powerCondition);
 733
 734     /*!
 735      * @function doStop
 736      * @abstract
 737      * Stop (spin down) the media.
 738      * @discussion
 739      * This method calls doStartStop.
 740      */
 741     virtual IOReturn    doStop(void);
 742
 743     /*!
 744      * @function standardFormatMedia
 745      * @abstract
 746      * Perform a standard media format operation.
 747      * @discussion
 748      * See doFormatMedia for further information.
 749      */
 750     virtual IOReturn    standardFormatMedia(UInt64 byteCapacity);
 751
 752     /*!
 753      * @function standardSynchronizeCache
 754      * @abstract
 755      * Perform a standard Synchronize-Cache operation.
 756      * @discussion
 757      * See doFormatMedia for further information.
 758      */
 759     virtual IOReturn    standardSynchronizeCache(void);
 760
 761                                    /*
 762      * @endgroup
 763      */
 764
 765     /* Device information : */
 766
 767     /*!
 768      * @var _mediaPresent
 769      * True if media is present; False if media is not present.
 770      */
 771     bool                _mediaPresent;
 772
 773     /*!
 774      * @var _startStopDisabled
 775      * True if the start/stop commands are disabled due to an error.
 776      */
 777     bool                _startStopDisabled;
 778
 779     /*!
 780      * @var _restoreState
 781      * True if we must restore the device electronics state after a power-up.
 782      */
 783     bool                _restoreState;          /* true if we must restore after power-up */                                        };
 784 #endif