电源管理
=============

概述
------
PM 模块提供电源管理功能。

功能特性
-------------------

- 提供电源管理基础功能。
- 支持相关设备注册参与电源管理。
- 支持投票控制低功耗功能。
- 支持休眠管理功能。
- 唤醒源管理
- 关机模式

深度睡眠
---------
系统在空闲时自动进入休眠状态，当有唤醒源中断产生或系统 timer 到时时唤醒系统继续运行。

系统在深度睡眠期间，外设和cpu将停止工作并掉电，内存处于深度睡眠保持模式

- 依赖关系

  系统进入休眠状态时软件和大部分外设不能继续工作，故进入休眠前需检查所有模块的状态，确保对系统电源无依赖方可进入休眠

  所有对电源有依赖的模块可调用 :c:func:`wq_power_mgnt_register_node` 注册依赖到电源管理，系统进入休眠前将检查依赖情况

  依赖检查的回调原型：

  .. code:: c
    :number-lines:

    typedef uint32_t (*idle_check_callback)(uint32_t time_ms);

  参数 `time_ms`: 系统请求的休眠时间。
  返回值 `uint32_t`: 模块空闲的时间，以毫秒为单位。

  系统当前已添硬件外设的依赖关系，如果外设正在工作，则系统不会进入休眠状态

- 保存与恢复

  系统进入休眠后，大部分外设将处于掉电状态，唤醒后，将处于复位状态，需要对睡眠前的外设状态进行保存并在唤醒后进行恢复

  当前系统已对休眠时掉电的外设添加了保存和恢复，应用无需关心，唤醒后可继续正常使用。

- 唤醒源

  进入低功耗模式后，已下中断具备对系统的唤醒能力：

  - AONGPIO, 仅*电平*中断支持唤醒, 仅ACORE
  - CHARGER, 5v/3.3v, 仅支持电平中断唤醒, 仅ACORE
  - TOUCH_KEY, 内置触摸设备中断, 仅ACORE
  - DEBOUNCE, 按键中断, 仅ACORE
  - IPC, 核间通信, 仅ACORE
  - BT, 仅BCORE

  系统在无外部唤醒源时，在os指定的时间也会自动唤醒，故使用 :c:func:`os_delay` 和 `os_timer` 也可使系统在指定时间继续工作

  .. note:: 说明：
    配置唤醒源时，应先单独配置中断，再开启对应的唤醒源，例如配置AONGPIO00 高电平唤醒

    .. code:: c
      :number-lines:

      wq_gpio_open_as_interrupt(WQ_GPIO_A00, WQ_GPIO_INT_LEVEL_HIGH, NULL);
      wq_gpio_wakeup_enable(WQ_GPIO_A00);
      wq_power_mgnt_enable_shutdown_wakeup_source(WQ_DS_WAKEUP_SRC_GPIO);

- 禁止低功耗状态

  在特定场景下，可能需要临时禁止系统进入低功耗状态已提高系统响应速度，可使用
  :c:func:`wq_power_mgnt_keep_active` 使系统 **禁止** 进入低功耗状态
  :c:func:`wq_power_mgnt_release_keep_active` **允许** 进入低功耗状态

关机
---------
系统仅保留极少模块用于唤醒，其余模块关闭且下电。使芯片处于极低功耗模式下，并且在指定唤醒源产生时使系统开机，从头还是初始化并加载运行软件。

相当于低功耗模式，关机模式时将关闭memory，故系统被唤醒时只能从rom阶段开始启动



API 介绍
------------
.. doxygenfile:: power_mgnt.h
.. doxygenfile:: power_mgnt_device.h