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  *   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
 170 class 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
 263 protected:
 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