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