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