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; 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. 53message 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. 76message 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. 88message 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. 102message 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. 112message 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. 120message 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. 133message 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