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