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