| 1 | /*␊ |
| 2 | * Copyright (c) 2006 Apple Computer, Inc. All rights reserved.␊ |
| 3 | *␊ |
| 4 | * @APPLE_LICENSE_HEADER_START@␊ |
| 5 | * ␊ |
| 6 | * This file contains Original Code and/or Modifications of Original Code␊ |
| 7 | * as defined in and that are subject to the Apple Public Source License␊ |
| 8 | * Version 2.0 (the 'License'). You may not use this file except in␊ |
| 9 | * compliance with the License. Please obtain a copy of the License at␊ |
| 10 | * http://www.opensource.apple.com/apsl/ and read it before using this␊ |
| 11 | * file.␊ |
| 12 | * ␊ |
| 13 | * The Original Code and all software distributed under the License are␊ |
| 14 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER␊ |
| 15 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,␊ |
| 16 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,␊ |
| 17 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.␊ |
| 18 | * Please see the License for the specific language governing rights and␊ |
| 19 | * limitations under the License.␊ |
| 20 | * ␊ |
| 21 | * @APPLE_LICENSE_HEADER_END@␊ |
| 22 | */␊ |
| 23 | ␊ |
| 24 | #ifndef __OPEN_SOURCE__␊ |
| 25 | /*␊ |
| 26 | *␊ |
| 27 | *␉$Log: IOUSBHubDevice.h,v $␊ |
| 28 | *␉Revision 1.11 2009/09/12 03:42:16 rhoads␊ |
| 29 | *␉merge in the changes for the 390.3.4b QL␊ |
| 30 | *␊ |
| 31 | *␉Revision 1.10.52.1 2009/09/10 18:50:52 nano␊ |
| 32 | *␉<rdar://problem/7134800> Task: Extra Current support for Ibex Peak RMHs -- look for a property that tells us to ask our USB plane parent for the extra current. This will allow the RMH to pass on the request to it's parent.␊ |
| 33 | *␉␊ |
| 34 | *␉Revision 1.10 2009/05/07 19:43:09 nano␊ |
| 35 | *␉Move our SnowLeopard branch to TOT␊ |
| 36 | *␉␊ |
| 37 | *␉Revision 1.6.102.3 2008/06/16 22:02:16 nano␊ |
| 38 | *␉Bring in changes from Foxound 320.2.19␊ |
| 39 | *␉␊ |
| 40 | ␊ |
| 41 | *␉Revision 1.6.102.2 2008/04/22 22:38:01 nano␊ |
| 42 | *␉Bring in changes from Foxhound-320.2.9␊ |
| 43 | *␉␊ |
| 44 | *␉Revision 1.8.62.2 2008/06/06 21:08:44 nano␊ |
| 45 | *␉Enable dynamic allocation of power for M89, so we don't reserve it if there isn't a high power device attached␊ |
| 46 | *␉␊ |
| 47 | *␉Revision 1.8.62.1 2008/06/06 04:14:32 nano␊ |
| 48 | *␉Fix SleepCurrent allocation so it will work with hub devices and root hub devices as well as consolidating it across all controllers␊ |
| 49 | *␉␊ |
| 50 | *␉Revision 1.8 2008/04/17 16:56:57 nano␊ |
| 51 | *␉Bring in branches for rdar://5867990 & rdar://5768343␊ |
| 52 | *␉␊ |
| 53 | *␉Revision 1.7.4.1 2008/04/17 15:54:07 nano␊ |
| 54 | *␉Merged PR-5768343 into this branch and fixed a couple of issues␊ |
| 55 | *␉␊ |
| 56 | *␉Revision 1.7.2.1 2008/04/16 00:48:49 ferg␊ |
| 57 | *␉Bug #: 5768343␊ |
| 58 | *␉Add support for hubs with high-power downstream port capability. This is␊ |
| 59 | *␉controlled by the properties "AAPL,current-available" and "AAPL,current-extra".␊ |
| 60 | *␉␊ |
| 61 | *␉Revision 1.7 2008/04/14 16:08:38 nano␊ |
| 62 | *␉Add new APIs for high power and for GetDeviceInformation.␊ |
| 63 | *␉␊ |
| 64 | *␉Revision 1.6.144.1 2008/04/11 22:25:44 nano␊ |
| 65 | *␉Initial work on new user-client APIs and new IOUSBDevice APIs to return port state information and manage extra power requests, as well as groundwork for calling the policy maker directly from the IOUSBDevice␊ |
| 66 | *␉␊ |
| 67 | *␉Revision 1.6 2007/08/01 16:10:18 rhoads␊ |
| 68 | *␉roll in extra power changes␊ |
| 69 | *␉␊ |
| 70 | *␉Revision 1.5.118.1 2007/07/27 16:49:10 rhoads␊ |
| 71 | *␉merge the extra current stuff into Leopard, and add extra sleep current for self powered hubs␊ |
| 72 | *␉␊ |
| 73 | *␉Revision 1.5 2007/01/20 00:47:01 rhoads␊ |
| 74 | *␉roll in Hub Policy Maker changes␊ |
| 75 | *␉␊ |
| 76 | *␉Revision 1.4 2006/12/22 23:05:46 rhoads␊ |
| 77 | *␉roll in branches 4364835 and 4277683-2␊ |
| 78 | *␉␊ |
| 79 | *␉Revision 1.3.20.3 2007/01/15 19:58:07 rhoads␊ |
| 80 | *␉saving more changes␊ |
| 81 | *␉␊ |
| 82 | *␉Revision 1.3.20.2 2007/01/09 21:55:53 rhoads␊ |
| 83 | *␉commit some stuff to try to fix a permissions issue␊ |
| 84 | *␉␊ |
| 85 | *␉Revision 1.3.20.1 2006/12/18 19:13:56 rhoads␊ |
| 86 | *␉re-integrate the old branch into TOT␊ |
| 87 | *␉␊ |
| 88 | *␉Revision 1.3.12.4 2006/12/18 17:33:48 rhoads␊ |
| 89 | *␉looking good except for sleep/wake␊ |
| 90 | *␉␊ |
| 91 | *␉Revision 1.3.12.3 2006/12/08 05:42:40 rhoads␊ |
| 92 | *␉mostly working␊ |
| 93 | *␉␊ |
| 94 | *␉Revision 1.3.12.2 2006/11/14 22:37:06 rhoads␊ |
| 95 | *␉more changes with the root hubs␊ |
| 96 | *␉␊ |
| 97 | *␉Revision 1.3.12.1 2006/11/07 16:55:52 rhoads␊ |
| 98 | *␉change to get the IOUSBHubDevice nubs into the IOPower tree␊ |
| 99 | *␉␊ |
| 100 | *␉Revision 1.3 2006/10/06 04:42:02 rhoads␊ |
| 101 | *␉roll in branches 4727961, 4758404, 4759810, 4760274, and 4762769␊ |
| 102 | *␉␊ |
| 103 | *␉Revision 1.2.4.2 2006/10/04 23:01:24 rhoads␊ |
| 104 | *␉better naming␊ |
| 105 | *␉␊ |
| 106 | *␉Revision 1.2.4.1 2006/10/04 16:03:57 rhoads␊ |
| 107 | *␉better IOUSBHubDevice design␊ |
| 108 | *␉␊ |
| 109 | */␊ |
| 110 | #endif␊ |
| 111 | ␊ |
| 112 | ␊ |
| 113 | #ifndef _IOKIT_IOUSBHUBDEVICE_H␊ |
| 114 | #define _IOKIT_IOUSBHUBDEVICE_H␊ |
| 115 | ␊ |
| 116 | #include <IOKit/usb/IOUSBDevice.h>␉␉␉␉␉␉// our superclass␊ |
| 117 | ␊ |
| 118 | // forward refeference. we don't include the header file because it would cause a circular reference␊ |
| 119 | class IOUSBHubPolicyMaker;␊ |
| 120 | ␊ |
| 121 | enum {␊ |
| 122 | ␉kIOUSBHubDeviceIsRootHub␉␉␉=␉0x0001,␊ |
| 123 | ␉kIOUSBHubDeviceIsOnHighSpeedBus␉␉=␉0x0002,␊ |
| 124 | ␉kIOUSBHubDeviceCanSleep␉␉␉␉=␉0x0004␊ |
| 125 | };␊ |
| 126 | ␊ |
| 127 | /*!␊ |
| 128 | @class IOUSBHubDevice␊ |
| 129 | @abstract New in MAC OS X 10.5. The IOKit object representing a hub device on the USB bus. It is a subclass of IOUSBDevice.␊ |
| 130 | @discussion With the exception of the IOUSBRootHubDevice objects representing the root hubs, every IOUSBDevice␊ |
| 131 | ␉will have an IOUSBHubDevice as its parent in the IOUSB plane. USB KEXT drivers will have the ability to ␊ |
| 132 | ␉query this device for characteristics of the hub into which they are connected. This class will also give a dive driver␊ |
| 133 | ␉the abilty to get an IOService* pointing to the hub driver itself, which can then be used as the parent in the power plane.␊ |
| 134 | */␊ |
| 135 | ␊ |
| 136 | class IOUSBHubDevice : public IOUSBDevice␊ |
| 137 | {␊ |
| 138 | ␉friend class IOUSBHubPolicyMaker;␊ |
| 139 | ␉friend class AppleUSBHub;␊ |
| 140 | ␉friend class IOUSBController;␉␉␉␉␉␉␉␉// for the "can sleep" characteristic␊ |
| 141 | ␉␊ |
| 142 | private:␊ |
| 143 | OSDeclareDefaultStructors(IOUSBHubDevice)␊ |
| 144 | ␊ |
| 145 | ␉UInt32␉␉␉␉␉_myCharacteristics;␉␉␉␉␉// bitmap of my characteristics␊ |
| 146 | ␉IOUSBHubPolicyMaker␉␉*_myPolicyMaker;␉␉␉␉␉// pointer to the policy maker in the IOPower tree for this hub␊ |
| 147 | ␊ |
| 148 | struct ExpansionData ␊ |
| 149 | ␉{ ␊ |
| 150 | ␉␉UInt32␉␉␉␉␉_maxPortCurrent;␉␉␉␉// maximum current in milliamps per downstream port␊ |
| 151 | ␉␉UInt32␉␉␉␉␉_totalExtraCurrent;␉␉␉␉// total amount of current above the spec'ed current per port available (during normal operation)␊ |
| 152 | ␉␉UInt32␉␉␉␉␉_totalSleepCurrent;␉␉␉␉// total amount of current that can be drawn during sleep␊ |
| 153 | ␉␉UInt32␉␉␉␉␉_canRequestExtraPower;␉␉␉// If 0, this hub does not support requesting extra power from its parent, non-zero: how much power we need to request in order to give out _extraPowerForPorts␊ |
| 154 | ␉␉UInt32␉␉␉␉␉_extraPowerForPorts;␉␉␉// Of the power requested from our parent, how much can we parcel out -- the rest is consumed by voltage drop thru the cable␊ |
| 155 | ␉␉UInt32␉␉␉␉␉_extraPowerAllocated;␉␉␉// Amount of power that we actually got from our parent␊ |
| 156 | ␉␉bool␉␉␉␉␉_requestFromParent;␉␉␉␉// True if we are to request the extra power from our parent, without modifying the request. Used for RMHs␊ |
| 157 | ␉};␊ |
| 158 | ExpansionData␉␉␉*_expansionData;␊ |
| 159 | ␉␊ |
| 160 | protected:␊ |
| 161 | ␉// IOUSBHubDevice methods which will be used by the hub driver (which is also the Policy Maker)␊ |
| 162 | ␉virtual␉void␉␉␉SetPolicyMaker(IOUSBHubPolicyMaker *policyMaker);␊ |
| 163 | ␉virtual void␉␉␉SetHubCharacteristics(UInt32);␊ |
| 164 | ␉virtual bool␉␉␉InitializeCharacteristics(void);␉␉␉␉␉// used at start␊ |
| 165 | ␉␊ |
| 166 | public:␊ |
| 167 | ␉// static constructor␊ |
| 168 | static IOUSBHubDevice␉*NewHubDevice(void);␊ |
| 169 | ␊ |
| 170 | ␉// IOKit methods␊ |
| 171 | virtual bool␉␉␉init();␊ |
| 172 | ␉virtual bool␉␉␉start( IOService * provider );␊ |
| 173 | virtual void␉␉␉stop( IOService *provider );␊ |
| 174 | virtual void␉␉␉free();␊ |
| 175 | ␉␊ |
| 176 | ␉// public IOUSBHubDevice methods␊ |
| 177 | ␊ |
| 178 | ␉void␉␉␉␉␉SetTotalSleepCurrent(UInt32 sleepCurrent);␊ |
| 179 | ␉UInt32␉␉␉␉␉GetTotalSleepCurrent();␊ |
| 180 | ␉␊ |
| 181 | /*!␊ |
| 182 | ␉ @function GetPolicyMaker␊ |
| 183 | ␉ returns a pointer to the policy maker for the hub, which can be used as the power plane parent.␊ |
| 184 | ␉ @result returns an IOUSBHubPolicyMaker* pointing to the policy maker for this hub. returns NULL is no policy maker is active on the hub device.␊ |
| 185 | ␉ */␊ |
| 186 | ␉virtual IOUSBHubPolicyMaker *GetPolicyMaker(void);␊ |
| 187 | ␉␊ |
| 188 | /*!␊ |
| 189 | ␉@function GetHubCharacteristics␊ |
| 190 | ␉returns characteristics of the hub device which might be useful for the driver of a device connected to the hub.␊ |
| 191 | ␉␉kIOUSBHubDeviceIsRootHub indicates that the hub is a root hub␊ |
| 192 | ␉␉kIOUSBHubDeviceIsOnHighSpeedBus indicates that the hub is running on a High Speed bus. If this bit is set and kIOUSBHubDeviceIsHighSpeed is clear, then this is a Classic Speed hub running on a High Speed bus, which means that Split Transactions will be used to communicate with downstream devices.␊ |
| 193 | ␊ |
| 194 | ␉@result returns a bitmap of characteristics␊ |
| 195 | */␊ |
| 196 | ␉virtual␉UInt32␉␉␉GetHubCharacteristics();␊ |
| 197 | ␉␊ |
| 198 | /*!␊ |
| 199 | ␉@function GetMaxProvidedPower␊ |
| 200 | ␉returns the maximum amount of power available on any downstream port of this hub␊ |
| 201 | ␉@result the power is returned in milliamps - usually 100ma or 500 ma.␊ |
| 202 | */␊ |
| 203 | ␉virtual UInt32␉␉␉GetMaxProvidedPower();␊ |
| 204 | ␊ |
| 205 | /*!␊ |
| 206 | ␉@function RequestProvidedPower␊ |
| 207 | ␉requests power from the hub device␊ |
| 208 | ␉@param requestedPower - the amount of power requested in milliamps (usually 100ma or 500 ma)␊ |
| 209 | ␉@result the amount of power allocated for this driver in milliamps (usually 100ma or 500 ma)␊ |
| 210 | */␊ |
| 211 | ␉virtual UInt32␉␉␉RequestProvidedPower(UInt32 requestedPower);␊ |
| 212 | ␊ |
| 213 | ␉virtual UInt32␉␉␉RequestExtraPower(UInt32 requestedPower);␊ |
| 214 | ␊ |
| 215 | ␉virtual void␉␉␉ReturnExtraPower(UInt32 returnedPower);␊ |
| 216 | ␉␊ |
| 217 | OSMetaClassDeclareReservedUsed(IOUSBHubDevice, 0);␊ |
| 218 | ␉␊ |
| 219 | ␉virtual void␉␉␉InitializeExtraPower(UInt32 maxPortCurrent, UInt32 totalExtraCurrent);␊ |
| 220 | ␉␊ |
| 221 | OSMetaClassDeclareReservedUsed(IOUSBHubDevice, 1);␊ |
| 222 | ␉virtual UInt32␉␉␉RequestSleepPower(UInt32 requestedPower);␊ |
| 223 | ␊ |
| 224 | OSMetaClassDeclareReservedUsed(IOUSBHubDevice, 2);␊ |
| 225 | ␉virtual void␉␉␉ReturnSleepPower(UInt32 returnedPower);␊ |
| 226 | ␊ |
| 227 | OSMetaClassDeclareReservedUsed(IOUSBHubDevice, 3);␊ |
| 228 | ␉virtual void␉␉␉SetSleepCurrent(UInt32 sleepCurrent);␊ |
| 229 | ␉␊ |
| 230 | OSMetaClassDeclareReservedUsed(IOUSBHubDevice, 4);␊ |
| 231 | ␉virtual␉UInt32␉␉␉GetSleepCurrent();␊ |
| 232 | ␉␊ |
| 233 | OSMetaClassDeclareReservedUnused(IOUSBHubDevice, 5);␊ |
| 234 | OSMetaClassDeclareReservedUnused(IOUSBHubDevice, 6);␊ |
| 235 | OSMetaClassDeclareReservedUnused(IOUSBHubDevice, 7);␊ |
| 236 | OSMetaClassDeclareReservedUnused(IOUSBHubDevice, 8);␊ |
| 237 | OSMetaClassDeclareReservedUnused(IOUSBHubDevice, 9);␊ |
| 238 | OSMetaClassDeclareReservedUnused(IOUSBHubDevice, 10);␊ |
| 239 | OSMetaClassDeclareReservedUnused(IOUSBHubDevice, 11);␊ |
| 240 | OSMetaClassDeclareReservedUnused(IOUSBHubDevice, 12);␊ |
| 241 | OSMetaClassDeclareReservedUnused(IOUSBHubDevice, 13);␊ |
| 242 | OSMetaClassDeclareReservedUnused(IOUSBHubDevice, 14);␊ |
| 243 | OSMetaClassDeclareReservedUnused(IOUSBHubDevice, 15);␊ |
| 244 | };␊ |
| 245 | ␊ |
| 246 | #endif /* _IOKIT_IOUSBROOTHUBDEVICE_H */␊ |
| 247 | ␊ |
| 248 | |
