【Android】Android 11(R) Power HAL AIDL简析 -- 基本接口

1 前言

Android 11 引入了在 Android 中使用 AIDL 实现 HAL 的功能。这样就可以在不使用 HIDL 的情况下实现 Android 的部分代码。Power HAL模块即可以采用AIDL方式来实现。在Android 11中已经引入这个Power AIDL Interface，源码位于：

/hardware/interfaces/power/aidl/

在学习这部分之前，推荐阅读AIDL的相关知识，特别是Android 10之后引入的对稳定的 Android 接口定义语言 (AIDL) 的支持（stable AIDL）,这里放上几篇官网链接：

• AIDL 概览（AIDL Overview）
• AIDL 后端 （AIDL Backends）
• 稳定的 AIDL（Stable AIDL）
• 适用于 HAL 的 AIDL（AIDL for HALs）
• 动态运行 AIDL 服务（Running AIDL Services Dynamically）
• 以 AIDL 编写的注释 （Annotations in AIDL）
  
• 快速消息队列与 AIDL （Fast Message Queue with AIDL）

2 Power HAL AIDL接口介绍

2.1 接口定义源码的目录结构

1. 在Androi源码目录/hardware/interfaces/power/aidl/android/hardware/power/下定义了三个aidl文件，分别为：

• IPower.aidl 定义 power hal接口
• Mode.aidl 定义各种 power mode
• Boost.aidl 定义Boost type

2. aidl_api目录：对于Stable AIDL，从 Android 11 开始，versions 冻结在 aidl_api/name 下，和AIDL接口版本相关。
3. default目录：功能实现的一个示例代码，实现了一个android.hardware.power-service.example 这个aidl service。
4. vts目录：vts测试用例

2.2 IPower接口介绍

先看看IPower源码是如何定义的，interface IPower的源码定义如下：

 * limitations under the License.
 */

package android.hardware.power;

import android.hardware.power.Boost;
import android.hardware.power.IPowerHintSession;
import android.hardware.power.Mode;

@VintfStability
interface IPower {
    /**
     * setMode() is called to enable/disable specific hint mode, which
     * may result in adjustment of power/performance parameters of the
     * cpufreq governor and other controls on device side.
     *
     * A particular platform may choose to ignore any mode hint.
     *
     * @param type Mode which is to be enable/disable.
     * @param enabled true to enable, false to disable the mode.
     */
    oneway void setMode(in Mode type, in boolean enabled);

    /**
     * isModeSupported() is called to query if the given mode hint is
     * supported by vendor.
     *
     * @return true if the hint passed is supported on this platform.
     *         If false, setting the mode will have no effect.
     * @param type Mode to be queried
     */
    boolean isModeSupported(in Mode type);

    /**
     * setBoost() indicates the device may need to boost some resources, as the
     * the load is likely to increase before the kernel governors can react.
     * Depending on the boost, it may be appropriate to raise the frequencies of
     * CPU, GPU, memory subsystem, or stop CPU from going into deep sleep state.
     * A particular platform may choose to ignore this hint.
     *
     * @param type Boost type which is to be set with a timeout.
     * @param durationMs The expected duration of the user's interaction, if
     *        known, or 0 if the expected duration is unknown.
     *        a negative value indicates canceling previous boost.
     *        A given platform can choose to boost some time based on durationMs,
     *        and may also pick an appropriate timeout for 0 case.
     */
    oneway void setBoost(in Boost type, in int durationMs);

    /**
     * isBoostSupported() is called to query if the given boost hint is
     * supported by vendor. When returns false, set the boost will have
     * no effect on the platform.
     *
     * @return true if the hint passed is supported on this platform.
     *         If false, setting the boost will have no effect.
     * @param type Boost to be queried
     */
    boolean isBoostSupported(in Boost type);

    /**
     * A Session represents a group of threads with an inter-related workload such that hints for
     * their performance should be considered as a unit. The threads in a given session should be
     * long-life and not created or destroyed dynamically.
     *
     * Each session is expected to have a periodic workload with a target duration for each
     * cycle. The cycle duration is likely greater than the target work duration to allow other
     * parts of the pipeline to run within the available budget. For example, a renderer thread may
     * work at 60hz in order to produce frames at the display's frame but have a target work
     * duration of only 6ms.
     *
     * Creates a session for the given set of threads and sets their initial target work
     * duration.
     *
     * @return  the new session if it is supported on this device, otherwise return with
     *          EX_UNSUPPORTED_OPERATION error if hint session is not supported on this device.
     * @param   tgid The TGID to be associated with this session.
     * @param   uid The UID to be associated with this session.
     * @param   threadIds The list of threads to be associated with this session.
     * @param   durationNanos The desired duration in nanoseconds for this session.
     */
    IPowerHintSession createHintSession(
            in int tgid, in int uid, in int[] threadIds, in long durationNanos);

    /**
     * Get preferred update rate (interval) information for this device. Framework must communicate
     * this rate to Apps, and also ensure the session hint sent no faster than the update rate.
     *
     * @return the preferred update rate in nanoseconds supported by device software. Return with
     *         EX_UNSUPPORTED_OPERATION if hint session is not supported.
     */
    long getHintSessionPreferredRate();
}

从源码中可以看到，IPower的定义还是比较简单的，只提供了4个接口，从源码注释也很容易理解其作用，下面我们简单总结一下：

接口名称	参数	返回值	作用
setMode	Mode type：开启或关闭的Power Mode. boolean enabled：true表示开启，false表示关闭	无	调用这个接口可以启用/禁用特定Power Mode，这可能导致cpufreq调控器或设备端其他控件的power/performance参数调整。
isModeSupported	Mode type：要查询的Power Mode	true：支持 fasle：不支持	查询给定的Power Mode是否支持
setBoost	Boost type: 需要设置的type. int durationMs：已知情况下的用户交互的预期时间。值为0表示未知预期时间，负值表示取消上一次的boost	无	表示设备可能需要增加一些资源，因为在内核调控器做出反应之前，负载可能会增加。根据增压情况，可能适合提高CPU、GPU、内存子系统的频率或停止CPU进入深度睡眠状态.
isBoostSupported	Boost type：要查询的Boost type	true：支持 fasle：不支持	查询给定的Boost type是否支持
IPowerHintSession createHintSession(in int tgid, in int uid, in int[] threadIds, in long durationNanos);	tgid 与这个会话相关的TGID。uid 要与这个会话相关联的UID。threadIds 与此会话相关的线程列表。durationNanos 这个会话所需的持续时间，单位是纳秒。	该方法返回一个新会话，如果它在此设备上受支持，否则返回EX_UNSUPPORTED_OPERATION错误，如果提示会话在此设备上不受支持。	Session代表一组具有相互关联的工作负载的线程，因此它们的性能提示应该被视为一个单元。给定会话中的线程应该是长生命周期的，不能动态创建或销毁。每个session预期有一个周期的工作负载，每个周期的目标持续时间。周期持续时间可能大于目标工作持续时间，以允许管道的其他部分在可用预算内运行。例如，渲染器线程可能工作在60hz，以便在显示器的帧上产生帧，但其目标工作时间仅为6ms。为给定的一组线程创建一个会话，并设置它们的初始目标工作时间。
long getHintSessionPreferredRate();	无	获取此设备的首选更新速率(间隔)信息。框架必须将此速率传递给应用程序，并确保会话提示发送不快于更新速率。	@返回设备软件支持的首选更新率，单位为纳秒。如果不支持提示会话，则以EX_UNSUPPORTED_OPERATION返回。

注释：TGID（Thread Group ID）是Linux操作系统中的一个进程标识符，用于表示一组共享相同父进程的线程。每个线程有一个唯一的线程ID（TID），而TGID是这组线程的共同标识符。这些线程共享相同的内存地址空间、文件描述符、信号处理器和其他系统资源。uid 要与这个会话相关联的UID。
UID（User ID）是Linux操作系统中的一个整数标识符，用于标识用户账户。在Linux系统中，每个用户都有一个唯一的UID。这个标识符用于访问系统资源，如文件、文件夹和进程。不同的用户可能具有不同的访问权限，因此通过检查用户的UID来确定用户是否具有执行特定操作的权限。

2.3 Power Mode介绍

先看一下AIDL文件中的定义

package android.hardware.power;

@VintfStability
@Backing(type="int")
enum Mode {
    /**
     * This mode indicates that the device is to allow wake up when the
     * screen is tapped twice.
     */
    DOUBLE_TAP_TO_WAKE,

    /**
     * This mode indicates Low power mode is activated or not. Low power
     * mode is intended to save battery at the cost of performance.
     */
    LOW_POWER,

    /**
     * This mode indicates Sustained Performance mode is activated or not.
     * Sustained performance mode is intended to provide a consistent level of
     * performance for a prolonged amount of time.
     */
    SUSTAINED_PERFORMANCE,

    /**
     * Sets the device to a fixed performance level which can be sustained under
     * normal indoor conditions for at least 10 minutes.
     *
     * This is similar to sustained performance mode, except that whereas
     * sustained performance mode puts an upper bound on performance in the
     * interest of long-term stability, fixed performance mode puts both upper
     * and lower bounds on performance such that any workload run while in a
     * fixed performance mode should complete in a repeatable amount of time
     * (except if the device is under thermal throttling).
     *
     * This mode is not intended for general purpose use, but rather to enable
     * games and other performance-sensitive applications to reduce the number
     * of variables during profiling and performance debugging. As such, while
     * it is valid to set the device to minimum clocks for all subsystems in
     * this mode, it is preferable to attempt to make the relative performance
     * of the CPU, GPU, and other subsystems match typical usage, even if the
     * frequencies have to be reduced to provide sustainability.
     *
     * To calibrate this mode, follow these steps:
     *
     * 1) Build and push the HWUI macrobench as described in
     *    //frameworks/base/libs/hwui/tests/macrobench/how_to_run.txt
     * 2) Run the macrobench as follows:
     *    while true; do \
     *      adb shell /data/benchmarktest/hwuimacro/hwuimacro shadowgrid2 -c 200 -r 10; \
     *    done
     * 3) Determine a fixed set of device clocks such that the loop in (2) can
     *    run for at least 10 minutes, starting from an idle device on a desk
     *    at room temperature (roughly 22 Celsius), without hitting thermal
     *    throttling.
     * 4) After setting those clocks, set the system property
     *    ro.power.fixed_performance_scale_factor to a value N, where N is the
     *    number of times the loop from (2) runs during the 10 minute test
     *    cycle. It is expected that in FIXED_PERFORMANCE mode, unless there is
     *    thermal throttling, the loop will run N to N+1 times (inclusive).
     *
     * After calibrating this, while in FIXED_PERFORMANCE mode, the macrobench
     * results obtained while running the loop in (2) should be consistent both
     * within a given run and from the first run in the 10 minute window through
     * the last run in the window.
     */
    FIXED_PERFORMANCE,

    /**
     * This mode indicates VR Mode is activated or not. VR mode is intended
     * to provide minimum guarantee for performance for the amount of time the
     * device can sustain it.
     */
    VR,

    /**
     * This mode indicates that an application has been launched.
     */
    LAUNCH,

    /**
     * This mode indicates that the device is about to enter a period of
     * expensive rendering.
     */
    EXPENSIVE_RENDERING,

    /**
     * This mode indicates that the device is about entering/leaving
     * interactive state. (that is, the system is awake and ready for
     * interaction, often with UI devices such as display and touchscreen
     * enabled) or non-interactive state (the
     * system appears asleep, display usually turned off). The
     * non-interactive state may be entered after a period of
     * inactivity in order to conserve battery power during
     * such inactive periods.
     *
     * Typical actions are to turn on or off devices and adjust
     * cpufreq parameters. This function may also call the
     * appropriate interfaces to allow the kernel to suspend the
     * system to low-power sleep state when entering non-interactive
     * state, and to disallow low-power suspend when the system is in
     * interactive state. When low-power suspend state is allowed, the
     * kernel may suspend the system whenever no wakelocks are held.
     */
    INTERACTIVE,

    /**
     * This mode indicates the device is in device idle, externally known as doze.
     * More details on:
     * https://developer.android.com/training/monitoring-device-state/doze-standby
     */
    DEVICE_IDLE,

    /**
     * This mode indicates that display is either off or still on but is optimized
     * for low-power.
     */
    DISPLAY_INACTIVE,

    /**
     * Below hints are currently not sent in Android framework but OEM might choose to
     * implement for power/perf optimizations.
     */

    /**
     * This mode indicates that low latency audio is active.
     */
    AUDIO_STREAMING_LOW_LATENCY,

    /**
     * This hint indicates that camera secure stream is being started.
     */
    CAMERA_STREAMING_SECURE,

    /**
     * This hint indicates that camera low resolution stream is being started.
     */
    CAMERA_STREAMING_LOW,

    /**
     * This hint indicates that camera mid resolution stream is being started.
     */
    CAMERA_STREAMING_MID,

    /**
     * This hint indicates that camera high resolution stream is being started.
     */
    CAMERA_STREAMING_HIGH,

    /**
     * This mode indicates that user is playing a game.
     */
    GAME,

    /**
     * This mode indicates that the user is waiting for loading in a game.
     */
    GAME_LOADING,
}

简单介绍各个Mode:

• DOUBLE_TAP_TO_WAKE : 此模式表示设备允许在屏幕被点击两次时被唤醒。
• LOW_POWER：此模式表示低电量模式是否被激活。这种模式以牺牲性能为代价来节省电量消耗。
• SUSTAINED_PERFORMANCE：持续性能模式旨在在较长时间内提供一致的性能水平。
• FIXED_PERFORMANCE：将设备设置为一个固定的性能水平，该水平可在正常室内条件下持续至少10分钟。此模式于SUSTAINED_PERFORMANCE模式，不同之处在于：SUSTAINED_PERFORMANCE为了长期稳定性对性能设置了上限；FIXED_PERFORMANCE模式对性能同时设置了上限和下限，以便在FIXED_PERFORMANCE模式下运行的任何工作负载都应在可重复的时间内完成。
• VR：VR 模式旨在在设备可以维持的时间内为性能提供最低限度的保证。
• LAUNCH：此模式表示已启动应用程序。
• EXPENSIVE_RENDERING：此模式表示设备即将进入昂贵的渲染周期。
• INTERACTIVE：此模式表示设备即将进入/离开 交互状态或非交互状态。 非交互状态可以在不活动时间段之后进入，以便在这样的不活动时间段期间节省电池电量。典型的操作是打开或关闭设备并调整 cpufreq 参数。该函数还可以调用适当的接口，允许内核在进入非交互状态时将系统挂起到低功耗休眠状态，并在系统处于交互状态时禁止低功耗挂起。 当允许低功耗挂起状态时，内核可以在没有唤醒锁保持时挂起系统。
• DEVICE_IDLE：此模式表示设备处于设备空闲状态，详细信息可参考： 针对低电耗模式和应用待机模式进行优化
• DISPLAY_INACTIVE：此模式表示显示器关闭或仍然打开，但已针对低功耗进行了优化。

以下提示选项目前未在加入 Android framework，但 OEM 可能会选择实施电源/性能优化。

• AUDIO_STREAMING_LOW_LATENCY：此模式表示低延迟音频处于激活状态
• CAMERA_STREAMING_SECURE：此模式表示正在启动相机 安全流
• CAMERA_STREAMING_LOW：此模式表示正在启动相机 低 分辨率流。
• CAMERA_STREAMING_MID：此模式表示正在启动相机 中 分辨率流。
• CAMERA_STREAMING_HIGH：此模式表示正在启动相机 高 分辨率流
• GAME：该模式表示用户正在玩游戏。
• GAME_LOADING：这种模式表示用户正在等待游戏中的加载。

2.4 Boost type介绍

首先看一下AIDL的源码：

package android.hardware.power;

@VintfStability
@Backing(type="int")
enum Boost {
    /**
     * This boost is set when user interacting with the device, for example,
     * touchscreen events are incoming. CPU and GPU load may be expected soon,
     * and it may be appropriate to raise speeds of CPU, memory bus etc.
     * Note that this is different from INTERACTIVE mode, which only indicates
     * that such interaction *may* occur, not that it is actively occurring.
     */
    INTERACTION,

    /**
     * This boost indicates that the framework is likely to provide a new
     * display frame soon. This implies that the device should ensure that the
     * display processing path is powered up and ready to receive that update.
     */
    DISPLAY_UPDATE_IMMINENT,

    /**
     * Below hints are currently not sent in Android framework but OEM might choose to
     * implement for power/perf optimizations.
     */

    /**
     * This boost indicates that the device is interacting with ML accelerator.
     */
    ML_ACC,

    /**
     * This boost indicates that the device is setting up audio stream.
     */
    AUDIO_LAUNCH,

    /**
     * This boost indicates that camera is being launched.
     */
    CAMERA_LAUNCH,

    /**
     * This boost indicates that camera shot is being taken.
     */
    CAMERA_SHOT,
}

几个枚举常量的大概解释如下：

• INTERACTION：这种boost是在用户与设备交互时设置的，例如，触摸屏事件传入。 CPU 和 GPU 负载可能很快就会出现，可能适当提高 CPU、内存总线等的速度。 注意，这与 INTERACTIVE 模式不同，交互模式仅表示这种交互可能发生，而不是主动发生 。
• DISPLAY_UPDATE_IMMINENT：这种boost表明框架可能很快会提供一个新的显示帧。这意味着设备应确保显示处理路径已通电并准备好接收该更新。

以下提示目前没有在Androidd framework中发送，但OEM可能会选择实现功耗/性能的优化:

• ML_ACC：此boost表明设备正在与 ML 加速器交互。
• AUDIO_LAUNCH：这个提升表示设备正在设置音频流。
• CAMERA_LAUNCH：此boost表示Camera正在被启动。
• CAMERA_SHOT：此boost表示Camera正在拍摄。

3 结语

通过上面的介绍，应该对power hal aidl有了一个直观的认识，清楚了有哪些接口/哪些模式，下一篇中我们会在此基础上通过一个示例讲解如何实现这个aidl serivice功能。