当前位置：首页 > news >正文

OpenHarmony子系统开发 - 调测工具（一）

news 来源：原创 2025/9/18 21:50:43

OpenHarmony子系统开发 - 调测工具（一）

一、bytrace使用指导

简介

bytrace是开发人员用于追踪进程轨迹、分析性能的一种工具，主要对内核ftrace进行了封装和扩展，来支持用户态的打点。通过该工具可以打开想要查看的用户态和内核label（通过下面命令行bytrace -l，查看支持的所有label），然后通过命令行进行抓取trace信息到指定文件中。

参数说明

bytrace当前支持以下命令：

表1 命令行列表

Option	Description
-h，--help	查看option帮助
-b n，--buffer_size n	指定_n_(KB)内存大小用于存取trace日志，默认2048KB
-t n，--time n	用来指定trace运行的时间（单位：s），取决于需要分析过程的时间
--trace_clock clock	trace输出的时钟类型，一般设备支持boot、global、mono、uptime、perf等，默认为boot
--trace_begin	启动抓trace
--trace_dump	将数据输出到指定位置（默认控制台）
--trace_finish	停止抓trace，并将数据输出到指定位置（默认控制台）
-l，--list_categories	输出手机能支持的trace模块
--overwrite	当缓冲区满的时候，将丢弃最新的信息。（默认丢弃最老的日志）
-o filename，--output filename	指定输出的目标文件名称
-z	抓取trace后进行压缩

使用实例

准备工作，使用bytrace工具需要先进入shell命令行：

hdc shell

以下是常用bytrace命令示例，供开发者参考：

查询支持的label。

bytrace -l

或者

bytrace --list_categories

设置4M缓存，抓取10秒，抓取label为ability的trace信息。

bytrace -b 4096 -t 10 --overwrite ability > /data/mytrace.ftrace

设置trace的输出时钟为mono。

bytrace --trace_clock mono  -b 4096 -t 10 --overwrite ability > /data/mytrace.ftrace

抓取trace后进行压缩。

bytrace -z  -b 4096 -t 10 --overwrite ability > /data/mytrace.ftrace

二、hdc使用指导

hdc（OpenHarmony Device Connector）是 OpenHarmony 为开发人员提供的用于调试的命令行工具，通过该工具可以在Windows/Linux/MacOS等系统上与开发机或者模拟器进行交互。

下文将介绍hdc的环境准备和常用命令及使用举例。

环境准备

hdc 工具获取方式：

通过OpenHarmony sdk获取，hdc在sdk的toolchains目录下。

使用举例：

下面以windows侧使用方式举例：

获取windows的sdk，将hdc.exe放到磁盘某个位置即可使用。

注意事项

使用hdc，如果出现异常，可以尝试通过hdc kill命令杀掉hdc服务，或者通过hdc start -r命令重启服务进程进行解决。
如果出现hdc list targets获取不到设备信息，通过任务管理器查看是否有hdc进程存在，如果进程存在，可以通过杀掉该进程进行解决。

option相关的命令

option涉及以下命令：

-h/help -v/version 用于显示hdc相关的帮助、版本信息。

表1 命令说明

返回值返回值说明
返回对应信息帮助或者版本信息

使用方法：
```
hdc -h / hdc help
```
```
hdc -v / hdc version
```
-l 0-5 用于指定运行时日志等级,默认为LOG_INFO。

表2 命令说明

参数参数说明
0 LOG_OFF
1 LOG_FATAL
2 LOG_WARN
3 LOG_INFO
4 LOG_DEBUG
5 LOG_ALL

使用方法：
```
hdc -l5 start
```
-t key 用于连接指定设备标识为key的设备。

表3 命令说明

参数参数说明
key 为 IP地址:port 格式，或者USB序列号
返回值 返回值说明
①error: device '***' not found
②Nothing to do... ①设备不存在
②附加的命令不存在

使用方法：

该option需要与具体的操作命令搭配使用，下面以shell命令举例：

hdc list targets （获取设备信息）

hdc -t key shell （-t后面添加的_key_ 需要替换为上面查询的设备信息）

说明： 一台开发机可支持多个设备连接，每个设备有其唯一的设备标识，如果通过网络与设备连接,其标识为IP地址:port格式，如果通过USB连接则标识为设备sn号。该命令需要跟随具体操作命令。
checkserver 用于获取client-server版本。

表4 命令说明

返回值返回值说明
Client version: server version: client-server版本号

使用方法：
```
hdc checkserver
```

返回值	返回值说明
返回对应信息	帮助或者版本信息

参数	参数说明
0	LOG_OFF
1	LOG_FATAL
2	LOG_WARN
3	LOG_INFO
4	LOG_DEBUG
5	LOG_ALL

参数	参数说明
key	为 IP地址:port 格式，或者USB序列号
返回值	返回值说明
①error: device '***' not found ②Nothing to do...	①设备不存在 ②附加的命令不存在

返回值	返回值说明
Client version: server version:	client-server版本号

查询设备列表的命令

查询设备列表涉及以下命令：

list targets[-v]

显示所有已经连接的目标设备列表

表5 命令说明

参数	参数说明
-v	添加-v选项，则会打印设备详细信息
返回值	返回值说明
①返回设备信息 ②[Empty]	①已经连接的设备列表信息 ②没有查询到设备信息

使用方法：

hdc list targets

hdc list targets -v

服务进程相关命令

服务进程涉及以下命令：

target mount 以读写模式挂载系统分区。

表6 命令说明

参数参数说明
无无
返回值 返回值说明
①Mount finish
②返回具体信息 ①成功情况下返回的信息
②失败情况下的具体信息

使用方法：
```
hdc target mount
```
target boot 设备重启。

使用方法：
```
hdc target boot
```
smode [-r] 授予后台服务进程root权限，使用-r参数取消授权。

使用方法：
```
hdc smode
```
```
hdc smode -r
```
kill [-r] 终止服务进程。

表7 命令说明

参数参数说明
-r 触发服务重启
返回值 返回值说明
①Kill server finish
②返回具体信息 ①成功情况下返回的信息
②失败情况下的具体信息

使用方法：
```
hdc kill
```
start [-r] 启动服务进程。

表8 命令说明

参数参数说明
-r 如果服务进程已经启动，-r选项会触发服务进程重新启动
返回值 返回值说明
无无

使用方法：
```
hdc start
```

参数	参数说明
无	无
返回值	返回值说明
①Mount finish ②返回具体信息	①成功情况下返回的信息 ②失败情况下的具体信息

参数	参数说明
-r	触发服务重启
返回值	返回值说明
①Kill server finish ②返回具体信息	①成功情况下返回的信息 ②失败情况下的具体信息

参数	参数说明
-r	如果服务进程已经启动，-r选项会触发服务进程重新启动
返回值	返回值说明
无	无

网络相关的命令

网络部分涉及以下命令：

tconn host[:port][-remove] 通过【ip地址：端口号】来指定连接的设备

表9 命令说明

参数	参数说明
host[:port]	为IP地址:port格式
-remove	表示断开与指定设备的连接
返回值	返回值说明
①返回具体信息 ②无	①失败情况下的具体信息 ②成功情况下无返回值

使用方法（举例）：

hdc tconn 192.168.0.100:8710

tmode usb 执行后设备端对应daemon进程重启，并首先选用USB连接方式。

表10 命令说明

参数参数说明
无无
返回值 返回值说明
①返回具体信息
②无 ①失败情况下的具体信息
②成功情况下无返回值

使用方法：
```
hdc tmode usb
```
tmode port port-number 执行后设备端对应daemon进程重启，并优先使用网络方式连接设备，如果连接设备失败，再选择USB连接。

表11 命令说明

参数参数说明
port-number listen连接的网络端口号
返回值 返回值说明
①返回具体信息
②无 ①失败情况下的具体信息
②成功情况下无返回值

使用方法：
```
hdc tmode port 8710
```
说明： 执行完毕后，远端daemon将会退出并重启，默认启用TCP连接，如果不加上listen端口则listen随机端口。
fport localnode remotenode 端口转发，指定主机端口转发数据到设备侧端口。

使用方法：
```
hdc fport tcp:1234 tcp:1080
```
rport remotenode localnode 端口转发，指定设备侧端口转发数据到主机端口。

使用方法：
```
hdc rport tcp:2080 tcp:2345
```
fport ls 列出全部转发端口转发任务。

表12 命令说明

参数参数说明
无无
返回值 返回值说明
'tcp:1234 tcp:1080' [Forward] 正向端口转发任务
'tcp:2080 tcp:2345' [Reverse] 反向端口转发任务

使用方法：
```
hdc fport ls
```
fport rm 删除指定端口转发任务。

使用方法：
```
hdc fport rm tcp:1234 tcp:1080
```

参数	参数说明
无	无
返回值	返回值说明
①返回具体信息 ②无	①失败情况下的具体信息 ②成功情况下无返回值

参数	参数说明
port-number	listen连接的网络端口号
返回值	返回值说明
①返回具体信息 ②无	①失败情况下的具体信息 ②成功情况下无返回值

参数	参数说明
无	无
返回值	返回值说明
'tcp:1234 tcp:1080' [Forward]	正向端口转发任务
'tcp:2080 tcp:2345' [Reverse]	反向端口转发任务

文件相关的命令

文件部分涉及以下命令：

file send local remote 发送文件至远端设备。

表13 命令说明

参数	参数说明
local	本地待发送文件路径
remote	远程待接收文件路径
返回值	返回值说明
①返回具体信息 ②返回传输结果	①失败情况下的具体信息 ②成功传输的结果信息

使用方法（举例）：

hdc file send E:\a.txt   /data/local/tmp/a.txt

file recv [-a] remote local 从远端设备接收文件至本地。

表14 命令说明

参数	参数说明
-a	文件保留时间戳模式
local	本地待接收文件路径
remote	远程待发送文件路径
返回值	返回值说明
①返回具体信息 ②无	①失败情况下的具体信息 ②成功情况下无返回值

使用方法（举例）：

hdc file recv  /data/local/tmp/a.txt   ./a.txt

应用相关的命令

应用部分涉及以下命令：

install [-r/-d/-g] package 安装OpenHarmony APP package。

表15 命令说明

参数	参数说明
package	OpenHarmony应用安装包文件名
-r	替换已存在应用
-d	允许降级安装
-g	应用动态授权
返回值	返回值说明
①返回具体信息 ②无	①失败情况下的具体信息 ②成功情况下无返回值

使用方法（举例）：

hdc install hwadmin.hap

uninstall [-k] package 卸载OpenHarmony应用。

表16 命令说明

参数参数说明
package OpenHarmony应用安装包
-k 保留/data/cache
返回值 返回值说明
①返回具体信息
②无 ①失败情况下的具体信息
②成功情况下无返回值

使用方法（举例）：
```
hdc uninstall package
```

参数	参数说明
package	OpenHarmony应用安装包
-k	保留/data/cache
返回值	返回值说明
①返回具体信息 ②无	①失败情况下的具体信息 ②成功情况下无返回值

调试相关的命令

调试涉及以下命令：

hilog 支持抓取log信息。

表17 命令说明

参数参数说明
无无
返回值 返回值说明
返回具体信息抓取的日志信息

抓取hilog日志：
```
hdc hilog
```
清理hilog缓存日志：
```
hdc shell "hilog -r"
```
shell [command] 远程执行命令或进入交互命令环境。

表18 命令说明

参数参数说明
command 需要执行的单次命令
返回值 返回值说明
返回具体信息 shell后面执行命令的结果信息

使用方法：
```
hdc shell
```
jpid 获取可调试进程列表。

使用方法：
```
hdc jpid
```

参数	参数说明
无	无
返回值	返回值说明
返回具体信息	抓取的日志信息

参数	参数说明
command	需要执行的单次命令
返回值	返回值说明
返回具体信息	shell后面执行命令的结果信息

常见问题

hdc连接不到设备

现象描述 执行 "hdc list targets"命令后结果为：[Empty]
解决方法
1. 设备没有被识别：在设备管理器中查看是否有hdc设备，在通用串行总线设备中会有“HDC Device”信息。如果没有，hdc无法连接。此时需要断开并重联PC和OpenHarmony设备之间的USB连接，或者烧写最新的镜像。
2. hdc工作异常：可以执行"hdc kill"或者"hdc start -r"杀掉hdc服务或者重启hdc服务，然后再执行hdc list targets查看是否已经可以获取设备信息。
3. hdc与设备不匹配：如果设备烧写的是最新镜像，hdc也需要使用最新版本。

hdc运行不了

现象描述 点击hdc.exe文件无法运行。
解决方法
1. 运行环境异常： linux版本建议ubuntu 18.04以上 64位，其他相近版本也可；libc++.so引用错误请使用ldd/readelf等命令检查库引用 windows版本建议windows10 64位，如果低版本windows winusb库缺失，请使用zadig更新库。对于复合设备，需要使用zadig工具安装libusb-win32驱动。
2. 如何运行hdc.exe： hdc.exe不需要安装，直接放到磁盘上就能使用，也可以添加到环境变量中。通过打开cmd执行hdc命令直接使用。

hdc client如何远程访问hdc server

使用场景

本地client指定远程server上的设备，执行hdc命令。
连接步骤
1. 关闭本地sever：
```
hdc kill
```
2. -s [ip:]port -m 启动远程server：
```
hdc -s severIP:8710 -m
```
3. -s [ip:]port command 指定server执行指令：
```
hdc -s severIP:8710 list targets
```