src/third_party/cros_system_api/dbus/power_manager/suspend.proto

   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 message SuspendImminent {
  39   // Next ID to use: 2
  40
  41   // Unique ID corresponding to this suspend request. This is included in the
  42   // SuspendReadinessInfo message passed via HandleSuspendReadiness.
  43   optional int32 suspend_id = 1;
  44 }
  45
  46 // Included in powerd's SuspendDone signal, sent after the system has completed
  47 // a suspend request. Each SuspendImminent signal will be followed by a
  48 // SuspendDone signal.
  49 message SuspendDone {
  50   // Next ID to use: 3
  51
  52   // Unique ID corresponding to the suspend request.
  53   optional int32 suspend_id = 1;
  54
  55   // Wall time that the system was suspended, as given by
  56   // base::TimeDelta::ToInternalValue().
  57   optional int64 suspend_duration = 2;
  58 }
  59
  60 // Included in calls to powerd's RegisterSuspendDelay method.
  61 message RegisterSuspendDelayRequest {
  62   // Next ID to use: 3
  63
  64   // Upper bound on the amount of time that the power manager will wait for this
  65   // client to call HandleSuspendReadiness before suspending the system, as
  66   // given by base::TimeDelta::ToInternalValue().
  67   optional int64 timeout = 1;
  68
  69   // Human-readable description of the delay's purpose (e.g. the name of
  70   // the daemon that requested the delay). Only used for debugging.
  71   optional string description = 2;
  72 }
  73
  74 // Included in responses to powerd's RegisterSuspendDelay method.
  75 message RegisterSuspendDelayReply {
  76   // Next ID to use: 2
  77
  78   // Unique ID assigned to the client that registered this suspend delay. This
  79   // is included in later HandleSuspendReadiness and UnregisterSuspendDelay
  80   // calls.
  81   optional int32 delay_id = 1;
  82 }
  83
  84 // Included in calls to powerd's UnregisterSuspendDelay method.
  85 message UnregisterSuspendDelayRequest {
  86   // Next ID to use: 2
  87
  88   // ID that was returned in response to the original RegisterSuspendDelay call.
  89   optional int32 delay_id = 1;
  90 }
  91
  92 // Included in calls to powerd's HandleSuspendReadiness method.
  93 message SuspendReadinessInfo {
  94   // Next ID to use: 3
  95
  96   // ID that was returned to the client in response to its invocation of
  97   // RegisterSuspendDelay.
  98   optional int32 delay_id = 1;
  99
 100   // ID that was included in the SuspendImminent signal that provoked this
 101   // readiness call.
 102   optional int32 suspend_id = 2;
 103 }