MindStudio Debug VSCode Plugin

介绍

MindStudio Debug VSCode Plugin基于msdebug上板调试算子工具提供VSCode可视化调试昇腾算子功能。 附：算子开发编程语言Ascend C简介

特性

• 断点调试（设置/删除/禁用/启用断点）
• 单步执行调试(逐行执行/内部执行/跳出函数)/继续/暂停/重启
• 查看变量/寄存器/堆栈/断点信息，监视器支持执行表达式
• 内存查询
• 核切换
• NPU coredump文件可视化调试

规格要求

• VSCode-huawei (v1.81.3版本及以上)
• VSCode-huawei已安装远程登录插件
• 支持平台: Linux
• 调试AscendC算子程序时，Linux环境已安装CANN工具包（含算子调试器）
• 仅支持调试AscendC算子，且算子经过调试模式重新编译后才能调试
• 当前支持的CANN包最低版本：
  • 社区版： 8.0.RC3.alpha001
  • 商用版： 8.0.RC3

约束

• 参考CANN工具包的约束要求

功能

软件包下载和完整性校验

1. （推荐）从插件市场直接在线安装
2. 若软件包从插件市场下载后计划后续本地安装，安装前建议进行完整性校验：

sha256sum Ascend.MindStudio-Debug-VSCode-Plugin-{version}.vsix # 验证vsix包，若校验码一致，则vsix包在下载中没有受损

快速使用

1. 打开VSCode-huawei IDE界面，安装远程登录插件(如RemoteDev)
2. IDE界面远程SSH登录算子开发环境，打开已编译的算子工程文件(本插件不具备编译功能)
3. 安装MindStudio Debug VSCode Plugin插件

• （推荐）IDE界面插件市场在线安装

• IDE界面离线本地安装

 - 插件.vsix文件上传linux环境
 - 展开IDE界面左侧边栏的插件菜单
 - 点击右上角...图标，选择Install from VSIX...选项，选择本地的插件文件进行安装

• 后台命令行离线本地安装

 - 插件.vsix文件上传linux环境
 - 后台输入命令安装插件文件: code --install-extension /xx_dir/MindStudio-Debug-VSCode-Plugin-1.0.5.vsix

4. 点开debug侧边工具栏，若未生成.vscode/launch.json文件，则根据提示点击生成launch.json文件(弹窗中调试器选择MSDebug)

• 需要注意vscode当前打开目录的选择，因为当前目录会影响launch.json文件中cwd参数的值。若msdebug的调试参数文件和打断点的源码文件不直接在同一个目录下（比如源码在src目录下，测试用例在test目录下），则建议切换当前目录为共同的父目录下，再创建.vscode/launch.json文件。

5. 在.vscode/launch.json中添加调试配置(格式参考下面推荐配置)
6. (可选)配置launch.json的environmentScripts参数时，若用户需要配置复杂逻辑的环境变量执行脚本（脚本包含除了export key=value以外的逻辑），需要执行以下步骤：

• 用户登录linux终端（如打开vscode IDE的终端栏），先执行设置环境变量的相关脚本，例如source /xx/set_env1.sh; source /yy/set_env2.sh等
• 接着输入 env> ${path_to_project}/.vscode/.env命令并执行，手动导出环境变量信息到.env配置文件中，供后续插件读取
• 最后将生成的.env文件路径：/xx/xx/.vscode/.env（绝对路径格式），配置到launch.json的environmentScripts参数中，配置方式参考后面章节

7. debug侧边工具栏中，选择已配置的调试器，点击debug或按F5启动调试

• launch方式推荐配置（可复制）

{
    "configurations": [
        {
            "name": "xx-debug",
            "type": "msdebug-mi",
            "request": "launch",
            "cwd": "${workspaceFolder}",
            "target": "/xxx/xx/xx_operator",
            "targetArgs": [
                "arg1",
                "arg2"
            ],
            "msdebugMiPath": "/xx/x/msdebug-mi",
            "environmentScripts": [
                "/xxx/xx/Ascend/ascend-toolkit/set_env.sh",
                "/xxx/xx/xx-user-bussiness/set_env.sh",
                "/xx/xxx/project/.vscode/.env"            // 命令行执行环境变量设置的命令(export xx=xx)和脚本(source /xx/set_env.sh)之后，输入命令env > .vscode/.env生成环境变量配置文件
            ],
            "environment": [
                {
                    "name": "LD_LIBRARY_PATH",
                    "value": "/xx/x/lib:${LD_LIBRARY_PATH}"
                },
                {
                    // 可选：通过配置LAUNCH_KERNEL_PATH环境变量，指定算子加载路径，导入调试信息
                    "name": "LAUNCH_KERNEL_PATH",
                    "value": "/xx/x/my_kernel.o"
                }
            ]
        }
    ]
}

• name 调试插件的名称
• type 固定值"msdebug-mi"
• request 固定值"launch"
• cwd 调试器启动的工作目录。注意：当target和targetArgs参数不为绝对路径时，cwd参数在target和targetArgs参数上生效。${workspaceFolder}为vscode IDE的当前打开目录。
• target (必要配置项)被调试的可执行文件的路径。target可设为算子二进制文件，或者python等二进制命令，建议配置绝对路径
• targetArgs 可选配置，被调试的算子可执行文件的参数列表。举例"targetArgs": ["arg1","arg2"]，底层msdebug-mi调试命令调用效果等价于: # msdebug ${target} ${arg1} ${arg2}，若不配置target和targetArgs的绝对路径，则默认加上cwd的路径前缀。
• printMiInput 可选配置，打印msdebug-mi的输入命令日志。默认为false建议不配置，避免生成大量冗余日志
• printMiOutput 可选配置，打印msdebug-mi的命令输出信息日志。默认为false建议不配置，避免生成大量冗余日志
• skipEnvCheck 可选配置，插件初始化加载时是否跳过环境校验。默认为false建议不配置
• enableLog 可选配置，是否归档debug console生成的日志打印，用于问题定位，日志位置为vscode-server目录下的msdebuglogs/msdebug.log。默认为false建议不配置
• msdebugMiPath 可选配置，调试器路径，不配置默认为$ASCEND_TOOLKIT_HOME/tools/msdebug/bin/msdebug-mi
• environmentScripts 可选配置，为包含msdebug启动所需的环境变量的脚本数组(默认支持配置内容仅含export key=value的脚本文件，而含复杂逻辑脚本的environmentScripts配置方法参考快速使用-第6点)，依次加载数组中各脚本中的环境变量。若有重复设置可能会产生值覆盖。
• environment 可选配置，为包含自定义环境变量的对象数组，在加载完environmentScripts脚本中的环境变量后依次加载environment中的环境变量，格式需满足:[{"name": "xxx", "value":"yyy"}]。若和environmentScripts配置的脚本中有重复设置的环境变量可能会产生值覆盖。

断点调试（设置/删除/禁用/启用断点）

• 可以在算子程序行号显示处添加、删除、禁用、开启或关闭断点，也可以在左侧边栏中的底部断点工具栏执行相同操作。
• 支持调试cce文件类型，需要设置vscode系统配置：（1）Ctrl + Shift + P打开命令窗口，输入open workspace settings，打开工作区配置 （2）搜索Files:Associations，添加键值对[*.cce, cpp]新增对.cce文件类型的支持。

单步执行调试(逐行执行/内部执行/跳出函数)/继续/暂停/重启

• 可以单击顶部调试工具栏上的图标控制程序，包括单步执行、步入、步出、继续、暂停、重启或停止程序的操作。

查看变量/寄存器/堆栈/断点信息，监视器支持执行表达式

• 启动调试后，程序会停止在断点，当进程处于停止状态时，可以在IDE界面左侧查看当前线程的变量、堆栈、监视器和断点信息。其中监视器支持执行表达式。

内存查询

• 变量右键内存查询
• 调试停在断点时，光标移到代码编辑区的变量上，右键并点击Read Memory菜单跳转到内存查看页面，支持切换数据类型和列数改变内存展示效果
• 自定义内存查看
• 点击右下角Read Memory菜单项也可跳转到内存查看页面。支持手动输入内存位置、内存地址、内存大小来进行自定义内存位置的内存查看

核切换

• 左下角展开KERNEL FOCUS工具栏，可查看核状态，高亮行是当前所在核；点击其他行数据进行切核

NPU coredump文件可视化调试

• NPU coredump调试官网特性说明
• launch.json增量配置（可以和原先msdebug-mi配置共存）

{
    "configurations": [
        {
            "name": "xx-debug",
            "type": "msdebug-mi",
            ...
        },
        // 以下为coredump调试配置
        {
            "name": "xx-debug",
            "type": "msdebug-coredump",     // 注意区别
            "request": "launch",
            "cwd": "${workspaceFolder}",
            "msdebugMiPath": "/xx/x/msdebug-mi", 
            "environmentScripts": [
                xxx         // 和msdebug-mi调试参数设置一致即可
            ],
            "environment": [
                xxx         // 和msdebug-mi调试参数设置一致即可
            ]
        }
    ]
}

• launch.json参数说明
  • 原先type=msdebug-mi配置参数继承：name、type（值不同）、requtest、cwd、msdebugMiPath、printMiInput、printMiOutput、environment、environmentScripts、enableLog、skipEnvCheck.
  • 新增dumpfilePath参数：必要配置项，coredump文件路径（和cwd配置共同组合成coredump文件的绝对路径，也可单独设成绝对路径）。建议设置前检查下coredump文件是否具备执行权限！！
• 使用方法：
  • 配置launch.json后，选择msdebug-coredump方式启动调试
  • 启动后加载coredump info界面，可以查看coredump信息 (不慎关闭也可通过右下角read coredump按钮重新打开页面)
  • 左下角展开切核菜单，进行NPU核切换
  • coredump ino界面点击每一行最左memory按钮，弹窗显示该地址对应的内存值（若内存地址含invalid则查看无效）
  • 点击右下角的read memory按钮跳转内存查看页面，可以自定义查询内存值。
  • 点击右下角的read register按钮跳转寄存器查看页面，可以查看寄存器值。
  • 结束调试

免责声明

所有对本软件及其附属内容的下载和使用，均视为已仔细阅读并完全同意以下条款：

• 本软件为实验性产品，仅用于个人学习和交流。严禁将其用于任何违法或恶意目的。
• 若发现有任何第三方商业行为及违法使用情况，软件作者有权撤销其使用权限。
• 使用本软件所产生的风险完全由用户自行承担，软件作者不承担任何责任。
• 对于本声明中未涵盖的问题，请参照国家相关法律法规。
• 本软件声明的版权及其修改、更新和最终解释权归软件作者所有。