X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/21362eb3e66fd2c787aee132bce100a44d71a99c..d9a64523371fa019c4575bb400cbbc3a50ac9903:/iokit/IOKit/pwr_mgt/IOPMPowerSource.h diff --git a/iokit/IOKit/pwr_mgt/IOPMPowerSource.h b/iokit/IOKit/pwr_mgt/IOPMPowerSource.h index 047eb7f39..015c70a05 100644 --- a/iokit/IOKit/pwr_mgt/IOPMPowerSource.h +++ b/iokit/IOKit/pwr_mgt/IOPMPowerSource.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000 Apple Computer, Inc. All rights reserved. + * Copyright (c) 1998-2005 Apple Computer, Inc. All rights reserved. * * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ * @@ -25,59 +25,279 @@ * * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ */ + +#ifndef _IOPMPowerSource_h_ +#define _IOPMPowerSource_h_ + #include +#include #include #include -#include "IOPM.h" +#include -class ApplePMU; +enum { + kSecondsPerHour = 3600, + kTenMinutesInSeconds = 600 +}; -const unsigned long kSecondsPerHour = (60*60); -const unsigned long kTenMinutesInSeconds = (10 * 60); -// our battery (power source) object +/*! @class IOPMPowerSource + * + * See IOKit/pwr_mgt/IOPM.h for power source keys relevant to this class. These + * report-type keys are required for calls to IOPMPowerSource::setReportables(), + * and they define the IORegistry interface through which data is passed back + * up to the rest of the system. + * + * A subclassing driver that doesn't want to do anything fancy should: + * 1. Subclass IOPMPowerSource + * 2. Install its own battery change notifications or polling routine that can + * converse with actual battery hardware. + * 3. When battery state changes, change the relevant member variables + * through setCurrentCapacity() style accessors. + * 4. Call updateStatus() on itself when all such settings have been updated. + * + * The subclass driver should also initially populate its settings and call + * updateStatus() on launch. + * + * + * Settings: + * + * 
+ * ExternalConnected
+ * Type: bool
+ * IORegistry Key: kIOPMPSExternalConnectedKey
+ * True if computer is drawing external power 
+ *
+ * ExternalChargeCapable
+ * Type: bool
+ * IORegistry Key: kIOPMPSExternalChargeCapableKey
+ * True if external power is capable of charging internal battery
+ *
+ * BatteryInstalled
+ * Type: bool
+ * IORegistry Key: kIOPMPSBatteryInstalledKey
+ * True if a battery is present; false if removed
+ *
+ * IsCharging
+ * Type: bool
+ * IORegistry Key: kIOPMPSIsChargingKey
+ * True if battery is charging itself from external power
+ *
+ * AtWarnLevel
+ * Type: bool
+ * IORegistry Key: kIOPMPSAtWarnLevelKey
+ * True if draining battery capacity and past warn level
+ *
+ * AtCriticalLevel
+ * Type: bool
+ * IORegistry Key: kIOPMPSAtCriticalLevelKey
+ * True if draining battery capacity and past critical level
+ *
+ * CurrentCapacity
+ * MaxCapacity
+ * Type: unsigned int
+ * IORegistry Key: kIOPMPSCurrentCapacityKey, kIOPMPSMaxCapacityKey
+ * Capacity measured in mAh
+ *
+ * TimeRemaining
+ * Type: int
+ * IORegistry Key: kIOPMPSTimeRemainingKey
+ * Time remaining measured in minutes
+ *
+ * Amperage
+ * Type: int
+ * IORegistry Key: kIOPMPSAmperageKey
+ * Current is measured in mA
+ *
+ * Voltage
+ * Type: unsigned int
+ * IORegistry Key: kIOPMPSVoltageKey
+ * Voltage measured in mV
+ *
+ * CycleCount
+ * Type: unsigned int
+ * IORegistry Key: kIOPMPSCycleCountKey
+ * Number of charge/discharge cycles
+ *
+ * AdapterInfo
+ * Type: int
+ * IORegistry Key: kIOPMPSAdapterInfoKey
+ * Power adapter information
+ *
+ * Location
+ * Type: int
+ * IORegistry Key: kIOPMPSLocationKey
+ * Clue about battery's location in machine - Left vs. Right
+ *
+ * ErrorCondition
+ * Type: OSSymbol
+ * IORegistry Key: kIOPMPSErrorConditionKey
+ * String describing error state of battery
+ *
+ * Manufacturer
+ * Type: OSSymbol
+ * IORegistry Key: kIOPMPSManufacturerKey
+ * String describing battery manufacturer
+ *
+ * Manufactured Date
+ * Type: unsigned 16-bit bitfield
+ * IORegistry Key: kIOPMPSManufactureDateKey
+ * Date is published in a bitfield per the Smart Battery Data spec rev 1.1 
+ * in section 5.1.26
+ *   Bits 0...4 => day (value 1-31; 5 bits)
+ *   Bits 5...8 => month (value 1-12; 4 bits)
+ *   Bits 9...15 => years since 1980 (value 0-127; 7 bits)
+ *
+ * Model
+ * Type: OSSymbol
+ * IORegistry Key: kIOPMPSModelKey
+ * String describing model number
+ *
+ * Serial
+ * Type: OSSymbol
+ * IORegistry Key: kIOPMPSSerialKey
+ * String describing serial number or unique info
+ * The serial number published hear bears no correspondence to the Apple serial
+ * number printed on each battery. This is a manufacturer serial number with 
+ * no correlation to the printed serial number.
+ *
+ * LegacyIOBatteryInfo
+ * Type: OSDictionary
+ * IORegistry Key: kIOPMPSLegacyBatteryInfoKey
+ * Dictionary conforming to the OS X 10.0-10.4 
+ *
+ */ -class IOPMPowerSource : public OSObject +class IOPMPowerSource : public IOService { OSDeclareDefaultStructors(IOPMPowerSource) + friend class IOPMPowerSourceList; + protected: - UInt32 bFlags; - UInt32 bTimeRemaining; - UInt16 bCurCapacity; - UInt16 bMaxCapacity; - SInt16 bCurrent; - UInt16 bVoltage; - UInt16 bBatteryIndex; +/*! @var settingsChangedSinceLastUpdate + * Used by subclasses to determine if any settings have been modified via the + * accessors below since last call to update(). true is settings have changed; + * false otherwise. + */ + bool settingsChangedSinceUpdate; + +/*! @var properties + * Stores power source state + */ + OSDictionary *properties; + + const OSSymbol *externalConnectedKey; + const OSSymbol *externalChargeCapableKey; + const OSSymbol *batteryInstalledKey; + const OSSymbol *chargingKey; + const OSSymbol *warnLevelKey; + const OSSymbol *criticalLevelKey; + const OSSymbol *currentCapacityKey; + const OSSymbol *maxCapacityKey; + const OSSymbol *timeRemainingKey; + const OSSymbol *amperageKey; + const OSSymbol *voltageKey; + const OSSymbol *cycleCountKey; + const OSSymbol *adapterInfoKey; + const OSSymbol *locationKey; + const OSSymbol *errorConditionKey; + const OSSymbol *manufacturerKey; + const OSSymbol *modelKey; + const OSSymbol *serialKey; + const OSSymbol *batteryInfoKey; + + // Tracking for IOPMPowerSourceList + IOPMPowerSource *nextInList; public: - IOPMPowerSource * nextInList; +/*! @function powerSource + @abstract Creates a new IOPMPowerSource nub. Must be attached to IORegistry, + and registered by provider. +*/ + static IOPMPowerSource *powerSource(void); - bool init (unsigned short whichBatteryIndex); - unsigned long capacityPercentRemaining (void); - bool atWarnLevel (void); - bool depleted (void); + virtual bool init(void) APPLE_KEXT_OVERRIDE; + + virtual void free(void) APPLE_KEXT_OVERRIDE; - // accessors +/*! @function updateStatus + @abstract Must be called by physical battery controller when battery state + has changed significantly. + @discussion The system will not poll this object for battery updates. Rather \ + the battery's controller must call updateStatus() every time state changes \ + and the settings will be relayed to higher levels of power management. \ + The subclassing driver should override this only if the driver needs to add \ + new settings to the base class. +*/ + virtual void updateStatus(void); - bool isInstalled (void); - bool isCharging (void); - bool acConnected (void); - unsigned long timeRemaining (void); - unsigned long maxCapacity (void); - unsigned long curCapacity (void); - long currentDrawn (void); - unsigned long voltage (void); +/* Public accessors for battery state + */ + bool externalConnected(void); + bool externalChargeCapable(void); + bool batteryInstalled(void); + bool isCharging(void); + bool atWarnLevel(void); + bool atCriticalLevel(void); - // calculations + unsigned int currentCapacity(void); + unsigned int maxCapacity(void); + unsigned int capacityPercentRemaining(void); + int timeRemaining(void); + int amperage(void); + unsigned int voltage(void); + unsigned int cycleCount(void); + int adapterInfo(void); + int location(void); + + OSSymbol *errorCondition(void); + OSSymbol *manufacturer(void); + OSSymbol *model(void); + OSSymbol *serial(void); + OSDictionary *legacyIOBatteryInfo(void); + + OSObject *getPSProperty(const OSSymbol *); + +protected: - // function updateStatus is called whenever the system needs - // to obtain the latest power source state...must be overridden - // by subclasses. - virtual void updateStatus (void); -}; +/* Protected "setter" methods for subclasses + * Subclasses should use these setters to modify all battery properties. + * + * Subclasses must follow all property changes with a call to updateStatus() + * to flush settings changes to upper level battery API clients. + * + */ + void setExternalConnected(bool); + void setExternalChargeCapable(bool); + void setBatteryInstalled(bool); + void setIsCharging(bool); + void setAtWarnLevel(bool); + void setAtCriticalLevel(bool); + + void setCurrentCapacity(unsigned int); + void setMaxCapacity(unsigned int); + void setTimeRemaining(int); + void setAmperage(int); + void setVoltage(unsigned int); + void setCycleCount(unsigned int); + void setAdapterInfo(int); + void setLocation(int); + void setErrorCondition(OSSymbol *); + void setManufacturer(OSSymbol *); + void setModel(OSSymbol *); + void setSerial(OSSymbol *); + void setLegacyIOBatteryInfo(OSDictionary *); +/*! All of these methods funnel through the generic accessor method + setPSProperty. Caller can pass in any arbitrary OSSymbol key, and + that value will be stored in the PM settings dictionary, and relayed + onto the IORegistry at update time. + */ + void setPSProperty(const OSSymbol *, OSObject *); +}; +#endif