iokit/IOKit/ata/IOATAController_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 /*!
  25 @header IOATAController_Reference.h
  26
  27 This header defines the IOATAController class.
  28
  29 IOATAController provides the superclass for the ATA Family. In most
  30 cases, actual controller drivers should be implemented to IOATAStandardDriver
  31 which converts the relatively high-level commands produced by this class
  32 to low-level ATA register commands.
  33
  34 This class may be useful in cases where the actual ATA device is connected
  35 by some intermediate bus and it would be more efficient for family for that
  36 bus to deal with high-level commands rather than low-level ATA register I/O.
  37 */
  38
  39 class IOATAStandardController : public IOService
  40 {
  41
  42 public:
  43
  44 /*!
  45 @function reset
  46 @abstract
  47 Perform an ATA bus reset.
  48 @discussion
  49 This function requests the IOATAController class to perform an ATA Bus reset.
  50
  51 The IOATAController class will convert this request into a reset command and
  52 will call the resetCommand() function.
  53
  54 The reset() function is synchronous, i.e. it will wait for the reset to complete.
  55 */
  56     IOReturn                    reset();
  57
  58 protected:
  59
  60 /*!
  61 @function enableCommands
  62 @abstract
  63 Resume sending I/O commands to your driver.
  64 @discussion
  65 Resumes sending I/O commands to your driver that were previously suspended
  66 by calling disableCommands().
  67 */
  68     void                        enableCommands();
  69
  70 /*!
  71 @function disableCommands
  72 @abstract
  73 Suspend sending I/O commands to your driver.
  74 @discussion
  75 In cases where your executeCommand() member function cannot accept
  76 commands, you may disable further calls by invoking disableCommands().
  77 Use enableCommands() to resume receiving commands.
  78
  79 Note: The resetCommand() and cancelCommands() entry points are not
  80 affected by the use of this function.
  81
  82 Note: The default timeout for disableCommands() is 5s. If this timeout
  83 is exceeded the IOATAController class will call your driver's
  84 disableTimeoutOccurred() function. The default action of this function
  85 is to issue a ATA Bus Reset by calling your driver's resetCommand()
  86 function.
  87 @param timeoutmS
  88 Your driver may override the default timeout
  89 by specifying a timeout value in milliseconds.
  90 */
  91     void                        disableCommands( UInt32 disableTimeoutmS );
  92
  93 /*!
  94 @function rescheduleCommand
  95 @abstract
  96 Return a IOATACommand for rescheduling.
  97 @discussion
  98 If your subclass function cannot start processing an otherwise
  99 acceptable IOATACommand, you may have the IOATACommand rescheduled by
 100 calling rescheduleCommand(). A IOATACommand passed to this function
 101 should be treated as 'complete', i.e. you should make no further
 102 accesses to it.
 103
 104 Note: If you cannot process further commands, you should call the
 105 disableCommands() function to prevent receiving additional commands
 106 until you are ready to accept them.
 107 @param ataCommand
 108 Pointer to IOATACommand your driver needs to reschedule.
 109 */
 110     void                        rescheduleCommand( IOATAStandardCommand *forATACmd );
 111
 112     void                        resetStarted();
 113     void                        resetOccurred();
 114
 115
 116 /*!
 117 @function findCommandWithNexus
 118 @abstract
 119 Locate an active IOATACommand using device/tag values.
 120 @discussion
 121 Your subclass can use this function to search for an active
 122 IOATACommand by providing the device/tag values for the command. In
 123 the case of a non-tagged command the second parameter must either be
 124 omitted or set to -1.
 125
 126 An unsuccessful search will return 0.
 127 @param forDevice
 128 Pointer to an IOATADevice.
 129 wish to search for.
 130 @param tagValue
 131 Optional tag value you wish to search for.
 132 */
 133     IOATAStandardCommand        *findCommandWithNexus( IOATAStandardDevice *forDevice, UInt32 tagValue = (UInt32)-1 );
 134
 135 /*!
 136 @function getDeviceData
 137 @abstract
 138 Obtains a pointer to per-device data allocated by IOATAController.
 139 @discussion
 140 This function returns a pointer to per-device workarea allocated for
 141 your driver's use. The size of this area must be specified in the
 142 during the configure() function. See struct ATAControllerInfo,
 143 field devicePrivateDataSize.
 144 @param forUnit
 145 The unit number of the ata device.
 146 */
 147     void                        *getDeviceData( ATAUnit forUnit );
 148
 149 /*!
 150 @function getWorkLoop
 151 @abstract
 152 Returns/provides the IOWorkLoop object that services your driver.
 153 @discussion
 154 If your driver wishes to create its own workloop, you should implement this
 155 function and return the IOWorkLoop for your subclass. Otherwise, if you
 156 return 0, the IOATAController class will create a workloop for your driver.
 157 */
 158     virtual IOWorkLoop          *getWorkLoop() const;
 159
 160 /*!
 161 @function getCommandCount
 162 @abstract
 163 Returns the current active command count for your driver.
 164 @discussion
 165 This indicates the number of executeCommands that have been sent to your
 166 driver and have not been completed.
 167 */
 168     UInt32                      getCommandCount();
 169
 170 /*!
 171 @function setCommandLimit
 172 @abstract
 173 Modifies command limit indicated for the IOATADevice device.
 174 @discussion
 175 If the device currently has more than commands outstanding than the new command limit,
 176 additional commands will not be sent to the device. If the command limit is increased,
 177 the additional commands will be sent until the command limit is met.
 178 @param device
 179 Pointer to an IOATADevice.
 180 @param commandLimit
 181 New limit on outstanding executeCommands.
 182 */
 183     void                        setCommandLimit( IOATAStandardDevice *device, UInt32 commandLimit );
 184
 185 /*!
 186 @function suspendDevice
 187 @abstract
 188 Stops sending executeCommands to the indicated device.
 189 @discussion
 190 This function causes the IOATAController class to stop sending executeCommands to the
 191 indicated device.
 192 @param forATADevice
 193 Pointer to an IOATADevice for which executeCommand delivery is to be suspended.
 194 */
 195     void                        suspendDevice( IOATAStandardDevice *forATADevice );
 196
 197 /*!
 198 @function resumeDevice
 199 @abstract
 200 Resumes sending executeCommands to the indicated device.
 201 @discussion
 202 This function causes the IOATAController class to resume sending executeCommands to an
 203 IOATADevice that was previously suspended. If the IOATADevice was not previously
 204 suspended, then this call has no effect.
 205 @param forATADevice
 206 Pointer to an IOATADevice for which executeCommand delivery is to be resumed.
 207 */
 208     void                        resumeDevice( IOATAStandardDevice *forATADevice );
 209
 210 /*!
 211 @function selectDevice
 212 @abstract
 213 Returns a pointer to the IOATADevice device that was suspended the for the
 214 longest amount of time.
 215 @discussion
 216 This function returns a 'hint' as which device to resume to implement fairness
 217 in servicing IOATADevice contending for access to the ATA bus.
 218 */
 219     IOATAStandardDevice         *selectDevice();
 220
 221 protected:
 222
 223 /*!
 224 @function configure
 225 @abstract
 226 Driver configuration/initialization request.
 227 @discussion
 228 The configure() member function is the first call your subclass will
 229 receive. You should provide the information requested in the
 230 ATAControllerInfo structure and enable your hardware for operation.
 231 If your driver initialized successfully, you should return true, otherwise,
 232 your driver should return false.
 233 @param provider
 234 Pointer to an object (usually IOPCIDevice) which represents the bus of
 235 your device is attached to . Typically your driver will use functions
 236 supplied by this object to access PCI space on your hardware. See
 237 IOPCIDevice for a description of PCI services.
 238 @param controllerInfo
 239 Pointer to a ATAControllerInfo structure. Your driver should provide
 240 the information requested in this structure prior to returning from
 241 the configure() call.
 242 */
 243     virtual bool                configure( IOService *provider, ATAControllerInfo *controllerInfo ) = 0;
 244
 245 /*!
 246 @function getProtocolSupported
 247 @abstract
 248 Returns a bit mask of transport protocols this IOATADevice supports.
 249 @discussion
 250 The subclass of IOATAController must return a bit-mask of transport protocols supported.
 251 @param protocolsSupported
 252 Pointer to a (UInt32) to receive a bit mask of transport protocols supported. See enum
 253 ATAProtocol of a list of transport protocols.
 254 */
 255     virtual bool                getProtocolsSupported( ATAProtocol *protocolsSupported ) = 0;
 256
 257 /*!
 258 @function executeCommand
 259 @abstract
 260 Execute an IOATACommand.
 261 @discussion
 262 The executeCommand() function is called for all 'routine' I/O requests.
 263 The driver is passed a pointer to an
 264 IOATACommand object. The driver obtains information about the I/O
 265 request by using function calls provided by the IOATACommand
 266 class.
 267 @param ataCommand
 268 Pointer to an IOATACommand. See IOATACommand_Reference for more information.
 269 */
 270     virtual void                executeCommand( IOATAStandardCommand *forATACmd ) = 0;
 271
 272 /*!
 273 @function cancelCommand
 274 @abstract
 275 Cancels a IOATACommand previously submitted.
 276 @discussion
 277 The cancelCommand() function is called to inform your subclass to force
 278 completion of an ATA command.
 279
 280 Your subclass should call the getOriginalCmd() to determine the command
 281 to complete.
 282
 283 After calling complete() on the original command, you should complete
 284 the IOATACommand passed to the cancelCommand() function
 285
 286 Note: When a cancelCommand is issued, your subclass may presume that any
 287 activity to remove an active command has already occurred.
 288 @param ataCommand
 289 Pointer to a IOATACommand. See IOATACommand for more information.
 290 */
 291     virtual void                cancelCommand(  IOATAStandardCommand *forATACmd ) = 0;
 292
 293 /*!
 294 @function resetCommand
 295 @abstract
 296 Request the IOATAController subclass issue an ATA Bus reset.
 297 @discussion
 298 The resetCommand() function indicates you should do an ATA Bus Reset.
 299 After issuing the reset you should complete to IOATACommand passed.
 300
 301 Note: After you report the IOATACommand Reset complete, you will
 302 receive cancelCommand() requests for all outstanding commands.
 303 @param ataCommand
 304 Pointer to a IOATACommand. See IOATACommand for more information.
 305 */
 306     virtual void                resetCommand(   IOATAStandardCommand *forATACmd ) = 0;
 307
 308 /*!
 309 @function abortCommand
 310 @abstract
 311 Requests the IOATAController subclass abort a currently executing command.
 312
 313 Note: In most cases ATA does not provide semantics to cleanly abort an executing
 314 command. In these cases, the subclass may reset the ATA bus to implement this
 315 function.
 316 @param forATACmd
 317 Pointer to an active IOATACommand to be aborted.
 318 */
 319     virtual void                abortCommand(   IOATAStandardCommand *forATACmd ) = 0;
 320
 321 /*!
 322 @function calculateTiming
 323 Convert ATA timing parameters to controller register settings.
 324 @discussion
 325 The IOATAController subclass is presented with proposed timings. If the subclass
 326 can support the provided timing parameters, it should calculate the corresponding
 327 controller register settings and make them available for future lookup indexed
 328 by the timingProtocol field of the ATATiming structure. If the controller driver
 329 cannot support the indicated timing it should return false as the calculateTiming()
 330 result.
 331 @param deviceNum
 332 The unit number (0/1) of the IOATADevice the timing is to apply to.
 333 @param timing
 334 A pointer to a ATATiming structure containing the parameters for the selected
 335 timing.
 336 */
 337     virtual bool                calculateTiming( UInt32 deviceNum,  ATATiming *timing ) = 0;
 338
 339
 340 /*!
 341 @function allocateDevice
 342 @abstract
 343 The IOATAController class informs its subclass of allocation of an ATA device.
 344 @discussion
 345 The IOATAController subclass will be called at its allocateDevice() function when an
 346 ATA device is about to be probed. The subclass should initialize its per-device data at
 347 this time. If the subclass wishes to prevent probing of this device, it should return false
 348 as the result of this function call.
 349
 350 Note: This is an optional function. Your driver is not required to implement it.
 351 @param unit
 352 The ATA unit number of the device about to be allocated.
 353 */
 354     virtual bool                allocateDevice( ATAUnit unit );
 355
 356 /*!
 357 @function deallocateDevice
 358 @abstract
 359 The IOATAController class informs its subclass of deallocation of an ATA device.
 360 @discussion
 361 The IOATAController subclass will be called at its deallocateDevice() function when
 362 an ATA device is about to be deallocated. The subclass must insure that there will
 363 be no further access to the per-device data allocated to this device.
 364
 365 Note: This is an optional function. Your driver is not required to implement it.
 366 @param unit
 367 The ATA unit number of the device about to be deallocated.
 368 */
 369     virtual void                deallocateDevice( ATAUnit unit );
 370
 371 /*!
 372 @function disableTimeoutOccurred
 373 @abstract
 374 Indicates the IOATAController subclass has suspended commands too long.
 375 @discussion
 376 The IOATAController class will timeout disableCommand() requests
 377 to preclude the possibility of a hung ATA bus. If a timeout occurs,
 378 then disableTimeoutOccurred() will be called. The default action of this
 379 routine is to do a ATA Bus Reset by calling resetCommand(). Your
 380 subclass may choose to modify the default behavior of this routine to do
 381 additional adapter specific error recovery.
 382 */
 383     virtual void                disableTimeoutOccurred();
 384
 385 /*!
 386 @function enableControllerInterrupts
 387 @abstract
 388 Indicates the IOATAController subclass should enables its controller interrupt.
 389 @discussion
 390 The default implementation of this function enables all interrupt sources
 391 associated with the current workloop. If the subclass needs more precise
 392 control of its interrupt sources it should replace the implementation of
 393 this function with its own.
 394 */
 395     virtual void                enableControllerInterrupts();
 396
 397 /*!
 398 @function disableControllerInterrupts
 399 @abstract
 400 Indicates the IOATAController subclass should disable its controller interrupt.
 401 @discussion
 402 The default implementation of this function disables all interrupt sources
 403 associated with the current workloop. If the subclass needs more precise
 404 control of its interrupt sources it should replace the implementation of
 405 this function with its own.
 406 */
 407     virtual void                disableControllerInterrupts();
 408
 409 };
 410