1/* 2 * Copyright (c) 1998-2008 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/* 24 * 25 * IOATACommand.h 26 * 27 */ 28 29#ifndef _IOATACOMMAND_H 30#define _IOATACOMMAND_H 31 32#include <libkern/c++/OSObject.h> 33#include <IOKit/IOTypes.h> 34#include <IOKit/IOMemoryDescriptor.h> 35#include <IOKit/IOCommand.h> 36#include "IOATATypes.h" 37 38 39class IOExtendedLBA; 40class IOATACommand; 41 42 43/*! @typedef IOATACompletionFunction callback function for ATA disk devices. 44*/ 45typedef void (IOATACompletionFunction)(IOATACommand* command ); 46 47 48/*! 49@class IOATACommand 50 51@discussion 52Command structure superclass, created and freed only by IOATADevice objects 53populated by disk device drivers with command parameters 54then submitted for operation to their IOATADevice provider for execution. 55 56IOATACommand is a virtual class, a concrete subclass contains the methods and fields needed 57by IOATAControllers. Subclasses may be specific to particular controller hardware. 58Disk device drivers will only have visibility to this interface and may not subclass this object. 59Disk device drivers should instead make use of the void* refcon field which the controllers will not 60touch 61*/ 62 63class IOATACommand : public IOCommand { 64 65 OSDeclareAbstractStructors( IOATACommand ); 66 67 public: 68 69 /*!@function zeroCommand 70 @abstract set to blank state, MUST call prior to re-use of this object 71 */ 72 virtual void zeroCommand(void); 73 74 /*!@function setOpcode 75 @abstract command opcode as defined in IOATATypes. 76 */ 77 virtual void setOpcode( ataOpcode inCode); 78 79 /*!@function setFlags 80 @abstract set the flags for this command, as defined in IOATATypes. 81 */ 82 virtual void setFlags( UInt32 inFlags); 83 84 /*!@function setUnit 85 @abstract set the unit number for this command. 86 */ 87 virtual void setUnit( ataUnitID inUnit); 88 89 /*!@function setTimeoutMS 90 @abstract how long to allow this command to complete, in milliseconds, once issued to 91 the hardware. if the time period expires, this command will return with a timeout error. 92 */ 93 virtual void setTimeoutMS( UInt32 inMs); 94 95 /*!@function setCallbackPtr 96 @abstract set the function pointer to call when this command completes. 97 */ 98 virtual void setCallbackPtr (IOATACompletionFunction* inCompletion); 99 100 /*!@function setRegMask 101 @abstract used when accessing registers or reading registers on an error result. Mask is defined 102 in IOATATypes.h 103 */ 104 virtual void setRegMask( ataRegMask mask); 105 106 // memory information 107 // Since ATA hardware is limited in the amount of bytes 108 // that can be transfered in a command, the disk driver shall supply 109 // a seperate offset and byte count per transfer. 110 // the offset may be any amount. The byte count must be a multiple of the 111 // sector size of the device, ie, N * 512 bytes for ata hard drives. 112 /*!@function setBuffer 113 @abstract set the IIOMemoryDescriptor for this transaction. 114 */ 115 virtual void setBuffer ( IOMemoryDescriptor* inDesc); 116 117 /*!@function setPosition 118 @abstract used to set an offset into the memory descriptor for this transfer. 119 */ 120 virtual void setPosition (IOByteCount fromPosition); 121 122 /*!@function setByteCount 123 @abstract set the byte count for this transaction. Should agree with the device command and the 124 memory descriptor in use. 125 */ 126 virtual void setByteCount (IOByteCount numBytes); 127 128 /*!@function setTransferChunkSize 129 @abstract set the size of transfer between intervening interrupts. necessary when doing PIO Read/Write Multiple, etc. so the controller knows when to expect an interrupt during multi-sector data transfers. 130 */ 131 virtual void setTransferChunkSize( IOByteCount chunk = kATADefaultSectorSize); 132 133 /*!@function setFeatures 134 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 135 */ 136 virtual void setFeatures( UInt8 in); 137 138 /*!@function getErrorReg 139 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 140 */ 141 virtual UInt8 getErrorReg (void ); 142 143 /*!@function setSectorCount 144 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 145 */ 146 virtual void setSectorCount( UInt8 in); 147 148 /*!@function getSectorCount 149 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 150 */ 151 virtual UInt8 getSectorCount (void ); 152 153 /*!@function setSectorNumber 154 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 155 */ 156 virtual void setSectorNumber( UInt8 in); 157 158 /*!@function getSectorNumber 159 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 160 */ 161 virtual UInt8 getSectorNumber (void ); 162 163 /*!@function setCylLo 164 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 165 */ 166 virtual void setCylLo ( UInt8 in); 167 168 /*!@function getCylLo 169 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 170 */ 171 virtual UInt8 getCylLo (void ); 172 173 /*!@function setCylHi 174 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 175 */ 176 virtual void setCylHi( UInt8 in); 177 178 /*!@function getCylHi 179 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 180 */ 181 virtual UInt8 getCylHi (void ); 182 183 /*!@function setDevice_Head 184 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 185 */ 186 virtual void setDevice_Head( UInt8 in); 187 188 /*!@function getDevice_Head 189 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 190 */ 191 virtual UInt8 getDevice_Head (void ); 192 193 /*!@function setCommand 194 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 195 */ 196 virtual void setCommand ( UInt8 in); 197 198 /*!@function getStatus 199 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 200 */ 201 virtual UInt8 getStatus (void ); 202 203 /*!@function setLBA28 204 @abstract convenience method that sets the taskfile registers into a 28-bit LBA address, with unit selected and LBA bit set. return err if param out of range, return kIOSuccess (kATANoErr) = 0 on return if successful 205 */ 206 virtual IOReturn setLBA28( UInt32 lba, ataUnitID inUnit); 207 208 /*!@function setPacketCommand 209 @abstract ATAPI command packet max size is 16 bytes. Makes deep copy of data. 210 */ 211 virtual IOReturn setPacketCommand( UInt16 packetSizeBytes, UInt8* command); 212 213 // the following registers are only accessed by register access 214 // commands. Not by normal command dispatch where they are handled 215 // by the controller. 216 217 // not part of task file params. not written to device when sending commands. 218 virtual void setDataReg ( UInt16 in); 219 virtual UInt16 getDataReg (void ); 220 221 // not part of taskfile. Not usually used except by controller. 222 virtual void setControl ( UInt8 in); 223 virtual UInt8 getAltStatus (void ); 224 225 // return values 226 /*!@function getResult 227 @abstract IOReturn value of the result of this command. ATA family errors are defined in IOATATypes.h 228 */ 229 virtual IOReturn getResult (void); 230 231 /*!@function getBuffer 232 @abstract the IOMemoryDescriptor used in this transaction. 233 */ 234 virtual IOMemoryDescriptor* getBuffer ( void ); 235 236 /*!@function getActualTransfer 237 @abstract The byte count on the ending result, as best as can be determined by the controller. May be zero, but partial transfer may have occurred on error in some cases. 238 */ 239 virtual IOByteCount getActualTransfer ( void ); 240 241 /*!@function getEndStatusReg 242 @abstract the value of the status register on the end of the command. 243 */ 244 virtual UInt8 getEndStatusReg (void); // always returned 245 246 /*!@function getEndErrorReg 247 @abstract If the error bit was set in the status register, the value of the error register is returned at the end of a command. 248 */ 249 virtual UInt8 getEndErrorReg( void ); 250 251 /*!@function getCommandInUse 252 @abstract returns true if IOATAController is still in control of the command. 253 */ 254 virtual bool getCommandInUse( void ); // returns true if IOATAController is using the command. 255 256 // for use by disk drivers, clients of IOATADevice only. 257 // IOATADevice and IOATAControllers shall not use this field in any manner 258 /*!@var refCon 259 @abstract for use by disk drivers, clients of IOATADevice only. IOATADevice and IOATAControllers shall not use this field in any manner. 260 */ 261 void* refCon; 262 263 /*!@var refCon2 264 @abstract for use by disk drivers, clients of IOATADevice only. IOATADevice and IOATAControllers shall not use this field in any manner. 265 */ 266 void* refCon2; 267 268 protected: 269 // < return from ATA controllers to disk drivers 270 // > sent to ATA controllers from disk drivers 271 ataOpcode _opCode; // > Command code for the controller. 272 UInt32 _flags; // > Flags for this command 273 ataRegisterImage _taskFile; // <> Taskfile + data and control registers. 274 ATAPICmdPacket _packet; // > ATAPI packet 275 ataUnitID _unit; // > Unit number 276 UInt32 _timeoutMS; // > timeout command in ms. 277 IOMemoryDescriptor* _desc; // > Buffer for data may be nil if command transfer no data 278 IOByteCount _position; // > Position within the descriptor for this command 279 IOByteCount _byteCount; // > How many bytes to transfer. 280 IOByteCount _logicalChunkSize; // > How many bytes between intervening interrupts (R/W Multiple) 281 ataRegMask _regMask; // > Which registers to write or read for reg access commands 282 IOATACompletionFunction* _callback; // > if nil, command is synchronous 283 284 IOReturn _result; // < result 285 IOByteCount _actualByteCount; // < actual bytes transfered. 286 UInt8 _status; // < Status register at end of command 287 UInt8 _errReg; // < Error register at end of command if error bit set. 288 bool _inUse; // < true while IOATAController has possesion of the command 289 290 291 virtual bool init(); 292protected: 293/*! @struct ExpansionData 294 @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future. 295 */ 296 struct ExpansionData {IOExtendedLBA* extLBA; }; 297 298/*! @var reserved 299 Reserved for future use. (Internal use only) */ 300 ExpansionData *fExpansionData; 301 302 // overrides 303 virtual void free(); 304 305 306private: 307 OSMetaClassDeclareReservedUsed(IOATACommand, 0); // set end result 308 OSMetaClassDeclareReservedUsed(IOATACommand, 1); // get extendedLBAPtr 309 OSMetaClassDeclareReservedUnused(IOATACommand, 2); 310 OSMetaClassDeclareReservedUnused(IOATACommand, 3); 311 OSMetaClassDeclareReservedUnused(IOATACommand, 4); 312 OSMetaClassDeclareReservedUnused(IOATACommand, 5); 313 OSMetaClassDeclareReservedUnused(IOATACommand, 6); 314 OSMetaClassDeclareReservedUnused(IOATACommand, 7); 315 OSMetaClassDeclareReservedUnused(IOATACommand, 8); 316 OSMetaClassDeclareReservedUnused(IOATACommand, 9); 317 OSMetaClassDeclareReservedUnused(IOATACommand, 10); 318 OSMetaClassDeclareReservedUnused(IOATACommand, 11); 319 OSMetaClassDeclareReservedUnused(IOATACommand, 12); 320 OSMetaClassDeclareReservedUnused(IOATACommand, 13); 321 OSMetaClassDeclareReservedUnused(IOATACommand, 14); 322 OSMetaClassDeclareReservedUnused(IOATACommand, 15); 323 OSMetaClassDeclareReservedUnused(IOATACommand, 16); 324 OSMetaClassDeclareReservedUnused(IOATACommand, 17); 325 OSMetaClassDeclareReservedUnused(IOATACommand, 18); 326 OSMetaClassDeclareReservedUnused(IOATACommand, 19); 327 OSMetaClassDeclareReservedUnused(IOATACommand, 20); 328 329public: 330 virtual void setEndResult(UInt8 inStatus, UInt8 endError ); 331 virtual IOExtendedLBA* getExtendedLBA(void); 332 333 334}; 335 336 337/*! 338@class IOExtendedLBA 339 340@discussion 341If 48-bit LBAs are supported, IOExtendedLBA is used to represent a 48-bit LBA. 342The driver examines the ATA identify data to determine if 48-bit addressing is 343supported. 344*/ 345 346class IOExtendedLBA : public OSObject 347{ 348 OSDeclareDefaultStructors( IOExtendedLBA ); 349 350 public: 351 static IOExtendedLBA* createIOExtendedLBA(IOATACommand* owner); 352 353 // terminology as established in ATA/ATAPI-6. 354 // for the extended LBA address 355 356 /*!@function setLBALow16 357 @abstract convenience method that sets the lower 16 bits of a 48-bit LBA 358 */ 359 virtual void setLBALow16( UInt16 lbaLow); 360 361 /*!@function getLBALow16 362 @abstract convenience method that gets the lower 16 bits of a 48-bit LBA 363 */ 364 virtual UInt16 getLBALow16 (void); 365 366 /*!@function setLBAMid16 367 @abstract convenience method that sets the middle 16 bits of a 48-bit LBA 368 */ 369 virtual void setLBAMid16 (UInt16 lbaMid); 370 371 /*!@function getLBAMid16 372 @abstract convenience method that gets the middle 16 bits of a 48-bit LBA 373 */ 374 virtual UInt16 getLBAMid16( void ); 375 376 /*!@function setLBAHigh16 377 @abstract convenience method that sets the high 16 bits of a 48-bit LBA 378 */ 379 virtual void setLBAHigh16( UInt16 lbaHigh ); 380 381 /*!@function getLBAHigh16 382 @abstract convenience method that gets the high 16 bits of a 48-bit LBA 383 */ 384 virtual UInt16 getLBAHigh16( void ); 385 386 /*!@function setSectorCount16 387 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 388 */ 389 virtual void setSectorCount16( UInt16 sectorCount ); 390 391 /*!@function getSectorCount16 392 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 393 */ 394 virtual UInt16 getSectorCount16( void ); 395 396 /*!@function setFeatures16 397 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 398 */ 399 virtual void setFeatures16( UInt16 features ); 400 401 /*!@function getFeatures16 402 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 403 */ 404 virtual UInt16 getFeatures16( void ); 405 406 /*!@function setDevice 407 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 408 */ 409 virtual void setDevice( UInt8 inDevice ); 410 411 /*!@function getDevice 412 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 413 */ 414 virtual UInt8 getDevice( void ); 415 416 /*!@function setCommand 417 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 418 */ 419 virtual void setCommand( UInt8 inCommand ); 420 421 /*!@function getCommand 422 @abstract Taskfile access. Registers are named in accordance with ATA Standards conventions 423 */ 424 virtual UInt8 getCommand( void ); 425 426 /*!@function setExtendedLBA 427 @abstract convenience method that sets the taskfile registers into a 48-bit LBA address, along with sector count, and unit selected and LBA bit set 428 */ 429 virtual void setExtendedLBA( UInt32 inLBAHi, UInt32 inLBALo, ataUnitID inUnit, UInt16 extendedCount, UInt8 extendedCommand); 430 431 /*!@function getExtendedLBA 432 @abstract convenience method that gets a 48-bit LBA 433 */ 434 virtual void getExtendedLBA( UInt32* outLBAHi, UInt32* outLBALo ); 435 436 /*!@function zeroData 437 @abstract convenience method that zeros out the lba, sector count, features, device, and command member variables 438 */ 439 virtual void zeroData(void); 440 441 /*! @struct ExpansionData 442 @discussion This structure will be used to expand the capablilties in the future. 443 */ 444 struct ExpansionData { }; 445 446 /*! @var reserved 447 Reserved for future use. (Internal use only) */ 448 ExpansionData *reserved; 449 450 451 protected: 452 453 IOATACommand* owner; 454 UInt16 lbaLow; 455 UInt16 lbaMid; 456 UInt16 lbaHigh; 457 UInt16 sectorCount; 458 UInt16 features; 459 UInt16 device; 460 UInt16 command; 461 462 private: 463 OSMetaClassDeclareReservedUnused(IOExtendedLBA, 0); 464 OSMetaClassDeclareReservedUnused(IOExtendedLBA, 1); 465 OSMetaClassDeclareReservedUnused(IOExtendedLBA, 2); 466 OSMetaClassDeclareReservedUnused(IOExtendedLBA, 3); 467 OSMetaClassDeclareReservedUnused(IOExtendedLBA, 4); 468 OSMetaClassDeclareReservedUnused(IOExtendedLBA, 5); 469 OSMetaClassDeclareReservedUnused(IOExtendedLBA, 6); 470 OSMetaClassDeclareReservedUnused(IOExtendedLBA, 7); 471 OSMetaClassDeclareReservedUnused(IOExtendedLBA, 8); 472 OSMetaClassDeclareReservedUnused(IOExtendedLBA, 9); 473 OSMetaClassDeclareReservedUnused(IOExtendedLBA, 10); 474 475 476}; 477 478#endif 479