iokit/IOKit/pwr_mgt/IOPMPowerSource.h

   1 /*
   2  * Copyright (c) 1998-2005 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22
  23 #ifndef _IOPMPowerSource_h_
  24 #define _IOPMPowerSource_h_
  25
  26 #include <libkern/c++/OSObject.h>
  27 #include <IOKit/pwr_mgt/IOPM.h>
  28 #include <IOKit/IOTypes.h>
  29 #include <IOKit/IOReturn.h>
  30 #include <IOKit/IOService.h>
  31
  32 enum {
  33     kSecondsPerHour = 3600,
  34     kTenMinutesInSeconds = 600
  35 };
  36
  37 /* class IOPMPowerSource
  38  *
  39  * See IOKit/pwr_mgt/IOPM.h for power source keys relevant to this class. These
  40  * report-type keys are required for calls to IOPMPowerSource::setReportables(),
  41  * and they define the IORegistry interface through which data is passed back
  42  * up to the rest of the system.
  43  *
  44  * A subclassing driver that doesn't want to do anything fancy should:
  45  *   1. Subclass IOPMPowerSource
  46  *   3. Install its own battery change notifications or polling routine that can
  47  *          converse with actual battery hardware.
  48  *   4. When battery state changes, change the relevant member variables
  49  *          through setCurrentCapacity() style accessors.
  50  *   5. Call updateStatus() on itself when all such settings have been updated.
  51  *
  52  * The subclass driver should also initially populate its settings and call
  53  * updateStatus() on launch.
  54  *
  55  *
  56  * Settings
  57  *
  58  * ExternalConnected
  59  * Type: bool
  60  * IORegistry Key: kIOPMPSExternalConnectedKey
  61  * True if computer is drawing external power
  62  *
  63  * ExternalChargeCapable
  64  * Type: bool
  65  * IORegistry Key: kIOPMPSExternalChargeCapableKey
  66  * True if external power is capable of charging internal battery
  67  *
  68  * BatteryInstalled
  69  * Type: bool
  70  * IORegistry Key: kIOPMPSBatteryInstalledKey
  71  * True if a battery is present; false if removed
  72  *
  73  * IsCharging
  74  * Type: bool
  75  * IORegistry Key: kIOPMPSIsChargingKey
  76  * True if battery is charging itself from external power
  77  *
  78  * AtWarnLevel
  79  * Type: bool
  80  * IORegistry Key: kIOPMPSAtWarnLevelKey
  81  * True if draining battery capacity and past warn level
  82  *
  83  * AtCriticalLevel
  84  * Type: bool
  85  * IORegistry Key: kIOPMPSAtCriticalLevelKey
  86  * True if draining battery capacity and past critical level
  87  *
  88  * CurrentCapacity
  89  * MaxCapacity
  90  * Type: unsigned int
  91  * IORegistry Key: kIOPMPSCurrentCapacityKey, kIOPMPSMaxCapacityKey
  92  * Capacity measured in mAh
  93  *
  94  * TimeRemaining
  95  * Type: int
  96  * IORegistry Key: kIOPMPSTimeRemainingKey
  97  * Time remaining measured in minutes
  98  *
  99  * Amperage
 100  * Type: int
 101  * IORegistry Key: kIOPMPSAmperageKey
 102  * Current is measured in mA
 103  *
 104  * Voltage
 105  * Type: unsigned int
 106  * IORegistry Key: kIOPMPSVoltageKey
 107  * Voltage measured in mV
 108  *
 109  * CycleCount
 110  * Type: unsigned int
 111  * IORegistry Key: kIOPMPSCycleCountKey
 112  * Number of charge/discharge cycles
 113  *
 114  * AdapterInfo
 115  * Type: int
 116  * IORegistry Key: kIOPMPSAdapterInfoKey
 117  * Power adapter information
 118  *
 119  * Location
 120  * Type: int
 121  * IORegistry Key: kIOPMPSLocationKey
 122  * Clue about battery's location in machine - Left vs. Right
 123  *
 124  * ErrorCondition
 125  * Type: OSSymbol
 126  * IORegistry Key: kIOPMPSErrorConditionKey
 127  * String describing error state of battery
 128  *
 129  * Manufacturer
 130  * Type: OSSymbol
 131  * IORegistry Key: kIOPMPSManufacturerKey
 132  * String describing battery manufacturer
 133  *
 134  * Model
 135  * Type: OSSymbol
 136  * IORegistry Key: kIOPMPSModelKey
 137  * String describing model number
 138  *
 139  * Serial
 140  * Type: OSSymbol
 141  * IORegistry Key: kIOPMPSSerialKey
 142  * String describing serial number  or unique info
 143  *
 144  * LegacyIOBatteryInfo
 145  * Type: OSDictionary
 146  * IORegistry Key: kIOPMPSLegacyBatteryInfoKey
 147  * Dictionary conforming to the OS X 10.0-10.4
 148  */
 149
 150 class IOPMPowerSource : public IOService
 151 {
 152     OSDeclareDefaultStructors(IOPMPowerSource)
 153
 154     friend class IOPMPowerSourceList;
 155
 156  protected:
 157     // Tracking for IOPMPowerSourceList
 158     IOPMPowerSource         *nextInList;
 159
 160     OSDictionary            *properties;
 161
 162     const OSSymbol *externalConnectedKey;
 163     const OSSymbol *externalChargeCapableKey;
 164     const OSSymbol *batteryInstalledKey;
 165     const OSSymbol *chargingKey;
 166     const OSSymbol *warnLevelKey;
 167     const OSSymbol *criticalLevelKey;
 168     const OSSymbol *currentCapacityKey;
 169     const OSSymbol *maxCapacityKey;
 170     const OSSymbol *timeRemainingKey;
 171     const OSSymbol *amperageKey;
 172     const OSSymbol *voltageKey;
 173     const OSSymbol *cycleCountKey;
 174     const OSSymbol *adapterInfoKey;
 175     const OSSymbol *locationKey;
 176     const OSSymbol *errorConditionKey;
 177     const OSSymbol *manufacturerKey;
 178     const OSSymbol *modelKey;
 179     const OSSymbol *serialKey;
 180     const OSSymbol *batteryInfoKey;
 181
 182  public:
 183
 184 /*! @function powerSource
 185     @abstract Creates a new IOPMPowerSource nub. Must be attached to IORegistry,
 186         and registered by provider.
 187 */
 188     static IOPMPowerSource *powerSource(void);
 189
 190     virtual bool init(void);
 191
 192     virtual void free(void);
 193
 194 /*! @function updateStatus
 195     @abstract Must be called by physical battery controller when battery state
 196                 has changed significantly.
 197     @discussion The system will not poll this object for battery updates. Rather \
 198     the battery's controller must call updateStatus() every time state changes \
 199     and the settings will be relayed to higher levels of power management. \
 200     The subclassing driver should override this only if the driver needs to add \
 201     new settings to the base class.
 202 */
 203     virtual void updateStatus(void);
 204
 205 /* Public accessors for battery state
 206  */
 207     bool externalConnected(void);
 208     bool externalChargeCapable(void);
 209     bool batteryInstalled(void);
 210     bool isCharging(void);
 211     bool atWarnLevel(void);
 212     bool atCriticalLevel(void);
 213
 214     unsigned int currentCapacity(void);
 215     unsigned int maxCapacity(void);
 216     unsigned int capacityPercentRemaining(void);
 217     int timeRemaining(void);
 218     int amperage(void);
 219     unsigned int voltage(void);
 220     unsigned int cycleCount(void);
 221     int adapterInfo(void);
 222     int location(void);
 223
 224     OSSymbol *errorCondition(void);
 225     OSSymbol *manufacturer(void);
 226     OSSymbol *model(void);
 227     OSSymbol *serial(void);
 228     OSDictionary *legacyIOBatteryInfo(void);
 229
 230 protected:
 231 /* Protected "setter" methods for subclasses
 232  * Subclasses should use these setters to modify all battery properties.
 233  *
 234  * Subclasses must follow all property changes with a call to updateStatus()
 235  * to flush settings changes to upper level battery API clients.
 236  *
 237  */
 238     void setExternalConnected(bool);
 239     void setExternalChargeCapable(bool);
 240     void setBatteryInstalled(bool);
 241     void setIsCharging(bool);
 242     void setAtWarnLevel(bool);
 243     void setAtCriticalLevel(bool);
 244
 245     void setCurrentCapacity(unsigned int);
 246     void setMaxCapacity(unsigned int);
 247     void setTimeRemaining(int);
 248     void setAmperage(int);
 249     void setVoltage(unsigned int);
 250     void setCycleCount(unsigned int);
 251     void setAdapterInfo(int);
 252     void setLocation(int);
 253
 254     void setErrorCondition(OSSymbol *);
 255     void setManufacturer(OSSymbol *);
 256     void setModel(OSSymbol *);
 257     void setSerial(OSSymbol *);
 258     void setLegacyIOBatteryInfo(OSDictionary *);
 259
 260 };
 261
 262 #endif