低功耗与唤醒
===================================

低功耗相关参数配置
#########################

    在apps/app/bsp/cpu/bd49/power/power_config.c文件中，通过power_param结构体成员配置VDDIO电压
        | 1、vddiom_lev：系统正常运行时的VDDIO电压；
        | 2、vddiow_lev：系统低功耗时的VDDIO电压；

    如果需要配置flash为VDDIO供电，将函数void board_power_init()中PCONTROL_FLASH_PG_VDDIO的后一个参数改为1，否则至成0

        .. image:: power_config.png
            :alt: "图13-1 唤醒初始化配置参数“
            :align: center
        .. centered:: 图13-1 唤醒初始化配置参数

    本章着重介绍Soft off、Power down以及唤醒。
        | Soft off及Power down相关函数：
        | void sys_softoff();
        | void sys_power_down(u32 usec);

    唤醒相关函数：
        | u8 is_wakeup_source(enum WAKEUP_REASON index);

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

唤醒相关参数配置
#######################

    Soft off与Power down共用唤醒模块，AW30N最多可以设置12个IO唤醒源。可以在apps/app/bsp/cpu/bd49/power_api.c添加_p33_io_edge_wakeup_config结构体和初始化唤醒口增加唤醒源。

    唤醒前需要先配置唤醒参数结构体_p33_io_edge_wakeup_config，内容如下：

    gpio: 唤醒IO口。支持所有PA口、PB口和USB_io；

    pullup_down_enable：上/下拉使能；

    filter：边沿唤醒选择消抖的脉冲时长;
        | ①　PORT_FLT_DISABLE；
        | ②　PORT_FLT_16us；
        | ③　PORT_FLT_128us；
        | ④　PORT_FLT_1ms；
        | ⑤　PORT_FLT_4ms；
    
    edge：边沿触发方式；
        | ①　RISING_EDGE：上升沿；
        | ②　FALLING_EDGE：下降沿唤醒；
        | ③　BOTH_ENGE：双边沿唤醒；
    
    callback：唤醒回调；

    *注：使用边沿唤醒的应用，注意唤醒IO在唤醒时的电平不可位于1.3~1.7V，该范围的电压处于芯片高电平和低电平之间的中间态，可能出现无法唤醒的现象。*

    .. image:: aw30n_wakeup_config.png
        :alt: "图13-2 唤醒初始化配置参数“
        :align: center
    .. centered:: 图13-2 唤醒初始化配置参数

^^^^^^^^^^^^^^^^^^^^^^

低功耗相关函数
##########################

函数void app_powerdown_deal(u8 is_busy)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    .. note:: 应用层函数，此函数实现在系统空闲时，指定超时时间进入powerdown的处理以及退出powerdown的恢复，其中参数：
    
        1、is_busy：系统繁忙标志位
            | ①　0：系统空闲；
            | ②　1：系统繁忙中；

函数void sys_softoff(void)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    .. note:: 此函数实现使系统进入软关机。

函数void board_set_soft_poweroff(void)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    .. note:: 此函数实现在进入软关机之前将IO口设置成高阻，并将唤醒引脚设为对应的待唤醒状态，若需要保留某些I/O口原来状态，可在apps/app/bsp/cpu/bd49/power/gpio_config.c调用函数PORT_PROTECT(u32 gpio)。

    .. image:: aw30_io_protect.png
        :alt: "图13-3 唤醒IO保护“
        :align: center
    .. centered:: 图13-3 唤醒IO保护

函数void sys_power_down(u32 usec)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^    
    .. note:: 此函数实现进入系统power down，并通过延时或者触发唤醒。其中参数：
        
        1.usec：唤醒时间（微秒），该时间不可超过看门狗复位时间的一半；
    
powerdown系统繁忙轮询机制
##########################

    AW30N的powerdown在系统休眠前新增了系统模块空闲链表查询的机制，只要有一个模块标志不处于空闲，系统就不会进入休眠并且退出powerdown函数，当所有模块都处于空闲时系统才能进入休眠。

    *注：该机制轮询的位置已关闭总中断，对于定时响应的任务或者对时间要求比较苛刻的中断应用可能会造成影响。*

    使用案例如图：

    .. image:: modules_idle_query.png
        :alt: "图13-4 系统模块idle使用案例“
        :align: center
    .. centered:: 图13-4 系统模块idle使用案例

    参考图中的案例，用户可以自行编写一个函数(如图中的key_idle_query函数)，然后注册到结构体中，需要自定义结构体名(括号中的key_lp_target为用户自定义的结构体名)。当用户调用powerdown函数时，powerdown内部会查询用户所有已注册函数的返回值。当返回值为0时，会自动退出powerdown；当返回值为1时，就会进入休眠。

.. _唤醒相关函数:

唤醒相关函数
###########################
函数bool is_wakeup_source(enum WAKEUP_REASON index)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    .. note:: 此函数实现查询传入的唤醒源参数，是否与系统soft off的唤醒源一致。该接口需要在系统初始化power_early_flowing()之后调用，否则获取的唤醒源不准确，其中参数：
    
        1.index：唤醒端口；
            | ①　PWR_WK_REASON_FALLING_EDGE：io下降沿唤醒源0~11;
            | ②　具体可传入的唤醒源请查看power_wakeup.h中的WAKEUP_REASON枚举；
        2.返回值：
            | 1  传入的唤醒源为本次系统的唤醒源；
            | 0  传入的唤醒源非本次系统的唤醒源；

长短按复位相关函数
###################################
函数void p33_mclr_sw(u8 en)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    此函数实现开关PB0短按复位功能。其中参数：

        1.en：
            | 1 开启短按复位使能
            | 0 关闭短按复位使能

    .. note:: 此函数在使用前需要将短按复位口设置成上拉数字输入

函数gpio_longpress_pino_reset_config(u32 pin, u32 level, u32 time, u32 release, u32 pull_enable)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    .. note:: 此函数实现配置长按复位功能。其中参数

        1.pin：长按复位IO, 默认使用PA3，支持任意PA口、PB口和USB_io
        
        2.level：io口输入上下拉配置。1为上拉, 0为下拉
        
        3.time：长按复位时间。支持1s、2s、4s、8s、16s。时间设为0时会关闭长按复位功能。
        
        4.release： 0 等到io电平反转再释放系统运行 1 立即释放系统运行
        
        5.pull_enable：上下拉使能