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