iokit/IOKit/ata/IOATADevice_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 IOATADevice_Reference.h
  25
  26 This header defines the IOATADevice class.
  27
  28 The ATA/ATAPI framework creates instances of this class to
  29 represent each valid ATA/ATAPI device detected during
  30 ATA bus scanning. When an instance of this class is registered with
  31 IOKit, the instance will be presented to clients which
  32 'match' the IOATADevice class.
  33 */
  34
  35 /*!
  36 @enum ATADeviceType
  37 Defines ATA/ATAPI Device types.
  38 @constant kATADeviceNone
  39 Indicates no device installed.
  40 @constant kATADeviceATA
  41 Indicates ATA type device, i.e. packet protocols not supported.
  42 @constant kATADeviceATAPI
  43 Indicates ATAPI type device, i.e. packet protocols supported.
  44 */
  45 enum ATADeviceType {
  46
  47     kATADeviceNone,
  48     kATADeviceATA,
  49     kATADeviceATAPI,
  50
  51 };
  52
  53 /*!
  54 @enum ATATimingProtocol
  55 Defines supported transport timing. See getTimingsSupported(), selectTiming().
  56 @constant kATATimingPIO
  57 Indicates transport timing is for Programmed I/O.
  58 @constant kATATimingDMA
  59 Indicates transport timing is for DMA.
  60 @constant kATATimingDMA33
  61 Indicates transport timing is for Ultra DMA/33.
  62 @constant kATATimingDMA66
  63 Indicates transport timing is for Ultra DMA/66.
  64 @constant kATAMaxTimings
  65 Indicates number of timing protocols defined.
  66 */
  67 enum ATATimingProtocol
  68 {
  69     kATATimingPIO               = (1 << 0),
  70     kATATimingDMA               = (1 << 1),
  71     kATATimingUltraDMA33        = (1 << 2),
  72     kATATimingUltraDMA66        = (1 << 3),
  73     kATAMaxTimings              = 4,
  74
  75 };
  76
  77 /*!
  78 @enum ATAProtocol
  79 Defines supported transport protocols. See getProtocolsSupported().
  80 @constant kATAProtocolNone
  81 Indicates no transport protocol defined.
  82 @constant kATAProtocolSetRegs
  83 Indicates the transport driver should do a Set ATA Registers operation. For this
  84 protocol, the transport driver sets the requested taskfile registers as indicated
  85 in the ATATaskfile structure and then reads back the taskfile registers requested.
  86 The transport presumes the device will not generate an interrupt as a result
  87 of this operation.
  88 @constant kATAProtocolPIO
  89 Indicates the transport driver should do a Programmed I/O operation. For this
  90 protocol, the transport driver sets the requested taskfile registers, and transfers
  91 data to/from the IOATADevice via Programmed I/O operations. The IOATADevice client
  92 can control the direction/amount data transferred by using setPointers() function.
  93 The client can indicate a zero data transfer length to implement non-data transfer
  94 commands such as power-management and set features.
  95 @constant kATAProtocolDMA
  96 Indicates the transport driver should do a DMA I/O operation to the device. For this
  97 protocol, the transport driver sets the requested taskfile registers, and transfers
  98 data to/from the IOATADevice via DMA operations.
  99 @constant kATAProtocolDMAQueued
 100 Indicates the transport driver should do DMA Queued I/O operations. In this case,
 101 the driver will queue multiple I/O operations at the IOATADevice. Both the device
 102 and the transport driver must support this protocol.
 103 @constant kATAProtocolDMAQueueRelease
 104 Indicates the transport driver should do DMA Queued I/O operations with bus release.
 105 In this case, the driver will queue multiple I/O operations at the IOATADevice. In
 106 addition this protocol allows Overlap between both devices on the ATA Bus.
 107 @constant kATAProtocolATAPIPIO
 108 Indicates the transport driver should send an use ATAPI packet protocol and transfer
 109 data to/from the device via PIO cycles.
 110 @constant kATAProtocolATAPIDMA
 111 Indicates the transport driver should send an use ATAPI packet protocol and transfer
 112 data to/from the device via DMA cycles.
 113 */
 114 enum ATAProtocol {
 115
 116    kATAProtocolNone             = 0,
 117    kATAProtocolSetRegs          = (1 << 0),
 118    kATAProtocolPIO              = (1 << 1),
 119    kATAProtocolDMA              = (1 << 2),
 120    kATAProtocolDMAQueued        = (1 << 3),
 121    kATAProtocolDMAQueuedRelease = (1 << 4),
 122
 123    kATAProtocolATAPIPIO         = (1 << 16),
 124    kATAProtocolATAPIDMA         = (1 << 17),
 125
 126 };
 127
 128 /*!
 129 @typedef ATATiming
 130 @abstract
 131 Provides the low-level cycle times for the transport timing indicated.
 132 @discussion
 133 See enum ATATimingProtocols for a list of transport timing protocols.
 134 @field timingProtocol
 135 Indicates transport timing the structure refers to. See enum ATATimingProtocol
 136 for a list of transport timings.
 137 @field mode
 138 Indicates the ATA DMA/PIO mode supported. The mode is a number indicating preset
 139 timings for a particular set of timings as defined by the ATA specification.
 140 @field minDataAccess
 141 The minimum time (in nS) that IOW-/IOR- indicates that the data is valid for 16-bit
 142 data transfers. This field does not apply for Ultra/33 and Ultra/66 timings.
 143 @field minDataCycle
 144 The minimum time (in nS) that a full 16-bit data transfer will take, i.e. the time
 145 between consecutive assertions of IOW-/IOR-. For Ultra/33 and Ultra/66 timings
 146 this field indicates the average single cycle time.
 147 @field minCmdAccess
 148 The minimum time (in nS) that IOW-/IOR- indicates that the data is valid for 8-bit
 149 pio command transfers.
 150 @field minCmdCycle
 151 The minimum time (in nS) that a full 8-bit pio data transfer will take, i.e. the time
 152 between consecutive assertions of IOW-/IOR-.
 153 */
 154 typedef struct ATATiming {
 155
 156     ATATimingProtocol   timingProtocol;
 157
 158     UInt32              featureSetting;
 159
 160     UInt32              mode;
 161     UInt32              minDataAccess;
 162     UInt32              minDataCycle;
 163     UInt32              minCmdAccess;
 164     UInt32              minCmdCycle;
 165     UInt32              reserved_3[9];
 166
 167 } ATATiming;
 168
 169 class IOATAStandardDevice : public IOATADevice
 170 {
 171 public:
 172
 173 /*!
 174 @function allocCommand
 175 @abstract
 176 Allocates an IOATACommand object for this device.
 177 @discussion
 178 The client uses the allocCommand() member function to allocate IOATACommand(s)
 179 for an IOATADevice. The client then uses the member functions of
 180 the IOATACommand to initialize it and send it to the device. A completed IOATACommand
 181 may be reused for subsequent I/O requests or returned to the ATA/ATAPI Family.
 182 @param deviceType
 183 Always specify kIOATADevice.
 184 @param clientDataSize
 185 The client may indicate the size of a per-command data area for its own
 186 use.
 187 */
 188      IOATACommand       *allocCommand( IOATADevice *deviceType, UInt32 clientDataSize = 0 );
 189
 190 /*!
 191 @function getUnit
 192 @abstract
 193 Returns the ATA unit number corresponding to this device.
 194 */
 195     ATAUnit                     getUnit();
 196
 197 /*!
 198 @function getDeviceType
 199 @abstract
 200 Returns the type of the corresponding ATA/ATAPI device.
 201 @discussion
 202 See enum ATADeviceType for return values for this function.
 203 */
 204     ATADeviceType               getDeviceType();
 205
 206 /*!
 207 @function getIdentifyData
 208 @abstract
 209 Returns the ATA/ATAPI Identify data for the IOATADevice
 210 @discussion
 211 Identify data is from the results of the last ATA bus probe.
 212 @param identifyBuffer
 213 Pointer to a 512-byte data buffer to receive the ATA/ATAPI Identify data.
 214 */
 215     bool                        getIdentifyData( ATAIdentify *identifyBuffer );
 216
 217 /*!
 218 @function getInquiryData
 219 @abstract
 220 Returns ATAPI Inquiry data for the IOATADevice.
 221 @discussion
 222 Inquiry data returned is from the results of the last ATA bus probe.
 223 @param inquiryBufSize
 224 Size of the buffer supplied.
 225 @param inquiryBuffer
 226 Pointer to a buffer to receive the Inquiry data.
 227 */
 228     bool                        getInquiryData( UInt32 inquiryBufSize, ATAPIInquiry *inquiryBuffer );
 229
 230 /*!
 231 @function getDeviceCapacity
 232 @abstract
 233 Returns the block count and block size of the ATA/ATAPI device.
 234 @discussion
 235 This function returns the capacity as returned by the ATA Identify command for ATA devices,
 236 and the Read Device Capacity for ATAPI devices. The client should use caution in interpreting
 237 the results of this function since the results are based on the last ATA bus scan.
 238 @param blockMax
 239 Pointer to a (UInt32) to receive the maximum addressable block on the device. Note: The device
 240 block count is one greater than the maximum addressable block number.
 241 @param blockSize
 242 Pointer to a (UInt32) to receive the block size of the device in bytes.
 243 */
 244     bool                        getDeviceCapacity( UInt32 *blockMax, UInt32 *blockSize );
 245
 246
 247 /*!
 248 @function getProtocolSupported
 249 @abstract
 250 Returns a bit mask of transport protocols this IOATADevice supports.
 251 @discussion
 252 There is no guarantee that a particular device/driver combination will support
 253 all transport protocols defined. The IOATADevice client must use this function
 254 to determine which ATAProtocol values are valid for this device.
 255 @param protocolsSupported
 256 Pointer to a (UInt32) to receive a bit mask of transport protocols supported. See enum
 257 ATAProtocol of a list of transport protocols.
 258 */
 259     bool                        getProtocolsSupported( ATAProtocol *protocolsSupported );
 260
 261 /*!
 262 @function getTimingsSupported
 263 @abstract
 264 Returns a bit mask of transport timings this IOATADevice supports
 265 @discussion
 266 There is no guarantee that a particular device/driver combination will support
 267 all transport timings defined. The IOATADevice client must use this function
 268 to determine which ATATimingProtocol values are valid for this device.
 269 @param protocolsSupported
 270 Pointer to a (UInt32) to receive a bit mask of transport timings supported. See enum
 271 ATATimingProtocol of a list of transport timings.
 272 */
 273     bool                        getTimingsSupported( ATATimingProtocol *timingsSupported );
 274
 275 /*!
 276 @function getTimingSelected
 277 @abstract
 278 Returns the last transport timing selected for the device
 279 @param timingProtocol
 280 Pointer to a (UInt32) to receive the current timing protocol selected. See enum ATATimingProtocol
 281 for a list of transport timing protocols.
 282 */
 283     bool                        getTimingSelected( ATATimingProtocol *timingProtocol );
 284
 285 /*!
 286 @function getTiming
 287 @abstract
 288 Returns the parameters for the transport timing indicated.
 289 @discussion
 290 If the transport/device combination does not support the transport timing
 291 indicated, then this function will return false. See getTimingsSupported()
 292 to obtain a bit mask of supported timings.
 293 @param timingProtocol
 294 Pointer to a (UInt32) which the client has set to the timing protocol whose parameters are
 295 to be obtained.
 296 @param timing
 297 Pointer to a (struct ATATiming) to receive the parameters (cycle timings) for the requested
 298 timing.
 299 */
 300     bool                        getTiming( ATATimingProtocol *timingProtocol, ATATiming *timing );
 301
 302 /*!
 303 @function getATAPIPktInt
 304 @abstract
 305 Returns whether the an ATAPI device will generate an Interrupt prior to signal it is ready
 306 to request a command packet.
 307 @discussion
 308 A return value of (true) will indicates the device will generate a packet transfer interrupt.
 309 This function would not normally need to be used by the IOATADevice client. It is for use
 310 by the transport driver.
 311 */
 312     bool                        getATAPIPktInt();
 313
 314 /*!
 315 @function selectTiming
 316 @abstract
 317 Selects the transport timing to be used for this IOATADevice.
 318 @discussion
 319 The IOATADevice client must issue the selectTiming() function when initializing an IOATADevice and
 320 after an ATA Bus Reset event.
 321 @param timingProtocol
 322 The transport timing to be selected for the device. See getTimingsSupported() for transport timings
 323 supported by the transport/device combination.
 324 @param fNotifyMsg
 325 If fNotifyMsg is set to false, selectTiming() operates a synchronous call, i.e. it blocks the
 326 client until it completes. If the client needs to call this function during an event such as
 327 an ATA Bus Reset, it must use the asynchronous version of this function by setting fNotifyMsg
 328 to true. In this case the client will be notified via a message when this function has
 329 completed.
 330 */
 331     bool                        selectTiming( ATATimingProtocol timingProtocol, bool fNotifyMsg = false );
 332
 333 /*!
 334 @function holdQueue
 335 @abstract
 336 Suspends sending additional IOATACommand to this device.
 337 @discussion
 338 holdQueue() may only be called from the IOATADevice workloop. The client
 339 is guaranteed to be running in this context during a message() notification.
 340
 341 holdQueue() has no effect on commands already passed to the host adapter. One
 342 or more commands may complete after the queue is held. See notifyIdle()
 343 @param queueType
 344 Perform action on the indicated queue. See enum ATAQueueType in IOATACommand.
 345 */
 346     void                        holdQueue( UInt32 queueType );
 347
 348 /*!
 349 @function releaseQueue
 350 @abstract
 351 Resumes sending IOATACommands to the IOATADevice.
 352 @discussion
 353 If the device queue was not held, releaseQueue() has no effect.
 354
 355 releaseQueue() may only be called from the IOATADevice workloop. This is guaranteed
 356 to be the case after a IOATACommand completion of after a message() notification.
 357 @param queueType
 358 Perform action on the indicated queue. See enum ATAQueueType in IOATACommand.
 359 */
 360     void                        releaseQueue( UInt32 queueType );
 361
 362 /*!
 363 @function flushQueue
 364 @abstract
 365 Returns any commands on the IOATADevice's pending work queue.
 366 @discussion
 367 flushQueue() may only be called from the IOATADevice workloop. This is
 368 guaranteed to be the case after a IOATACommand completion of after a
 369 message() notification.
 370
 371 All pending command are completed prior to flushQueue() returning to the caller.
 372
 373 flushQueue() has no effect on commands already passed to the host adapter. One
 374 or more commands may complete after the queue is flushed. See notifyIdle().
 375 @param queueType
 376 Perform action on the indicated queue. See enum ATAQueueType in IOATACommand.
 377 @param rc
 378 The return code of any flushed commands is set to (rc).
 379 */
 380     void                        flushQueue( UInt32 queueType, IOReturn rc );
 381
 382 /*!
 383 @function notifyIdle
 384 @abstract
 385 Notifies the client when all active commands on an ATA device have completed.
 386 @discussion
 387 notifyIdle() may only be called from the IOATADevice workloop. This is guaranteed
 388 to be the case after a IOATACommand completion of after a message() notification.
 389
 390 Only one notifyIdle() call may be active. Any outstanding notifyIdle() calls may
 391 be cancelled by calling notifyIdle() with no parameters.
 392 @param target
 393 Object to receive the notification. Normally the client's (this) pointer.
 394 @param callback
 395 Pointer to a callback routine of type CallbackFn.
 396 @param refcon
 397 Pointer to client's private data.
 398 */
 399     void                        notifyIdle(  void *target = 0, CallbackFn callback = 0, void *refcon = 0 );
 400
 401 /*!
 402 @function getWorkLoop
 403 @abstract
 404 Returns the IOWorkLoop object that services this IOATADevice.
 405 */
 406 IOWorkloop *getWorkLoop();
 407
 408 };