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