1/* 2 * Copyright (c) 1998-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 * IOATADevice.h 24 * 25 * This object implements a relay to an ATA Bus where a drive is attached. 26 */ 27 28 29#ifndef _IOATADEVICE_H 30#define _IOATADEVICE_H 31 32#include <IOKit/IOService.h> 33#include <IOKit/IOTypes.h> 34#include "IOATATypes.h" 35#include "IOATACommand.h" 36#include "IOATABusInfo.h" 37#include "IOATADevConfig.h" 38 39class IOATAController; 40 41 42/*! 43 @class IOATADevice 44 @abstract This object implements a relay to an ATA Bus where a drive is attached. 45 @discussion IOATADevice is the superclass which represents a particular device attached to a particular IOATAController (bus). IOATADevice is the provider for ATA mass-storage device drivers.IOATADevice is the factory for all IOATACommand objects and is responsible for creating and freeing IOATACommands. IOATAControllers will create an instance of IOATADevice for each device physically connected to the ata bus. IOATADevice is virtual and specific subclass should be implemented for particular types of IOATAController. In this manner, controller-specifc IOATACommands may be paired with the proper type of controller. 46*/ 47 48class IOATADevice : public IOService 49{ 50 OSDeclareDefaultStructors(IOATADevice); 51 52public: 53 54 // 55 /*!@function getUnitID 56 @abstract Determine whether this device is number 0 or 1 (ie, master/slave) 57 @result ataUnitID - 0 or 1. 58 */ 59 virtual ataUnitID getUnitID( void ); 60 61 // 62 /*!@function getDeviceType 63 @abstract Find out what kind of device this nub is (ata or atapi) 64 @result ataDeviceType as defined in IOATATypes.h 65 */ 66 virtual ataDeviceType getDeviceType( void ); 67 68 // 69 /*!@function provideBusInfo 70 @abstract Find out the bus capability so the client can choose the features to set and commands to run. 71 @param getInfo a pointer to a valid IOATABusInfo object. 72 @result kIOSuccess (0) and the getInfo object will be filled out by the bus controller with information about the bus. 73 */ 74 virtual IOReturn provideBusInfo( IOATABusInfo* getInfo); 75 76 // 77 /*!@function selectConfig 78 @abstract Tell the bus what speed to use for your device. 79 @param configRequest pointer to a valid and initialized IOATADevConfig object. 80 @result kIOSuccess (0) if the configuration was succesfully selected. 81 @discussion This should only be called once during a disk drivers start method before registering its availability, and must be called prior to issuing any data IO transactions. 82 */ 83 virtual IOReturn selectConfig( IOATADevConfig* configRequest); 84 85 // 86 /*!@function provideConfig 87 @abstract Find out what speed the bus has configured for this unit. 88 @param configRequest pointer to a valid IOATADevConfig object. 89 @result kIOSuccess (0) on successful completion and configRequest will contain the configuration information. 90 */ 91 virtual IOReturn provideConfig( IOATADevConfig* configRequest); 92 93 // Submit IO requests 94 /*! 95 @function executeCommand 96 @abstract Submit IO requests 97 @param command pointer to a valid IOATACommand with the command to be executed. 98 @result kIOSuccess (0) if the command was successfully queued in the controller. 99 */ 100 virtual IOReturn executeCommand(IOATACommand* command); 101 102 // create and destroy IOATACommands 103 /*! 104 @function allocCommand 105 @abstract create IOATACommands. Device drivers should allocate command objects only through this method. 106 @result null if allocation failed. Retain count is one. 107 */ 108 virtual IOATACommand* allocCommand( void ); 109 110 /*! 111 @function freeCommand 112 @abstract release a command object that is no longer needed. Do not free an object in use and do not release the object anymore times than you have retained it. 113 @param inCommand the command to be released. 114 */ 115 virtual void freeCommand( IOATACommand* inCommand); 116 117 // matching stuff for IOBSDInit and so on. 118 /*!@function matchPropertyTable 119 @abstract matching stuff for IOBSDInit and so on. 120 */ 121 virtual bool matchPropertyTable(OSDictionary * table); 122 123 /*!@function matchLocation 124 @abstract matching stuff for IOBSDInit and so on. 125 */ 126 virtual IOService* matchLocation(IOService * client); 127 128 /*!@function matchPropertyTable 129 @abstract matching stuff for IOBSDInit and so on. 130 */ 131 virtual bool matchPropertyTable(OSDictionary * table, SInt32 * score); 132 133 // called by controllers when they need to send a message to client drivers. 134 /*! 135 @function notifyEvent 136 @abstract called by controllers when they need to send a message to client (disk) drivers. 137 */ 138 virtual void notifyEvent( UInt32 event ); 139 140 141protected: 142 IOATAController* _provider; 143 ataUnitID _unitNumber; // 0 - master, 1 - slave, -1 = not Valid 144 ataDeviceType _deviceType; // ata, atapi, unknown 145protected: 146/*! @struct ExpansionData 147 @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future. 148 */ 149 struct ExpansionData { }; 150 151/*! @var reserved 152 Reserved for future use. (Internal use only) */ 153 ExpansionData *reserved; 154 155private: 156 OSMetaClassDeclareReservedUnused(IOATADevice, 0); 157 OSMetaClassDeclareReservedUnused(IOATADevice, 1); 158 OSMetaClassDeclareReservedUnused(IOATADevice, 2); 159 OSMetaClassDeclareReservedUnused(IOATADevice, 3); 160 OSMetaClassDeclareReservedUnused(IOATADevice, 4); 161 OSMetaClassDeclareReservedUnused(IOATADevice, 5); 162 OSMetaClassDeclareReservedUnused(IOATADevice, 6); 163 OSMetaClassDeclareReservedUnused(IOATADevice, 7); 164 OSMetaClassDeclareReservedUnused(IOATADevice, 8); 165 OSMetaClassDeclareReservedUnused(IOATADevice, 9); 166 OSMetaClassDeclareReservedUnused(IOATADevice, 10); 167 OSMetaClassDeclareReservedUnused(IOATADevice, 11); 168 OSMetaClassDeclareReservedUnused(IOATADevice, 12); 169 OSMetaClassDeclareReservedUnused(IOATADevice, 13); 170 OSMetaClassDeclareReservedUnused(IOATADevice, 14); 171 OSMetaClassDeclareReservedUnused(IOATADevice, 15); 172 OSMetaClassDeclareReservedUnused(IOATADevice, 16); 173 OSMetaClassDeclareReservedUnused(IOATADevice, 17); 174 OSMetaClassDeclareReservedUnused(IOATADevice, 18); 175 OSMetaClassDeclareReservedUnused(IOATADevice, 19); 176 OSMetaClassDeclareReservedUnused(IOATADevice, 20); 177}; 178 179#endif /* !_IOATABUSNUB_H */ 180