iokit/IOKit/pwr_mgt/IOPMchangeNoteList.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_OSREFERENCE_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
  10  * License may not be used to create, or enable the creation or
  11  * redistribution of, unlawful or unlicensed copies of an Apple operating
  12  * system, or to circumvent, violate, or enable the circumvention or
  13  * violation of, any terms of an Apple operating system software license
  14  * agreement.
  15  *
  16  * Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29  */
  30 #include <libkern/c++/OSObject.h>
  31 #include <IOKit/IOReturn.h>
  32
  33 class IOPowerConnection;
  34
  35 // This is a list of State Changes which are in progress.  Its purpose is to keep track of the
  36 // notifications and acknowledgements caused by state change.  A change is added to the list
  37 // when either our parent notifies us that the power domain is changing state or when we decide
  38 // to change power to our device or domain.
  39 //
  40 // A change is removed from the list when all interested parties have been informed of the upcoming
  41 // change, all of them have acknowledged the notification, the change has been made, all interested
  42 // parties have been informed that the change was made, and all of them have acknowledged.
  43 //
  44 // The list is strictly first-in, first-out.  It is implemented as a circular list in a linear
  45 // array.  There are two pointers into the array.  The circular list is empty when these two
  46 // pointers are equal.
  47
  48 // More specifically, a change note is put into the array when one of these things happens:
  49 //   the device decides it is idle and needs to reduce power. (changePowerStateTo)
  50 //   the device decides it is not idle and needs to increase power. (changePowerStateTo)
  51 //   the controlling driver requests a state change. (changePowerStateTo)
  52 //   some client needs to use the device but it is powered down. (makeUsable)
  53 //   the parent says the domain power is changing. (powerStateWillChangeTo)
  54 //   a child says it no longer needs power, and all other children are similarly idle. (requestDomainState)
  55 //.  a child wants more power in the domain so it can raise its power state. (requestDomainState)
  56 //
  57 // A change note is removed from the array when all interested drivers and power domain
  58 // children have acknowledged the change.
  59
  60 // Each change note contains:
  61 // A flag field which describes the change.
  62 // Which power state the device will be in after the change.
  63 // The power flags which describe the result of this change.
  64
  65 struct changeNoteItem{
  66 unsigned long           flags;
  67 unsigned long           newStateNumber;
  68 IOPMPowerFlags          outputPowerCharacter;
  69 IOPMPowerFlags          inputPowerRequirement;
  70 IOPMPowerFlags          domainState;
  71 IOPowerConnection *     parent;
  72 IOPMPowerFlags          singleParentState;
  73 IOPMPowerFlags          capabilityFlags;
  74 };
  75
  76 typedef struct changeNoteItem changeNoteItem;
  77
  78
  79                                         // flags field
  80
  81 #define IOPMParentInitiated             1               // this power change initiated by our  parent
  82 #define IOPMWeInitiated         2               // this power change initiated by this device (not parent)
  83 #define IOPMNotDone             4               // we couldn't make this change
  84 #define IOPMNotInUse            8               // this list element not currently in use
  85 #define IOPMDomainWillChange    16              // parent change started by PowerDomainWillChangeTo
  86 #define IOPMDomainDidChange     32              // parent change started by PowerDomainDidChangeTo
  87
  88
  89 // Length of change note list is maximum 5.  There cannot be two adjacent device-initiated change notes unless
  90 // one is currently being actioned, because two adjacent in-active device-initiated changes are always collapsed
  91 // into one, and there cannot be more than two parent-initiated change notes in the queue (from one parent),
  92 // because the parent does not
  93 // initiate a change (by calling domainStateWillChange) until everybody has acknowledged the previous one
  94 // (by calling domainStateDidChange), although if we are the last to send that acknowledgement, the change we
  95 // are acknowledging will still be in the queue as we acknowledge, and at that point the parent can give us another
  96 // (by callingdomainStateWillChange).  So we need room for two parent changes, two non-adjacent device changes,
  97 // one more per additional parent, say two more,
  98 // and room for one more device change to get into the queue before collapsing it with its neighbor.  In this case, seven
  99 // entryies suffices.  Or, we need
 100 // room for two adjacent device changes (one in progress), a parent change, another device change, another parent change,
 101 // another device change, another parent change, another device change, plus
 102 // one more device change to get into the queue before collapsing it with its neighbor.  Nine entries in this case.
 103 // I'm not sure what irrationallity causes me to code for twenty entries in the queue.
 104 #define IOPMMaxChangeNotes 20
 105
 106 class IOPMchangeNoteList :public OSObject
 107 {
 108 OSDeclareDefaultStructors(IOPMchangeNoteList)
 109
 110 private:
 111     unsigned long               firstInList;            // points to oldest active change note in list
 112     unsigned long               firstUnused;            // points just beyond newest change note in list
 113
 114 public:
 115
 116         changeNoteItem          changeNote[IOPMMaxChangeNotes];
 117
 118
 119 void initialize ( void );
 120
 121 long createChangeNote ( void );
 122
 123 long currentChange ( void );
 124
 125 long latestChange ( void );
 126
 127 IOReturn releaseHeadChangeNote ( void );
 128
 129 IOReturn releaseTailChangeNote ( void );
 130
 131 bool changeNoteInUse ( unsigned long ordinal );
 132
 133 long nextChangeNote ( unsigned long ordinal );
 134
 135 unsigned long increment (unsigned long ordinal );
 136
 137 unsigned long decrement (unsigned long ordinal );
 138
 139 long previousChangeNote (unsigned long ordinal );
 140
 141 bool listEmpty ( void );
 142
 143 };