Return to IOPMchangeNoteList.h CVS log

Up to [Apple XNU] / XNU / iokit / IOKit / pwr_mgt

Annotation of XNU/iokit/IOKit/pwr_mgt/IOPMchangeNoteList.h, revision 1.1

1.1     ! root        1: /*
        !             2:  * Copyright (c) 1998-2000 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: #include <libkern/c++/OSObject.h>
        !            23: #include <IOKit/IOReturn.h>
        !            24: 
        !            25: // This is a list of State Changes which are in progress.  Its purpose is to keep track of the
        !            26: // notifications and acknowledgements caused by state change.  A change is added to the list
        !            27: // when either our parent notifies us that the power domain is changing state or when we decide
        !            28: // to change power to our device or domain.
        !            29: //
        !            30: // A change is removed from the list when all interested parties have been informed of the upcoming
        !            31: // change, all of them have acknowledged the notification, the change has been made, all interested
        !            32: // parties have been informed that the change was made, and all of them have acknowledged.
        !            33: //
        !            34: // The list is strictly first-in, first-out.  It is implemented as a circular list in a linear
        !            35: // array.  There are two pointers into the array.  The circular list is empty when these two
        !            36: // pointers are equal.
        !            37: 
        !            38: // More specifically, a change note is put into the array when one of these things happens:
        !            39: //   the device decides it is idle and needs to reduce power. (changeStateTo)
        !            40: //   the device decides it is not idle and needs to increase power. (changeStateTo)
        !            41: //   the controlling driver requests a state change. (changeStateTo)
        !            42: //   some client needs to use the device but it is powered down. (makeUsable)
        !            43: //   the parent says the domain power is changing. (powerStateWillChangeTo)
        !            44: //   a child says it no longer needs power, and all other children are similarly idle. (requestDomainState)
        !            45: //.  a child wants more power in the domain so it can raise its power state. (requestDomainState)
        !            46: //
        !            47: // A change note is removed from the array when all interested drivers and power domain
        !            48: // children have acknowledged the change.
        !            49: 
        !            50: // Each change note contains:
        !            51: // A flag field which describes the change.
        !            52: // Which power state the device will be in after the change.
        !            53: // The power flags which describe the result of this change.
        !            54: 
        !            55: struct changeNoteItem{
        !            56: unsigned long          flags;
        !            57: unsigned long          newStateNumber;
        !            58: IOPMPowerFlags         outputPowerCharacter;
        !            59: IOPMPowerFlags         inputPowerRequirement;
        !            60: IOPMPowerFlags         domainState;
        !            61: IOPMPowerFlags         capabilityFlags;
        !            62: };
        !            63: 
        !            64: typedef struct changeNoteItem changeNoteItem;
        !            65: 
        !            66: 
        !            67:                                        // flags field
        !            68:        
        !            69: #define IOPMParentInitiated            1               // this power change initiated by our  parent
        !            70: #define IOPMWeInitiated                        2               // this power change initiated by this device (not parent)
        !            71: #define IOPMNotDone                    4               // we couldn't make this change
        !            72: #define IOPMNotInUse                   8               // this list element not currently in use
        !            73: 
        !            74: 
        !            75: // Length of change note list is maximum 5.  There cannot be two adjacent device-initiated change notes unless
        !            76: // one is currently being actioned, because two adjacent in-active device-initiated changes are always collapsed
        !            77: // into one, and there cannot be more than two parent-initiated change notes in the queue, because the parent does not
        !            78: // initiate a change (by calling domainStateWillChange) until everybody has acknowledged the previous one
        !            79: // (by calling domainStateDidChange), although if we are the last to send that acknowledgement, the change we
        !            80: // are acknowledging will still be in the queue as we acknowledge, and at that point the parent can give us another
        !            81: // (by callingdomainStateWillChange).  So we need room for two parent changes, two non-adjacent device changes,
        !            82: // and room for one more device change to get into the queue before collapsing it with its neighbor.  Or, we need
        !            83: // room for two adjacent device changes (one in progress), a parent change, another device change, and room for
        !            84: // one more device change to get into the queue before collapsing it with its neighbor.  Five entries in either case. 
        !            85: // I'm not sure what irrationallity causes me to code for ten entries in the queue.
        !            86: #define IOPMMaxChangeNotes 10
        !            87: 
        !            88: class IOPMchangeNoteList :public OSObject
        !            89: {
        !            90: OSDeclareDefaultStructors(IOPMchangeNoteList)
        !            91:     
        !            92: private:
        !            93:     unsigned long              firstInList;            // points to oldest active change note in list
        !            94:     unsigned long              firstUnused;            // points just beyond newest change note in list
        !            95: 
        !            96: public:
        !            97: 
        !            98:         changeNoteItem         changeNote[IOPMMaxChangeNotes];
        !            99:     
        !           100: 
        !           101: void initialize ( void );
        !           102: 
        !           103: long createChangeNote ( void );
        !           104: 
        !           105: long currentChange ( void );
        !           106: 
        !           107: long latestChange ( void );
        !           108: 
        !           109: IOReturn releaseHeadChangeNote ( void );
        !           110: 
        !           111: IOReturn releaseTailChangeNote ( void );
        !           112: 
        !           113: bool changeNoteInUse ( unsigned long ordinal );
        !           114: 
        !           115: long nextChangeNote ( unsigned long ordinal );
        !           116: 
        !           117: unsigned long increment (unsigned long ordinal );
        !           118: 
        !           119: unsigned long decrement (unsigned long ordinal );
        !           120: 
        !           121: long previousChangeNote (unsigned long ordinal );
        !           122: 
        !           123: bool listEmpty ( void );
        !           124: 
        !           125: };

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.