iokit/IOKit/ata/IOATADriver_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 IOATAStandardDriver_Reference.h
  25
  26 This header defines the IOATAStandardDriver class.
  27
  28 This class provides a standard ATA/ATAPI driver implementation.
  29
  30 In most cases ATA controller drivers should be implemented to this class since
  31 it relieves the controller driver writer from having to implement most of the ATA/ATAPI
  32 protocol.
  33 */
  34
  35 /*!
  36 @typedef ATAControllerInfo
  37 Parameter structure passed for configure() function.
  38 @field maxDevicesSupported
  39 Maximum ATA devices supported per bus. Normally set to (2).
  40 @field devicePrivateDataSize
  41 Size of per unit storage (in bytes) available to the controller driver. See getDeviceData.
  42 @field commandPrivateDataSize
  43 Size of per command storage (in bytes) available to the controller driver. See getCommandData.
  44 @field disableCancelCommands
  45 Normally set to false by the controller driver.
  46 */
  47 typedef struct ATAControllerInfo {
  48
  49     UInt32      maxDevicesSupported;
  50
  51     UInt32      devicePrivateDataSize;
  52     UInt32      commandPrivateDataSize;
  53
  54     bool        disableCancelCommands;
  55
  56     UInt32      reserved[64];
  57
  58 } ATAControllerInfo;
  59
  60 class IOATAStandardDriver : public IOATAStandardController
  61 {
  62 protected:
  63
  64 /*!
  65 @function writeATAReg
  66 @abstract
  67 ATA taskfile register write function.
  68 @discussion
  69 The controller driver must implement this function by writing the indicated
  70 ATA register.
  71 @param regIndex
  72 Register index values are defined by enum ATARegs. See IOATADevice_Reference.
  73 @param regValue
  74 Register value. For the ATA Data Register this is a 16-bit value. For other registers,
  75 this is an 8-bit value.
  76 */
  77     virtual void                writeATAReg( UInt32 regIndex, UInt32 regValue )         = 0;
  78
  79 /*!
  80 @function readATAReg
  81 ATA taskfile register read function.
  82 @discussion
  83 The controller driver must implement this function by reading the indicated ATA register and returning the register value as a (UInt32).
  84 @param regIndex
  85 Register index values are defined by enum ATARegs. See IOATADevice_Reference.
  86 */
  87     virtual UInt32              readATAReg(  UInt32 regIndex )                          = 0;
  88
  89 /*!
  90 @function selectTiming
  91 Select ATA timing parameters.
  92 @discussion
  93 The controller driver will be called at this entry point to indicate the timing to use
  94 the next time the indicated device is selected. See newDeviceSelected().
  95 @param deviceNum
  96 The unit number (0/1) of the IOATADevice the timing is to apply to.
  97 @param timingProtocol
  98 The timing protocol to use the next time the device is selected. See enum ATATimingProtocol in
  99 IOATADevice_Reference.
 100
 101 Note:The controller driver should have calculated and cached the necessary
 102 controller register settings when the timing parameters were presented by the
 103 calculateTiming() function.
 104 */
 105     virtual bool                selectTiming( ATAUnit deviceNum, ATATimingProtocol timingProtocol ) = 0;
 106
 107 /*!
 108 @function calculateTiming
 109 Convert ATA timing parameters to controller register settings.
 110 @discussion
 111 The controller driver is presented with proposed timings. If the controller driver
 112 can support the provided timing parameters, it should calculate the corresponding
 113 controller register settings and make them available for future lookup indexed
 114 by the timingProtocol field of the ATATiming structure. If the controller driver
 115 cannot support the indicated timing it should return false as the calculateTiming()
 116 result.
 117 @param deviceNum
 118 The unit number (0/1) of the IOATADevice the timing is to apply to.
 119 @param timing
 120 A pointer to a ATATiming structure containing the parameters for the selected
 121 timing.
 122 */
 123     virtual bool                calculateTiming( UInt32 deviceNum,  ATATiming *timing )                 = 0;
 124
 125 /*!
 126 @function programDMA
 127 Program the controller DMA hardware.
 128 @discussion
 129 The controller driver is presented with an IOATACommand and should use the
 130 IOATACommand's getPointers() function to obtain the command's IOMemoryDescriptor,
 131 transfer length and transfer direction. The controller driver then should
 132 use IOMemoryCursor functions to obtain the physical transfer list for
 133 the data buffer.
 134 @param cmd
 135 Pointer to an IOATACommand.
 136 */
 137     virtual bool                programDma( IOATAStandardCommand *cmd );
 138
 139 /*!
 140 @function startDma
 141 Start the controller DMA hardware.
 142 @discussion
 143 The controller driver should start the controller's DMA hardware with settings
 144 corresponding to the last programDma() function call.
 145 @param cmd
 146 Pointer to an IOATACommand. This will normally be the same command that was previously
 147 presented during the programDma() call.
 148 */
 149     virtual bool                startDma( IOATAStandardCommand *cmd );
 150
 151 /*!
 152 @function stopDma
 153 Stop the controller DMA hardware.
 154 @discussion
 155 The controller driver should stop the controller's DMA hardware and return the
 156 current transfer count.
 157 @param cmd
 158 Pointer to an IOATACommand. This will normally be the same command that was previously
 159 presented during the programDma() call.
 160 */
 161     virtual bool                stopDma( IOATAStandardCommand *cmd, UInt32 *transferCount );
 162
 163 /*!
 164 @function resetDma
 165 Reset the controller DMA hardware.
 166 @discussion
 167 The controller driver should unconditionally stop the controller's DMA hardware.
 168 */
 169     virtual bool                resetDma();
 170
 171 /*!
 172 @function checkDmaActive
 173 Return the state of the controller's DMA hardware.
 174 @discussion
 175 This function should return true if the controller's DMA channel is active, i.e. there
 176 is a non-zero transfer count and false if the transfer count has been met.
 177 */
 178     virtual bool                checkDmaActive();
 179
 180 /*!
 181 @function newDeviceSelected
 182 Indicates that a new ATA unit is to be selected.
 183 @discussion
 184 The controller driver should do any controller operation associated with selecting
 185 a new ata unit.
 186 */
 187     virtual void                newDeviceSelected( IOATAStandardDevice *newDevice );
 188
 189 /*!
 190 @function interruptOccurred
 191 Indicates that a controller interrupt occurred.
 192 @discussion
 193 This function will be called prior to the ATA standard driver begins processing
 194 the interrupt event. A controller which 'latches' interrupt events should clear
 195 the interrupting condition and then call the ATA standard driver interrupt handler
 196 by calling super::interruptOccurred().
 197 */
 198     virtual void                interruptOccurred();
 199
 200 /*!
 201 @function configure
 202 @abstract
 203 Driver configuration/initialization request.
 204 @discussion
 205 The configure() member function is the first call your subclass will
 206 receive. You should provide the information requested in the
 207 ATAControllerInfo structure and enable your hardware for operation.
 208 If your driver initialized successfully, you should return true, otherwise,
 209 your driver should return false.
 210 @param provider
 211 Pointer to an object (usually IOPCIDevice) which represents the bus of
 212 your device is attached to . Typically your driver will use functions
 213 supplied by this object to access PCI space on your hardware. See
 214 IOPCIDevice for a description of PCI services.
 215 @param controllerInfo
 216 Pointer to a ATAControllerInfo structure. Your driver should provide
 217 the information requested in this structure prior to returning from
 218 the configure() call.
 219 */
 220     virtual bool                configure( IOService *provider, ATAControllerInfo *controllerInfo ) = 0;
 221
 222 };
 223