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