1// Copyright 2014 The Chromium OS Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5syntax = "proto2";
6
7option optimize_for = LITE_RUNTIME;
8
9package power_manager;
10option go_package = "power_manager_proto";
11
12// Included in powerd's SuspendImminent signal, sent when the system is about to
13// suspend.  If any clients previously called RegisterSuspendDelay, suspending
14// will be deferred until they've called powerd's HandleSuspendReadiness method.
15//
16// The general flow is as follows:
17//
18// 1. A client that needs to perform some work before the system can be
19//    suspended listens for SuspendImminent and SuspendDone signals from powerd.
20// 2. The client passes a RegisterSuspendDelayRequest message to powerd's
21//    RegisterSuspendDelay method and receives a RegisterSuspendDelayReply
22//    message in response. The client saves the |delay_id| field from the
23//    response.
24// 3. When the power manager is about to suspend the system, it emits a
25//    SuspendImminent signal containing a SuspendImminent message.
26// 4. Upon receipt of the signal, the client performs any last minute work
27//    that it needs to do and then calls powerd's HandleSuspendReadiness method,
28//    including a SuspendReadinessInfo message with its |delay_id| and the
29//    |suspend_id| field from the SuspendImminent signal.
30// 5. Once powerd has received notification that all registered clients are
31//    ready to suspend, the system will be suspended. If the initial suspend
32//    attempt fails, it will be retried automatically, but additional
33//    SuspendImminent signals will not be emitted.
34// 6. After the suspend request is complete, powerd emits a SuspendDone signal
35//    containing a SuspendDone message. The client should undo any pre-suspend
36//    work that was done in response to the SuspendImminent signal.
37// 7. Before the client exits, it calls UnregisterSuspendDelayRequest with a
38//    UnregisterSuspendDelayRequest message containing its delay ID.
39//
40// Note that the original suspend request may be aborted before all clients have
41// reported readiness; this can happen if a user closes and then quickly opens
42// the lid, for instance. In this case, powerd will emit SuspendDone and return
43// to normal unsuspended behavior without waiting for clients to report
44// readiness. It's unnecessary for clients to report readiness for the original
45// |suspend_id| after a SuspendDone containing the same ID has been received.
46//
47// Clients that start asynchronous operations in response to SuspendImminent
48// should take this possibility into account. One approach is to queue the
49// "undo" operation when SuspendDone is received so it will run after the
50// original operation completes. Note that a second SuspendImminent signal may
51// be emitted before the original operation has completed; in this case, the
52// client may wish to unqueue the undo operation and instead report readiness
53// for the second, current |suspend_id| once the original operation completes.
54message SuspendImminent {
55  // Next ID to use: 2
56
57  enum Reason {
58    // The user inactivity idle timeout was reached.
59    IDLE = 0;
60    // The lid was closed.
61    LID_CLOSED = 1;
62    // Some other reason (e.g. an explicit user request).
63    OTHER = 2;
64  }
65
66  // Unique ID corresponding to this suspend request. This is included in the
67  // SuspendReadinessInfo message passed via HandleSuspendReadiness.
68  optional int32 suspend_id = 1;
69
70  // The reason the system is suspending.
71  optional Reason reason = 2;
72}
73
74// Included in powerd's SuspendDone signal, sent after the system has completed
75// a suspend request. Each SuspendImminent signal will be followed by a
76// SuspendDone signal.
77message SuspendDone {
78  // Next ID to use: 4
79
80  enum WakeupType {
81    UNKNOWN = 0;
82    // Set when last suspend failed.
83    NOT_APPLICABLE = 1;
84    // Resume is triggered by an input device.
85    INPUT = 2;
86    // Resume is triggered by non-input devices (RTC for example).
87    OTHER = 3;
88  }
89  // Unique ID corresponding to the suspend request.
90  optional int32 suspend_id = 1;
91
92  // Wall time that the system was suspended, as given by
93  // base::TimeDelta::ToInternalValue().
94  optional int64 suspend_duration = 2;
95
96   // Type of wakeup source.
97  optional WakeupType wakeup_type = 3;
98}
99
100// Included in calls to powerd's RegisterSuspendDelay method.
101message RegisterSuspendDelayRequest {
102  // Next ID to use: 3
103
104  // Upper bound on the amount of time that the power manager will wait for this
105  // client to call HandleSuspendReadiness before suspending the system, as
106  // given by base::TimeDelta::ToInternalValue(). Setting this to -1 will make
107  // power manager wait for the maximum time delay possible before resuspending.
108  optional int64 timeout = 1;
109
110  // Human-readable description of the delay's purpose (e.g. the name of
111  // the daemon that requested the delay). Only used for debugging.
112  optional string description = 2;
113}
114
115// Included in responses to powerd's RegisterSuspendDelay method.
116message RegisterSuspendDelayReply {
117  // Next ID to use: 2
118
119  // Unique ID assigned to the client that registered this suspend delay. This
120  // is included in later HandleSuspendReadiness and UnregisterSuspendDelay
121  // calls.
122  optional int32 delay_id = 1;
123
124  // Minimum delay the power manager will wait for, for the client that sent the
125  // corresponding |RegisterSuspendDelayRequest|, before resuspending.
126  optional int32 min_delay_timeout_ms = 2;
127}
128
129// Included in calls to powerd's UnregisterSuspendDelay method.
130message UnregisterSuspendDelayRequest {
131  // Next ID to use: 2
132
133  // ID that was returned in response to the original RegisterSuspendDelay call.
134  optional int32 delay_id = 1;
135}
136
137// Included in calls to powerd's HandleSuspendReadiness method.
138message SuspendReadinessInfo {
139  // Next ID to use: 3
140
141  // ID that was returned to the client in response to its invocation of
142  // RegisterSuspendDelay.
143  optional int32 delay_id = 1;
144
145  // ID that was included in the SuspendImminent signal that provoked this
146  // readiness call.
147  optional int32 suspend_id = 2;
148}
149
150// Included in calls to powerd's RecordDarkResumeWakeReason method.
151message DarkResumeWakeReason {
152  // Next ID to use: 2
153
154  // Wake reason that caused the current dark resume.
155  optional string wake_reason = 1;
156}
157
158