iokit/IOKit/ata/IOATACommand_Reference.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 IOATACommand_Reference.h
  25
  26 This header defines the IOATACommand class.
  27
  28 This class encapsulates an ATA/ATAPI Command. The client driver allocates a
  29 command using IOATADevice::allocCommand() and initializes it using
  30 functions of this class. The client can then submit the command to
  31 the ATA/ATAPI stack by invoking the execute() function.
  32 */
  33
  34 /*!
  35 @typedef ATATaskfile
  36 @discussion
  37 The ATATaskfile structure provides information to be read/written into an IOATACommand. This
  38 information includes the ATA taskfile register settings and the protocol the transport driver
  39 is to use when the corresponding IOATACommand is executed.
  40 @field protocol
  41 Indicates the type of protocol the ATA Controller driver is to use when executing this command.
  42 See enum ATAProtocol in IOATADevice_Reference for allowable values for this field.
  43 @field tagType
  44 Indicates whether an ATA command requires a tag. This field is only used when the protocol
  45 selected for the command supports the Overlap feature set.
  46 @field tag
  47 This field is set by the IOATAController class to tell the host
  48 adapter driver the tag value to assign to this IOATACommand.
  49 @field resultmask
  50 This field is set by the IOATADevice client and is a bit mask indicating the registers to be
  51 returned when the IOATACommand completes. Clients should use ATARegToMask() convert ATA register
  52 index values to bit mask values.
  53 @field regmask
  54 This field is set by the IOATADevice client and is a bit mask indicating the registers to be written
  55 when an IOATACommand is executed. Clients should use ATARegToMask() convert ATA register
  56 index values to bit mask values.
  57 @field ataRegs
  58 This array contains the ATA taskfile register values to be written when an IOATACommand is executed.
  59 The index values for ATA taskfile registers is specified by enum ATARegs.
  60 */
  61 typedef struct ATATaskfile {
  62
  63     ATAProtocol         protocol;
  64
  65     UInt32              flags;
  66
  67     UInt8               tagType;
  68     UInt32              tag;
  69
  70     UInt32              resultmask;
  71
  72     UInt32              regmask;
  73     UInt32              ataRegs[kMaxATARegs];
  74
  75 } ATATaskfile;
  76
  77 /*!
  78 @typedef ATACDBInfo
  79 @discussion
  80 The ATACDBInfo structure provides cdb information to be read/written into an IOATACommand.
  81 @field cdbFlags
  82 Indicates flags to applicable to the CDB to be executed. There are currently no flags defined for
  83 IOATADevice clients.
  84 @field cdbLength
  85 Set by the IOATADevice client to the length of the Command Descriptor
  86 Block (CDB).
  87 @field cdb
  88 Set by the IOATADevice client to command descriptor block the client
  89 wishes the ATAPI device to execute.
  90 */
  91 typedef struct ATACDBInfo {
  92
  93     UInt32              cdbFlags;
  94
  95     UInt32              cdbLength;
  96     UInt8               cdb[16];
  97
  98     UInt32              reserved[16];
  99
 100 } ATACDBInfo;
 101
 102 /*!
 103 @typedef ATAResults
 104 @discussion
 105 The ATAResults structure provides completion information for an IOATACommand.
 106 @field returnCode
 107 The overall return code for the command. See iokit/iokit/IOReturn.h.
 108 This value is also returned as the getResults() return value.
 109 @field bytesTransferred
 110 The total number of bytes transferred to/from the ATA device.
 111 Note: Some ATA controllers are not capable of returning accurate byte counts when
 112 operating in bus-master mode. Clients should use some caution in interpreting the
 113 contents of this field.
 114 @field adapterStatus
 115 This field contains the low-level ATA Controller status for a completed IOATACommand.
 116 Values for this field are defined by enum ATAReturnCode.
 117 @field requestSenseDone
 118 A boolean indicating whether sense data was obtained from the ATAPI
 119 device.
 120 @field requestSenseLength
 121 The number of sense data bytes returned from the ATAPI device.
 122 @field ataRegs
 123 This array contains the ATA taskfile register values to be returned when an IOATACommand completes.
 124 The index values for ATA taskfile registers is specified by enum ATARegs. Registers to be returned
 125 are indicated by the bit mask resultmask. See structure ATATaskfile.
 126 */
 127 typedef struct ATAResults {
 128
 129     IOReturn            returnCode;
 130
 131     UInt32              bytesTransferred;
 132
 133     ATAReturnCode       adapterStatus;
 134
 135     bool                requestSenseDone;
 136     UInt32              requestSenseLength;
 137
 138     UInt32              ataRegs[kMaxATARegs];
 139
 140     UInt32              reserved[16];
 141
 142 } ATAResults;
 143
 144
 145
 146 class IOATACommand : public IOCDBCommand
 147 {
 148 public:
 149
 150
 151 /*!
 152 @function setPointers
 153 @abstract
 154 Sets the data buffer component of an ATA/ATAPI Command.
 155 @discussion
 156 The client provides an IOMemoryDescriptor object to corresponding
 157 to the client's data or request sense buffer, the maximum data transfer count
 158 and data transfer direction.
 159 @param desc
 160 Pointer to a IOMemoryDescriptor describing the client's I/O buffer.
 161 @param transferCount
 162 Maximum data transfer count in bytes.
 163 @param isWrite
 164 Data transfer direction. (Defined with respect to the device, i.e. isWrite = true
 165 indicates the host is writing to the device.
 166 @param isSense
 167 If isSense is set to false, the IOATACommand's data buffer information is set. If isSense is
 168 set to true, the IOATACommand's request sense buffer information is set.
 169 */
 170      void                       setPointers( IOMemoryDescriptor         *desc,
 171                                              UInt32                     transferCount,
 172                                              bool                       isWrite,
 173                                              bool                       isSense = false );
 174 /*!
 175 @function getPointers
 176 @abstract
 177 Gets the data buffer component of an ATA/ATAPI Command.
 178 @discussion
 179 The client provides a set of pointers to fields to receive the IOATACommand's
 180 data/request sense buffer pointers.
 181 @param desc
 182 Pointer to a field (IOMemoryDescriptor *) to receive the IOATACommand's IOMemoryDescriptor pointer.
 183 @param transferCount
 184 Pointer to a field (UInt32) to receive the IOATACommand's maximum transfer count.
 185 @param isWrite
 186 Pointer to a field (bool) to receive the IOATACommand's transfer direction.
 187 @param isSense
 188 If isSense is set to true, the IOATACommand's data buffer information is returned. Otherwise,
 189 the IOATACommand's request sense buffer information is returned.
 190 */
 191      void                       getPointers( IOMemoryDescriptor         **desc,
 192                                              UInt32                     *transferCount,
 193                                              bool                       *isWrite,
 194                                              bool                       isSense = false );
 195 /*!
 196 @function setTimeout
 197 @abstract
 198 Sets the timeout for the command in milliseconds.
 199 @discussion
 200 The IOATAController class will abort a command which does not
 201 complete with in the time interval specified. The client should
 202 set the timeout parameter to zero if they want to suppress
 203 timing.
 204 @param timeout
 205 Command timeout in milliseconds.
 206 */
 207      void                       setTimeout( UInt32  timeoutmS );
 208
 209 /*!
 210 @function getTimeout
 211 @abstract
 212 Gets the timeout for the command in milliseconds.
 213 @discussion
 214 This function returns the command timeout previously set by setTimeout().
 215 @param timeout
 216 Command timeout in milliseconds.
 217 */
 218      UInt32                     getTimeout();
 219
 220 /*!
 221 @function setCallback
 222 @abstract
 223 Sets the callback routine to be invoked when the ATA/ATAPI Command completes.
 224 @param target
 225 Pointer to the object to be passed to the callback routine. This would usually
 226 be the client's (this) pointer.
 227 @param callback
 228 Pointer to the client's function to process the completed command
 229 @param refcon
 230 Pointer to the information required by the client's callback routine to process
 231 the completed command.
 232 */
 233      void                       setCallback( void *target = 0, CallbackFn callback = 0, void *refcon = 0 );
 234
 235 /*!
 236 @function execute
 237 @abstract
 238 Submits a ATA/ATAPI command to be executed.
 239 @discussion
 240 Once the execute() function is called, the client should not
 241 invoke any further functions on the ATA/ATAPI Command with the
 242 exception of abort().
 243
 244 The execute() function optionally returns sets a unique sequence
 245 number token for the command. If the client intends to use the abort()
 246 method they must retain this sequence number token.
 247 @param sequenceNumber
 248 Pointer to field (UInt32) to receive the sequence number assigned to the ATA/ATAPI
 249 Command.
 250 */
 251      bool                       execute( UInt32 *sequenceNumber = 0 );
 252
 253 /*!
 254 @function abort
 255 @abstract
 256 Aborts an executing ATA/ATAPI Command.
 257 @discussion
 258 The client may invoke the abort() method to force the completion of an
 259 executing ATA/ATAPI Command. The client must pass the sequence number
 260 provided when the execute() function was invoked.
 261
 262 Note: The abort function provides no status on whether or not a
 263 command has been successfully aborted. The client should wait for the
 264 command to actually complete to determine whether the abort completed
 265 successfully.
 266 @param sequenceNumber
 267 The client must pass the sequence number assigned to the command when
 268 the client called the execute() function.
 269 */
 270      void                       abort( UInt32 sequenceNumber );
 271
 272 /*!
 273 @function complete
 274 @abstract
 275 Indicates the IOATAController subclass (host adapter driver) has completed an ATA/ATAPI command.
 276 @discussion
 277 Once the complete() function is called, the controller
 278 subclass should make no further accesses to the IOATACommand
 279 being completed.
 280
 281 A IOATADevice client would not normally call this function.
 282 */
 283      void                       complete();
 284
 285 /*!
 286 @function getClientData
 287 @abstract
 288 Returns a pointer to the ATA/ATAPI Command's client data area.
 289 @discussion
 290 The client may allocate storage in the ATA/ATAPI Command for its own use.
 291 See IOATADevice::allocateCmd().
 292 */
 293      void                       *getClientData();
 294
 295 /*
 296 @function getCommandData
 297 @abstract
 298 Returns a pointer to the ATA Command's controller data area
 299 @discussion
 300 This area is allocated for use by the IOATAController subclass (host adapter
 301 driver). The client should not normally access this area.
 302 */
 303
 304           void                  *getCommandData();
 305
 306 /*!
 307 @function getSequenceNumber
 308 @abstract
 309 Returns the sequence number assigned to an executing command.
 310 @discussion
 311 The caller should check the sequence number for 0. This indicates that
 312 the command has completed or has not been processed to the point where
 313 a sequence number has been assigned.
 314 */
 315     UInt32                      getSequenceNumber();
 316
 317 /*!
 318 @function setTaskfile
 319 @abstract
 320 Sets the ATA taskfile register information and ATA/ATAPI protocol for the IOATACommand.
 321 @discussion
 322 See struct ATATaskfile additional information.
 323 @param ATATaskfile
 324 Pointer to an ATATaskfile structure.
 325 */
 326     void                        setTaskfile( ATATaskfile *taskfile );
 327
 328 /*!
 329 @function getTaskfile
 330 @abstract
 331 Sets the ATA taskfile register information and ATA/ATAPI protocol for the IOATACommand.
 332 @param ATATaskfile
 333 Pointer to an ATATaskfile structure.
 334 */
 335     void                        getTaskfile( ATATaskfile *taskfile );
 336
 337 /*!
 338 @function getProtocol
 339 @abstract
 340 Returns the protocol specified for the ATA/ATAPI Command.
 341 @discussion
 342 The protocol returned is specified by the client in the ATATaskfile structure. See setTaskfile().
 343 This function is normally used by subclasses of IOATAController to obtain information about the
 344 ATA command being executed.
 345 */
 346     ATAProtocol                 getProtocol();
 347
 348 /*!
 349 @function getResultMask
 350 @abstract
 351 Returns the resultMask specified for the ATA/ATAPI Command.
 352 @discussion
 353 The resultMask is specified by the client in the ATATaskfile structure and indicates the ATA taskfile registers
 354 to be returned when the ATA/ATAPI command completes. See setTaskfile(). This function is normally used by
 355 subclasses of IOATAController to obtain information about the ATA command being executed.
 356 */
 357     UInt32                      getResultMask();
 358
 359 /*!
 360 @function getFlags
 361 @abstract
 362 Returns the flags specified for the ATA/ATAPI Command.
 363 @discussion
 364 The flags are specified by the client in the ATATaskfile structure.  See setTaskfile(). This function is
 365 normally used by subclasses of IOATAController to obtain information about the ATA command being executed.
 366 */
 367     UInt32                      getFlags();
 368
 369 /*!
 370 @function setCDB
 371 @abstract
 372 Sets the CDB component of a ATA/ATAPI Command.
 373 @param ataCDB
 374 Pointer to a ATACDBInfo structure.
 375 */
 376      void                       setCDB( ATACDBInfo *ataCmd );
 377
 378 /*!
 379 @function getCDB
 380 @abstract
 381 Gets the CDB component of a ATA/ATAPI Command.
 382 @param ataCDB
 383 Pointer to an ATACDBInfo structure to receive the ATA/ATAPI Command's cdb information.
 384 */
 385
 386      void                       getCDB( ATACDBInfo *ataCmd );
 387
 388 /*!
 389 @function getResults
 390 @abstract
 391 Gets results from a completed ATA/ATAPI Command.
 392 @discussion
 393 The getResults() function returns the value of the returnCode field of the command results. If
 394 the client is only interested in a pass/fail indication for the command, the client
 395 can pass (ATAResults *)0 as a parameter.
 396 @param results
 397 Pointer to a ATAResults structure to receive the ATA/ATAPI Command's completion information.
 398 */
 399      IOReturn                   getResults( ATAResults *results );
 400
 401 /*!
 402 @function setResults
 403 @abstract
 404 Sets the results component of a ATA/ATAPI Command.
 405 @discussion
 406 The setResults() function is used by the IOATAController subclass (host
 407 adapter driver) return results for a ATA/ATAPI Command about to be completed.
 408 @param ataResults Pointer to a ATAResults structure containing
 409 completion information for the ATA/ATAPI Command.
 410
 411 Completion information is copied into the command, so the caller may
 412 release the ATAResults structure provided when this function returns.
 413 */
 414      void                       setResults( ATAResults *results );
 415
 416 /*!
 417 @function getDevice
 418 @abstract
 419 Returns the IOATADevice this command is targeted to.
 420 @param deviceType
 421 The caller should use value kIOATADeviceType.
 422 @discussion
 423 In some cases a IOATACommand is not associated with a specific ATA Unit. This
 424 would be the case for a ATA Bus Reset. In this case getDevice() returns 0.
 425 */
 426      IOATADevice        *getDevice( IOATAStandardDevice *deviceType );
 427
 428 /*!
 429 @function getUnit
 430 @abstract
 431 Returns the unit number for the IOATADevice this command is associated with.
 432 */
 433      ATAUnit                    getUnit();
 434
 435 /*!
 436 @function setQueueInfo
 437 @abstract
 438 Sets queuing information for the ATA/ATAPI Command.
 439 @discussion
 440 Each IOATADevice has two queues, a normal Q and a bypass Q. The treatment of the
 441 queues is essentially identical except that the bypass Q is given preference whenever
 442 it has commands available.
 443
 444 Usually, the client will use the normal Q for regular I/O commands and the bypass Q
 445 to send error recovery commands to the device.
 446 @param queueType
 447 Set to kATAQTypeNormalQ or kATAQTypeBypassQ to indicate which IOATADevice queue the
 448 ATA/ATAPI Command should be routed to.
 449 @param queuePosition
 450 Set to kATAQPositionTail or kATAQPositionHead to indicate whether the ATA/ATAPI Command should
 451 be added to the head to tail for the selected IOATADevice queue.
 452 */
 453     void                        setQueueInfo(  UInt32 forQueueType = kATAQTypeNormalQ, UInt32 forQueuePosition = kATAQPositionTail );
 454
 455 /*!
 456 @function getQueueInfo
 457 @abstract
 458 Gets queuing information for the ATA Command.
 459 @param queueType
 460 Pointer to a field (UInt32) to receive the queue type previously set for this ATA Command.
 461 @param queuePosition
 462 Pointer to a field (UInt32) to receive the queue position previously set for this ATA Command.
 463 */
 464     void                        getQueueInfo(  UInt32 *forQueueType, UInt32 *forQueuePosition = 0 );
 465
 466 /*!
 467 @function getCmdType
 468 @abstract
 469 Obtains the underlying 'intent' of an ATA/ATAPI Command.
 470 @discussion
 471 This function provides information on the intent of a ATA/ATAPI
 472 Command. For example, since Aborts, Request Sense and normal Execute commands are
 473 all sent to the executeCommand() function, invoking getCmdType()
 474 will indicate whether a Request Sense, Abort or Normal I/O request is
 475 being processed.
 476
 477 This information is not normally meaningful to IOATADevice clients.
 478 */
 479      UInt32                     getCmdType();
 480
 481 /*!
 482 @function getOriginalCmd
 483 @abstract
 484 Obtains a 'related' ATA/ATAPI Command.
 485 @discussion
 486 In cases where a ATA command is related to a previous command, this
 487 function will return the original command. For example, if a
 488 Request Sense command  (CmdType = kATACommandReqSense)is processed,
 489 then this function can be used to obtain the original command that
 490 caused the check condition. If an Abort command (CmdType =
 491 kATACommandAbort) then this function can be used to obtain the original
 492 command the abort was issued against.
 493
 494 It this information is not normally meaningful to IOATADevice clients.
 495 */
 496
 497      IOATAStandardCommand       *getOriginalCmd();
 498
 499 };
 500