1/*
2 * Copyright (c) 1998-2005 Apple Computer, 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
38enum {
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
171class 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
264protected:
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