2 * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
4 * @APPLE_LICENSE_HEADER_START@
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.
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
20 * @APPLE_LICENSE_HEADER_END@
24 @header IOATAStandardDriver_Reference.h
26 This header defines the IOATAStandardDriver class.
28 This class provides a standard ATA/ATAPI driver implementation.
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
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.
47 typedef struct ATAControllerInfo
{
49 UInt32 maxDevicesSupported
;
51 UInt32 devicePrivateDataSize
;
52 UInt32 commandPrivateDataSize
;
54 bool disableCancelCommands
;
60 class IOATAStandardDriver
: public IOATAStandardController
67 ATA taskfile register write function.
69 The controller driver must implement this function by writing the indicated
72 Register index values are defined by enum ATARegs. See IOATADevice_Reference.
74 Register value. For the ATA Data Register this is a 16-bit value. For other registers,
75 this is an 8-bit value.
77 virtual void writeATAReg( UInt32 regIndex
, UInt32 regValue
) = 0;
81 ATA taskfile register read function.
83 The controller driver must implement this function by reading the indicated ATA register and returning the register value as a (UInt32).
85 Register index values are defined by enum ATARegs. See IOATADevice_Reference.
87 virtual UInt32
readATAReg( UInt32 regIndex
) = 0;
90 @function selectTiming
91 Select ATA timing parameters.
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().
96 The unit number (0/1) of the IOATADevice the timing is to apply to.
98 The timing protocol to use the next time the device is selected. See enum ATATimingProtocol in
99 IOATADevice_Reference.
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.
105 virtual bool selectTiming( ATAUnit deviceNum
, ATATimingProtocol timingProtocol
) = 0;
108 @function calculateTiming
109 Convert ATA timing parameters to controller register settings.
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()
118 The unit number (0/1) of the IOATADevice the timing is to apply to.
120 A pointer to a ATATiming structure containing the parameters for the selected
123 virtual bool calculateTiming( UInt32 deviceNum
, ATATiming
*timing
) = 0;
127 Program the controller DMA hardware.
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
135 Pointer to an IOATACommand.
137 virtual bool programDma( IOATAStandardCommand
*cmd
);
141 Start the controller DMA hardware.
143 The controller driver should start the controller's DMA hardware with settings
144 corresponding to the last programDma() function call.
146 Pointer to an IOATACommand. This will normally be the same command that was previously
147 presented during the programDma() call.
149 virtual bool startDma( IOATAStandardCommand
*cmd
);
153 Stop the controller DMA hardware.
155 The controller driver should stop the controller's DMA hardware and return the
156 current transfer count.
158 Pointer to an IOATACommand. This will normally be the same command that was previously
159 presented during the programDma() call.
161 virtual bool stopDma( IOATAStandardCommand
*cmd
, UInt32
*transferCount
);
165 Reset the controller DMA hardware.
167 The controller driver should unconditionally stop the controller's DMA hardware.
169 virtual bool resetDma();
172 @function checkDmaActive
173 Return the state of the controller's DMA hardware.
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.
178 virtual bool checkDmaActive();
181 @function newDeviceSelected
182 Indicates that a new ATA unit is to be selected.
184 The controller driver should do any controller operation associated with selecting
187 virtual void newDeviceSelected( IOATAStandardDevice
*newDevice
);
190 @function interruptOccurred
191 Indicates that a controller interrupt occurred.
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().
198 virtual void interruptOccurred();
203 Driver configuration/initialization request.
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.
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.
220 virtual bool configure( IOService
*provider
, ATAControllerInfo
*controllerInfo
) = 0;