iokit/IOKit/pwr_mgt/IOPMPowerSource.h

   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
  38 enum {
  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
 168 class 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
 261 protected:
 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