1 | /* |
2 | * Copyright (c) 1998-2019 Apple Inc. All rights reserved. |
3 | * |
4 | * @APPLE_OSREFERENCE_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. The rights granted to you under the License |
10 | * may not be used to create, or enable the creation or redistribution of, |
11 | * unlawful or unlicensed copies of an Apple operating system, or to |
12 | * circumvent, violate, or enable the circumvention or violation of, any |
13 | * terms of an Apple operating system software license agreement. |
14 | * |
15 | * Please obtain a copy of the License at |
16 | * http://www.opensource.apple.com/apsl/ and read it before using this file. |
17 | * |
18 | * The Original Code and all software distributed under the License are |
19 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER |
20 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
21 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, |
22 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. |
23 | * Please see the License for the specific language governing rights and |
24 | * limitations under the License. |
25 | * |
26 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ |
27 | */ |
28 | |
29 | #ifndef _IOPMPowerSource_h_ |
30 | #define _IOPMPowerSource_h_ |
31 | |
32 | #include <libkern/c++/OSObject.h> |
33 | #include <IOKit/pwr_mgt/IOPM.h> |
34 | #include <IOKit/IOTypes.h> |
35 | #include <IOKit/IOReturn.h> |
36 | #include <IOKit/IOService.h> |
37 | |
38 | enum { |
39 | kSecondsPerHour = 3600, |
40 | kTenMinutesInSeconds = 600 |
41 | }; |
42 | |
43 | |
44 | /*! @class IOPMPowerSource |
45 | * |
46 | * See IOKit/pwr_mgt/IOPM.h for power source keys relevant to this class. These |
47 | * report-type keys are required for calls to IOPMPowerSource::setReportables(), |
48 | * and they define the IORegistry interface through which data is passed back |
49 | * up to the rest of the system. |
50 | * |
51 | * A subclassing driver that doesn't want to do anything fancy should: |
52 | * 1. Subclass IOPMPowerSource |
53 | * 2. Install its own battery change notifications or polling routine that can |
54 | * converse with actual battery hardware. |
55 | * 3. When battery state changes, change the relevant member variables |
56 | * through setCurrentCapacity() style accessors. |
57 | * 4. Call updateStatus() on itself when all such settings have been updated. |
58 | * |
59 | * The subclass driver should also initially populate its settings and call |
60 | * updateStatus() on launch. |
61 | * |
62 | * |
63 | * Settings: |
64 | * |
65 | * <pre> |
66 | * ExternalConnected |
67 | * Type: bool |
68 | * IORegistry Key: kIOPMPSExternalConnectedKey |
69 | * True if computer is drawing external power |
70 | * |
71 | * ExternalChargeCapable |
72 | * Type: bool |
73 | * IORegistry Key: kIOPMPSExternalChargeCapableKey |
74 | * True if external power is capable of charging internal battery |
75 | * |
76 | * BatteryInstalled |
77 | * Type: bool |
78 | * IORegistry Key: kIOPMPSBatteryInstalledKey |
79 | * True if a battery is present; false if removed |
80 | * |
81 | * IsCharging |
82 | * Type: bool |
83 | * IORegistry Key: kIOPMPSIsChargingKey |
84 | * True if battery is charging itself from external power |
85 | * |
86 | * AtWarnLevel |
87 | * Type: bool |
88 | * IORegistry Key: kIOPMPSAtWarnLevelKey |
89 | * True if draining battery capacity and past warn level |
90 | * |
91 | * AtCriticalLevel |
92 | * Type: bool |
93 | * IORegistry Key: kIOPMPSAtCriticalLevelKey |
94 | * True if draining battery capacity and past critical level |
95 | * |
96 | * CurrentCapacity |
97 | * MaxCapacity |
98 | * Type: unsigned int |
99 | * IORegistry Key: kIOPMPSCurrentCapacityKey, kIOPMPSMaxCapacityKey |
100 | * Capacity measured in mAh |
101 | * |
102 | * TimeRemaining |
103 | * Type: int |
104 | * IORegistry Key: kIOPMPSTimeRemainingKey |
105 | * Time remaining measured in minutes |
106 | * |
107 | * Amperage |
108 | * Type: int |
109 | * IORegistry Key: kIOPMPSAmperageKey |
110 | * Current is measured in mA |
111 | * |
112 | * Voltage |
113 | * Type: unsigned int |
114 | * IORegistry Key: kIOPMPSVoltageKey |
115 | * Voltage measured in mV |
116 | * |
117 | * CycleCount |
118 | * Type: unsigned int |
119 | * IORegistry Key: kIOPMPSCycleCountKey |
120 | * Number of charge/discharge cycles |
121 | * |
122 | * AdapterInfo |
123 | * Type: int |
124 | * IORegistry Key: kIOPMPSAdapterInfoKey |
125 | * Power adapter information |
126 | * |
127 | * Location |
128 | * Type: int |
129 | * IORegistry Key: kIOPMPSLocationKey |
130 | * Clue about battery's location in machine - Left vs. Right |
131 | * |
132 | * ErrorCondition |
133 | * Type: OSSymbol |
134 | * IORegistry Key: kIOPMPSErrorConditionKey |
135 | * String describing error state of battery |
136 | * |
137 | * Manufacturer |
138 | * Type: OSSymbol |
139 | * IORegistry Key: kIOPMPSManufacturerKey |
140 | * String describing battery manufacturer |
141 | * |
142 | * Manufactured Date |
143 | * Type: unsigned 16-bit bitfield |
144 | * IORegistry Key: kIOPMPSManufactureDateKey |
145 | * Date is published in a bitfield per the Smart Battery Data spec rev 1.1 |
146 | * in section 5.1.26 |
147 | * Bits 0...4 => day (value 1-31; 5 bits) |
148 | * Bits 5...8 => month (value 1-12; 4 bits) |
149 | * Bits 9...15 => years since 1980 (value 0-127; 7 bits) |
150 | * |
151 | * Model |
152 | * Type: OSSymbol |
153 | * IORegistry Key: kIOPMPSModelKey |
154 | * String describing model number |
155 | * |
156 | * Serial |
157 | * Type: OSSymbol |
158 | * IORegistry Key: kIOPMPSSerialKey |
159 | * String describing serial number or unique info |
160 | * The serial number published hear bears no correspondence to the Apple serial |
161 | * number printed on each battery. This is a manufacturer serial number with |
162 | * no correlation to the printed serial number. |
163 | * |
164 | * LegacyIOBatteryInfo |
165 | * Type: OSDictionary |
166 | * IORegistry Key: kIOPMPSLegacyBatteryInfoKey |
167 | * Dictionary conforming to the OS X 10.0-10.4 |
168 | * </pre> |
169 | */ |
170 | |
171 | class IOPMPowerSource : public IOService |
172 | { |
173 | OSDeclareDefaultStructors(IOPMPowerSource); |
174 | |
175 | friend class IOPMPowerSourceList; |
176 | |
177 | protected: |
178 | |
179 | /*! @var settingsChangedSinceLastUpdate |
180 | * Used by subclasses to determine if any settings have been modified via the |
181 | * accessors below since last call to update(). true is settings have changed; |
182 | * false otherwise. |
183 | */ |
184 | bool settingsChangedSinceUpdate; |
185 | |
186 | /*! @var properties |
187 | * Stores power source state |
188 | */ |
189 | OSDictionary *properties; |
190 | |
191 | const OSSymbol *externalConnectedKey; |
192 | const OSSymbol *externalChargeCapableKey; |
193 | const OSSymbol *batteryInstalledKey; |
194 | const OSSymbol *chargingKey; |
195 | const OSSymbol *warnLevelKey; |
196 | const OSSymbol *criticalLevelKey; |
197 | const OSSymbol *currentCapacityKey; |
198 | const OSSymbol *maxCapacityKey; |
199 | const OSSymbol *timeRemainingKey; |
200 | const OSSymbol *amperageKey; |
201 | const OSSymbol *voltageKey; |
202 | const OSSymbol *cycleCountKey; |
203 | const OSSymbol *adapterInfoKey; |
204 | const OSSymbol *locationKey; |
205 | const OSSymbol *errorConditionKey; |
206 | const OSSymbol *manufacturerKey; |
207 | const OSSymbol *modelKey; |
208 | const OSSymbol *serialKey; |
209 | const OSSymbol *batteryInfoKey; |
210 | |
211 | // Tracking for IOPMPowerSourceList |
212 | IOPMPowerSource *nextInList; |
213 | |
214 | public: |
215 | |
216 | /*! @function powerSource |
217 | * @abstract Creates a new IOPMPowerSource nub. Must be attached to IORegistry, |
218 | * and registered by provider. |
219 | */ |
220 | static IOPMPowerSource *powerSource(void); |
221 | |
222 | virtual bool init(void) APPLE_KEXT_OVERRIDE; |
223 | |
224 | virtual void free(void) APPLE_KEXT_OVERRIDE; |
225 | |
226 | /*! @function updateStatus |
227 | * @abstract Must be called by physical battery controller when battery state |
228 | * has changed significantly. |
229 | * @discussion The system will not poll this object for battery updates. Rather \ |
230 | * the battery's controller must call updateStatus() every time state changes \ |
231 | * and the settings will be relayed to higher levels of power management. \ |
232 | * The subclassing driver should override this only if the driver needs to add \ |
233 | * new settings to the base class. |
234 | */ |
235 | virtual void updateStatus(void); |
236 | |
237 | /* Public accessors for battery state |
238 | */ |
239 | bool externalConnected(void); |
240 | bool externalChargeCapable(void); |
241 | bool batteryInstalled(void); |
242 | bool isCharging(void); |
243 | bool atWarnLevel(void); |
244 | bool atCriticalLevel(void); |
245 | |
246 | unsigned int currentCapacity(void); |
247 | unsigned int maxCapacity(void); |
248 | unsigned int capacityPercentRemaining(void); |
249 | int timeRemaining(void); |
250 | int amperage(void); |
251 | unsigned int voltage(void); |
252 | unsigned int cycleCount(void); |
253 | int adapterInfo(void); |
254 | int location(void); |
255 | |
256 | OSSymbol *errorCondition(void); |
257 | OSSymbol *manufacturer(void); |
258 | OSSymbol *model(void); |
259 | OSSymbol *serial(void); |
260 | OSDictionary *legacyIOBatteryInfo(void); |
261 | |
262 | OSObject *getPSProperty(const OSSymbol *); |
263 | |
264 | protected: |
265 | |
266 | /* Protected "setter" methods for subclasses |
267 | * Subclasses should use these setters to modify all battery properties. |
268 | * |
269 | * Subclasses must follow all property changes with a call to updateStatus() |
270 | * to flush settings changes to upper level battery API clients. |
271 | * |
272 | */ |
273 | void setExternalConnected(bool); |
274 | void setExternalChargeCapable(bool); |
275 | void setBatteryInstalled(bool); |
276 | void setIsCharging(bool); |
277 | void setAtWarnLevel(bool); |
278 | void setAtCriticalLevel(bool); |
279 | |
280 | void setCurrentCapacity(unsigned int); |
281 | void setMaxCapacity(unsigned int); |
282 | void setTimeRemaining(int); |
283 | void setAmperage(int); |
284 | void setVoltage(unsigned int); |
285 | void setCycleCount(unsigned int); |
286 | void setAdapterInfo(int); |
287 | void setLocation(int); |
288 | |
289 | void setErrorCondition(OSSymbol *); |
290 | void setManufacturer(OSSymbol *); |
291 | void setModel(OSSymbol *); |
292 | void setSerial(OSSymbol *); |
293 | void setLegacyIOBatteryInfo(OSDictionary *); |
294 | |
295 | /*! All of these methods funnel through the generic accessor method |
296 | * setPSProperty. Caller can pass in any arbitrary OSSymbol key, and |
297 | * that value will be stored in the PM settings dictionary, and relayed |
298 | * onto the IORegistry at update time. |
299 | */ |
300 | void setPSProperty(const OSSymbol *, OSObject *); |
301 | }; |
302 | |
303 | #endif |
304 | |