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