xnu-3247.1.106.tar.gz

[apple/xnu.git] / iokit / IOKit / pwr_mgt / IOPMPowerSource.h

diff --git a/iokit/IOKit/pwr_mgt/IOPMPowerSource.h b/iokit/IOKit/pwr_mgt/IOPMPowerSource.h
index b398ee81a42c5c78a1807e3f8260cf826c84bed4..cd0db25bf743613106d120db491f2a7640138c10 100644 (file)
--- a/iokit/IOKit/pwr_mgt/IOPMPowerSource.h
+++ b/iokit/IOKit/pwr_mgt/IOPMPowerSource.h
@@ -40,7 +40,7 @@ enum {
     kTenMinutesInSeconds = 600
 };
 
-/* class IOPMPowerSource
+/*! @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(),
@@ -49,18 +49,19 @@ enum {
  *
  * A subclassing driver that doesn't want to do anything fancy should:
  *   1. Subclass IOPMPowerSource
- *   3. Install its own battery change notifications or polling routine that can
+ *   2. Install its own battery change notifications or polling routine that can
  *          converse with actual battery hardware.
- *   4. When battery state changes, change the relevant member variables
+ *   3. When battery state changes, change the relevant member variables
  *          through setCurrentCapacity() style accessors.
- *   5. Call updateStatus() on itself when all such settings have been updated.
+ *   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
+ * Settings:
  *
+ * <pre>
  * ExternalConnected
  * Type: bool
  * IORegistry Key: kIOPMPSExternalConnectedKey
@@ -137,6 +138,15 @@ enum {
  * 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
@@ -145,12 +155,16 @@ enum {
  * Serial
  * Type: OSSymbol
  * IORegistry Key: kIOPMPSSerialKey
- * String describing serial number  or unique info
+ * 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 
+ * </pre>
  */
 
 class IOPMPowerSource : public IOService
@@ -160,9 +174,17 @@ class IOPMPowerSource : public IOService
     friend class IOPMPowerSourceList;
 
  protected:
-    // Tracking for IOPMPowerSourceList
-    IOPMPowerSource         *nextInList;
+
+/*! @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;
@@ -185,6 +207,9 @@ class IOPMPowerSource : public IOService
     const OSSymbol *serialKey;
     const OSSymbol *batteryInfoKey;
 
+    // Tracking for IOPMPowerSourceList
+    IOPMPowerSource         *nextInList;
+
  public:
 
 /*! @function powerSource
@@ -193,9 +218,9 @@ class IOPMPowerSource : public IOService
 */
     static IOPMPowerSource *powerSource(void);
 
-    virtual bool init(void);
+    virtual bool init(void) APPLE_KEXT_OVERRIDE;
     
-    virtual void free(void);
+    virtual void free(void) APPLE_KEXT_OVERRIDE;
 
 /*! @function updateStatus
     @abstract Must be called by physical battery controller when battery state
@@ -233,7 +258,10 @@ class IOPMPowerSource : public IOService
     OSSymbol *serial(void);
     OSDictionary *legacyIOBatteryInfo(void);
     
+    OSObject *getPSProperty(const OSSymbol *);
+    
 protected:
+
 /* Protected "setter" methods for subclasses
  * Subclasses should use these setters to modify all battery properties.
  * 
@@ -262,7 +290,13 @@ protected:
     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