ADB 调试与日志分析

1. 概述

1.1 功能简介

ADB（Android Debug Bridge）是 Android 系统的核心调试工具，本文档介绍 shimetapi RK3588 开发板（C-3588LQ 核心板 + SHIMETAPI-M5-R2A 底板）的 ADB 连接配置、常用调试命令、日志分析方法以及内存调试工具的使用。

1.2 应用场景

• 应用调试与安装部署
• 系统日志抓取与分析
• 内存性能 profiling（Procrank / Dumpsys）
• 内核崩溃日志分析（Last log / pstore）
• Shell 远程访问与文件管理

1.3 工作原理

ADB 调试架构：
PC (adb client) --USB OTG/WiFi--> RK3588 (adbd 守护进程) --> Android Shell / Logcat / 服务

ADB 组成：
- Client：PC 端（adb 命令）
- Server：PC 端后台进程（管理 Client 与 设备通信）
- Daemon (adbd)：Android 设备端守护进程

ADB 根据连接方式分为两类：

• USB ADB：主机通过 USB 线连接到设备的 USB OTG 口
• 网络 ADB：主机通过有线/无线网络（同一局域网）连接到设备

2. 硬件准备

设备	型号/规格	数量	说明
核心板	C-3588LQ V1.0	1	RK3588 主芯片
底板	SHIMETAPI-M5-R2A V1.0	1	提供 USB OTG 接口
USB 数据线	Type-C	1	用于 ADB 连接（接底板 OTG 口）
调试串口线	USB 转 TTL（3.3V）	1	可选，用于串口调试和 FIQ 模式
电源适配器	12V/3A DC	1

3. 软件准备

项目	说明
ADB 工具	platform-tools（ADB 1.0.41+，建议使用最新版本）
Android 系统	RK3588 Android 14 系统（已烧录并启动）
USB 驱动	DriverAssitant v5.1.1（Windows 必需）
串口终端	picocom / screen（macOS/Linux），PuTTY（Windows）

4. 操作步骤

4.1 USB ADB 连接

步骤1：开启开发者选项和 USB 调试

1. 进入 Android 设置：Settings -> About tablet
2. 连续点击"Build number"（版本号）7 次，开启开发者选项
3. 返回 Settings -> Developer options（开发者选项）
4. 打开"USB debugging"（USB 调试）开关
5. 打开"Connect to computer"（已连接到计算机）开关

步骤2：连接设备

1. 使用 USB 线连接底板 OTG 口到 PC
2. 注意：ADB 只支持 USB OTG 口，不支持 USB Host 口
3. 设备上弹出"允许 USB 调试"对话框，确认并勾选"始终允许"

步骤3：验证连接

# 查看已连接的设备
adb devices

实测输出：

$ adb devices
List of devices attached
aec7944879c313ab        device

如果显示 unauthorized，请检查设备上的 USB 调试授权确认框。

userdebug 固件的 root 权限： 实测固件为 userdebug 版本，可直接获取 root：

$ adb root
restarting adbd as root

root 后 dmesg 等命令可用；shell 用户直接执行 dmesg 会报 klogctl: Permission denied。

步骤4：进入设备 shell

adb shell

限制说明：

• USB ADB 只支持 USB OTG 口
• 不支持多个客户端同时使用（如多个 cmd 窗口）
• 只支持主机连接一个设备，不支持连接多个设备
• 如需连接多个设备，使用 adb -s <serial> 指定设备

4.2 网络 ADB 连接

步骤1：获取设备 IP 地址

adb shell ip addr show eth0
# 或
adb shell ifconfig

步骤2：切换到网络模式

# 连接网络 ADB（设备 IP 为 192.168.1.100）
adb connect 192.168.1.100

实测示例：设备 eth0 地址为 192.168.49.63 时，执行 adb connect 192.168.49.63。

步骤3：验证连接

adb devices

预期输出：

List of devices attached
192.168.1.100:5555      device

4.3 ADB 常用命令

设备管理

# 查看设备列表
adb devices

# 查看设备信息
adb shell getprop ro.product.model
adb shell getprop ro.build.version.release
adb shell getprop ro.build.version.sdk

# 重启设备
adb reboot

# 重启到 bootloader
adb reboot bootloader

# 重启到 recovery
adb reboot recovery

# 重启到 fastbootd（动态分区模式）
adb reboot fastboot

应用管理

# 安装 APK
adb install /path/to/app.apk

# 重新安装（保留数据）
adb install -r /path/to/app.apk

# 安装到 SD 卡
adb install -s /path/to/app.apk

# 卸载应用
adb uninstall com.example.package

# 列出所有已安装应用
adb shell pm list packages

# 列出第三方应用
adb shell pm list packages -3

文件传输

# 上传文件到设备
adb push /local/file.txt /sdcard/

# 从设备下载文件
adb pull /sdcard/file.txt /local/path/

# 在设备上删除文件
adb shell rm /sdcard/file.txt

系统信息

# 查看所有系统属性
adb shell getprop

# 查看 bug 报告（包含 dumpsys、dumpstate、logcat 信息）
adb bugreport

# 查看内核日志
adb shell dmesg

4.4 Logcat 日志分析

Logcat 是 Android 系统日志输出工具，用于查看系统调试信息。

基本用法

# 进入 shell 后查看日志
adb shell
logcat

# 直接查看日志
adb logcat

日志优先级过滤

Android 日志优先级从低到高：

优先级	说明
V	Verbose（详细，最低优先级）
D	Debug（调试）
I	Info（信息）
W	Warning（警告）
E	Error（错误）
F	Fatal（致命）
S	Silent（静默，最高优先级）

# 只显示 Warning 及以上级别的日志
adb logcat *:W

# 只显示 Error 及以上级别的日志
adb logcat *:E

按标签过滤

# 只显示指定标签的日志（方式一）
adb logcat -s TagName

# 只显示指定标签的日志（方式二）
adb logcat TagName:* *:S

# 示例：只显示 ActivityManager 标签的日志
adb logcat -s ActivityManager

标签+优先级组合过滤

# 显示 ActivityManager 的 Info 及以上 + MyApp 的 Debug 及以上，其他静默
adb logcat ActivityManager:I MyApp:D *:S

# 显示指定标签的特定优先级
adb logcat TagName:I *:S

示例说明：

logcat ActivityManager:I MyApp:D *:S

• 输出所有标签为 ActivityManager 且优先级为 Info 及以上的日志
• 输出所有标签为 MyApp 且优先级为 Debug 及以上的日志
• 其他所有标签的日志被静默（S）

日志保存

# 将日志输出到文件
adb logcat -d > logcat.txt

# 实时日志保存
adb logcat -v time > logcat.txt
# Ctrl+C 停止

4.5 Procrank 内存分析工具

Procrank 是 Android 自带的内存调试工具，运行在设备侧 shell 环境下，用于输出进程的内存快照。

内存指标说明

指标	全称	说明
VSS	Virtual Set Size	虚拟耗用内存大小（包含共享库占用的内存）
RSS	Resident Set Size	实际使用物理内存大小（包含共享库占用的内存）
PSS	Proportional Set Size	实际使用的物理内存大小（比例分配共享库占用的内存）
USS	Unique Set Size	进程独自占用的物理内存大小（不包含共享库占用的内存）

注意：

• USS 大小代表只属于本进程正在使用的内存大小，进程被杀死后会被完整回收
• VSS/RSS 包含了共享库使用的内存，对查看单一进程内存状态没有参考价值
• PSS 是按照比例将共享内存分割后，某单一进程对共享内存区的占用情况

使用 Procrank

执行 procrank 前需要先获取 root 权限：

adb shell
su
procrank

实测：本固件 procrank 位于 /system/bin/procrank，adb root 后即可直接运行；/system/xbin/ 下另有 su。

命令格式：

procrank [ -W ] [ -v | -r | -p | -u | -h ]

选项	说明
-v	按照 VSS 排序
-r	按照 RSS 排序
-p	按照 PSS 排序（默认）
-u	按照 USS 排序
-R	切换递增/递减排序
-w	只显示 working set 的统计计数
-W	重置 working set 的统计计数
-h	帮助

检索指定进程内存

# 查看 systemUI 进程的内存占用
procrank | grep "com.android.systemui"

# 按 PID 查看
procrank | grep 3396

跟踪进程内存泄漏

通过编写脚本连续输出进程内存快照，对比 USS 段判断是否存在内存泄漏：

#!/bin/bash
while true; do
    adb shell procrank | grep "com.android.systemui"
    sleep 1
done

4.6 Dumpsys 系统服务分析

Dumpsys 是 Android 系统中用于获取正在运行的服务状态信息的调试工具。

查看帮助

dumpsys -help

查看服务列表

# 列出所有可 dump 的服务
dumpsys -l

实测：服务列表包含 SurfaceFlinger、SurfaceFlingerAIDL、activity、window 等常用服务（节选）：

Currently running services:
  DockObserver
  SurfaceFlinger
  SurfaceFlingerAIDL
  accessibility
  account
  activity
  activity_task
  ...

注意：系统启动早期（sys.boot_completed=0）SurfaceFlinger 可能尚未注册，此时 dumpsys SurfaceFlinger 会报 Can't find service: SurfaceFlinger，等待启动完成（getprop sys.boot_completed 为 1）后即可正常使用。

查看指定服务信息

# 查看 SurfaceFlinger 服务信息
dumpsys SurfaceFlinger

# 查看内存信息
dumpsys meminfo

# 查看指定进程的内存信息
dumpsys meminfo com.android.systemui

# 查看电池信息
dumpsys battery

# 查看网络信息
dumpsys connectivity

# 查看 WiFi 信息
dumpsys wifi

# 查看活动窗口信息
dumpsys window windows

# 查看 Activity 栈
dumpsys activity activities

注意： 服务名称是大小写敏感的，必须输入完整服务名称。

Dumpsys 输出条件

• 只能打印已经加载到 ServiceManager 中的服务
• 如果服务端代码中的 dump 函数没有被实现，则没有信息输出

4.7 Last Log（pstore）内核崩溃日志

当系统发生内核 panic 或异常重启时，可以通过 pstore 机制（利用一块预留内存，在重启后仍保留上一次启动的日志）保存日志。

设备树配置

在 kernel dts 文件中添加以下节点启用 ramoops（pstore）：

ramoops_mem: ramoops_mem {
    reg = <0x0 0x110000 0x0 0xf0000>;
    reg-names = "ramoops_mem";
};

ramoops {
    compatible = "ramoops";
    record-size = <0x0 0x20000>;
    console-size = <0x0 0x80000>;
    ftrace-size = <0x0 0x00000>;
    pmsg-size = <0x0 0x50000>;
    memory-region = <&ramoops_mem>;
};

查看 Last Log

系统重启后，在 /sys/fs/pstore/ 目录下查看：

# 查看 pstore 目录
ls /sys/fs/pstore/

实测：本固件 ramoops 已启用，正常启动（无 panic）时目录内容为：

console-ramoops-0
pmsg-ramoops-0

文件	说明
dmesg-ramoops-0	上次内核 panic 后保存的日志
console-ramoops-0	上次启动的 kernel log（优先级高于默认 log level 的日志）
pmsg-ramoops-0	上次用户空间的 log（Android 的 log）
ftrace-ramoops-0	某个时间段内的 function trace

使用方法：

# 查看内核 panic 日志
cat /sys/fs/pstore/dmesg-ramoops-0

# 查看上次启动的 kernel log
cat /sys/fs/pstore/console-ramoops-0

# 通过 logcat 解析上次用户空间日志
logcat -L

# 查看 function trace
cat /sys/fs/pstore/ftrace-ramoops-0

4.8 FIQ 调试模式

当设备死机或卡住时，可以在串口输入 fiq 命令查看系统状态。

实测：本固件内核 cmdline 已启用 FIQ 控制台（console=ttyFIQ0），earlycon 为 uart8250,mmio32,0xfeb50000（UART2）。

进入 FIQ 模式

# 在串口终端输入（需串口连接）
fiq

进入 FIQ Debugger 后，显示 debug> 提示符，可输入以下命令：

debug> help
FIQ Debugger commands:
  pc             PC status
  regs           Register dump
  allregs        Extended Register dump
  bt             Stack trace
  reboot [<c>]   Reboot with command <c>
  reset [<c>]    Hard reset with command <c>
  irqs           Interrupt status
  kmsg           Kernel log
  version        Kernel version
  sleep          Allow sleep while in FIQ
  nosleep        Disable sleep while in FIQ
  console        Switch terminal to console
  cpu            Current CPU
  cpu <number>   Switch to CPU<number>
  ps             Process list
  sysrq          sysrq options
  sysrq <param>  Execute sysrq with <param>

常用 FIQ 调试命令

# 查看当前 CPU 程序计数器
debug> pc

# 查看寄存器状态
debug> regs

# 查看堆栈回溯
debug> bt

# 查看所有 CPU 状态
debug> cpu
debug> cpu 1    # 切换到 CPU1

# 查看进程列表
debug> ps

# 查看内核日志
debug> kmsg

# 重启设备
debug> reboot

5. 代码详解

5.1 ADB 权限配置

在 Android 14 中，如需在 user 版本固件中使用 root 权限调试，可以烧写 boot-debug.img 替代 boot.img：

# 烧写 boot-debug.img（使用 upgrade_tool）
sudo upgrade_tool DI -b boot-debug.img

# 烧写后重启，即可获得 root 权限
adb root
adb remount

5.2 调试串口配置

RK3588 调试串口（UART2）设备树配置：

&uart2 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&uart2m0_xfer>;
};

引脚对应关系：

信号	GPIO	核心板引脚
UART2_TX_M0	GPIO0_B6_D	发送
UART2_RX_M0	GPIO0_B5_D	接收

串口参数：波特率 1500000（1.5Mbps），8 数据位，1 停止位，无校验。

实测依据：内核 cmdline 中的 earlycon=uart8250,mmio32,0xfeb50000 就是 UART2 的基地址，dmesg 开头也能看到 printk: bootconsole [uart8250] enabled。

5.3 日志级别配置

内核日志级别可通过 dmesg -n 或 /proc/sys/kernel/printk 配置：

# 查看当前日志级别
cat /proc/sys/kernel/printk

# 设置日志级别（数字越小优先级越高）
# 7=DEBUG, 6=INFO, 5=NOTICE, 4=WARNING, 3=ERR, 2=CRIT, 1=ALERT, 0=EMERG
echo "4 4 1 7" > /proc/sys/kernel/printk

6. 常见问题

6.1 ADB 无法识别设备

现象： adb devices 显示为空列表或 unauthorized。

原因：

1. 未开启 USB 调试
2. USB 驱动未安装（Windows）
3. 连接的是 USB Host 口而非 OTG 口
4. 设备上未确认 USB 调试授权

解决方案：

1. 确认已开启 Developer options -> USB debugging
2. 确认使用底板 OTG 接口（Type-C）连接
3. Windows 下安装 DriverAssitant v5.1.1
4. 检查设备屏幕是否有调试授权弹窗，确认并勾选"始终允许"
5. 撤销 USB 调试授权后重新连接：Settings -> Developer options -> Revoke USB debugging authorizations

6.2 Logcat 日志过多无法定位

现象： logcat 输出信息量巨大，难以找到关键信息。

原因： Android 系统日志级别默认输出 Verbose 级别，包含大量冗余信息。

解决方案：

1. 使用优先级过滤：logcat *:E（只显示 Error 级别）
2. 使用标签过滤：logcat -s TagName
3. 使用 grep 过滤：logcat | grep "Keyword"
4. 保存到文件后分析：logcat -d > log.txt
5. 使用 -v 参数格式化输出：logcat -v time（添加时间戳）、logcat -v threadtime（添加线程时间戳）

6.3 设备死机时无法获取日志

现象： 系统死机或卡死后，无法使用 ADB 或 logcat 获取日志。

原因： 系统崩溃后 ADB 守护进程（adbd）也可能不可用。

解决方案：

1. 使用串口连接，通过 FIQ 模式查看系统状态（fiq 命令）
2. 重启后查看 pstore 日志：cat /sys/fs/pstore/console-ramoops-0
3. 使用 logcat -L 查看上次重启前的用户空间日志
4. 确保 dts 中已配置 ramoops 节点以启用 last log 功能

6.4 Procrank 命令找不到

现象： 执行 procrank 提示 command not found。

原因： 某些 Android 14 固件可能未包含 procrank 工具。

解决方案：

1. 使用替代方案查看内存信息：

   # 使用 dumpsys meminfo 查看整体内存
   dumpsys meminfo
   
   # 查看指定进程内存
   dumpsys meminfo com.android.systemui
   
   # 通过 /proc 查看进程内存
   cat /proc/`pidof com.android.systemui`/status

2. 从 SDK 中提取 procrank 二进制文件并 push 到设备

3. 在完整编译的 userdebug 版本中确认 procrank 可用

实测说明：本固件（ssi_16_arm64 userdebug）已内置 procrank（/system/bin/procrank），adb root 后可直接运行。

6.5 ADB 连接多个设备冲突

现象： 连接多个 Android 设备时，adb shell 提示 error: more than one device。

解决方案：

# 列出所有设备
adb devices

# 指定设备执行命令
adb -s 0123456789ABCDEF shell
adb -s 192.168.1.100:5555 shell

# 使用环境变量指定默认设备
export ANDROID_SERIAL=0123456789ABCDEF

7. 相关文档

文档	说明
ch01-android-flashing-and-boot.md	系统烧录与启动
ch02-android-basic-operations.md	Android 系统基础操作
Debian-Ubuntu/quick-start-guide/ch01-boot-and-basic-operations.md	Linux 系统调试参考
quick-start-guide/ch02-development-environment.md	开发环境搭建（串口终端配置）
hardware-reference/ch01-core-board-specifications.md	核心板参数