JLink Script文件基础及其在IAR下调用方法

JLink可以说是MCU开发者最熟悉的调试工具了，相比于其他调试器（比如DAPLink、ST-LINK、I-jet等），JLink除了性能强大之外，还胜在其配套各种软件小工具相当方便易用。JLink工具玩得熟的老司机一定在J-Link Commander命令行工具(即\SEGGER\JLink_Vxxx\JLink.exe)下敲过命令，读写内存、下载文件、操控内核无所不能。这个底层工具其实也是JLink精华所在，今天痞子衡要讲的JLink Script文件主题其实就是依赖这个工具。

一、JLink Script作用

如果你有脚本语言经验（比如Python），你应该很熟悉脚本语言那一套规则，脚本语言不同于一般编译型语言（比如C），编译型语言经过编译链接生成的二进制机器码被CPU直接识别执行，但脚本不需要预编译，它是由配套解释器动态翻译执行的，而CPU负责执行的是脚本解释器。

基于上述概念JLink.exe就是一个解释器，它能解释执行JLink Script文件，其命令格式如下，使用-JLinkScriptFile参数指定JLink Script文件路径便可执行JLink Script文件里的语句。

• 命令格式：JLink.exe -JLinkScriptFile MyFile.JLinkScript

为什么需要JLink Script文件？有些情况下，需要定制J-Link执行的某些操作，比如J-Link连接顺序或者执行复位的方式等，或者一些定制的硬件板需要一些特殊处理，这些动作没法直接集成到J-Link软件的通用处理里，因此需要被放在单独的JLink Script文件里，根据连接的具体目标对象来指定加载执行。

• Note：其实除了常见的明文脚本(.JLinkScript)文件之外，JLink Script文件还有另外一种经过预编译的文件形式(.pex)，这种格式是纯二进制的，可以保护脚本内容。

二、JLink Script文件基础

JLink Script这一套东西整体上由五大部分组成：基本语法、全局DLL变量、全局DLL常量、系统API接口、用户自定义动作集。

2.1 脚本基础语法

JLink Script并不是一个通用的脚本语言，因此其并不像你熟知的那些Python之类的脚本语言那样语法完善，它仅是为了配合JLink完成一些必要操作。JLink Script语法跟C语言类似，支持C语言中允许的大多数语句（if else，while，变量声明，…），但不是所有的语句。

此外，还有一些语句是特定于JLink Script的，JLink Script已经尽可能允许最大的灵活性，因此几乎任何必要的目标初始化操作都可以得到支持。

• 语法简明手册：https://wiki.segger.com/J-Link_script_files#Script_file_language

2.2 全局DLL常/变量

JLink Script在被解释执行时，其实是和JLink DLL（即\SEGGER\JLink_Vxxx\JLinkARM.dll）联动的，DLL里存放了JLink各种底层功能集合，同时也默认预定义一些全局变量，这些变量用于DLL配置，需要在JLink Script中被赋值。比如最基础的变量CPU，用于指示连接的目标内核类型，而支持的全部CPU类型都定义在全局常量里。

• 变量列表：https://wiki.segger.com/J-Link_script_files#Global_DLL_variables
• 常量列表：https://wiki.segger.com/J-Link_script_files#Global_DLL_constants

2.3 系统内置的API接口

JLink DLL中实现了很多基础操作功能，这些功能通过API函数接口形式开放给JLink Script来调用，这些API全部以JLINK_为前缀。举一个比较常用的API函数JLINK_TARGET_Halt()，这个函数功能就是挂起目标内核。

• API接口列表：https://wiki.segger.com/J-Link_script_files#Script_file_API_functions

2.4 用户可自定义动作集

终于要讲到JLink Script最关键的部分了，前面都是基础，而JLink Script最核心的功能其实在用户自定义动作集合里，这些动作由JLink预先定义，但是内部具体操作可由用户来编写。在IDE在线下载调试过程中按规定触发条件来调用执行这些动作，下表列出了全部动作，其中蓝框标出的四个动作最常用。

• InitTarget()：替换J-Link DLL的目标CPU自动查找过程。对于默认情况下不可访问且需要执行一些特殊步骤才能成功执行常规调试连接过程的目标CPU非常有用。
• SetupTarget()：在InitTarget()以及JLink常规调试连接序列之后被调用，通常用于更高级别的CPU调试设置，如写入某些内存位置、初始化PLL以加快下载速度等。
• ResetTarget()：替换DLL的复位策略。无论在DLL中选择了什么复位类型，如果存在此函数，将调用它而不是DLL内部复位。
• AfterResetTarget()：在ResetTarget()之后调用。复位结束后，用于初始化一些必要外设（比如看门狗）。除此之外，对于某些内核类型有必要在复位后执行一些特殊操作，以保证复位后的设备功能正常。

• 自定义动作列表：https://wiki.segger.com/J-Link_script_files#Customizable_actions

三、JLink Script在IAR下调用方法

单纯的JLink Script没有意义，需要和工具链配合使用才能发挥最大作用，除了SEGGER工具之外（Embedded Studio、Ozone、SystemView），JLink Script还可以和常见的IDE环境（IAR/Keil/Eclipse）一起工作，痞子衡以IAR为例介绍三种调用JLink Script的方法（使用的是恩智浦i.MXRT685-EVK开发板做的测试）。

3.1 JLinkDevices.xml中指定

第一种方法是在 \SEGGER\JLink_Vxxx\JLinkDevices.xml 文件中指定，如果你对这个文件不了解，可先回顾下痞子衡之前写的文章 《串行NOR Flash下载算法(J-Link工具篇)》。

给板卡通上电，连上J-Link调试器，随便打开一个测试工程（\SDK_xxx_EVK-MIMXRT685\boards\evkmimxrt685\demo_apps\hello_world\iar），选择flash_debug，将其工程选项做如下更改：

1. 设置内核为Cortex-M33，即不启用Device里的NXP MIMXRT685S_CM33设置
2. 调试器选择J-Link/J-Trace，且不要勾选Use flash loader(s)

这么做是为了在IAR下载时不用NXP MIMXRT685S_CM33默认指定的JLink下载算法，而弹出一个框让用户主动选择合适的JLink下载算法，我们修改JLinkDevices.xml如下：

• Note：\SEGGER\JLink_Vxxx\Devices\NXP\iMXRT6xx_UFL\iMXRT6xx_CortexM33.JLinkScript便是我们要测试的JLink Script，在里面我们可以加一句JLINK_SYS_Report("J-Link script: This UFL script comes from Segger package"); 便于检查调用结果。

选好MIMXRT685_UFL这个指定下载算法后，直接在IAR里点击下载，进入正常调试后，可以在Debug Log里看到iMXRT6xx_CortexM33.JLinkScript确实被调用了。

3.2 工程选项Debugger/Extra Options中指定

在上一小节测试基础上，将JLinkDevices.xml里的 JLinkScriptFile="Devices/NXP/iMXRT6xx_UFL/iMXRT6xx_CortexM33.JLinkScript" 这一句去掉，即不在下载算法里直接调用JLink Script。然后将iMXRT6xx_CortexM33.JLinkScript文件拷贝一份放到\SDK_xxx_EVK-MIMXRT685\boards\evkmimxrt685\demo_apps\hello_world\iar目录下，并在IAR工程选项中做如下设置：

• Note：\SDK_xxx_EVK-MIMXRT685\boards\evkmimxrt685\demo_apps\hello_world\iar\iMXRT6xx_CortexM33.JLinkScript便是我们要测试的JLink Script，在里面我们可以加一句JLINK_SYS_Report("J-Link script: This UFL script comes from Extra Option"); 便于检查调用结果。

再次在IAR里点击下载，进入正常调试后，可以在Debug Log里看到新的iMXRT6xx_CortexM33.JLinkScript确实被调用了。

3.3 工程目录settings文件下指定

在上一小节测试基础上，不勾选IAR工程选项Extra Options中Use command line options。然后将iMXRT6xx_CortexM33.JLinkScript文件拷贝一份放到\SDK_xxx_EVK-MIMXRT685\boards\evkmimxrt685\demo_apps\hello_world\iar\settings目录下，需要重命名JLink Script文件与测试工程名一致：

• Note：\SDK_xxx_EVK-MIMXRT685\boards\evkmimxrt685\demo_apps\hello_world\iar\settings\hello_world_flash_debug.JLinkScript便是我们要测试的JLink Script，在里面我们可以加一句JLINK_SYS_Report("J-Link script: This UFL script comes from settings"); 便于检查调用结果。

再次在IAR里点击下载，进入正常调试后，可以在Debug Log里看到hello_world_flash_debug.JLinkScript确实被调用了。

最后，大家可以公众号『嵌入式专栏』，后台回复“IAR系列教程”查看关于IAR的更多内容。