iokit/IOKit/storage/ata/IOATAHDDrive.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  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved.
  24  *
  25  * IOATAHDDrive.h
  26  *
  27  * HISTORY
  28  * Aug 27, 1999    jliu - Ported from AppleATADrive.
  29  */
  30
  31 #ifndef _IOATAHDDRIVE_H
  32 #define _IOATAHDDRIVE_H
  33
  34 #include <IOKit/IOTypes.h>
  35 #include <IOKit/ata/IOATADeviceInterface.h>
  36 #include <IOKit/IOCommandGate.h>
  37 #include <IOKit/IOWorkLoop.h>
  38 #include <IOKit/storage/IOStorage.h>
  39
  40 class IOSyncer;
  41
  42 // ATA parameters.
  43 //
  44 #define kIOATASectorSize          512
  45 #define kIOATAMaxBlocksPerXfer    256
  46
  47 // ATA commands.
  48 //
  49 enum {
  50     kIOATACommandReadPIO            = 0x20,
  51     kIOATACommandWritePIO           = 0x30,
  52     kIOATACommandReadDMA            = 0xc8,
  53     kIOATACommandWriteDMA           = 0xca,
  54     kIOATACommandReadDMAQueued      = 0xc7,
  55     kIOATACommandWriteDMAQueued     = 0xcc,
  56     kIOATACommandStandbyImmediate   = 0xe0,
  57     kIOATACommandSleep              = 0xe6,
  58     kIOATACommandFlushCache         = 0xe7,
  59     kIOATACommandSetFeatures        = 0xef,
  60 };
  61
  62 // ATA power states, from lowest to highest power usage.
  63 //
  64 typedef enum {
  65     kIOATAPowerStateSleep = 0,
  66     kIOATAPowerStateStandby,
  67     kIOATAPowerStateIdle,
  68     kIOATAPowerStateActive
  69 } IOATAPowerState;
  70
  71 // ATA supported features.
  72 //
  73 enum {
  74     kIOATAFeaturePowerManagement  = 0x01,
  75     kIOATAFeatureWriteCache       = 0x02
  76 };
  77
  78 // Stages to transition into each power state.
  79 //
  80 enum {
  81     kIOATAStandbyStage0,  /* hold the queue */
  82     kIOATAStandbyStage1,  /* flush disk write cache */
  83     kIOATAStandbyStage2,  /* issue ATA STANDBY IMMEDIATE command */
  84     kIOATAStandbyStage3   /* finalize state transition */
  85 };
  86
  87 enum {
  88     kIOATAActiveStage0,   /* issue a software reset */
  89     kIOATAActiveStage1,   /* spin up the drive */
  90     kIOATAActiveStage2,   /* release the queue */
  91         kIOATAActiveStage3    /* finalize state transition */
  92 };
  93
  94 // Property table keys.
  95 //
  96 #define kIOATASupportedFeaturesKey   "ATA Features"
  97 #define kIOATAEnableWriteCacheKey    "Enable Write Cache"
  98
  99 //===========================================================================
 100 // IOATAClientData - This structure is stored on the IOATACommand's
 101 // driver private area.
 102 //===========================================================================
 103
 104 struct IOATAClientData
 105 {
 106     IOATACommand *          command;     // back pointer to command object.
 107     IOMemoryDescriptor *    buffer;      // transfer buffer descriptor.
 108     union {
 109         IOStorageCompletion async;       // completion target/action/param.
 110         IOSyncer *          syncLock;    // used by sync commands.
 111     } completion;
 112     bool                    isSync;      // command is synchronous.
 113     SInt32                  maxRetries;  // max retry attempts (0 = no retry).
 114     IOReturn                returnCode;  // sync command return code.
 115 };
 116
 117 // Get driver private data (IOATAClientData) from an IOATACommand object.
 118 //
 119 #define ATA_CLIENT_DATA(x)    ((IOATAClientData *)((x)->getClientData()))
 120
 121 //===========================================================================
 122 // IOATAHDDrive
 123 //===========================================================================
 124
 125 class IOATAHDDrive : public IOService
 126 {
 127     OSDeclareDefaultStructors(IOATAHDDrive)
 128
 129 protected:
 130     IOATADevice *         _ataDevice;
 131     IOCommandGate *       _cmdGate;
 132     UInt                  _unit;
 133     ATATimingProtocol     _timingProtocol;
 134     ATAProtocol           _ataProtocol;
 135     UInt8                 _ataReadCmd;
 136     UInt8                 _ataWriteCmd;
 137     char                  _revision[9];
 138     char                  _model[41];
 139     bool                  _powerStateChanging;
 140     bool                  _setPowerAckPending;
 141     bool                  _logSelectedTimingProtocol;
 142     IOOptionBits          _supportedFeatures;
 143     IOATAPowerState       _currentATAPowerState;
 144     IOATAPowerState       _proposedATAPowerState;
 145     void *                _configThreadCall;
 146     bool                  _pmReady;
 147
 148     //-----------------------------------------------------------------------
 149     // Default timeout (in milliseconds) for async and sync commands.
 150
 151     static const UInt kATADefaultTimeout = 30000;        // 30 seconds
 152
 153     //-----------------------------------------------------------------------
 154     // Default retry count for async and sync commands.
 155
 156     static const UInt kATADefaultRetries = 4;
 157     static const UInt kATAZeroRetry      = 0;
 158
 159     //-----------------------------------------------------------------------
 160     // Static member functions called by IOCommandGate, or registered
 161     // as completion routines.
 162
 163     static void sHandleCommandCompletion(IOATAHDDrive * self,
 164                                          IOATACommand * cmd);
 165
 166     static void sHandleSetPowerState(IOATAHDDrive * self,
 167                                      UInt32         powerStateOrdinal,
 168                                      IOService *    whatDevice,
 169                                      IOReturn *     handlerReturn);
 170
 171     static void sHandleSleepStateTransition(IOATAHDDrive * self,
 172                                             void *         stage,
 173                                             IOReturn       status,
 174                                             UInt64         bytesTransferred);
 175
 176     static void sHandleActiveStateTransition(IOATAHDDrive * self,
 177                                              void *         stage,
 178                                              IOReturn       status,
 179                                              UInt64         bytesTransferred);
 180
 181     static void sHandleIdleStateTransition(IOATAHDDrive * self,
 182                                            void *         stage,
 183                                            IOReturn       status,
 184                                            UInt64         bytesTransferred);
 185
 186     static void sHandleStandbyStateTransition(IOATAHDDrive * self,
 187                                               void *         stage,
 188                                               IOReturn       status,
 189                                               UInt64         bytesTransferred);
 190
 191     static void sHandleInitialPowerStateForDomainState(
 192                                               IOATAHDDrive * self,
 193                                               IOPMPowerFlags domainState,
 194                                               UInt32 *       state);
 195
 196     static void sHandleConfigureDevice(IOATAHDDrive * self);
 197
 198     //-----------------------------------------------------------------------
 199     // Release all allocated resource before calling super::free().
 200
 201     virtual void free();
 202
 203     //-----------------------------------------------------------------------
 204     // Select the device timing protocol.
 205
 206     virtual bool selectTimingProtocol();
 207
 208     //-----------------------------------------------------------------------
 209     // Select the ATA protocol.
 210
 211     virtual bool selectCommandProtocol(bool isDMA);
 212
 213     //-----------------------------------------------------------------------
 214     // Setup an ATATaskFile from the parameters given, and write the taskfile
 215     // to the ATATaskfile structure pointer provided.
 216
 217     virtual void setupReadWriteTaskFile(ATATaskfile * taskfile,
 218                                         ATAProtocol   protocol,
 219                                         UInt8         command,
 220                                         UInt32        block,
 221                                         UInt32        nblks);
 222
 223     //-----------------------------------------------------------------------
 224     // Return an IOATACommand initialized to perform a read/write operation.
 225
 226     virtual IOATACommand * ataCommandReadWrite(IOMemoryDescriptor * buffer,
 227                                                UInt32               block,
 228                                                UInt32               nblks);
 229
 230     //-----------------------------------------------------------------------
 231     // Return a ATA Set Features command.
 232
 233     virtual IOATACommand * ataCommandSetFeatures(UInt8 features,
 234                                                  UInt8 SectorCount   = 0,
 235                                                  UInt8 SectorNumber  = 0,
 236                                                  UInt8 CylinderLow   = 0,
 237                                                  UInt8 CyclinderHigh = 0);
 238
 239     //-----------------------------------------------------------------------
 240     // Return a ATA Flush Cache command.
 241
 242     virtual IOATACommand * ataCommandFlushCache();
 243
 244     //-----------------------------------------------------------------------
 245     // Return a ATA Standby Immediate command.
 246
 247     virtual IOATACommand * ataCommandStandby();
 248
 249     //-----------------------------------------------------------------------
 250     // Issue a synchronous ATA command.
 251
 252     virtual IOReturn syncExecute(IOATACommand * cmd,
 253                                  UInt32         timeout = kATADefaultTimeout,
 254                                  UInt           retries = kATADefaultRetries,
 255                                  IOMemoryDescriptor * senseData = 0);
 256
 257     //-----------------------------------------------------------------------
 258     // Issue an asynchronous ATA command.
 259
 260     virtual IOReturn asyncExecute(
 261                           IOATACommand *      cmd,
 262                           IOStorageCompletion completion,
 263                           UInt32              timeout = kATADefaultTimeout,
 264                           UInt                retries = kATADefaultRetries);
 265
 266     //-----------------------------------------------------------------------
 267     // Allocate an IOATACommand object.
 268
 269     virtual IOATACommand * allocateCommand();
 270
 271     //-----------------------------------------------------------------------
 272     // Inspect the ATA device.
 273
 274     virtual bool inspectDevice(IOATADevice * device);
 275
 276     //-----------------------------------------------------------------------
 277     // Configure the ATA device.
 278
 279     virtual bool configureDevice(IOATADevice * device);
 280
 281     //-----------------------------------------------------------------------
 282     // Returns an IOATAHDDriveNub instance.
 283
 284     virtual IOService * instantiateNub();
 285
 286     //-----------------------------------------------------------------------
 287     // Calls instantiateNub() then initialize, attach, and register the
 288     // drive nub.
 289
 290     virtual bool createNub(IOService * provider);
 291
 292     //-----------------------------------------------------------------------
 293     // Power management support. Subclasses can override these functions
 294     // to replace/enhance the default power management support.
 295
 296     virtual void initForPM();
 297
 298     virtual UInt32 handleInitialPowerStateForDomainState(
 299                                              IOPMPowerFlags domainState);
 300
 301     virtual IOReturn handleSetPowerState(UInt32      powerStateOrdinal,
 302                                          IOService * whatDevice);
 303
 304     virtual IOATAPowerState getATAPowerStateForStateOrdinal(
 305                                                UInt32 stateOrdinal);
 306
 307     virtual void startATAPowerStateTransition(IOATAPowerState ataPowerState);
 308
 309     virtual void endATAPowerStateTransition(IOATAPowerState ataPowerState);
 310
 311     virtual void abortATAPowerStateTransition();
 312
 313     virtual void handleSleepStateTransition(UInt32 stage, IOReturn status);
 314
 315     virtual void handleActiveStateTransition(UInt32 stage, IOReturn status);
 316
 317     virtual void handleIdleStateTransition(UInt32 stage, IOReturn status);
 318
 319     virtual void handleStandbyStateTransition( UInt32 stage, IOReturn status);
 320
 321     virtual IOReturn readSector(IOStorageCompletion completion,
 322                                 UInt32              sector = 0);
 323
 324     static void acknowledgeATAPowerStateTransition(void *castMeToIOATAHDDrive, void*);
 325
 326 public:
 327     /*
 328      * Overrides from IOService.
 329      */
 330     virtual bool        init(OSDictionary * properties);
 331     virtual IOService * probe(IOService * provider, SInt32 * score);
 332     virtual bool        start(IOService * provider);
 333     virtual void        stop(IOService * provider);
 334
 335     //-----------------------------------------------------------------------
 336     // Report the type of ATA device (ATA vs. ATAPI).
 337
 338     virtual ATADeviceType reportATADeviceType() const;
 339
 340     //-----------------------------------------------------------------------
 341     // Handles read/write requests.
 342
 343     virtual IOReturn doAsyncReadWrite(IOMemoryDescriptor * buffer,
 344                                       UInt32               block,
 345                                       UInt32               nblks,
 346                                       IOStorageCompletion  completion);
 347
 348     virtual IOReturn doSyncReadWrite(IOMemoryDescriptor * buffer,
 349                                      UInt32               block,
 350                                      UInt32               nblks);
 351
 352     //-----------------------------------------------------------------------
 353     // Eject the media in the drive.
 354
 355     virtual IOReturn doEjectMedia();
 356
 357     //-----------------------------------------------------------------------
 358     // Format the media in the drive.
 359
 360     virtual IOReturn doFormatMedia(UInt64 byteCapacity);
 361
 362     //-----------------------------------------------------------------------
 363     // Returns disk capacity in bytes.
 364
 365     virtual UInt32 doGetFormatCapacities(UInt64 * capacities,
 366                                          UInt32   capacitiesMaxCount) const;
 367
 368     //-----------------------------------------------------------------------
 369     // Lock the media and prevent a user-initiated eject.
 370
 371     virtual IOReturn doLockUnlockMedia(bool doLock);
 372
 373     //-----------------------------------------------------------------------
 374     // Flush the write-cache to the physical media.
 375
 376     virtual IOReturn doSynchronizeCache();
 377
 378     //-----------------------------------------------------------------------
 379     // Start/stop the drive.
 380
 381     virtual IOReturn doStart();
 382     virtual IOReturn doStop();
 383
 384     //-----------------------------------------------------------------------
 385     // Return device identification strings
 386
 387     virtual char * getAdditionalDeviceInfoString();
 388     virtual char * getProductString();
 389     virtual char * getRevisionString();
 390     virtual char * getVendorString();
 391
 392     //-----------------------------------------------------------------------
 393     // Report the device block size in bytes.
 394
 395     virtual IOReturn reportBlockSize(UInt64 * blockSize);
 396
 397     //-----------------------------------------------------------------------
 398     // Report whether the media in the ATA device is ejectable.
 399
 400     virtual IOReturn reportEjectability(bool * isEjectable);
 401
 402     //-----------------------------------------------------------------------
 403     // Report whether the media can be locked.
 404
 405     virtual IOReturn reportLockability(bool * isLockable);
 406
 407     //-----------------------------------------------------------------------
 408     // Report the polling requirements for a removable media.
 409
 410     virtual IOReturn reportPollRequirements(bool * pollRequired,
 411                                                   bool * pollIsExpensive);
 412
 413     //-----------------------------------------------------------------------
 414     // Report the max number of bytes transferred for an ATA read command.
 415
 416     virtual IOReturn reportMaxReadTransfer(UInt64   blocksize,
 417                                            UInt64 * max);
 418
 419     //-----------------------------------------------------------------------
 420     // Report the max number of bytes transferred for an ATA write command.
 421
 422     virtual IOReturn reportMaxWriteTransfer(UInt64   blocksize,
 423                                             UInt64 * max);
 424
 425     //-----------------------------------------------------------------------
 426     // Returns the maximum addressable sector number.
 427
 428     virtual IOReturn reportMaxValidBlock(UInt64 * maxBlock);
 429
 430     //-----------------------------------------------------------------------
 431     // Report whether the media is currently present, and whether a media
 432     // change has been registered since the last reporting.
 433
 434     virtual IOReturn reportMediaState(bool * mediaPresent,
 435                                       bool * changed);
 436
 437     //-----------------------------------------------------------------------
 438     // Report whether the media is removable.
 439
 440     virtual IOReturn reportRemovability(bool * isRemovable);
 441
 442     //-----------------------------------------------------------------------
 443     // Report if the media is write-protected.
 444
 445     virtual IOReturn reportWriteProtection(bool * isWriteProtected);
 446
 447     //-----------------------------------------------------------------------
 448     // Handles messages (notifications) from our provider.
 449
 450     virtual IOReturn message(UInt32      type,
 451                              IOService * provider,
 452                              void *      argument);
 453
 454     //-----------------------------------------------------------------------
 455     // Returns the device type.
 456
 457     virtual const char * getDeviceTypeName();
 458
 459     //-----------------------------------------------------------------------
 460     // Power management support. Functions inherited from IOService.
 461
 462     virtual IOReturn setAggressiveness(UInt32 type, UInt32 minutes);
 463
 464     virtual UInt32 initialPowerStateForDomainState(IOPMPowerFlags domainState);
 465
 466     virtual IOReturn setPowerState(UInt32      powerStateOrdinal,
 467                                    IOService * whatDevice);
 468 };
 469
 470 #endif /* !_IOATAHDDRIVE_H */