裝置電源管理

在 Fuchsia 中,驅動程式會與驅動程式架構和 Fuchsia 電源架構 (包括電源代理和系統活動管理工具) 整合,參與電源管理。

系統暫停和繼續

如果平台已啟用系統暫停功能,驅動程式管理員會為繫結至驅動程式庫的每個節點建立二進位電源元素,其中 0 的電源等級為關閉/暫停,1 的電源等級為開啟/啟用。電源元素的依附元件會包含節點祖系的電源元素 (繫結至驅動程式庫程式),以及其他幾個電源元素,例如 CPU 電源元素、儲存空間電源元素等。這可確保節點的暫停/恢復順序正確,繫結的驅動程式庫不會在祖系節點暫停時,嘗試使用祖系節點提供的服務。

處理暫停和繼續

驅動程式可以透過幾種不同方式處理暫停和繼續作業,如下所述。

執行階段管理的調度工具

建議驅動程式啟用執行階段管理的調度工具,以支援暫停和繼續。在這種狀態下,驅動程式代管程序 (而非驅動程式庫程式執行個體) 會執行與驅動程式庫電源元素相關聯的 fuchsia.power.broker/ElementRunner,並與驅動程式庫程式執行階段協調電源轉換:

  1. 暫停:當驅動程式庫的電源元素轉換為暫停狀態 (0) 時,驅動程式庫執行階段會:
    • 暫停所有電源管理調度器。
    • 將已排入佇列和新抵達的工作移至休眠佇列。
    • 等待正在執行的回呼完成。
    • 在驅動程式庫預設調度器的隨時可用檢視畫面上,叫用驅動程式庫程式的暫停掛鉤。
  2. 繼續:當驅動程式庫的電源元素轉換為啟用狀態 (1) 或註冊的喚醒向量觸發時,執行階段會:
    • 先在 AOD 叫用驅動程式的繼續掛鉤,以便還原硬體狀態。
    • 取消暫停受電源管理的調度器 (先執行任何觸發的喚醒向量任務,再執行佇列任務)。
  3. 在暫停時停止:如果 Driver Framework 在驅動程式暫停時停止驅動程式庫,執行階段會:
    • 繼續執行驅動程式庫 (SystemResume 或 system_resume)。
    • 叫用驅動程式庫的停靠點掛鉤 (Stop 或 stop)。

啟用執行階段管理的調度工具

如要啟用執行階段管理的調度工具,請在驅動程式庫的 .cml 檔案中設定 power_managed_dispatchers_enabled: "true"。加入 driver_component/power_managed_dispatchers.shard.cml 也會為您執行這項操作,同時轉送必要的電源通訊協定:

include: [
    // Enables runtime-managed dispatchers.
    "driver_component/power_managed_dispatchers.shard.cml",
],
program: {
    runner: "driver",
    binary: "driver/my_driver.so",
    bind: "meta/bind/my_driver.bindbc",
},

驅動程式可以實作暫停和繼續生命週期方法,在電源管理調度器暫停後,將硬體置於低功耗狀態,並在電源管理調度器喚醒後取消暫停前,還原硬體狀態。

當驅動程式本身註冊的執行階段喚醒向量 (例如中斷或繫結至電源管理調度器的通道等待) 觸發喚醒時,驅動程式代管程序會自動透過 fuchsia.power.broker/Topology.Lease 取得驅動程式庫程式電源元素的租約,並將 LeaseToken (C++ 中的 pe_lease 或 Rust 中的 lease) 傳遞至恢復掛鉤。如果驅動程式庫是做為其他驅動程式庫的依附元件恢復,或是在系統層級恢復期間恢復,則租約參數為 std::nullopt (或 None)。

C++

在 C++ 中,覆寫 fdf::DriverBase2 的 SystemSuspend 和 SystemResume:

#include <lib/driver/component/cpp/driver_base2.h>

class MyDriver : public fdf::DriverBase2 {
 public:
  MyDriver() : fdf::DriverBase2("my_driver") {}

  void SystemSuspend(fdf::SuspendCompleter completer) override {
    // Put hardware into low-power mode or save register state.
    completer(zx::ok());
  }

  void SystemResume(std::optional<fuchsia_power_broker::LeaseToken> pe_lease,
                    fdf::ResumeCompleter completer) override {
    // Restore hardware configuration. If woken by a wake vector, retain
    // `pe_lease` until the wake task finishes handling the event.
    completer(zx::ok());
  }
};

荒漠油廠

在 Rust 中,請在 fdf_component::Driver 特徵上實作 system_suspend 和 system_resume:

impl fdf_component::Driver for MyDriver {
    async fn system_suspend(&self) -> Result<(), fdf_component::DriverError> {
        // Put hardware into low-power mode or save register state.
        Ok(())
    }

    async fn system_resume(
        &self,
        lease: Option<zx::EventPair>,
    ) -> Result<(), fdf_component::DriverError> {
        // Restore hardware configuration. If woken by a wake vector, retain
        // `lease` until the wake task finishes handling the event.
        Ok(())
    }
}

駕駛人擁有的暫停

如果駕駛人想聽取暫停和繼續通知,但不希望調度員在暫停期間暫停,則可採用這種方法。

啟用驅動程式庫擁有的暫停功能

在驅動程式庫的 .cml 檔案中設定 suspend_enabled: "true"。

如果將 suspend_enabled 設為 "true",請務必將 power_managed_dispatchers_enabled 設為 "false" (或省略),否則 power_managed_dispatchers_enabled 會優先執行,且暫停事件一律不會轉送至 fdf_power::Suspendable (SuspendableDriver)。

program: {
    runner: "driver",
    binary: "driver/my_driver.so",
    bind: "meta/bind/my_driver.bindbc",
    suspend_enabled: "true",
},

C++

在 C++ 中,從 fdf_power::Suspendable 繼承、提供 take_power_element_runner(),並在 Start 期間呼叫 InitializeSuspend():

#include <lib/driver/component/cpp/driver_base2.h>
#include <lib/driver/power/cpp/suspend.h>

class MyDriver : public fdf::DriverBase2,
                 public fdf_power::Suspendable<MyDriver> {
 public:
  MyDriver() : fdf::DriverBase2("my_driver") {}

  zx::result<> Start(fdf::DriverContext context) override {
    power_element_runner_ = context.take_power_element_runner();
    if (zx::result result =
            InitializeSuspend(dispatcher(), context.incoming(), name());
        result.is_error()) {
      return result.take_error();
    }
    return zx::ok();
  }

  void Suspend(fdf_power::SuspendCompleter completer) override {
    // Drain internal queues and put hardware into a low-power state.
    completer();
  }

  void Resume(fdf_power::ResumeCompleter completer) override {
    // Restore hardware state and resume internal queues.
    completer();
  }

  bool SuspendEnabled() override { return true; }

  std::optional<fidl::ServerEnd<fuchsia_power_broker::ElementRunner>>
  take_power_element_runner() {
    return std::move(power_element_runner_);
  }

 private:
  std::optional<fidl::ServerEnd<fuchsia_power_broker::ElementRunner>>
      power_element_runner_;
};

荒漠油廠

在 Rust 中實作 fdf_power::SuspendableDriver,並註冊以 fdf_power::Suspendable 包裝的驅動程式庫:

use fdf_component::{Driver, DriverContext, DriverError, driver_register};
use fdf_power::{Suspendable, SuspendableDriver};

impl SuspendableDriver for MyDriver {
    async fn suspend(&self) {
        // Drain internal queues and put hardware into a low-power state.
    }

    async fn resume(&self) {
        // Restore hardware state and resume internal queues.
    }

    fn suspend_enabled(&self) -> bool {
        true
    }
}

driver_register!(Suspendable<MyDriver>);

自訂電源元素

除了驅動程式管理員建立的電源元素外,驅動程式也可以透過 fuchsia.power.broker/Topology (或 //sdk/lib/driver/power/cpp 中的輔助程式庫),手動建立及管理自訂電源元素,並設定各種電源等級和依附元件。自訂電源元素可與 power_managed_dispatchers_enabled 或 suspend_enabled 搭配使用,但自訂電源元素的等級轉換不會暫停驅動程式庫程式的調度工具。

電源租約和喚醒租約

  • Power Broker 租約:當註冊的喚醒向量透過執行階段管理的調度器喚醒暫停的驅動程式庫時,驅動程式代管程序會透過 fuchsia.power.broker/Topology.Lease 取得驅動程式庫程式電源元素的租約,並將其傳遞給 SystemResume (system_resume)。由於驅動程式庫的電源元素取決於其祖先驅動程式和 CPU 電源元素,因此保留此租約可讓裝置和 CPU 保持活動狀態,直到喚醒事件處理完畢或交給上游處理。
  • 系統喚醒租約:如果驅動程式需要直接防止系統在執行階段管理的喚醒向量之外暫停,可以向系統活動調節器 (fuchsia.power.system/ActivityGovernor.AcquireWakeLease,由 fdf_power::WakeLeaseProvider 和 fdf_power::TimeoutWakeLease 等輔助程式包裝) 取得喚醒租約。

如要進一步瞭解電源架構和測試暫停/恢復功能,請參閱「測試暫停和恢復功能」。