Understanding Android Dynamic Performance Framework (ADPF) and Its Performance‑Hint API

Android Dynamic Performance Framework (ADPF) is a Google‑promoted dynamic performance framework that aims to optimise thermal behaviour and CPU performance on Android devices. This article focuses on the performance‑hint part of ADPF.

1. Why ADPF was introduced

Android dynamically adjusts CPU frequency and core type based on workload. Heavy workloads raise the frequency and may migrate to a high‑performance core; light workloads reduce frequency. The mainstream load‑tracking algorithms (PELT – Per‑Entity Load Tracking and WALT – Window‑Assist Load Tracking) rely on historical thread activity, which introduces latency. The regulator may need about 200 ms to raise or lower CPU frequency, which is longer than a 33.3 ms frame at 60 Hz, causing visible stutter.

Figure 1. The regulator may need ~200 ms to change CPU frequency.

The delay in DCVS (Dynamic Clock and Voltage Scaling) leads to missed frames when the workload spikes within a frame.

Figure 2. Frame‑drop caused by slow CPU frequency scaling.

In the example, the QQ main thread shows normal execution for several frames, but a sudden workload increase forces the CPU to boost, missing the VSync and causing a stutter.

2. ADPF API description

ADPF lets applications or games send performance‑related hints (e.g., deadlines) to the system, helping it adjust scheduling and power usage more aggressively. The key APIs exposed in PerformanceHintManager.Session are:

close – Ends the current hint session.

reportActualWorkDuration(long actualDurationNanos) – Reports the actual duration of the last work cycle.

reportActualWorkDuration(WorkDuration workDuration) – Same as above with a WorkDuration object.

setPreferPowerEfficiency(boolean enabled) – Indicates that the session’s threads may prefer power‑efficiency cores over performance cores.

setThreads(int[] tids) – Sets the list of thread IDs that the hint session should monitor.

updateTargetWorkDuration(long targetDurationNanos) – Updates the target total duration for each work cycle (usually matching the VSync period).

3. How developers use ADPF

Developers can create a hint session (e.g., via createHintSession in Unity) and report per‑frame work durations with reportActualWorkDuration . This information allows the platform to adjust CPU frequency and schedule threads on performance or efficiency cores accordingly. Game engines such as Cocos, Unity, and Unreal already integrate ADPF to convey workload hints.

4. How low‑level developers support ADPF

On the kernel side, MediaTek’s implementation (e.g., in ioctl_powerhal.c for MT6989) provides functions that map directly to the ADPF APIs:

powerhal_adpf_create_session_hint_fp – Creates a session.

powerhal_adpf_report_actual_work_duration_fp – Reports work duration.

powerhal_adpf_set_threads_fp – Reports the key threads.

The adpf_set_threads function calls adpf_notify_callback(ADPF_SET_THREADS, sid) , which registers callbacks in both the scheduler and the FPSGO subsystem.

In the scheduler, the callback marks the reported threads as VIP (high‑priority) using set_task_basic_vip and groups them with __set_task_to_group for collective load tracking and frequency scaling.

FPSGO’s callback ( fpsgo_notifier_wq_cb_adpf_hint ) adds the threads to a dependency list for load tracking and uclamp‑based frequency adjustments.

5. Personal reflections

ADPF bridges the gap between application‑level performance goals and the kernel’s scheduling mechanisms, mitigating the latency of PELT/WALT and DCVS. It introduces concepts borrowed from iOS (thread groups, work‑interval objects) and aims to improve responsiveness on interactive devices. However, adoption is still limited (e.g., WebView, Flutter), and misuse of hints could lead to adverse effects.

Glossary

DCVS – Dynamic Clock and Voltage Scaling

ADPF – Android Dynamic Performance Framework

PELT – Per‑entity Load Tracking

WALT – Window‑assist Load Tracking

WIO – Work Interval Object