1*e5143657SBernard Zhao.. include:: ../disclaimer-zh_CN.rst 2*e5143657SBernard Zhao 3*e5143657SBernard Zhao:Original: Documentation/dev-tools/gcov.rst 4*e5143657SBernard Zhao:Translator: 赵军奎 Bernard Zhao <bernard@vivo.com> 5*e5143657SBernard Zhao 6*e5143657SBernard Zhao在Linux内核里使用gcov做代码覆盖率检查 7*e5143657SBernard Zhao===================================== 8*e5143657SBernard Zhao 9*e5143657SBernard Zhaogcov分析核心支持在Linux内核中启用GCC的覆盖率测试工具 gcov_ ,Linux内核 10*e5143657SBernard Zhao运行时的代码覆盖率数据会以gcov兼容的格式导出到“gcov”debugfs目录中,可 11*e5143657SBernard Zhao以通过gcov的 ``-o`` 选项(如下示例)获得指定文件的代码运行覆盖率统计数据 12*e5143657SBernard Zhao(需要跳转到内核编译路径下并且要有root权限):: 13*e5143657SBernard Zhao 14*e5143657SBernard Zhao # cd /tmp/linux-out 15*e5143657SBernard Zhao # gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c 16*e5143657SBernard Zhao 17*e5143657SBernard Zhao这将在当前目录中创建带有执行计数注释的源代码文件。 18*e5143657SBernard Zhao在获得这些统计文件后,可以使用图形化的gcov前端工具(比如 lcov_ ),来实现 19*e5143657SBernard Zhao自动化处理Linux内核的覆盖率运行数据,同时生成易于阅读的HTML格式文件。 20*e5143657SBernard Zhao 21*e5143657SBernard Zhao可能的用途: 22*e5143657SBernard Zhao 23*e5143657SBernard Zhao* 调试(用来判断每一行的代码是否已经运行过) 24*e5143657SBernard Zhao* 测试改进(如何修改测试代码,尽可能地覆盖到没有运行过的代码) 25*e5143657SBernard Zhao* 内核最小化配置(对于某一个选项配置,如果关联的代码从来没有运行过, 26*e5143657SBernard Zhao 是否还需要这个配置) 27*e5143657SBernard Zhao 28*e5143657SBernard Zhao.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html 29*e5143657SBernard Zhao.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php 30*e5143657SBernard Zhao 31*e5143657SBernard Zhao 32*e5143657SBernard Zhao准备 33*e5143657SBernard Zhao---- 34*e5143657SBernard Zhao 35*e5143657SBernard Zhao内核打开如下配置:: 36*e5143657SBernard Zhao 37*e5143657SBernard Zhao CONFIG_DEBUG_FS=y 38*e5143657SBernard Zhao CONFIG_GCOV_KERNEL=y 39*e5143657SBernard Zhao 40*e5143657SBernard Zhao获取整个内核的覆盖率数据,还需要打开:: 41*e5143657SBernard Zhao 42*e5143657SBernard Zhao CONFIG_GCOV_PROFILE_ALL=y 43*e5143657SBernard Zhao 44*e5143657SBernard Zhao需要注意的是,整个内核开启覆盖率统计会造成内核镜像文件尺寸的增大, 45*e5143657SBernard Zhao同时内核运行也会变慢一些。 46*e5143657SBernard Zhao另外,并不是所有的架构都支持整个内核开启覆盖率统计。 47*e5143657SBernard Zhao 48*e5143657SBernard Zhao代码运行覆盖率数据只在debugfs挂载完成后才可以访问:: 49*e5143657SBernard Zhao 50*e5143657SBernard Zhao mount -t debugfs none /sys/kernel/debug 51*e5143657SBernard Zhao 52*e5143657SBernard Zhao 53*e5143657SBernard Zhao定制化 54*e5143657SBernard Zhao------ 55*e5143657SBernard Zhao 56*e5143657SBernard Zhao如果要单独针对某一个路径或者文件进行代码覆盖率统计,可以在内核相应路 57*e5143657SBernard Zhao径的Makefile中增加如下的配置: 58*e5143657SBernard Zhao 59*e5143657SBernard Zhao- 单独统计单个文件(例如main.o):: 60*e5143657SBernard Zhao 61*e5143657SBernard Zhao GCOV_PROFILE_main.o := y 62*e5143657SBernard Zhao 63*e5143657SBernard Zhao- 单独统计某一个路径:: 64*e5143657SBernard Zhao 65*e5143657SBernard Zhao GCOV_PROFILE := y 66*e5143657SBernard Zhao 67*e5143657SBernard Zhao如果要在整个内核的覆盖率统计(开启CONFIG_GCOV_PROFILE_ALL)中单独排除 68*e5143657SBernard Zhao某一个文件或者路径,可以使用如下的方法:: 69*e5143657SBernard Zhao 70*e5143657SBernard Zhao GCOV_PROFILE_main.o := n 71*e5143657SBernard Zhao 72*e5143657SBernard Zhao和:: 73*e5143657SBernard Zhao 74*e5143657SBernard Zhao GCOV_PROFILE := n 75*e5143657SBernard Zhao 76*e5143657SBernard Zhao此机制仅支持链接到内核镜像或编译为内核模块的文件。 77*e5143657SBernard Zhao 78*e5143657SBernard Zhao 79*e5143657SBernard Zhao相关文件 80*e5143657SBernard Zhao-------- 81*e5143657SBernard Zhao 82*e5143657SBernard Zhaogcov功能需要在debugfs中创建如下文件: 83*e5143657SBernard Zhao 84*e5143657SBernard Zhao``/sys/kernel/debug/gcov`` 85*e5143657SBernard Zhao gcov相关功能的根路径 86*e5143657SBernard Zhao 87*e5143657SBernard Zhao``/sys/kernel/debug/gcov/reset`` 88*e5143657SBernard Zhao 全局复位文件:向该文件写入数据后会将所有的gcov统计数据清0 89*e5143657SBernard Zhao 90*e5143657SBernard Zhao``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda`` 91*e5143657SBernard Zhao gcov工具可以识别的覆盖率统计数据文件,向该文件写入数据后 92*e5143657SBernard Zhao 会将本文件的gcov统计数据清0 93*e5143657SBernard Zhao 94*e5143657SBernard Zhao``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno`` 95*e5143657SBernard Zhao gcov工具需要的软连接文件(指向编译时生成的信息统计文件),这个文件是 96*e5143657SBernard Zhao 在gcc编译时如果配置了选项 ``-ftest-coverage`` 时生成的。 97*e5143657SBernard Zhao 98*e5143657SBernard Zhao 99*e5143657SBernard Zhao针对模块的统计 100*e5143657SBernard Zhao-------------- 101*e5143657SBernard Zhao 102*e5143657SBernard Zhao内核中的模块会动态的加载和卸载,模块卸载时对应的数据会被清除掉。 103*e5143657SBernard Zhaogcov提供了一种机制,通过保留相关数据的副本来收集这部分卸载模块的覆盖率数据。 104*e5143657SBernard Zhao模块卸载后这些备份数据在debugfs中会继续存在。 105*e5143657SBernard Zhao一旦这个模块重新加载,模块关联的运行统计会被初始化成debugfs中备份的数据。 106*e5143657SBernard Zhao 107*e5143657SBernard Zhao可以通过对内核参数gcov_persist的修改来停用gcov对模块的备份机制:: 108*e5143657SBernard Zhao 109*e5143657SBernard Zhao gcov_persist = 0 110*e5143657SBernard Zhao 111*e5143657SBernard Zhao在运行时,用户还可以通过写入模块的数据文件或者写入gcov复位文件来丢弃已卸 112*e5143657SBernard Zhao载模块的数据。 113*e5143657SBernard Zhao 114*e5143657SBernard Zhao 115*e5143657SBernard Zhao编译机和测试机分离 116*e5143657SBernard Zhao------------------ 117*e5143657SBernard Zhao 118*e5143657SBernard Zhaogcov的内核分析插桩支持内核的编译和运行是在同一台机器上,也可以编译和运 119*e5143657SBernard Zhao行是在不同的机器上。 120*e5143657SBernard Zhao如果内核编译和运行是不同的机器,那么需要额外的准备工作,这取决于gcov工具 121*e5143657SBernard Zhao是在哪里使用的: 122*e5143657SBernard Zhao 123*e5143657SBernard Zhao.. _gcov-test_zh: 124*e5143657SBernard Zhao 125*e5143657SBernard Zhaoa) 若gcov运行在测试机上 126*e5143657SBernard Zhao 127*e5143657SBernard Zhao 测试机上面gcov工具的版本必须要跟内核编译机器使用的gcc版本相兼容, 128*e5143657SBernard Zhao 同时下面的文件要从编译机拷贝到测试机上: 129*e5143657SBernard Zhao 130*e5143657SBernard Zhao 从源代码中: 131*e5143657SBernard Zhao - 所有的C文件和头文件 132*e5143657SBernard Zhao 133*e5143657SBernard Zhao 从编译目录中: 134*e5143657SBernard Zhao - 所有的C文件和头文件 135*e5143657SBernard Zhao - 所有的.gcda文件和.gcno文件 136*e5143657SBernard Zhao - 所有目录的链接 137*e5143657SBernard Zhao 138*e5143657SBernard Zhao 特别需要注意,测试机器上面的目录结构跟编译机器上面的目录机构必须 139*e5143657SBernard Zhao 完全一致。 140*e5143657SBernard Zhao 如果文件是软链接,需要替换成真正的目录文件(这是由make的当前工作 141*e5143657SBernard Zhao 目录变量CURDIR引起的)。 142*e5143657SBernard Zhao 143*e5143657SBernard Zhao.. _gcov-build_zh: 144*e5143657SBernard Zhao 145*e5143657SBernard Zhaob) 若gcov运行在编译机上 146*e5143657SBernard Zhao 147*e5143657SBernard Zhao 测试用例运行结束后,如下的文件需要从测试机中拷贝到编译机上: 148*e5143657SBernard Zhao 149*e5143657SBernard Zhao 从sysfs中的gcov目录中: 150*e5143657SBernard Zhao - 所有的.gcda文件 151*e5143657SBernard Zhao - 所有的.gcno文件软链接 152*e5143657SBernard Zhao 153*e5143657SBernard Zhao 这些文件可以拷贝到编译机的任意目录下,gcov使用-o选项指定拷贝的 154*e5143657SBernard Zhao 目录。 155*e5143657SBernard Zhao 156*e5143657SBernard Zhao 比如一个是示例的目录结构如下:: 157*e5143657SBernard Zhao 158*e5143657SBernard Zhao /tmp/linux: 内核源码目录 159*e5143657SBernard Zhao /tmp/out: 内核编译文件路径(make O=指定) 160*e5143657SBernard Zhao /tmp/coverage: 从测试机器上面拷贝的数据文件路径 161*e5143657SBernard Zhao 162*e5143657SBernard Zhao [user@build] cd /tmp/out 163*e5143657SBernard Zhao [user@build] gcov -o /tmp/coverage/tmp/out/init main.c 164*e5143657SBernard Zhao 165*e5143657SBernard Zhao 166*e5143657SBernard Zhao关于编译器的注意事项 167*e5143657SBernard Zhao-------------------- 168*e5143657SBernard Zhao 169*e5143657SBernard ZhaoGCC和LLVM gcov工具不一定兼容。 170*e5143657SBernard Zhao如果编译器是GCC,使用 gcov_ 来处理.gcno和.gcda文件,如果是Clang编译器, 171*e5143657SBernard Zhao则使用 llvm-cov_ 。 172*e5143657SBernard Zhao 173*e5143657SBernard Zhao.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html 174*e5143657SBernard Zhao.. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html 175*e5143657SBernard Zhao 176*e5143657SBernard ZhaoGCC和Clang gcov之间的版本差异由Kconfig处理的。 177*e5143657SBernard Zhaokconfig会根据编译工具链的检查自动选择合适的gcov格式。 178*e5143657SBernard Zhao 179*e5143657SBernard Zhao问题定位 180*e5143657SBernard Zhao-------- 181*e5143657SBernard Zhao 182*e5143657SBernard Zhao可能出现的问题1 183*e5143657SBernard Zhao 编译到链接阶段报错终止 184*e5143657SBernard Zhao 185*e5143657SBernard Zhao问题原因 186*e5143657SBernard Zhao 分析标志指定在了源文件但是没有链接到主内核,或者客制化了链接程序 187*e5143657SBernard Zhao 188*e5143657SBernard Zhao解决方法 189*e5143657SBernard Zhao 通过在相应的Makefile中使用 ``GCOV_PROFILE := n`` 190*e5143657SBernard Zhao 或者 ``GCOV_PROFILE_basename.o := n`` 来将链接报错的文件排除掉 191*e5143657SBernard Zhao 192*e5143657SBernard Zhao可能出现的问题2 193*e5143657SBernard Zhao 从sysfs复制的文件显示为空或不完整 194*e5143657SBernard Zhao 195*e5143657SBernard Zhao问题原因 196*e5143657SBernard Zhao 由于seq_file的工作方式,某些工具(例如cp或tar)可能无法正确地从 197*e5143657SBernard Zhao sysfs复制文件。 198*e5143657SBernard Zhao 199*e5143657SBernard Zhao解决方法 200*e5143657SBernard Zhao 使用 ``cat`` 读取 ``.gcda`` 文件,使用 ``cp -d`` 复制链接,或者使用附录B 201*e5143657SBernard Zhao 中所示的机制。 202*e5143657SBernard Zhao 203*e5143657SBernard Zhao 204*e5143657SBernard Zhao附录A:collect_on_build.sh 205*e5143657SBernard Zhao-------------------------- 206*e5143657SBernard Zhao 207*e5143657SBernard Zhao用于在编译机上收集覆盖率元文件的示例脚本 208*e5143657SBernard Zhao(见 :ref:`编译机和测试机分离 a. <gcov-test_zh>` ) 209*e5143657SBernard Zhao 210*e5143657SBernard Zhao.. code-block:: sh 211*e5143657SBernard Zhao 212*e5143657SBernard Zhao #!/bin/bash 213*e5143657SBernard Zhao 214*e5143657SBernard Zhao KSRC=$1 215*e5143657SBernard Zhao KOBJ=$2 216*e5143657SBernard Zhao DEST=$3 217*e5143657SBernard Zhao 218*e5143657SBernard Zhao if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then 219*e5143657SBernard Zhao echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2 220*e5143657SBernard Zhao exit 1 221*e5143657SBernard Zhao fi 222*e5143657SBernard Zhao 223*e5143657SBernard Zhao KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) 224*e5143657SBernard Zhao KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) 225*e5143657SBernard Zhao 226*e5143657SBernard Zhao find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \ 227*e5143657SBernard Zhao -perm /u+r,g+r | tar cfz $DEST -P -T - 228*e5143657SBernard Zhao 229*e5143657SBernard Zhao if [ $? -eq 0 ] ; then 230*e5143657SBernard Zhao echo "$DEST successfully created, copy to test system and unpack with:" 231*e5143657SBernard Zhao echo " tar xfz $DEST -P" 232*e5143657SBernard Zhao else 233*e5143657SBernard Zhao echo "Could not create file $DEST" 234*e5143657SBernard Zhao fi 235*e5143657SBernard Zhao 236*e5143657SBernard Zhao 237*e5143657SBernard Zhao附录B:collect_on_test.sh 238*e5143657SBernard Zhao------------------------- 239*e5143657SBernard Zhao 240*e5143657SBernard Zhao用于在测试机上收集覆盖率数据文件的示例脚本 241*e5143657SBernard Zhao(见 :ref:`编译机和测试机分离 b. <gcov-build_zh>` ) 242*e5143657SBernard Zhao 243*e5143657SBernard Zhao.. code-block:: sh 244*e5143657SBernard Zhao 245*e5143657SBernard Zhao #!/bin/bash -e 246*e5143657SBernard Zhao 247*e5143657SBernard Zhao DEST=$1 248*e5143657SBernard Zhao GCDA=/sys/kernel/debug/gcov 249*e5143657SBernard Zhao 250*e5143657SBernard Zhao if [ -z "$DEST" ] ; then 251*e5143657SBernard Zhao echo "Usage: $0 <output.tar.gz>" >&2 252*e5143657SBernard Zhao exit 1 253*e5143657SBernard Zhao fi 254*e5143657SBernard Zhao 255*e5143657SBernard Zhao TEMPDIR=$(mktemp -d) 256*e5143657SBernard Zhao echo Collecting data.. 257*e5143657SBernard Zhao find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; 258*e5143657SBernard Zhao find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; 259*e5143657SBernard Zhao find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; 260*e5143657SBernard Zhao tar czf $DEST -C $TEMPDIR sys 261*e5143657SBernard Zhao rm -rf $TEMPDIR 262*e5143657SBernard Zhao 263*e5143657SBernard Zhao echo "$DEST successfully created, copy to build system and unpack with:" 264*e5143657SBernard Zhao echo " tar xfz $DEST" 265