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
  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