1 | /*␊ |
2 | * Copyright (c) 2007 Apple 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: IOUSBHubPolicyMaker.h,v $␊ |
28 | *␉Revision 1.10 2009/05/07 19:43:09 nano␊ |
29 | *␉Move our SnowLeopard branch to TOT␊ |
30 | *␊ |
31 | *␉Revision 1.7.72.3 2008/07/23 17:43:32 nano␊ |
32 | *␉<rdar://problem/5939357> IOUSBHIDDriver, IOHIDEventService missing HeaderDoc class declarations␊ |
33 | *␉␊ |
34 | *␉Revision 1.7.72.2 2008/04/22 22:38:01 nano␊ |
35 | *␉Bring in changes from Foxhound-320.2.9␊ |
36 | *␉␊ |
37 | *␉Revision 1.9 2008/04/17 16:56:57 nano␊ |
38 | *␉Bring in branches for rdar://5867990 & rdar://5768343␊ |
39 | *␉␊ |
40 | *␉Revision 1.8.4.1 2008/04/16 20:26:15 nano␊ |
41 | *␉<rdar://problem/5867990> Add API to allocate sleep current, as well as making sure that we return any extra power if our client dies or our device is terminated without returning it␊ |
42 | *␉␊ |
43 | *␉Revision 1.8 2008/04/14 16:08:38 nano␊ |
44 | *␉Add new APIs for high power and for GetDeviceInformation.␊ |
45 | *␉␊ |
46 | *␉Revision 1.7.114.1 2008/04/11 22:25:44 nano␊ |
47 | *␉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␊ |
48 | *␉␊ |
49 | *␉Revision 1.7 2007/08/17 22:41:11 nano␊ |
50 | *␉Bring in branch that fixes <rdar://problem/5414582> USB not honoring Resume recovery time (hub driver) and adds extra time for iPods␊ |
51 | *␉␊ |
52 | *␉Revision 1.6.30.1 2007/08/16 19:14:02 nano␊ |
53 | *␉ResumeRecovery additions.␊ |
54 | *␉␊ |
55 | *␉Revision 1.6 2007/08/01 16:10:18 rhoads␊ |
56 | *␉roll in extra power changes␊ |
57 | *␉␊ |
58 | *␉Revision 1.5.12.1 2007/07/27 16:49:10 rhoads␊ |
59 | *␉merge the extra current stuff into Leopard, and add extra sleep current for self powered hubs␊ |
60 | *␉␊ |
61 | *␉Revision 1.5 2007/07/20 22:31:22 rhoads␊ |
62 | *␉roll in branch300-3-2␊ |
63 | *␉␊ |
64 | *␉Revision 1.4.40.1 2007/07/18 18:44:24 rhoads␊ |
65 | *␉this is the 300.3.2g version plus some quieter logs␊ |
66 | *␉␊ |
67 | *␉Revision 1.4.34.2 2007/07/17 06:30:35 rhoads␊ |
68 | *␉more hub chain fixes␊ |
69 | *␉␊ |
70 | *␉Revision 1.4.34.1 2007/07/16 16:45:00 rhoads␊ |
71 | *␉more power management and termination tweaks␊ |
72 | *␉␊ |
73 | *␉Revision 1.4 2007/05/18 01:59:12 rhoads␊ |
74 | *␉roll in 5112084 and 5204170␊ |
75 | *␉␊ |
76 | *␉Revision 1.3.2.1 2007/05/15 18:23:48 rhoads␊ |
77 | *␉some initial power state bug fixes␊ |
78 | *␉␊ |
79 | *␉Revision 1.3 2007/05/10 22:25:35 rhoads␊ |
80 | *␉roll in branch 5113395 - the last major piece of the new power architecture␊ |
81 | *␉␊ |
82 | *␉Revision 1.2.64.4 2007/04/13 22:34:59 rhoads␊ |
83 | *␉fix restart and shutdown␊ |
84 | *␉␊ |
85 | *␉Revision 1.2.64.3 2007/04/11 23:56:23 rhoads␊ |
86 | *␉first mostly working dozing hub␊ |
87 | *␉␊ |
88 | *␉Revision 1.2.64.2 2007/04/10 02:09:09 rhoads␊ |
89 | *␉got UHCI almost working␊ |
90 | *␉␊ |
91 | *␉Revision 1.2.64.1 2007/04/05 02:57:50 rhoads␊ |
92 | *␉move power management out of AppleUSBHub and into IOUSBHubPolicyMaker␊ |
93 | *␉␊ |
94 | *␉Revision 1.2 2007/01/20 00:47:01 rhoads␊ |
95 | *␉roll in Hub Policy Maker changes␊ |
96 | *␉␊ |
97 | *␉Revision 1.1.2.4 2007/01/18 22:51:08 rhoads␊ |
98 | *␉add some padding␊ |
99 | *␉␊ |
100 | *␉Revision 1.1.2.3 2007/01/15 19:58:07 rhoads␊ |
101 | *␉saving more changes␊ |
102 | *␉␊ |
103 | *␉Revision 1.1.2.2 2007/01/09 23:55:36 rhoads␊ |
104 | *␉working version␊ |
105 | *␉␊ |
106 | *␉Revision 1.1.2.1 2007/01/09 21:57:02 rhoads␊ |
107 | *␉commit some stuff to try to fix a permissions issue␊ |
108 | *␉␊ |
109 | *␉␊ |
110 | */␊ |
111 | #endif␊ |
112 | #ifndef _IOKIT_IOUSBHUBPOLICYMAKER_H␊ |
113 | #define _IOKIT_IOUSBHUBPOLICYMAKER_H␊ |
114 | ␊ |
115 | #include␉<IOKit/IOService.h>␊ |
116 | #include␉<IOKit/usb/IOUSBController.h>␊ |
117 | #include␉<IOKit/usb/IOUSBHubDevice.h>␊ |
118 | ␊ |
119 | ␊ |
120 | enum {␊ |
121 | ␉kIOUSBHubPowerStateOff␉␉= 0,␉␉␉␉// losing power␊ |
122 | ␉kIOUSBHubPowerStateRestart␉= 1,␉␉␉␉// reseting bus, but may maintain power␊ |
123 | ␉kIOUSBHubPowerStateSleep␉= 2,␉␉␉␉// upstream port and all downstream ports suspended (from the top)␊ |
124 | ␉kIOUSBHubPowerStateLowPower␉= 3,␉␉␉␉// upstream port and all downstream ports suspended (from the bottom)␊ |
125 | ␉kIOUSBHubPowerStateOn␉␉= 4,␉␉␉␉// upstream port and at least one downstream port on␊ |
126 | ␉kIOUSBHubNumberPowerStates␉= 5␊ |
127 | };␊ |
128 | ␊ |
129 | enum {␊ |
130 | ␉kHubResumeRecoveryTime␉=␉10,␉␉␉␉␉␉␉␉// 10 ms to recover after I resume myself␊ |
131 | ␉kPortResumeRecoveryTime =␉10␉␉␉␉␉␉␉␉// 10 ms to recover another device␊ |
132 | };␊ |
133 | ␊ |
134 | #define kIOUSBHubPowerStateStable␉-1␊ |
135 | ␊ |
136 | /*!␊ |
137 | @class IOUSBHubPolicyMaker␊ |
138 | @abstract Super class for Hub drivers to incorporate common Power Management code.␊ |
139 | */␊ |
140 | class IOUSBHubPolicyMaker : public IOService␊ |
141 | {␊ |
142 | ␉OSDeclareAbstractStructors(IOUSBHubPolicyMaker)␊ |
143 | ␊ |
144 | protected:␊ |
145 | IOUSBControllerV2 *␉␉␉␉␉_bus;␊ |
146 | IOUSBHubDevice *␉␉␉␉␉_device;␉␉␉␉␉// our provider␊ |
147 | IOUSBHubDevice *␉␉␉␉␉_parentHubDevice;␉␉␉// for non root hub drivers, this is the hub device that my hub device is connected to␊ |
148 | bool␉␉␉␉␉␉␉␉_isRootHub;␉␉␉␉␉// this is a root hub␊ |
149 | ␉bool␉␉␉␉␉␉␉␉_dozeEnabled;␉␉␉␉// true if the controller has been enabled to go into doze mode␊ |
150 | ␉bool␉␉␉␉␉␉␉␉_dontAllowLowPower;␉␉␉// If true, we will not allow the hub to go into low power mode.␊ |
151 | ␉bool␉␉␉␉␉␉␉␉_dontAllowSleepPower;␉␉// If true, we will not allow extra sleep power for a self powered hub.␊ |
152 | ␉SInt32␉␉␉␉␉␉␉␉_powerStateChangingTo;␉␉// a power state if we are changing to one, or -1 if we are stable␊ |
153 | ␉unsigned long␉␉␉␉␉␉_myPowerState;␉␉␉␉// my current state (since getPowerState doesn't always change in time)␊ |
154 | ␉UInt32␉␉␉␉␉␉␉␉_extraPower;␉␉␉␉// how much extra power we might be able to get from our parent hub␊ |
155 | ␉UInt32␉␉␉␉␉␉␉␉_extraPowerRemaining;␉␉// how many milliamps we can still give to any one port␊ |
156 | ␉UInt32␉␉␉␉␉␉␉␉_hubResumeRecoveryTime;␉␉// # of ms that we will wait before issuing any transactions on our port (nominally 10ms)␊ |
157 | struct ExpansionData ␊ |
158 | ␉{ ␊ |
159 | ␉};␊ |
160 | ExpansionData␉␉␉*_expansionData;␊ |
161 | ␊ |
162 | public:␊ |
163 | ␉// IOService methods␊ |
164 | virtual bool␉␉␉␉␉␉start(IOService * provider);␊ |
165 | ␉virtual IOReturn␉␉␉␉␉powerStateWillChangeTo ( IOPMPowerFlags capabilities, unsigned long stateNumber, IOService* whatDevice);␊ |
166 | ␉virtual unsigned long␉␉␉␉powerStateForDomainState ( IOPMPowerFlags domainState );␊ |
167 | ␉virtual IOReturn␉␉␉␉␉setPowerState ( unsigned long powerStateOrdinal, IOService* whatDevice );␊ |
168 | ␉virtual IOReturn␉␉␉␉␉powerStateDidChangeTo ( IOPMPowerFlags capabilities, unsigned long stateNumber, IOService* whatDevice);␊ |
169 | ␉virtual unsigned long␉␉␉␉maxCapabilityForDomainState ( IOPMPowerFlags domainState );␊ |
170 | ␉virtual void␉␉␉␉␉␉powerChangeDone ( unsigned long fromState );␊ |
171 | ␊ |
172 | ␉// public methods which MAY be implemented in subclass␊ |
173 | ␉virtual IOReturn␉␉␉␉␉EnsureUsability(void);␊ |
174 | ␉␉␊ |
175 | ␉// Extra Port Power calls␊ |
176 | ␉void␉␉␉␉␉␉␉␉AllocateExtraPower();␊ |
177 | ␉IOReturn␉␉␉␉␉␉␉GetExtraPortPower(UInt32 portNum, UInt32 *extraPower);␊ |
178 | ␉IOReturn␉␉␉␉␉␉␉ReturnExtraPortPower(UInt32 portNum, UInt32 extraPower);␊ |
179 | ␊ |
180 | ␉// virtual methods to be implemented in the controlling driver subclass␊ |
181 | ␉virtual bool␉␉␉␉␉␉ConfigureHubDriver(void) = 0;␊ |
182 | ␉virtual IOReturn␉␉␉␉␉HubPowerChange(unsigned long powerStateOrdinal) = 0;␊ |
183 | ␊ |
184 | OSMetaClassDeclareReservedUsed(IOUSBHubPolicyMaker, 0);␊ |
185 | ␉virtual␉IOReturn␉␉␉␉␉GetPortInformation(UInt32 portNum, UInt32 *info);␊ |
186 | ␉␊ |
187 | OSMetaClassDeclareReservedUsed(IOUSBHubPolicyMaker, 1);␊ |
188 | ␉virtual␉IOReturn␉␉␉␉␉ResetPort(UInt32 portNum);␊ |
189 | ␉␊ |
190 | OSMetaClassDeclareReservedUsed(IOUSBHubPolicyMaker, 2);␊ |
191 | ␉virtual␉IOReturn␉␉␉␉␉SuspendPort(UInt32 portNum, bool suspend);␊ |
192 | ␉␊ |
193 | OSMetaClassDeclareReservedUsed(IOUSBHubPolicyMaker, 3);␊ |
194 | ␉virtual␉IOReturn␉␉␉␉␉ReEnumeratePort(UInt32 portNum, UInt32 options);␊ |
195 | ␉␊ |
196 | OSMetaClassDeclareReservedUsed(IOUSBHubPolicyMaker, 4);␊ |
197 | ␉virtual UInt32␉␉␉␉␉␉RequestExtraPower(UInt32 portNum, UInt32 type, UInt32 requestedPower);␊ |
198 | ␊ |
199 | OSMetaClassDeclareReservedUsed(IOUSBHubPolicyMaker, 5);␊ |
200 | ␉virtual IOReturn␉␉␉␉␉ReturnExtraPower(UInt32 portNum, UInt32 type, UInt32 returnedPower);␊ |
201 | ␊ |
202 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 6);␊ |
203 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 7);␊ |
204 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 8);␊ |
205 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 9);␊ |
206 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 10);␊ |
207 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 11);␊ |
208 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 12);␊ |
209 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 13);␊ |
210 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 14);␊ |
211 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 15);␊ |
212 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 16);␊ |
213 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 17);␊ |
214 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 18);␊ |
215 | OSMetaClassDeclareReservedUnused(IOUSBHubPolicyMaker, 19);␊ |
216 | };␊ |
217 | ␊ |
218 | #endif _IOKIT_IOUSBHUBPOLICYMAKER_H␊ |
219 | |