1/* 2 * Copyright (c) 2000-2008 Apple 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#ifndef _IOATADEVCONFIG_H 25#define _IOATADEVCONFIG_H 26 27#include <libkern/c++/OSObject.h> 28#include <IOKit/IOTypes.h> 29#include "IOATATypes.h" 30#include "IOATABusInfo.h" 31 32 33/*! 34 @class IOATADevConfig 35 @abstract used for configuring and communicating the desired transfer modes of a device. 36 A disk driver would typically use this object in conjunction with the 512-bytes of identification 37 data from the drive and the IOATABusInfo object for the bus it is connected to. 38 This object will determine the best matching transfer speeds available. 39 the device driver will then send a series of Set Features commands to configure the drive 40 and this object to the bus through the IOATADevice nub in order to configure the optimum transfer mode. 41 The driver for the disk drive may choose to populate this object with whatever transfer mode 42 desired, in the event that a different mode is required. 43 @discussion usually use the initWithBestSelection to make a best mode match. 44 The Mode accessors use bit significance to indicate a selected mode or supported modes(s) 45 ie, 00000001b indicates Mode-0, 00000010b indicates mode 1, etc. 46 Selected mode is indicated by a single set bit. No bit set indicates no mode in that class is selected. 47 ie, a bus will support multiple possible modes, but will only have one mode selected at that time. 48 49*/ 50 51class IOATADevConfig : public OSObject { 52 53 OSDeclareDefaultStructors( IOATADevConfig ); 54 55 public: 56 57 /*!@function atadevconfig 58 @abstract static creator function. 59 */ 60 static IOATADevConfig* atadevconfig(void); 61 62 /*!@function initWithBestSelection 63 @abstract Handy initializer: pass the 512-byte result of the Identify Device or 64 Identify Packet Device in endian-order for your platform (byte-swapped on PPC) 65 and the IOATABusInfo object for the bus. The object will initialize all fields 66 and select the best transfer modes that match on bus and device. 67 If the return value was 0 (success or noErr), then a matching mode is supported. 68 Examine the PIO and UDMA/DMA fields and to generate the apropriate SET FEATURES 69 parameters for your drive and send this initialised object to the IOATAController 70 when requesting a speed configuration. 71 failure means no supported transfer modes matched between bus and device info. 72 73 @param identifyData 512 bytes of data obtained from the device via IDENTIFY DEVICE or IDENTIFY PACKET DEVICE command. 74 @param busInfo pointer to an IOATAbusInfo object obtained from a previous atanub->provideBusInfo() call. 75 @result kIOSuccess (0) when a matching transfer mode is available between the device and controller. 76 */ 77 IOReturn initWithBestSelection( const UInt16* identifyData, IOATABusInfo* busInfo); 78 79 // intitialize with the 512 byte data from an ATA device identify command 80 IOReturn assignFromData( const UInt16* identifyData ); 81 82 /*!@function setPacketConfig 83 @param packetConfig 84 @abstract For ATAPI devices, if the device asserts interrupt after the Packet Command when it is ready to accept the packet, set this value to true (mostly older devices). If the device accepts the packet only by asserting DRQ bit in status, then set this value false. Tells the bus controller whether to wait for packet acceptance or set pending interrupt. 85 */ 86 void setPacketConfig ( atapiConfig packetConfig); 87 88 /*!@function getPacketConfig 89 @result atapiConfig as defined in IOATATypes.h 90 */ 91 atapiConfig getPacketConfig( void ); 92 93 // The following Mode accessors use bit significance to indicate a selected mode or supported modes(s) 94 // ie, 00000001b indicates Mode-0, 00000010b indicates mode 1, etc. 95 // Selected mode is indicated by a single set bit. No bit set indicates no mode in that class is selected. 96 // ie, a bus will support multiple possible modes, but will only have one mode selected at that time. 97 98 /*!@function setPIOMode 99 @param inModeBitMap bit-significant map of PIO mode 100 */ 101 void setPIOMode( UInt8 inModeBitMap); // bit-significant map of PIO mode(s) 102 103 /*!@function getPIOMode 104 @result bit-significant map of PIO mode 105 */ 106 UInt8 getPIOMode( void ); 107 108 /*!@function setDMAMode 109 @param inModeBitMap bit-significant map of DMA mode 110 */ 111 void setDMAMode( UInt8 inModeBitMap ); // bit-significant map of DMA mode(s) 112 113 /*!@function getDMAMode 114 @result bit-significant map of DMA mode 115 */ 116 UInt8 getDMAMode( void ); 117 118 /*!@function setUltraMode 119 @param inModeBitMap bit-significant map of Ultra mode 120 */ 121 void setUltraMode( UInt8 inModeBitMap ); // bit-significant map of Ultra mode(s) 122 123 /*!@function getUltraMode 124 @result bit-significant map of Ultra mode 125 */ 126 UInt8 getUltraMode( void ); 127 128 // The following cycle time accessors report cycle times in nanoseconds. 129 // A device requesting a mode should also request a cycle time as reported in the device's identification page. 130 // A bus controller will configure the bus not to exceed (go faster than) the minimum time requested. 131 // When a bus controller reports a mode configuration, the cycle time indicates the busses contract not to go 132 // faster than. However an actual cycle time may be slower than the indicated time. 133 /*!@function setPIOCycleTime 134 @param inNS PIO cycle time in nanoseconds. 135 */ 136 void setPIOCycleTime( UInt16 inNS ); 137 138 /*!@function getPIOCycleTime 139 @result reported PIO CycleTime in nanoseconds. 140 */ 141 UInt16 getPIOCycleTime( void ); 142 143 /*!@function setDMACycleTime 144 @param inNS reported multiword DMA Cycle time in nanoseconds. 145 */ 146 void setDMACycleTime( UInt16 inNS ); 147 148 /*!@function getDMACycleTime 149 @result Reported multiword DMA cycle time in nanoseconds. 150 */ 151 UInt16 getDMACycleTime( void ); 152 153 // Ultra ATA defines cycle times a device must meet to comply with standards. 154 // No cycle time field is needed. 155 156 // convert bit-significant to numeric value 157 /*!@function bitSigToNumeric 158 @abstract converts a bit-significant field to a numerical value. Note that a bit field of 0x00 has no defined result. 159 @param binary the bit significant field. 160 @result the numerical value of the highest bit set in the field. 161 */ 162 virtual UInt8 bitSigToNumeric( UInt16 binary); 163 164 165 protected: 166 167 atapiConfig _atapiIRQForPacket; // enum for bits 5 and 6 of word zero of 168 // the identify packet device info data for PACKET devices ONLY. 169 // shift word-0 5-bits left, mask 0x03 and these enums apply. 170 // values are: 171 172 // kATAPIDRQSlow = 0x00 - wait up to 3MS for packet on DRQ 173 // kATAPIIRQPacket = 0x01, - device asserts IRQ for packet 174 // kATAPIDRQFast = 0x10, - packet on DRQ within 50us 175 // kATAPIUnknown = 0x11 - reserved as of ATA/ATAPI-5 176 177 178 179 180 UInt8 _ataPIOMode; /* <->: PIO Mode Timing class bit-significant */ 181 UInt16 _ataPIOCycleTime; /* <->: Cycle time in ns for PIO mode */ 182 UInt8 _ataMultiDMAMode; /* <->: Multiple Word DMA Timing Class bit-significant*/ 183 UInt16 _ataMultiCycleTime; /* <->: Cycle time in ns for Multiword DMA mode */ 184 UInt8 _ataUltraDMAMode; /* <->: Ultra DMA timing class bit-significant */ 185 186 IOReturn _AssignPIOData( const UInt16* identifyData); 187 IOReturn _AssignDMAData(const UInt16* identifyData); 188 IOReturn _AssignUltraData(const UInt16* identifyData); 189 UInt8 _MostSignificantBit( UInt8 inByte); 190 191 192 virtual bool init(); 193protected: 194/*! @struct ExpansionData 195 @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future. 196 */ 197 struct ExpansionData { }; 198 199/*! @var reserved 200 Reserved for future use. (Internal use only) */ 201 ExpansionData *reserved; 202 203private: 204 OSMetaClassDeclareReservedUnused(IOATADevConfig, 0); 205 OSMetaClassDeclareReservedUnused(IOATADevConfig, 1); 206 OSMetaClassDeclareReservedUnused(IOATADevConfig, 2); 207 OSMetaClassDeclareReservedUnused(IOATADevConfig, 3); 208 OSMetaClassDeclareReservedUnused(IOATADevConfig, 4); 209 OSMetaClassDeclareReservedUnused(IOATADevConfig, 5); 210 OSMetaClassDeclareReservedUnused(IOATADevConfig, 6); 211 OSMetaClassDeclareReservedUnused(IOATADevConfig, 7); 212 OSMetaClassDeclareReservedUnused(IOATADevConfig, 8); 213 OSMetaClassDeclareReservedUnused(IOATADevConfig, 9); 214 OSMetaClassDeclareReservedUnused(IOATADevConfig, 10); 215 OSMetaClassDeclareReservedUnused(IOATADevConfig, 11); 216 OSMetaClassDeclareReservedUnused(IOATADevConfig, 12); 217 OSMetaClassDeclareReservedUnused(IOATADevConfig, 13); 218 OSMetaClassDeclareReservedUnused(IOATADevConfig, 14); 219 OSMetaClassDeclareReservedUnused(IOATADevConfig, 15); 220 OSMetaClassDeclareReservedUnused(IOATADevConfig, 16); 221 OSMetaClassDeclareReservedUnused(IOATADevConfig, 17); 222 OSMetaClassDeclareReservedUnused(IOATADevConfig, 18); 223 OSMetaClassDeclareReservedUnused(IOATADevConfig, 19); 224 OSMetaClassDeclareReservedUnused(IOATADevConfig, 20); 225 226public: 227 228//some static utility functions to parse the identify data for feature support 229 230 static bool sDriveSupports48BitLBA( const UInt16* identifyData ); 231 static UInt32 sDriveExtendedLBASize( UInt32* lbaHi, UInt32* lbaLo, const UInt16* identifyData); // result returned is same as lbaLo. 232 233}; 234 235 236// header doc info goes here. I find putting it within the delcarations more confusing than putting it all in the bottom of the header. 237 238 239#endif /* !_IOATADEVCONFIG_H */ 240