Scripting support

The LinkServer debug server supports a Basic like programming language that can be used to script low-level target operations.

Script format

The LinkServer scripts are written in a simple version of the BASIC programming language. In this variant of BASIC, 26 variables are available (%a to %z).

The available functions are described in the Low-level functions section.

Arguments can be passed in to the script by assigning values to the variables. The variables that can be used depend on the script invocation method. The LinkServer scripts can be invoked as follows:

  • via telnet and console connections: by assigning values to the variables explicitly before running the script text

  • on the Remote Procedure Call connections (via GDB server): by providing values for four RPC function values that are always assigned to a%, b%, c% and d%

Supplied scripts

A set of scripts (*.scp) are supplied within the LinkServer installation at:

These scripts can be referenced from device specific JSON data files, when needed. The call-outs where scripts can be referenced (if required) are:

  • preconnect-script and connect-script are intended to assist with the initial debug connection

  • preattach-script is intended to assist with the attach connection

  • reset-script is intended to assist with the target reset

  • masserase-script is intended to assist with resurrecting a locked Kinetis/MCXC/MCXE24x device

Preconnect scripts

Some chips require a preconnect script that prepares the target MCU for the initial debug connection. The preconnect-script (if available) helps establish access to the debug infrastructure (for example, the CoreSight DAP) before any debug session is requested. Execution of these scripts is requested via the LinkServer telnet interface. On entry to the preconnect-script, these variables have these values assigned:

  • a% is the probe index used

Preattach scripts

A preattach script is similar to a preconnect script, but it is intended to assist with the attach connection. The purpose of a preattach-script (if present) is to provide a method to do custom target initializations prior to the attach session. Execution of these scripts is requested via the LinkServer telnet interface. On entry to the preattach-script, these variables have these values assigned:

  • a% is the probe index used

Connect scripts

The purpose of a connect-script is to provide any additional help necessary to gain access to the specified debug bus at the beginning of a debug session. These scripts are executed upon request from the GDB server through the LinkServer RPC interface. On entry to the connect script, these variables have these values assigned:

  • a% is the probe index used

  • b% is the core index

  • No use is made of any of the variables on exit

Reset scripts

The purpose of a reset-script is to allow execution of the code held in Flash while removing any prior chip state. These scripts are executed upon request from the GDB server through the LinkServer RPC interface. A reset-script overrides the default debug reset behavior. A reset-script is less commonly required than a connect-script but can be used to work around issues where a standard reset cannot allow debug operations to survive. On entry to a reset-script, some variables have assigned values:

  • a% is the PC

  • b% is the SP

  • c% is the XPSR

  • d% is the VTOR

On exit from the script, %a is loaded into the PC and %b is loaded into the SP. This mechanism provides a way for the script to change the startup behavior of the application.

Pre-created scripts

The purpose of certain scripts is described below:

  • kinetismasserase.scp - invoked by the Flash Programmer to resurrect a locked Kinetis device

  • kinetisunlock.scp - if for any reason the Flash Programmer fails to resurrect a locked part (as above), this script can be specified in place of the above and the recovery attempt repeated

  • delayexample.scp - an example script showing how a delay can be performed

On occasion, it can be useful to run and debug code directly from RAM. Since an MCU does not boot from RAM, a scheme is needed to take control of the debuggers reset mechanism. This setup can be achieved using a LinkServer reset script. Within the LinkServer installation, certain pre-created scripts are located in binaries/Scripts.

Contained in this directory is a script called kinetisRamReset.scp (see below).

1 REM ======================================
2 REM Copyright 2020, 2023 NXP
3 REM All rights reserved.
4 REM SPDX-License-Identifier: BSD-3-Clause
5 REM ======================================

10  REM Kinetis K64F Internal RAM (@ 0x20000000) reset script
20  REM Connect script is passed PC/SP from the vector table in the image by the debugger
30  REM For the simple use case we pass them back to the debugger with the location of the reset context.
40  REM
50  REM Syntax here is that '~' commands a hex output, all integer variables are a% to z%
70  REM Find the probe index
80  p% = probefirstfound
90  REM Set the 'this' probe and core
100 selectprobecore p% 0
110 REM NOTE!! Vector table presumed RAM location is address 0x20000000
120 REM The script passes the SP (%b) and PC (%a) back to the debugger as the reset context.
130 b% = peek32 this 0x20000000
140 a% = peek32 this 0x20000004
145 d% = 0x20000000
150 print "Vector table SP/PC is the reset context."
160 print "PC = "; ~a%
170 print "SP = "; ~b%
180 print "XPSR = "; ~c%
185 print "VTOR = "; ~d%
190 end

This reset script makes an assumption that the user intends to run code from RAM at 0x20000000. This address is the value of the SRAM_Upper RAM block on Kinetis parts.

User scripts

Other user-generated scripts can be added directly to the LinkServer product installation, at binaries/Scripts or binaries/ToolScripts. These user scripts can be referenced from custom JSON data files, when needed.