Read this document in English

yumi 是一个功能强大的 Android CPU 调度控制系统，由轻量级的 WebUI 管理界面和高性能的 Rust 守护进程 (yumi) 组成。系统通过 eBPF 内核探针实时采集 CPU 调度事件和渲染帧数据，结合先进的 PID 控制器 和 CPU 负载调速器 (CLG)，根据不同使用场景动态调整 CPU 频率，实现最佳的性能与能效平衡。内置的 FAS (Frame Aware Scheduling) 帧感知调度引擎可实时分析游戏帧时间，以逐帧精度动态调频，在保证流畅度的同时最大化省电。

• 🔄 智能动态模式切换 - 根据当前前台应用自动调整性能模式。
• 🎯 FAS 帧感知调度 - 内置 PID 控制器 + 帧时间分析引擎，逐帧动态调频，游戏场景下兼顾流畅与功耗。
• 📊 eBPF 内核级监控 - 通过 sched_switch tracepoint 和 queueBuffer uprobe 实现零开销的 CPU 利用率和帧率采集。
• ⚡ CPU 负载调速器 (CLG) - 基于 eBPF 实时负载数据的自适应调频，替代传统内核调速器，适用于日常非游戏场景。
• 🌡️ 温度感知调控 - 实时读取 CPU 温度传感器，超过阈值时自动降频保护。
• 🌙 智能息屏节电 - 息屏时自动进入 Doze 模式，强制限制性能上限，极致省电。
• 🌐 轻量 WebUI - 无需安装额外 App，通过浏览器即可管理调度配置。
• 📱 应用规则管理 - 为不同应用设置专属的性能策略，支持 per-app 帧率档位和余量配置。
• 🔧 高度可配置 - YAML 配置文件支持深度自定义，配置热重载无需重启。
• 🌍 多语言支持 - 基于 Fluent 的 i18n 国际化系统，支持中英文日志。

• Android 版本: Android 8.0 (API 26) 及以上。
• 架构支持: ARM64 (AArch64)。
• 权限要求: Root 权限。
• 内核要求: 支持 eBPF（需要 CONFIG_BPF、CONFIG_BPF_SYSCALL 等内核选项）。

yumi 采用 Monitor + Scheduler 双线程架构，通过 mpsc 事件通道解耦数据采集与调度决策：

┌─────────────────────────────────────────────────────┐
│                   Monitor 线程组                      │
│                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │ app_detect   │  │ fps_monitor  │  │ cpu_monitor │ │
│  │ (Cgroup检测)  │  │ (eBPF uprobe)│  │(eBPF trace)│ │
│  └──────┬───────┘  └──────┬───────┘  └─────┬──────┘ │
│         │                 │                 │        │
│         │     ┌───────────┴─────────────────┘        │
│         │     │   DaemonEvent (mpsc channel)         │
└─────────┼─────┼──────────────────────────────────────┘
          │     │
          ▼     ▼
┌─────────────────────────────────────────────────────┐
│               Scheduler IPC 线程                      │
│                                                      │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ FAS 控制器    │  │ CLG 负载调速 │                  │
│  │ (游戏场景)    │  │ (日常场景)    │                  │
│  └──────────────┘  └──────────────┘                  │
│               ▼                                      │
│     sysfs 频率写入 (FastWriter)                       │
└─────────────────────────────────────────────────────┘

系统使用五种核心事件驱动调度决策：

yumi 提供五种性能模式：

在非 FAS 的四种模式下，yumi 使用 CPU 负载调速器 (CLG) 替代内核原生调速器。CLG 基于 eBPF 采集的真实 CPU 利用率数据，通过 EMA 平滑、升降频速率限制和 headroom 因子进行自适应调频。每种模式可独立配置 CLG 参数（升降频阈值、平滑系数、性能上下限等）。

息屏时，系统自动进入 Doze 模式，CLG 被重新配置为极致省电参数（性能上限锁死 40%、升频极迟钝、瞬间降频），大幅降低待机功耗。

yumi 内置轻量级 WebUI，通过浏览器即可完成所有管理操作，无需安装额外 App。

• 模式切换 - 实时切换性能模式。
• 应用规则管理 - 为不同应用配置专属性能策略。
• 配置编辑 - 在线编辑 YAML 配置文件。
• 日志查看 - 实时查看 yumi 守护进程日志。

yumi 的核心是由一个 Rust 守护进程 yumi 驱动的。它使用 eBPF 内核探针进行零开销数据采集，以极低的资源占用实现高效的性能控制。

• 高性能 Rust 实现: 极低的系统资源占用，运行功耗极低。
• eBPF 内核级监控: 通过 sched_switch tracepoint 精确采集每核心 CPU 利用率和线程运行时间；通过 queueBuffer uprobe 零开销捕获渲染帧间隔。
• 实时配置监听: 支持配置文件（config.yaml）和规则文件（rules.yaml）热重载，切换模式无需重启。
• 内置 FAS 引擎: PID 控制器驱动的帧感知调度，支持自动容量权重探测、per-app 配置、CPU 利用率辅助调频。
• CLG 负载调速器: 基于 eBPF 实时负载的自适应调频，替代内核原生调速器。
• 多语言国际化: 基于 Fluent 的 i18n 系统，支持中英文日志输出。

FAS (Frame Aware Scheduling) 是 yumi 内置的帧感知动态调频引擎，专为游戏场景设计。与传统的静态模式不同，FAS 通过 PID 控制器实时分析每一帧的渲染时间来精确控制 CPU 频率，在保证流畅度的同时尽可能降低功耗。

FAS 引擎维护一个 perf_index（性能指数，范围 0.0~1.0），并通过 PID 控制器根据帧时间的实时反馈来调整它：

• 帧时间超出预算 → PID 输出为负 → perf_index 上升 → CPU 频率提高
• 帧时间满足预算 → PID 输出为正 → perf_index 缓慢下降 → CPU 频率降低
• perf_index 通过 capacity_weight 映射到各核心簇的实际频率档位

PID 控制器使用三个可配置的系数（kp、ki、kd）分别控制比例、积分和微分响应，其中积分项带有泄漏机制防止饱和，微分项使用低通滤波抑制噪声。

• 自动帧率档位切换: 支持多档位帧率（如 30/60/90/120/144 fps），根据实际渲染能力自动升降档。降档前会先尝试 boost 提频确认是否真的需要降档，避免误降。支持低 perf 稳帧升档和极端帧率原生档位检测。
• CPU 负载辅助调频: 利用 eBPF 采集的前台最重线程利用率（EMA 平滑），对 perf_index 进行 util_cap 软封顶，防止频率虚高空转。
• 自动容量权重探测: 运行时读取各核心簇的 cpu_capacity，自动计算 capacity_weight（大核权重更高），无需手动配置核心架构。
• per-app 配置: 支持为每个游戏单独配置帧率档位列表和帧率余量，运行时动态匹配最近的档位。
• 加载场景检测: 自动识别游戏加载画面（持续重帧），进入加载状态后锁定中高频率，加载结束后带保护地恢复正常调度。
• 频率迟滞防抖: 相邻频率档位间设置迟滞带，防止在边界处频繁跳档。
• Jank 冷却机制: 发生严重掉帧后进入冷却期，期间维持较高频率，避免掉帧后立即降频引发连锁卡顿。Jank 响应强度随连续掉帧次数指数递增。
• 频率校验与恢复: 定期读回实际频率，检测是否被外部因素（如温控）覆盖，自动 unmount 并重新写入。
• 小窗模式支持: FAS 状态支持挂起/恢复（5 秒宽限期），短暂切离后可快速恢复调度，无需重新初始化。
• perf_floor 死锁救援: 检测 perf_index 长时间贴地板但帧率严重不足的情况，自动重置到冷启动性能值。

FAS 的参数通过 rules.yaml 中的 fas_rules 节进行配置：

fas_rules:
  fps_gears: [30.0, 60.0, 90.0, 120.0, 144.0]
  fps_margin: 3.0

  pid:
    kp: 0.05
    ki: 0.01
    kd: 0.006

  auto_capacity_weight: true

  perf_floor: 0.22
  perf_ceil: 1.0
  perf_init: 0.45
  perf_cold_boot: 0.85
  freq_hysteresis: 0.015

  heavy_frame_threshold_ms: 150.0
  loading_cumulative_ms: 2500.0
  loading_normal_tolerance: 3
  loading_perf_floor: 0.60
  loading_perf_ceiling: 0.70
  post_loading_ignore_frames: 5
  post_loading_perf: 0.65
  post_loading_downgrade_guard: 90

  upgrade_confirm_frames: 60
  downgrade_confirm_frames: 90
  upgrade_cooldown_after_downgrade: 90
  gear_dampen_frames: 60
  downgrade_boost_perf_inc: 0.18
  downgrade_boost_duration: 45

  fast_decay_frame_threshold: 75
  fast_decay_perf_threshold: 0.70
  fast_decay_max_step: 0.022
  fast_decay_min_step: 0.004

  jank_cooldown_frames: 15
  max_inc_damped: 0.045
  max_inc_normal: 0.075
  damped_perf_cap: 0.92

  app_switch_gap_ms: 3000.0
  app_switch_resume_perf: 0.60
  freq_force_reapply_interval: 30
  fixed_max_frame_ms: 500.0
  cold_boot_ms: 3500

  per_app_profiles:
    "com.miHoYo.GenshinImpact":
      target_fps: [30, 60]
      fps_margin: 4.0
    "com.tencent.tmgp.sgame":
      target_fps: [60, 90, 120]
      fps_margin: 3.0

关键参数说明：

yumi 使用 YAML 格式的配置文件，允许用户进行深度自定义。

这部分定义了守护进程的基本行为。

meta:
  loglevel: "INFO"
  language: "en"

function:
  CpuIdleScalingGovernor: false
  IOOptimization: true

需要 function.IOOptimization 为 true。启用后会遍历 /sys/block/* 下的所有块设备，逐一应用以下参数。

IO_Settings:
  Scheduler: "none"
  read_ahead_kb: "128"
  nomerges: "2"
  iostats: "0"

需要 function.CpuIdleScalingGovernor 为 true。

CpuIdle:
  current_governor: "ladder"

• current_governor: 设置 CPU Idle 调速器。

每种性能模式可独立配置 CPU 负载调速器 (CLG) 的参数：

# 省电模式 — 极致续航
powersave:
  cpu_load_governor:
    up_threshold: 0.85
    down_threshold: 0.60
    smoothing_up: 0.40
    smoothing_down: 0.50
    down_rate_limit_ticks: 2
    up_rate_limit_ticks: 2
    headroom_factor: 1.10
    headroom_ramp: 0.15
    perf_floor: 0.10
    perf_ceil: 0.70
    perf_init: 0.30
    up_jump_threshold: 0.35
    slow_up_scale: 0.02
    slow_down_scale: 0.5
    down_fast_threshold: 0.10
    down_fast_mult: 2.5

# 均衡模式 — 日常使用
balance:
  cpu_load_governor:
    up_threshold: 0.80
    down_threshold: 0.50
    smoothing_up: 0.60
    smoothing_down: 0.30
    down_rate_limit_ticks: 3
    up_rate_limit_ticks: 2
    headroom_factor: 1.25
    headroom_ramp: 0.15
    perf_floor: 0.15
    perf_ceil: 1.0
    perf_init: 0.50
    up_jump_threshold: 0.35
    slow_up_scale: 0.02
    slow_down_scale: 0.5
    down_fast_threshold: 0.10
    down_fast_mult: 2.5

# 性能模式 — 优先响应
performance:
  cpu_load_governor:
    up_threshold: 0.65
    down_threshold: 0.40
    smoothing_up: 0.80
    smoothing_down: 0.20
    down_rate_limit_ticks: 5
    up_rate_limit_ticks: 2
    headroom_factor: 1.40
    headroom_ramp: 0.15
    perf_floor: 0.35
    perf_ceil: 1.0
    perf_init: 0.60
    up_jump_threshold: 0.35
    slow_up_scale: 0.02
    slow_down_scale: 0.5
    down_fast_threshold: 0.10
    down_fast_mult: 2.5

# 极速模式 — 最大性能释放
fast:
  cpu_load_governor:
    up_threshold: 0.01
    down_threshold: 0.01
    smoothing_up: 1.0
    smoothing_down: 0.01
    down_rate_limit_ticks: 10
    up_rate_limit_ticks: 2
    headroom_factor: 2.0
    headroom_ramp: 0.15
    perf_floor: 1.0
    perf_ceil: 1.0
    perf_init: 1.0
    up_jump_threshold: 0.35
    slow_up_scale: 0.02
    slow_down_scale: 0.5
    down_fast_threshold: 0.10
    down_fast_mult: 2.5

yumi 使用两个 eBPF 探针进行内核级数据采集：

挂载到 tracepoint/sched/sched_switch，在每次上下文切换时触发，记录：

• 每核心 idle/busy 时间: 通过 PERCPU_ARRAY 累计，用户态读取后计算真实利用率。
• 每核心当前 TID: 用于用户态实时补偿尚未触发 sched_switch 的任务时间。
• 线程运行时间: 通过 HASH map 记录每个线程的累计 CPU 时间，用于计算前台应用最重线程利用率。

挂载到 libgui.so 的 Surface::queueBuffer 函数（uprobe），在每帧渲染提交时触发：

• 内核侧时间戳采集: 在 eBPF 中通过 bpf_ktime_get_ns() 记录帧提交时间，通过 RingBuf 零拷贝传输到用户态。
• per-PID uprobe 挂载: 每个目标进程持有独立的 eBPF 实例，PID 切换时自动 detach 旧实例并 attach 新实例，确保只捕获目标进程的帧事件。
• 用户态帧间隔计算: 用户态在 RingBuf 中读取连续帧时间戳，计算 delta，过滤异常帧间隔（1ms~200ms）。

1. 获取 Root 权限
2. 确保内核支持 eBPF（大部分 Android 10+ 设备均已支持）

1. 下载模块 - 从 Releases 下载最新版本。
2. 刷入模块 - 通过 Magisk / KernelSU 刷入 yumi 模块。
3. 访问 WebUI - 模块启动后，通过浏览器访问 WebUI 进行管理和配置。
4. 配置规则 - 根据需要为不同应用设置性能策略。

1. 使用均衡模式 - CLG 自适应调频，为大部分应用提供最佳的性能功耗平衡。
2. 设置应用规则 - 为游戏应用设置 FAS 模式。

1. 使用 FAS 模式 - 帧感知调度可在保证流畅度的同时自动省电，推荐作为游戏的首选模式。
2. 配置 per-app 参数 - 在 rules.yaml 中为特定游戏设置 target_fps 和 fps_margin。
3. 调整 PID 系数 - 如果觉得调频响应过快或过慢，可微调 kp/ki/kd。
4. 监控温度 - 设置 core_temp_threshold 启用温度保护，长时间游戏时防止过热。

1. 使用省电模式 - CLG 低性能上限，在低负载场景下最大化续航。
2. 息屏自动省电 - 无需手动操作，息屏时自动进入 Doze 模式。
3. 优化 I/O 调度 - 减少存储访问的功耗开销。

Q: 模块无法获取 Root 权限？

• 确保设备已正确 Root 并安装 Magisk / KernelSU。
• 检查 Root 管理器中是否允许了 yumi 的 Root 请求。
• 尝试重新刷入模块或重启设备。

Q: eBPF 探针加载失败？

• 确保内核支持 eBPF（CONFIG_BPF=y、CONFIG_BPF_SYSCALL=y）。
• 查看日志中的 eBPF 错误信息。
• 部分旧内核可能不支持所需的 BPF 功能。

Q: 智能动态模式不工作？

• 验证应用规则是否正确配置。
• 验证 yumi 模块是否安装并正常运行。
• 检查 ignored_apps 列表是否误将目标应用排除。

Q: 性能模式切换无效？

• 验证 yumi 模块是否安装并正常运行。
• 查看 yumi 模块日志以确定具体错误信息。
• 验证配置文件格式是否正确（YAML 语法敏感）。

Q: FAS 模式下帧率不稳定？

• 检查 rules.yaml 中的 fps_gears 是否包含目标帧率。
• 适当增大 fps_margin 可提供更多余量，减少边界波动。
• 查看日志中的 FAS 心跳信息（每 30 帧输出一次），确认调度状态是否正常。
• 若频率被温控覆盖，日志中会出现 "freq mismatch" 提示，属正常校验恢复行为。
• 尝试为该游戏配置 per_app_profiles 中的专属参数。

Q: CPU 利用率数据不准确？

• eBPF CPU 探针需要内核支持 tracepoint/sched/sched_switch。
• 用户态读取周期为 200ms，包含实时状态补偿以提高精度。
• 检查日志中的 cpu_monitor 初始化信息，确认在线核心列表是否正确。

• GitHub Issues - 项目问题和建议
• QQ 群 - 1036909137
• Telegram - 加入 TG 频道